Pourquoi le contexte bat le prompt.
Je suis sur Projet1. Ajoute un cache sur les appels à l'API externe, comme sur Projet2. Garde mes préférences Symfony habituelles. Quand c'est fait : fais une ADR, rajoute dans ma todo perso de faire un contre-audit avec Claude, mets à jour le ticket Jira, et envoie un mail à mon CTO pour une synthèse.
Il nomme tout, n'explique rien. Et l'agent sait où aller.
Va dans /Users/clement/Sites/Projet1 — app Symfony 7 / PHP 8.3, Doctrine. Je suis lead technique. Parle-moi en français, code et commentaires en anglais. Ajoute un cache sur les appels à l'API externe (client HTTP sortant). Le pattern de référence est dans /Users/clement/Sites/Projet2, sous src/Service/Cache/ — reprends-le à l'identique. Style : monolithe simple, pas de DDD/CQRS sans besoin réel, PSR-12. Lis le Makefile AVANT toute commande (make test, make qa). Pas d'abstraction inutile. Tests : PHPUnit, ajoute la couverture, lance make test et corrige jusqu'au vert. Perf : garde le HTTP cache, profile avec Blackfire si tu touches au chemin chaud. Crée une ADR dans docs/adr/, au format des existantes (cf. 0006), statut « accepted ». Ajoute une tâche dans ~/knowledge/todo.md, section Projet1, avec la date. Mon CTO et ses coordonnées sont dans ~/knowledge/people/contacts.md. Crée le ticket Jira projet « P1 », colonne In Progress, label perf. Envoie-lui un mail de synthèse : résumé, risques, validations lancées. Sécurité : aucun secret en dur, respecte .env.local, ne touche pas aux clés. Git : branche feature/cache, commits conventionnels.
Même intention. Personne ne réécrit ce pavé chaque matin.
À chaque nouvelle session, l'agent oublie tout : le projet, le stack, les conventions, les contacts. Tout est à réexpliquer.
On documente en Markdown depuis des années. Ça tombe bien : c'est le format qu'un agent lit et applique le mieux.
Projet1/ ├── src/ ├── docs/ │ ├── caching.md │ ├── architecture.md │ └── conventions.md ├── AGENTS.md └── Makefile
Un vieux concept : centraliser ses notes, ses décisions et ses références au même endroit, pour les retrouver et les réutiliser.
Concept : PKM · Tiago Forte, « Building a Second Brain »
Un fichier Markdown. Les règles que l'agent lit avant de toucher au code.
Projet1/AGENTS.md
## Stack - Symfony 7, PHP 8.3, Doctrine, Twig, PostgreSQL. ## Conventions - Contrôleurs fins, logique dans des services autowirés. - Migrations Doctrine ; jamais de schema:update. ## Qualité - Tout passe par le Makefile : make test, make stan. - PHPStan niveau 8, php-cs-fixer. Zéro warning.
Chaque outil y a déjà son fichier, à un chemin connu.
~/.claude/CLAUDE.md # Claude Code ~/.codex/AGENTS.md # Codex ~/.gemini/GEMINI.md # Gemini
Un seul fichier pour avoir les mêmes règles sur tous les projets.
~/AGENTS.md
## Moi - Clément, lead technique. Réponds-moi en français. ## Par défaut, partout - Rédige le code et la doc en anglais. - PHP/Symfony, monolithe simple. PHPStan niveau 4 minimum. - Jamais de push git sans mon GO.
Un seul fichier, symlinké là où chaque agent l'attend.
$ ln -s ~/AGENTS.md ~/.claude/CLAUDE.md $ ln -s ~/AGENTS.md ~/.codex/AGENTS.md $ ln -s ~/AGENTS.md ~/.gemini/GEMINI.md
L'agent lit les deux et les concatène : le global pose les défauts, le local ré-oriente le projet.
~/AGENTS.md # global · partout — anglais, PHPStan 4 Projet1/AGENTS.md # local · ce projet — français, PHPStan 8
Trop long, trop dur à maintenir — l'agent ne peut plus suivre autant de lignes.
3210 - Je m'appelle Clément. J'aime Symfony et les cookies. 3211 - Toujours répondre en français. 3212 - Ne jamais committer un vendredi soir. 3213 - Rappelle-moi de boire de l'eau. 3214 ⌃ … et 3 209 lignes au-dessus
Andrej Karpathy a décrit exactement ce cas : une base Markdown que l'agent construit et maintient, au lieu d'un fichier géant.
~/knowledge/ ├── projects/ # index.md = la carte de mes repos ├── tech/ # symfony-style · agentic-tools · review ├── people/ # contacts (« qui est mon CTO ? ») ├── index.md # LA carte, lue en premier └── log.md # ce qui a changé, daté
L'AGENTS.md et la base de connaissances sont déjà centralisés. Le même réflexe vaut pour les skills.
~/.aider/ ~/.claude/ ~/.codeium/ ~/.codex/ ~/.continue/ ~/.cursor/ ~/.gemini/ ~/.windsurf/ ~/.config/opencode/ ~/.config/amp/
Le standard existe déjà — XDG Base Directory. Mon contexte agent vit là, comme n'importe quel outil Unix.
$ ls ~/.config agent-context amp git htop iterm2 opencode uv
➜ ls ~/.config/agent-context/skills # la source unique handoff/ todo/ update-context/ low-profile-review/ … ➜ ls -la ~/.{claude,codex,agents}/skills # exposé partout ~/.claude/skills -> ~/.config/agent-context/skills # Claude Code ~/.codex/skills -> ~/.config/agent-context/skills # Codex ~/.agents/skills -> ~/.config/agent-context/skills # convention cross-agent
Je suis sur Projet1. Ajoute un cache sur les appels à l'API externe, comme sur Projet2. Garde mes préférences Symfony habituelles. Quand c'est fait : fais une ADR, rajoute dans ma todo perso de faire un contre-audit avec Claude, mets à jour le ticket Jira, et envoie un mail à mon CTO pour une synthèse.
Court. Et pourtant l'agent sait tout faire. Comment ?
Je suis sur Projet1. Ajoute un cache, comme sur Projet2. Garde mes préférences Symfony. Fais une ADR, une todo de contre-audit, mets à jour le ticket Jira, envoie un mail à mon CTO.
Quand la base grossit vraiment, d'autres outils prennent le relais :
AGENTS.md au niveau userknowledge/index.mdSources : Karpathy « LLM Wiki » · Forte « Building a Second Brain » · ~/knowledge
Les hooks permettent notamment de charger un contexte au démarrage d'une session — ici, l'index de la base.
"SessionStart": [{ "matcher": "startup|resume|clear|compact", "hooks": [{ "command": "… hooks/load_knowledge.py" }] }] # au démarrage, l'agent reçoit : ✓ Personal knowledge index (auto-loaded from ~/knowledge/index.md)
Clément Bertillon · SensioLabs