Acquérir les Connaissances de la Base de Code

Produit sept documents remplis dans docs/codebase/ couvrant tout ce qui est nécessaire pour travailler efficacement sur le projet. Documenter uniquement ce qui est vérifiable à partir de fichiers ou de sortie terminal — ne jamais déduire ou supposer.

Contrat de Sortie (Obligatoire)

Avant de terminer, tous les points suivants doivent être vrais :

1. Exactement ces fichiers existent dans docs/codebase/ : STACK.md, STRUCTURE.md, ARCHITECTURE.md, CONVENTIONS.md, INTEGRATIONS.md, TESTING.md, CONCERNS.md.
2. Chaque affirmation est traçable jusqu'à des fichiers source, une configuration ou une sortie terminal.
3. Les inconnues sont marquées comme [TODO]; les décisions dépendant de l'intention sont marquées [ASK USER].
4. Chaque document inclut une courte liste « d'éléments de preuve » avec des chemins de fichiers concrets.
5. La réponse finale inclut les questions numérotées [ASK USER] et les divergences entre l'intention et la réalité.

Flux de Travail

Copier et suivre cette checklist :

- [ ] Phase 1 : Exécuter l'analyse, lire les documents d'intention
- [ ] Phase 2 : Investiguer chaque domaine de documentation
- [ ] Phase 3 : Remplir les sept docs dans docs/codebase/
- [ ] Phase 4 : Valider les docs, présenter les résultats, résoudre tous les éléments [ASK USER]

Mode Zone Ciblée

Si l'utilisateur fournit une zone ciblée (par exemple : « architecture uniquement » ou « tests et préoccupations ») :

1. Toujours exécuter la Phase 1 intégralement.
2. Compléter d'abord entièrement les documents de la zone ciblée.
3. Pour les documents non-ciblés pas encore analysés, garder les sections requises présentes et marquer les inconnues comme [TODO].
4. Toujours exécuter la boucle de validation de Phase 4 sur les sept documents avant la sortie finale.

Phase 1 : Analyser et Lire l'Intention

1. Exécuter le script d'analyse depuis la racine du projet cible :

   python3 "$SKILL_ROOT/scripts/scan.py" --output docs/codebase/.codebase-scan.txt

   Où $SKILL_ROOT est le chemin absolu vers le dossier skill. Fonctionne sur Windows, macOS et Linux.

   Démarrage rapide : Si vous avez le chemin en ligne :

   python3 /absolute/path/to/skills/acquire-codebase-knowledge/scripts/scan.py --output docs/codebase/.codebase-scan.txt

2. Chercher les fichiers PRD, TRD, README, ROADMAP, SPEC, DESIGN et les lire.

3. Résumer l'intention déclarée du projet avant de lire tout code source.

Phase 2 : Investiguer

Utiliser la sortie d'analyse pour répondre aux questions de chacun des sept templates. Charger references/inquiry-checkpoints.md pour la liste complète des questions par template.

Si la pile technologique est ambiguë (fichiers manifestes multiples, types de fichiers non familiers, pas de package.json), charger references/stack-detection.md.

Phase 3 : Remplir les Templates

Copier chaque template de assets/templates/ dans docs/codebase/. Remplir dans cet ordre :

1. STACK.md — langage, runtime, frameworks, toutes les dépendances
2. STRUCTURE.md — disposition des répertoires, points d'entrée, fichiers clés
3. ARCHITECTURE.md — couches, patterns, flux de données
4. CONVENTIONS.md — nommage, formatage, gestion des erreurs, imports
5. INTEGRATIONS.md — APIs externes, bases de données, authentification, monitoring
6. TESTING.md — frameworks, organisation des fichiers, stratégie de mocking
7. CONCERNS.md — dette technique, bugs, risques de sécurité, goulets d'étranglement de performance

Utiliser [TODO] pour tout ce qui ne peut pas être déterminé à partir du code. Utiliser [ASK USER] où la bonne réponse nécessite l'intention de l'équipe.

Phase 4 : Valider, Réparer, Vérifier

Exécuter cette boucle de validation obligatoire avant la finalisation :

