agents-md-starter

Que fait agents-md-starter ?

Sortie : AGENTS.md à la racine du dépôt comme source unique de vérité, plus CLAUDE.md contenant @AGENTS.md (Claude Code lit CLAUDE.md et prend en charge les imports @path). Chaque commande dans le fichier doit avoir été exécutée avec succès ou être clairement marquée comme non vérifiée.

Étape 1 — Analyse

python3 scripts/scan_repo.py /chemin/vers/depot            # résumé humain
python3 scripts/scan_repo.py /chemin/vers/depot --json     # faits en JSON
python3 scripts/scan_repo.py /chemin/vers/depot --draft > AGENTS.draft.md   # modèle rempli

Il détecte : les langages par nombre de fichiers, le gestionnaire de paquets à partir des fichiers de verrouillage, les scripts dans package.json, les cibles Makefile, les outils pyproject.toml (pytest, ruff, mypy, uv/poetry), les fichiers de construction Go/Rust/Java, les frameworks (Next.js, Astro, Vite, Django, FastAPI, Rails…), les espaces de travail monorepo, les workflows CI, les fichiers env d'exemple et les fichiers de règles d'agent existants. Il n'exécute jamais le code du dépôt.

Étape 2 — Lire avant d'écrire

• Lisez chaque fichier de règles existant trouvé (CLAUDE.md, .cursorrules, .cursor/rules/*.mdc, .github/copilot-instructions.md, GEMINI.md, CONTRIBUTING.md). Conservez leurs vraies règles ; fusionnez, dédupliquez, supprimez les règles génériques ("écrire du code propre").
• Lisez le workflow CI : les commandes exécutées par CI sont la définition la plus fiable de "les tests passent".
• Parcourez 2–3 fichiers source représentatifs pour capturer les conventions réelles (nommage, gestion des erreurs, style d'import) — n'inventez pas de conventions que le code ne suit pas.

Étape 3 — Vérifier les commandes

Exécutez les commandes d'installation/construction/test/lint du brouillon (de manière sécurisée : pas de déploiement, pas de migrations contre des bases de données réelles, pas de publication). Pour chacune : conservez-la si elle fonctionne ; corrigez-la si la bonne variante est évidente ; sinon marquez-la (non vérifiée) et informez l'utilisateur. Notez la durée de la suite de tests si elle est lente.

Étape 4 — Écrire AGENTS.md

Partez de assets/AGENTS.template.md. Règles pour un bon contenu :

• Court. Visez moins d'environ 150 lignes. Les agents lisent ce fichier à chaque tâche ; chaque ligne coûte du contexte.
• Spécifique et vérifiable : "Exécutez pnpm test --filter web avant de commiter" est mieux que "testez votre code".
• Mettez les commandes en premier. Ensuite, la structure, les conventions, les pièges et les règles "ne pas faire".
• Enregistrez ce qui n'est pas évident : les fichiers générés à ne pas modifier, les variables d'environnement nécessaires aux tests, le test lent à ignorer en local, où les secrets ne doivent jamais aller.
• Monorepos : AGENTS.md racine pour les règles partagées + packages/x/AGENTS.md imbriqué pour les commandes spécifiques au package (les agents qui le prennent en charge lisent le fichier le plus proche).

Étape 5 — Connecter les autres outils

• Claude Code : créez CLAUDE.md à partir de assets/CLAUDE.template.md (il contient @AGENTS.md). Si un CLAUDE.md existe déjà, déplacez ses règles dans AGENTS.md et laissez les notes spécifiques à Claude en dessous de l'import.
• Codex : lit AGENTS.md nativement — rien d'autre n'est nécessaire.
• Cursor : lit AGENTS.md à la racine ; migrez le contenu de .cursorrules dans AGENTS.md et, après l'accord de l'utilisateur, supprimez .cursorrules (obsolète). Conservez .cursor/rules/*.mdc uniquement pour les règles basées sur des globs.
• Gemini CLI : lit GEMINI.md par défaut ; définissez "context": {"fileName": ["AGENTS.md", "GEMINI.md"]} dans .gemini/settings.json ou créez un GEMINI.md d'une ligne pointant vers AGENTS.md. Vérifiez la documentation de la version installée si cette clé a changé.
• Les liens symboliques (ln -s AGENTS.md CLAUDE.md) fonctionnent aussi mais cassent sur les checkouts Windows sans core.symlinks ; l'approche par import est plus sûre.

Voir references/tool-support.md pour le fichier que chaque outil lit.

Étape 6 — Rapport

Listez : les fichiers créés/modifiés, les commandes vérifiées (avec résultat), les commandes marquées non vérifiées, les règles supprimées comme doublons ou génériques, et tout ce pour quoi vous avez besoin d'une décision de l'utilisateur (par exemple supprimer .cursorrules?). Ne commitez pas sauf si l'utilisateur le demande.