Les trois fichiers qu'un monorepo Angular doit avoir avant qu'un agent écrive une ligne

La première partie s'achevait sur une équipe dont l'agent reste dans les garde-fous dès son premier essai. Cette partie construit ces garde-fous. Ce sont trois fichiers : un que l'agent doit lire, un qu'il doit faire passer au vert, un qu'il ne doit jamais quitter. Un après-midi de travail, et les règles qui vivaient dans la tête des gens deviennent des contraintes auxquelles l'agent doit obéir.

1. Le fichier qu'il doit lire

Avant d'agir, tout agent lit un fichier d'instructions placé à la racine du projet, et chaque outil a le sien : CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, .cursor/rules/. Plusieurs d'entre eux lisent désormais aussi AGENTS.md. Beaucoup d'équipes laissent ces fichiers vides, y collent le ou rédigent quatre copies qui finissent par diverger.

L'agent voit votre code, pas vos raisons. C'est dans le fichier de règles que vivent les raisons.

Écrivez un seul fichier, AGENTS.md, et réduisez chaque fichier d'outil à une ligne qui renvoie vers lui. Dans le dépôt de démonstration, CLAUDE.md se limite à @AGENTS.md, plus le bloc ajouté par l'outillage , et GEMINI.md demande à l'agent de lire et de suivre AGENTS.md avant toute chose. Une seule source de vérité, quel que soit l'agent. Les options propres à un outil, comme les permissions ou les , vont dans ses réglages à lui. Les règles, elles, ne bougent pas.

La partie , vous n'avez pas à l'écrire vous-même : l'équipe Angular la publie. Elle propose un best-practices.md sur angular.dev/ai et des pour agents dans angular/skills. Dans le dépôt de démonstration, elles se trouvent dans .agents/skills/, un dossier que plusieurs agents lisent, et les skills Angular et Atlas sont liées dans .claude/skills/ pour . Votre AGENTS.md ne retient que ce que l'équipe Angular ne peut pas savoir : vos frontières, votre , votre définition du « terminé ».

Son contenu est court, concret et surtout négatif. L'agent n'a que faire de votre vision d'architecture. Il lui faut des garde-fous. Version condensée de l'AGENTS.md du dépôt de démonstration :

# Atlas Bank : règles pour les agents de code (extrait)
 
## Organisation
- libs/domain         TypeScript pur, aucun import Angular
- libs/data-access/*  stores et services ; peuvent importer domain
- libs/ui             présentation uniquement ; n'importe jamais data-access
- libs/feature/*      fonctionnalités routées ; peuvent importer ui, data-access, domain
 
## Non négociable
- Les nouveaux composants sont standalone et utilisent les signals. Aucun nouveau NgModule.
- Ne jamais modifier libs/legacy/** sauf si le fichier de tâche demande une migration. L'envelopper.
- Franchir une frontière entre bibliothèques exige un lien vers un ADR dans la PR.
 
## Avant de déclarer la tâche terminée
- npm run lint:arch   doit passer
- npm run test        doit passer sans assertion modifiée
- Le diff fait ≤ 300 lignes, sauf si le fichier de tâche relève la limite

Un terme mérite qu'on s'y arrête. Un (architecture decision record) est une courte note datée qui explique pourquoi une frontière existe. Exiger de l'agent le lien vers un ADR, c'est lui demander de justifier le franchissement. En général, il en est incapable, et c'est justement le but.

2. Le fichier qu'il doit faire passer au vert

Une consigne reste une suggestion. Une commande qui échoue, non. On reprend donc les mêmes frontières sous forme de règle : @nx/enforce-module-boundaries dans un Nx, ou dans un projet classique. Extrait de la configuration flat du dépôt de démonstration :

// eslint.config.mjs (extrait)
const depConstraints = [
  { sourceTag: 'type:domain', onlyDependOnLibsWithTags: ['type:domain'] },
  { sourceTag: 'type:data-access', onlyDependOnLibsWithTags: ['type:data-access', 'type:domain'] },
  { sourceTag: 'type:ui', onlyDependOnLibsWithTags: ['type:ui', 'type:domain'] },
  { sourceTag: 'type:feature', onlyDependOnLibsWithTags: ['type:feature', 'type:ui', 'type:data-access', 'type:domain'] },
];
// ...
'@nx/enforce-module-boundaries': ['error', { depConstraints }],

Le fichier de règles peut désormais dire « lance lint:arch avant de terminer », et un agent qui lance cette commande réessaie en général jusqu'à ce qu'elle passe. « Merci de respecter l'architecture » est devenu une commande qui échoue.

Un import de data-access dans un composant ui, et le refuse avant même qu'un relecteur ait à le faire.

3. Le fichier qu'il ne doit jamais quitter

Le troisième fichier est propre à chaque tâche, pas au dépôt. C'est la demande, rédigée avant que l'agent ne la lise, avec un périmètre, ce qui en est exclu et une condition « terminé quand ». Ce peut être un , une aux rubriques fixes ou un fichier dans docs/tasks/. Peu importe la forme. L'essentiel tient en une phrase :

Périmètre : libs/feature/accounts uniquement. Terminé quand lint:arch et les tests passent et que le diff fait moins de 300 lignes.

C'est la limite de taille qui change le plus de choses. Les agents excellent à respecter des contraintes explicites et devinent très mal les contraintes implicites. Avec 300 dans la tâche, un de bien plus de mille lignes échoue au « terminé quand » avant que quiconque ne le lise.

Prompt · laissez l'agent trouver les trous de votre fichier de règles

Lis AGENTS.md. Ensuite, ouvre libs/ et dresse la liste numérotée de toutes les règles dont tu aurais besoin pour réaliser une fonctionnalité dans libs/feature/accounts et que le fichier ne précise pas : quels imports sont autorisés, quel store utiliser, comment écrire les tests, ce que « terminé » veut dire. N'écris pas de code. Ne propose pas de règles ; contente-toi de lister ce qui manque.

Lancez-le une fois par trimestre. La liste devient le de votre fichier de règles.

Ce qui change quand les trois fichiers existent

La première tentative de l'agent reste en général dans les garde-fous. La revue ne consiste plus à « tout lire », mais à « lire la décision ».
Les garde-fous font école : l'erreur lint explique une frontière mieux qu'une page de wiki.
Ces fichiers deviennent une trace concrète de l'architecture de l'équipe, ce que la plupart des équipes n'ont jamais eu.

Dès lundi

Rédigez AGENTS.md : une page environ, surtout des « jamais ». Faites pointer chaque fichier d'outil vers lui.
Transformez la liste d'organisation en règle lint et ajoutez lint:arch à la définition du « terminé ».
Fixez une limite de taille dans la prochaine tâche que vous confiez à un agent.

Exercice : le module 1 du dépôt de démonstration. Commencez sans les fichiers : git switch track1/m1-start. Puis la même tâche avec eux : git switch -c m1/you main. Référence : origin/track1/m1-solution. Venez avec votre propre agent.

Qui rédige ce troisième fichier, et en combien de temps : c'est l'objet de la partie suivante. L'agent le rédige à partir du ticket, et une personne décide.

Parcours 1, partie 2 de la série gratuite qui accompagne le Vite et sûr : l'IA dans votre code Angular.