Le fichier d'instructions qui pilote ton agent

Le concept : un fichier, un agent pilote

Quand tu ouvres un projet avec un coding agent (Claude Code, Cursor, Windsurf, Codex, Gemini CLI...), la premiere chose qu'il fait, c'est chercher un fichier d'instructions a la racine. Ce fichier lui dit qui il est, comment coder, et quelles regles suivre.

Sans ce fichier, l'agent improvise. Avec, il devient previsible.

Quel fichier pour quel outil?

Outil	Fichier	Format
Claude Code	`CLAUDE.md`	Markdown
Cursor	`.cursorrules` ou `.cursor/rules/`	Texte / Markdown
Windsurf	`.windsurfrules`	Markdown
Codex (OpenAI)	`AGENTS.md` ou `CODEX.md`	Markdown
Gemini CLI	`GEMINI.md`	Markdown
Aider	`.aider.conf.yml` + conventions file	YAML + Markdown
Cline	`.clinerules`	Markdown
Amp	`.amp/instructions.md`	Markdown

Le format varie, mais le principe est identique : du markdown que l'agent injecte dans son contexte avant chaque interaction.

Structure universelle

Peu importe l'outil, un bon fichier d'instructions couvre ces sections :

1. Identite du projet

Dis a l'agent ce qu'il construit. Nom du projet, stack technique, objectif. L'agent a besoin de contexte pour prendre les bonnes decisions.

# Mon Projet

Application web pour [description].
Stack : HTML + Tailwind CSS, deploye sur Cloudflare Pages.
Langue du code : anglais. Communication : francais.

2. Conventions techniques

C'est la section la plus importante. Sans elle, chaque agent va coder a sa facon.

Style de code — tabs vs spaces, nommage des variables, structure des fichiers
Stack specifique — versions, librairies autorisees, ce qui est interdit
Patterns — comment structurer les composants, ou mettre la logique, conventions de nommage

## Conventions

- Tailwind CSS v4, Play CDN en dev, CLI en production
- Zero framework UI, zero build step en dev
- Images en WebP, < 150 KB, chemins relatifs
- Noms de fichiers en anglais, kebab-case

3. Regles strictes

Les trucs qui ne sont jamais negociables. Mets-les en gras ou en majuscules — les modeles y font attention.

## Regles

- **NE JAMAIS** committer des fichiers .env ou credentials
- **NE JAMAIS** utiliser de framework si du HTML natif suffit
- **TOUJOURS** tester sur mobile avant de considerer termine
- Reponses courtes et directes — pas de bavardage

4. Structure du projet

Un arbre de fichiers aide l'agent a naviguer sans explorer a l'aveugle. Ca reduit les hallucinations et accelere les reponses.

## Structure

```
mon-projet/
├── index.html
├── a-propos.html
├── assets/
│   ├── logo/
│   └── hero/
├── articles/
└── CLAUDE.md
```

5. Workflow / Pipeline

Si ton projet a un flow de travail specifique (build, deploy, revue), documente-le. L'agent peut alors executer des etapes dans l'ordre.

## Pipeline

1. Editer le HTML
2. Tester localement (live server)
3. Build Tailwind CSS (npx @tailwindcss/cli)
4. Deploy via git push (Cloudflare Pages)

Conseils cross-model

Ces principes fonctionnent avec tous les modeles (Claude, GPT, Gemini, Llama, etc.) :

Sois explicite. "Code propre" ne veut rien dire. "Fonctions de moins de 20 lignes, noms descriptifs, zero commentaire sauf logique non-evidente" — ca, c'est clair.
Utilise des exemples. Un bloc de code d'exemple vaut 50 mots d'explication.
Mets les regles critiques en haut. Le debut du fichier a plus de poids dans le contexte du modele.
Evite les contradictions. Si tu dis "zero framework" a un endroit et "utilise React" a un autre, l'agent va halluciner.
Garde ca court. Un fichier de 200 lignes focusees bat un fichier de 2000 lignes dilue. Le contexte est limite — chaque ligne doit meriter sa place.
Versionne-le. Ton fichier d'instructions evolue avec le projet. Git track les changements — c'est la memoire de tes decisions.

Multi-fichiers : le pattern .skills/

Quand ton fichier principal devient trop long, split-le. Claude Code supporte un dossier .skills/ avec des fichiers markdown referencables. D'autres outils supportent des patterns similaires :

Cursor : dossier .cursor/rules/ avec des fichiers .mdc individuels
Codex : AGENTS.md dans chaque sous-dossier (heritage)
Cline : .clinerules principal + fichiers de contexte references

L'idee est la meme : un fichier principal leger qui pointe vers des fichiers specialises. Ca garde le contexte pertinent sans le noyer.

## Skills (voir .skills/)

- `.skills/build-html.md` — comment construire une page
- `.skills/styleguide.md` — palette, fonts, conventions visuelles
- `.skills/production-build.md` — pipeline Tailwind CLI

Portabilite entre outils

Si tu travailles avec plusieurs outils (ex: Claude Code en terminal + Cursor dans l'IDE), tu peux maintenir un fichier principal et creer des symlinks ou des copies :

# Terminal
cp CLAUDE.md .cursorrules
# Ou, si tu veux un seul fichier source :
ln -s CLAUDE.md .cursorrules

Le contenu est identique — c'est du markdown. Seul le nom de fichier change selon l'outil.

Anti-patterns

Trop de regles. Si ton fichier fait 3000 lignes, l'agent va en ignorer la moitie. Priorise.
Regles vagues. "Ecris du bon code" ne sert a rien. Sois precis.
Copier-coller sans adapter. Le CLAUDE.md de quelqu'un d'autre ne marche pas pour ton projet. Adapte-le.
Ne jamais le mettre a jour. Ton projet change. Ton fichier d'instructions doit suivre.
Cacher des instructions dans des commentaires HTML/code. Mets tout dans le fichier markdown — c'est fait pour ca.

Resume

Le fichier d'instructions est le programme de ton agent. C'est le seul fichier qui transforme un LLM generique en un collaborateur qui connait ton projet, tes conventions et tes limites.

Commence avec 50 lignes. Itere a chaque session. En une semaine, tu auras un fichier qui rend ton agent previsible — quel que soit le modele derriere.

Cet article fait partie des ressources open source d'Intelligence Locale. On build en public depuis Cowansville, Quebec.