robcsaszar/scaffold

Créer / Réviser AGENTS.md par IA

Deux modes : créer un nouveau AGENTS.md ou réviser un existant selon des normes de qualité fondées sur la recherche.

Détection du mode

• L'utilisateur fournit un AGENTS.md existant ou pointe vers un → Mode Révision
• L'utilisateur demande de créer/générer → Mode Création
• Ambigu → demander : (c)réer un nouveau AGENTS.md ou (r)éviser un existant ?

---

Mode Création

Étape 1 : Demander l'emplacement

Où doit être placé le AGENTS.md ?
(r)acine — fichier de base pour l'ensemble du dépôt
(p)arcours — répertoire spécifique (fournir le chemin)

Pour les monorepos : suggérer racine + fichiers par package. Le AGENTS.md le plus proche l'emporte.

Si AGENTS.md existe déjà au chemin cible → demander : Fichier existant. (r)éviser l'existant / (é)craser / (Q)uitter ?

Étape 2 : Réflexion experte

Avant d'écrire, déterminer pour CE projet :

• Qu'est-ce qui n'est pas découvrable ? Ce qui n'est pas déductible de package.json, des configurations, ou de la structure des répertoires.
• Qu'est-ce qui est dangereux ? Quelles commandes ou motifs provoquent des échecs silencieux ?
• Qu'est-ce qui est ambigu ? Où y a-t-il deux approches valides et l'agent devinerait mal ?
• Qu'est-ce qui n'est pas standard ? Quelles conventions diffèrent des valeurs par défaut du framework ?

Si toutes les réponses sont "rien" — le projet n'a peut-être pas besoin d'un AGENTS.md. Le dire.

Pour les dépôts sans package.json ni configurations de build (docs-only, dépôts de données, scripts simples) : se concentrer uniquement sur les limites de Mission + Jugement — les sections sur la chaîne d'outils et la clôture ne s'appliquent pas.

Étape 3 : Écrire dans l'ordre de priorité

Ajouter les sections UNIQUEMENT si elles passent le test de non-découvrabilité, dans cet ordre :

1. Mission (2 à 4 phrases) — objectif du projet + contrainte fondamentale que l'agent ne peut pas inférer
2. Registre de la chaîne d'outils — commandes sous forme de tableau, PAS ce que les outils imposent
3. Limites de jugement — niveaux JAMAIS / DEMANDER / TOUJOURS
4. Définition de clôture — "Fait" = codes de sortie spécifiques
5. Règles d'escalade — que faire en cas de blocage
6. Sections organisées par tâche — "Lors de l'écriture… / Lors de la révision… / Lors de la publication…"

Étape 4 : Valider

• Total ≤ 150 lignes (optimal : 60 à 100)
• Chaque section ≤ 50 lignes
• Chaque instruction répond à : "Quelle commande prouve que cela a été fait ?"
• Chaque "ne fais pas" est associé à un "fais"
• Aucune règle de linter répétée (priorité à la chaîne d'outils)
• Aucun paragraphe en prose sans commandes

OBLIGATOIRE — LIRE references/knowledge-base.md pour les motifs et preuves fondés sur la recherche. OBLIGATOIRE — LIRE references/template.md pour la structure de départ. Charger references/example.md uniquement lorsque l'utilisateur demande à quoi ressemble un AGENTS.md terminé, ou lorsque le dépôt est un monorepo JS/TS (c'est un exemple travaillé avec turborepo + pnpm) — ignorer sinon. NE PAS charger references/knowledge-base.md pendant le mode Révision si le AGENTS.md cible a < 20 lignes — la liste de contrôle du corps et la liste des anti-patterns suffisent pour les fichiers trivialement courts.

---

Mode Révision

Évaluer le AGENTS.md fourni selon des critères de qualité fondés sur la recherche.

Dimensions de notation

Dimension	Poids	Ce qu'il faut vérifier
Densité de signal	25 %	% de lignes qui sont des connaissances expertes non découvrables vs. génériques/redondantes
Priorité aux commandes	20 %	Chaque instruction a une commande vérifiable ou un code de sortie
Définition de clôture	15 %	Critères explicites "fait" avec vérifications spécifiques
Système de limites	15 %	Niveaux JAMAIS/DEMANDER/TOUJOURS présents et spécifiques
Discipline de longueur	10 %	≤150 total, ≤50 par section, pas de gonflement
Absence d'anti-patterns	15 %	Exempt de motifs ayant prouvé leur échec

