Le problème
Soyons honnêtes : nous ne voulons plus lire le code. Nous ne voulons pas vérifier tout ce que font les agents, ni garder en tête chaque détail technique du projet.
Mais si personne ne contrôle les agents, ils transformeront n'importe quel projet en un chaos immaintenable que ni un humain ni un agent ne pourra démêler. Ce n'est qu'une question de temps.
L'idée
HUMAN-INTENT.md est un fichier à la racine de votre dépôt. Il porte votre intention : l'architecture du projet, les règles de développement et les décisions produit.
Ce n'est pas la documentation du code. C'est la loi à laquelle le code doit obéir.
Les règles
-
Écrit par vous — et vous seul
Les agents ne modifient jamais ce fichier. Chaque ligne est une décision prise par un humain.
-
Ses instructions font loi pour l'agent
Ce que dit HUMAN-INTENT.md prime sur tout le reste. Si le code contredit le fichier, c'est le code qui a tort.
-
Il définit l'architecture, les règles et le produit
L'intention, pas les recettes. L'agent connaît déjà tous les patterns ; votre rôle est de fixer ce qui doit être vrai — et pourquoi.
Pourquoi ça marche
Impossible de suivre les agents : il y a plus de code que quiconque n'est prêt à en lire. Contrôler chaque ligne est sans espoir. Contrôler l'intention, non.
HUMAN-INTENT.md élève le contrôle d'un niveau : vous surveillez un fichier contenant vos décisions plutôt que des milliers de lignes de code. Tant que le fichier fait loi, le projet suit votre intention — même si personne ne lit le code.
Comment commencer
- Créez HUMAN-INTENT.md à la racine du dépôt.
- Notez les décisions déjà prises : architecture, règles de développement, produit.
- Dites à votre agent de lire ce fichier et de le traiter comme une loi — référencez-le depuis AGENTS.md ou CLAUDE.md.
- À chaque nouvelle décision, ajoutez-la au fichier. Ne laissez jamais un agent y écrire.
- Relisez ce fichier, pas le code.