Supprimez votre AGENTS.md (sauf les quelques lignes qui comptent)

Ouvrez votre fichier AGENTS.md. Décrit-il la structure de vos dossiers ? Explique-t-il qu’il faut utiliser npm install pour installer les dépendances et npm test pour lancer les tests unitaires ? Demande-t-il à l’agent d’« écrire du code propre et facile à maintenir » ?

Il n’apporte aucune plus-value à votre agent, vous pouvez le supprimer.

Si vous ne supprimez pas le fichier AGENTS.md, supprimez-en la majeure partie. Le contenu restant doit être court, précis et difficile à découvrir par l’agent dans un temps raisonnable. Dans la plupart des projets, quelques lignes suffisent, surtout si vous utilisez des skills.

Les agents n’ont plus besoin qu’on leur tienne la main

Les premiers agents de programmation ne savaient pas explorer un projet. Les longs fichiers d’instructions avaient donc leur utilité.

Aujourd’hui, les agents font ce qu’un bon développeur ferait dès son premier jour : ils lisent package.json et angular.json, remarquent que vos composants sont standalone et utilisent des signaux, exécutent les tests et reprennent le style du code environnant.

Ils déduisent, et ils le font bien. Leur dire « c’est une application Angular écrite en TypeScript », c’est comme tendre à un développeur senior une fiche indiquant « ceci est un clavier ».

Les deux règles d’or

Pour chaque ligne de votre fichier AGENTS.md, posez-vous deux questions :

1. Diriez-vous cela à un bon développeur ?

Imaginez qu’un développeur compétent commence demain. Vous ne lui diriez pas de « suivre les bonnes pratiques ». En revanche, vous lui diriez : « Ne reprends pas les patterns dans legacy/ : nous sommes en train de migrer ce code. » Ou encore : « Utilise le port 8001 pour tester l’application, car elle tourne derrière un proxy maison. » Si vous ne le diriez pas à un bon développeur, ne le dites pas à l’agent.

2. L’agent peut-il le découvrir tout seul sans que ça coute trop cher ?

La structure des dossiers, la version d’Angular, les scripts npm et les règles de formatage figurent dans le code et la configuration. Les consigner à nouveau crée une deuxième source de vérité, qui finira par diverger de la première. Si l’agent peut le déduire facilement, ne l’incluez pas.

Votre fichier actuel fait probablement plus de mal que de bien

Voici un fichier AGENTS.md tiré d’un vrai projet Angular. Je l’ai raccourci, car l’original fait plus de 80 lignes :