Conseils de notation

• Noter sévèrement la densité de signal pour les dépôts matures avec des chaînes d'outils établies — la plupart du contenu est probablement redondant
• Noter indulgent sur la clôture/les limites pour les projets en phase de démarrage — ils n'ont peut-être pas encore de passerelles CI
• Noter sévèrement la longueur pour les fichiers racine de monorepo — ils sont chargés à chaque session sur tous les packages
• Si le score total < 40 : recommander une réécriture plutôt que des corrections incrémentales

Liste de contrôle des anti-patterns

Signaler tout élément suivant (empiriquement prouvé comme nuisible à la performance de l'agent) :

• Paragraphes en prose sans commandes
• Directives ambiguës ("soyez prudent", "dans la mesure du possible")
• Priorités contradictoires sans ordre explicite
• Règles de style déjà appliquées par la configuration du linter
• Aperçus d'architecture (provoque une surexploration)
• 15+ avertissements sans alternatives associées
• Texte généré par LLM à partir de commandes /init
• Reformulation de ce que la chaîne d'outils applique
• Violations d'éléphants roses (longues listes "ne faites pas" qui maintiennent les concepts interdits actifs)

Format de sortie

## Révision de AGENTS.md : <nom ou chemin du fichier>

**Score** : X/100
**Verdict** : [Prêt pour la production / Nécessite des améliorations / Réécriture recommandée]

### Points forts
- ...

### Problèmes (par sévérité)
1. [CRITIQUE] ...
2. [ÉLEVÉ] ...
3. [FAIBLE] ...

### Suggestions de réécriture
1. ...
2. ...

Appliquer

La révision n'est pas le livrable — un meilleur AGENTS.md l'est. Après l'avoir présentée, proposer :

Appliquer ? (t)out / (s)électionner par numéro / (a)ucun

Sur (t) ou (s) : modifier le fichier sur place, un élément numéroté à la fois, puis réexécuter les dimensions de notation et signaler le nouveau score ainsi que l'ancien. Chaque ligne que la révision n'a pas signalée survit textuellement — une révision n'est pas un mandat de réécriture, et "améliorer" silencieusement de la prose non signalée détruit la voix et l'intention de l'auteur.

Sauter l'offre lorsque l'utilisateur a fourni le contenu en ligne plutôt qu'un chemin, ou que le fichier n'est pas inscriptible. Le dire plutôt que de signaler des améliorations comme appliquées.

OBLIGATOIRE — LIRE references/knowledge-base.md pour les preuves de recherche derrière chaque critère.

---

JAMAIS

• NE JAMAIS inclure de contenu que l'agent peut découvrir à partir de la structure du dépôt — les scripts package.json, la disposition des répertoires et les fichiers de configuration sont auto-documentés ; les répéter gaspille des tokens et crée une dérive de maintenance. À LA PLACE : référencer le fichier (voir biome.json) et passer à autre chose.
• NE JAMAIS reformuler les règles du linter/formateur — l'outil EST la contrainte ; la duplication crée de l'obsolescence et des exigences inutiles nuisent activement à la performance de l'agent. À LA PLACE : lister uniquement la commande d'exécution (Lint : \pnpm lint``).
• NE JAMAIS écrire un "ne fait pas" sans un "fais" associé — les documents uniquement avec des avertissements provoquent une surexploration ; 15+ "ne faites pas" sans alternatives rendent les agents conservateurs et moins productifs. À LA PLACE : associer chaque interdiction à l'alternative correcte.
• NE JAMAIS dépasser 150 lignes — au-delà de ce seuil, les gains s'inversent et le fichier nuit activement à la qualité. À LA PLACE : extraire les détails dans des fichiers référencés ou supprimer.
• NE JAMAIS utiliser le contenu généré par LLM comme final — la sortie de /init est un inventaire de ce que l'agent connaît déjà ; cela réduit la performance et augmente le coût. À LA PLACE : traiter comme un brouillon d'inventaire, puis supprimer tout ce que la chaîne d'outils applique déjà.
• NE JAMAIS écrire de paragraphes en prose — les agents les ignorent ; utiliser des commandes, des tableaux et des listes à puces avec des résultats vérifiables. À LA PLACE : convertir en commande + code de sortie + description d'une ligne.