Générateur de Contexte de Projet
Créez ou mettez à jour .claude/docs/project.md — la référence concise du projet que Claude charge à chaque conversation. Contrairement à un README (écrit pour les humains), project.md est écrit pour Claude : dense, factuel, sans prose marketing.
Pourquoi cette compétence existe
.claude/docs/project.md est automatiquement chargé dans chaque conversation Claude via CLAUDE.md. Lorsqu'il est manquant ou obsolète, Claude perd des tours à redécouvrir la stack technique, les commandes de test et l'architecture. Cette compétence automatise cette découverte et produit un fichier de référence précis et fiable.
Flux de travail
Étape 1 : Analyser la base de code
Exécutez une analyse structurée en trois phases pour rassembler les faits du projet. Étiquetez chaque fait avec un niveau de confiance : [confirmed] (lu depuis la source), [inferred-high] (forte évidence), [inferred-low] (évidence partielle), ou [unknown].
Voir references/analysis-methodology.md pour les actions d'outils détaillées, les motifs glob/grep et les modèles d'enregistrement.
Phase 1 — Métadonnées du projet : Globbing pour les fichiers de gestionnaire de paquets, les modèles d'environnement, les configurations CI et les fichiers de chaîne d'outils. Extrayez : nom du projet, langage, version Python, dépendances (avec objectifs), scripts/commandes, variables d'environnement, étapes CI, marqueurs de test.
Phase 2 — Scan d'architecture : Globbing pour tous les fichiers source. Identifiez les points d'entrée, construisez le graphe d'imports, classifiez les modules (core/leaf/orchestrator) et identifiez le patron d'architecture. Lisez les fichiers de configuration référencés par le code source.
Phase 3 — Sources de données et infrastructure : Identifiez les sources de données externes (bases de données, API, fichiers), les cibles de sortie (fichiers, téléchargements, API), la structure des tests et la hiérarchie d'exceptions personnalisées.
Étape 2 : Poser des questions de clarification
Après l'analyse, interrogez l'utilisateur sur les éléments [inferred-low] et [unknown]. Restez ciblé — ne posez pas de questions sur ce que vous savez déjà. Lacunes courantes :
- Objectif du projet : Quel problème cela résout-il ? (si pas évident depuis le code)
- Sources de données : Quels systèmes alimentent le projet en données ? Qu'est-ce qui reçoit la sortie ?
- Déploiement : Comment/où cela est-il exécuté ? (local, planifié, cloud)
Si la base de code est simple, vous n'aurez peut-être besoin que d'une ou deux questions — voire aucune.
Étape 3 : Générer project.md
Écrivez le fichier en utilisant la structure ci-dessous. Si .claude/docs/project.md existe déjà, confirmez avec l'utilisateur avant de l'écraser.
Structure de sortie
Le fichier project.md généré doit suivre cette structure. Adaptez la profondeur au projet — les petits projets peuvent ignorer des sections, les projets complexes peuvent ajouter des sous-sections.
# {Nom du projet} — Contexte du projet
{Description en une phrase : ce que c'est, ce que ça fait, technologie clé.}
## Stack technique
- **{Langage/Exécution}** — {contrainte de version si connue}
- **{Framework}** — {à quoi ça sert}
- **{Bibliothèque clé}** — {objectif}
- ...liste à puces, en gras le nom de l'outil, annoter l'objectif
## Structure du projet
```text
{arborescence annotée — une phrase courte par entrée}
```
## Flux de données
```text
{diagramme ASCII montrant le pipeline source → transformation → sortie}
```
## Sources de données
- `{NOM_SOURCE}` — {ce qu'elle fournit}
- ...pour bases de données, API, fichiers locaux, etc.
## Marqueurs de test
- `{commande de test}` — {ce qu'elle exécute}
- `{nom du marqueur}` — {ce qu'il conditionne}
## Patrons d'architecture clés
- **{Nom du patron}** (`{fichier}`) : {explication en une phrase}
- ...uniquement les patrons non évidents qui méritent d'être signalés
---
## Consignes de rédaction
- **Dense plutôt que verbeux.** Chaque ligne doit mériter sa place. Claude n'a pas besoin de motivation ou de mise en contexte — juste des faits.
- **Spécifique plutôt que générique.** "Exécuter `uv run pytest -m 'not snowflake'`" est mieux que "Exécuter les tests en excluant les dépendances externes."
- **Une phrase par patron.** Les patrons d'architecture doivent tenir en une ligne chacun — nom, fichier, explication.
- **Commandes réelles.** Copiez les commandes de test depuis `pyproject.toml` ou les configurations CI, pas des versions paraphrasées.
- **Annotez les dépendances.** Ne vous contentez pas de lister `polars` — dites `polars — DataFrames haute performance`.
- **Les sources de données sont critiques.** Claude a besoin de connaître les systèmes externes existants. Listez chaque base de données, API et fichier source.
- **Restez sous 100 lignes.** Si project.md dépasse environ 100 lignes de contenu, c'est trop détaillé — déplacez les spécificités vers une documentation dédiée et faites un lien vers elles.
## Sortie
Enregistrez le fichier sous `.claude/docs/project.md` (créez le répertoire si nécessaire). Si le fichier existe déjà, montrez à l'utilisateur un résumé des différences avant d'écraser.
Après avoir généré project.md, vérifiez si `CLAUDE.md` le référence. Si ce n'est pas le cas, suggérez d'ajouter une ligne comme :
```markdown
Voir [.claude/docs/project.md](.claude/docs/project.md) pour les détails spécifiques au projet (stack technique, architecture, marqueurs de test).
```