1# Instructions
2
3- This project is for internal use of XYZ company.
4
5## Angular Best Practices
6
7- **Use Angular CLI**: Use Angular CLI for creating components, services,
8  and other files.
9
10ng new component my-component --standalone
11ng generate service my-service
12ng generate interface my-interface
13
14## Project Folder Structure
15
16### Root Directory
17
18- Keep a **flat and predictable** structure.
19- **angular-project/**: This is the root directory of your Angular project.
20
21### Source Directory
22
23- **src/**: Contains the source code of your application.
24- **app/**: Main application folder.
25- **core/**: Contains singleton services [...]
26- **shared/**: Contains shared components, directives, and pipes.
27  [... 30 more lines of folders ...]
28- **polyfills.ts**: Polyfills for browser compatibility.
29
30### Other Files
31
32- **.postcssrc.json**: Postcss configuration file for Tailwindcss >= 4.
33- **angular.json**: Configuration file for Angular CLI.
34- **package.json**: NPM package configuration file.
35- **tsconfig.json**: TypeScript configuration file.
36
37## Angular Coding Guidelines
38
39- **Nested feature**: if the feature to create is a nested feature, create
40  the folder under the parent folder and place the new feature inside it.
41- **Standalone Components**: Utilize standalone components to simplify
42  module management and improve code clarity.
43- **Standalone Components**: Use `standalone: true` in component
44  configurations to leverage Angular's standalone component architecture.
45- ...
46
47## Tailwind Coding Guidelines
48
49- **.html**: Use Tailwind's utility classes directly in your HTML files.

Quelqu’un a manifestement consacré du temps à ce fichier. Voici ce que cela coûte.

Cela gaspille du contexte

Le fichier est chargé à chaque session et pour chaque tâche, ce qui consomme inutilement des tokens et encombre la fenêtre de contexte.

Quarante lignes d’arborescence de dossiers et un rappel que package.json est le « fichier de configuration du paquet NPM » prennent de la place au détriment de la tâche elle-même. L’agent peut lancer ls, sait ce qu’est package.json et se fiche de savoir que votre entreprise s’appelle XYZ.

Il contient des erreurs et contredit le code

ng new crée un nouveau workspace Angular, pas un composant.

Les projets Angular récents n’ont pas de fichier polyfills.ts.

Les composants sont standalone par défaut depuis Angular 19 : standalone: true n’est donc que du bruit que l’agent ajoutera consciencieusement partout.

C’est un template générique, pas une description de votre projet

« Gardez une structure plate et prévisible. » « Ceci est le répertoire racine de votre projet Angular. » Ces lignes conviendraient à n’importe quel projet Angular sur la planète : elles ne disent donc rien à l’agent sur le vôtre.

Les fichiers de ce genre sont souvent copiés depuis un article de blog ou générés une fois pour toutes. Et ça se voit, notamment au dossier angular-project, qui en réalité n’existe même pas.

L’agent connaît déjà les conseils génériques sur Angular. Ce qu’il ne peut pas savoir, c’est ce qui est propre à votre base de code et c’est précisément ce qui manque.

Une seule ligne mérite peut-être d’être gardée dans cet exemple

Passez ce fichier au crible des deux règles. Les commandes CLI, l’arborescence des dossiers, les fichiers de configuration et les composants standalone sont tous visibles dans le code. « Ce projet est destiné à un usage interne » ne change rien à la manière d’écrire le code. Que reste-t-il ? Peut-être la ligne sur Tailwind CSS, mais elle doit être reformulée. Par exemple :

1Prefer Tailwind utility classes over custom SCSS.

C’est un choix d’équipe que l’agent ne peut pas deviner dans un projet qui utilise les deux styles.

Que faut-il mettre dans AGENTS.md ?

Uniquement ce que l’agent ne peut pas deviner ou ce qui couterait cher à l’agent de découvrir par lui-même. Par exemple, une convention propre à votre projet :

1### Route inputs
2
3Give each router-bound input a one-line JSDoc: `/** <what it is>, from the route|query params */`.
4
5```ts
6/** The year id, from the query params */
7readonly year = input.required<string>();
8```

Cette règle est utile, car avec withComponentInputBinding, un input lié au routeur ressemble à n’importe quel autre input : rien n’indique que sa valeur vient de l’URL plutôt que du composant parent.

D’autres consignes peuvent aussi mériter leur place, par exemple celles qui signalent les dossiers à ne pas prendre pour modèle (« ne reproduis pas les patterns de legacy/, en cours de migration ») ou les particularités de l’environnement local (ng serve démarre sur le port 4200, mais il faut tester l’application sur le port 8001, derrière le proxy maison).

Les interdits sont souvent très utiles à ajouter au fichier AGENTS.md, car l’agent ne peut pas les deviner et une erreur coûte cher. Par exemple : « ne modifie pas les migrations Liquibase déjà appliquées, ne touche pas aux fichiers générés ».

Enfin, une règle n’est pas éternelle. Après quelques commits, les exemples présents dans le code pourraient suffire : par mimétisme, l’agent ajoutera très probablement ces commentaires JSDoc de lui-même. La règle sera alors devenue découvrable, et vous pourrez la supprimer. Un bon AGENTS.md maigrit avec le temps.

Conclusion

Passez votre AGENTS.md en revue, ligne par ligne. Si vous ne diriez pas cela à un bon développeur, ou si l’agent peut le découvrir tout seul sans consommer trop de tokens, supprimez-le.

Il vous restera peut-être quelques lignes. Probablement aucune. Dans les deux cas, c’est mieux qu’un fichier qui ment.