Contexte de projet

Que fait Contexte de projet ?

Aidez la personne à décider et à écrire les règles stables du projet, chacune dans le fichier qui lui correspond. La personne prend les décisions : vous lisez, proposez des options concrètes et rédigez.

Il remplace la constitution.md de Spec Kit. Tout son contenu trouve une meilleure place :

Contenu	Fichier	Lu par
Stack, couches, règles de dépendances, principes non négociables, glossaire	docs/ARCHITECTURE.md	Personnes et agents ; spec-to-plan et review-spec vérifient les principes
Qualité, branches, commits, PRs, relecture, utilisation de l’IA	CONTRIBUTING.md	Personnes (et agents, via lien)
Le pourquoi de chaque décision structurelle et les alternatives écartées	docs/adr/NNNN-*.md	Les deux, sur demande
Commandes, limites, conventions non évidentes, plan de documentation	AGENTS.md (+ CLAUDE.md avec @AGENTS.md)	Agents, à chaque session
Comment signaler des vulnérabilités, politique des agents	SECURITY.md	Personnes

Modèles dans assets/fr/ (français) et assets/es/ (espagnol). Utilisez la langue dans laquelle le projet est documenté ; demandez si ce n’est pas clair. Chaque modèle explique dans son commentaire d’ouverture comment le remplir.

Règles

• Ne pas dupliquer. Si quelque chose est déjà dans pyproject.toml, dans le CI ou dans un linter, faites un lien ; ne le copiez pas. Si un principe apparaît dans deux fichiers, ils finiront par se contredire : les principes vivent uniquement dans ARCHITECTURE.md.
• AGENTS.md court : moins de 150 lignes. C’est une carte qui relie ; elle ne contient pas. Pour chaque ligne : « si je l’enlève, l’agent ferait-il une erreur ? ». Si non, dehors.
• Ce qui peut être vérifié par un outil doit l’être. Pour chaque principe, demandez comment il est vérifié (lint, import-linter, test, CI, relecture) et notez-le dans sa colonne.
• Rien de volatil : pas de statut de sprint ni de TODOs. Ceux-ci vont dans le suivi ou dans docs/plans/.
• Affichez chaque fichier en entier (ou le diff, s’il existe déjà) et n’écrivez qu’après l’approbation de la personne.

Processus

1. Lire le projet

Avant de poser une question, lisez : les manifests (pyproject.toml, package.json, go.mod…), README.md, tous les fichiers de contexte existants, .github/workflows/, la configuration du linter et la structure des dossiers. Utilisez ce que vous trouvez pour proposer des réponses au lieu de poser des questions ouvertes.

Décidez du mode et informez la personne :

• Greenfield (pas de code ou presque) : ARCHITECTURE.md est prescriptif, comment ce sera.
• Brownfield : ARCHITECTURE.md est descriptif, comment c’est aujourd’hui. L’idéal va dans les ADR et les cliquets des outils. Si des fichiers de contexte existent déjà, ne posez de questions que sur les lacunes et proposez des diffs.
• Migration depuis une constitution.md : distribuez son contenu selon le tableau ci-dessus et proposez de la supprimer ou de la réduire à un lien.

2. Entretien par rounds

Une catégorie à la fois. Pour chaque question, proposez des options concrètes (A, B, « laisser ouvert », « autre »). Si les fichiers répondent déjà à la question, demandez une confirmation au lieu de poser la question. Si une catégorie ne s’applique pas (par exemple, pas de base de données), sautez-la et dites-le. À la fin de chaque round, résumez ce qui a été décidé.

Round	Ce qui est décidé	Destination
1. Objectif	Ce qu’est le projet et ce qui est exclu ; type (app, service, librairie, CLI)	ARCHITECTURE.md §1, README.md
2. Stack et architecture	Langage, framework, persistance, infrastructure ; couches ou modules et ce qui peut importer quoi	ARCHITECTURE.md §2–4, un ADR par décision structurelle
3. Principes non négociables	5–10 règles stables et vérifiables : pourquoi, et comment chacune est vérifiée	ARCHITECTURE.md §5
4. Qualité	Test d’abord ou après, couverture minimale, typage, ce qui n’est jamais mocké	CONTRIBUTING.md §5 ; si non négociable, aussi un principe
5. Sécurité	Authentification, données sensibles, validation des entrées, conformité réglementaire	ARCHITECTURE.md §10, SECURITY.md
6. Processus	Branches, Conventional Commits, merge ou squash, approbations, taille des PR, outils IA autorisés	CONTRIBUTING.md §4, §6–7
7. Dépendances	Politique d’ajout, librairies interdites, construire ou acheter	Principe (si non négociable) ou CONTRIBUTING.md
8. Pour l’agent	Commandes (la commande de vérification est obligatoire), conventions non évidentes, zones critiques ou fragiles (brownfield), limites (toujours / demander / jamais)	AGENTS.md

Au round 8, la commande de vérification est le contrat avec les autres compétences (plan-to-tasks, implement, review). Si elle n’existe pas, proposez setup-guardrails-python (ou un équivalent pour le langage) ou laissez-la comme question ouverte dans AGENTS.md. Si le projet va utiliser review-prepush ou review-pr, proposez aussi la section optionnelle ## Code review (modèle dans review-context/assets/AGENTS-code-review.md) : branche de base, chemins à haut risque, langue du rapport…

3. Rédiger et écrire

Ordre : ARCHITECTURE.md → ADRs → CONTRIBUTING.md → SECURITY.md → AGENTS.md. AGENTS.md arrive en dernier car il fait le lien avec tous les autres.

• Commencez par le modèle dans assets/. Supprimez les sections qui ne s’appliquent pas encore ; ne les laissez pas vides.
• ADRs : copiez ADR.md sous docs/adr/0000-template.md (0000-plantilla.md en espagnol) et adr-README.md sous docs/adr/README.md. Créez un ADR par décision structurelle des rounds 2–3. Brownfield : seulement 3–5 rétroactifs, pour ce qui est le plus questionné, avec les alternatives écartées.
• AGENTS.md doit inclure :
  • la ligne « Planification » : vérifier le plan par rapport aux principes dans docs/ARCHITECTURE.md avant d’implémenter ;
  • un lien vers CONTRIBUTING.md pour le processus.
• CLAUDE.md ne contient que @AGENTS.md, sauf s’il a déjà un contenu. Dans ce cas, proposez de le déplacer dans AGENTS.md.
• pull_request_template.md va dans .github/. Proposez-le, ne l’imposez pas.

4. Bilan

Listez les fichiers créés ou modifiés et les questions laissées ouvertes. Rappelez à la personne :

• AGENTS.md est relu mensuellement et allégé, surtout lors d’un changement de modèle.
• ARCHITECTURE.md est vérifié par rapport au code tous les trimestres.
• Chaque erreur que l’agent répète devient une règle d’outil ou, en dernier recours, une ligne sous « Pièges connus ».