1. Valider chaque doc par rapport à references/inquiry-checkpoints.md.
2. Pour chaque affirmation non triviale, confirmer qu'au moins une référence de preuve existe.
3. Si une section requise manque ou n'est pas supportée :

• Corriger le document.
• Réexécuter la validation.

4. Répéter jusqu'à ce que les sept docs réussissent.

Ensuite présenter un résumé des sept documents, lister chaque élément [ASK USER] comme une question numérotée, et mettre en évidence les divergences entre Intention et Réalité de la Phase 1.

Critères de réussite de la validation :

• Aucune affirmation non supportée.
• Aucune section requise vide.
• Les inconnues utilisent [TODO] plutôt que des suppositions.
• Les lacunes d'intention de l'équipe sont explicitement marquées [ASK USER].

Pièges

Monorepos : Le package.json racine peut ne pas avoir de source — vérifier les répertoires workspaces, packages/ ou apps/. Chaque workspace peut avoir des dépendances et conventions indépendantes. Mapper chaque sous-package séparément.

README obsolète : Le README décrit souvent l'architecture prévue, pas la réalité. Faire des références croisées avec la structure réelle des fichiers avant de traiter toute affirmation du README comme un fait.

Alias de chemins TypeScript : La configuration paths de tsconfig.json signifie que les imports comme @/foo ne correspondent pas directement au système de fichiers. Mapper les alias aux chemins réels avant de documenter la structure.

Sortie générée/compilée : Ne jamais documenter les patterns de dist/, build/, generated/, .next/, out/ ou __pycache__/. Ce sont des artefacts — documenter uniquement les conventions source.

.env.example révèle la configuration requise : Les secrets ne sont jamais commités. Lire .env.example, .env.template ou .env.sample pour découvrir les variables d'environnement requises.

devDependencies ≠ pile de production : Seules les dependencies (ou équivalent, p. ex. [tool.poetry.dependencies]) s'exécutent en production. Documenter les linters, formateurs et frameworks de test séparément comme outils de développement.

TODOs de test ≠ dette de production : Les TODOs à l'intérieur de test/, tests/, __tests__/ ou spec/ sont des lacunes de couverture, pas de la dette technique de production. Les séparer dans CONCERNS.md.

Fichiers très modifiés = zones fragiles : Les fichiers apparaissant le plus dans l'historique récent de git ont le taux de modification le plus élevé et probablement une complexité cachée. Les noter toujours dans CONCERNS.md.

Anti-Patterns

Sections Améliorées de Sortie d'Analyse

Le script scan.py produit maintenant les sections suivantes en addition à la sortie originale :

• CODE METRICS — Fichiers totaux, lignes de code par langage, plus grands fichiers (signaux de complexité)
• CI/CD PIPELINES — GitHub Actions, GitLab CI, Jenkins, CircleCI détectés, etc.
• CONTAINERS & ORCHESTRATION — Docker, Docker Compose, Kubernetes, configurations Vagrant
• SECURITY & COMPLIANCE — Snyk, Dependabot, SECURITY.md, SBOM, politiques de sécurité
• PERFORMANCE & TESTING — Configs de benchmark, marqueurs de profiling, outils de load testing

Utiliser ces sections lors de la Phase 2 pour informer les questions d'investigation et identifier les patterns spécifiques aux outils.

Ressources Incluses

| references/inquiry-checkpoints.md | Phase 2 — charger pour les questions d'investigation par template | | references/stack-detection.md | Phase 2 — seulement si la pile technologique est ambiguë | | assets/templates/STACK.md | Phase 3 étape 1 | | assets/templates/STRUCTURE.md | Phase 3 étape 2 | | assets/templates/ARCHITECTURE.md | Phase 3 étape 3 | | assets/templates/CONVENTIONS.md | Phase 3 étape 4 | | assets/templates/INTEGRATIONS.md | Phase 3 étape 5 | | assets/templates/TESTING.md | Phase 3 étape 6 | | assets/templates/CONCERNS.md | Phase 3 étape 7 |

Mode d'utilisation des templates :

• Mode par défaut : compléter uniquement les « Sections Essentielles (Obligatoires) » dans chaque template.
• Mode étendu : ajouter les sections optionnelles uniquement quand la complexité du repo les justifie.