Why context beats the prompt.
I am on Project1. Add a cache on the calls to the external API, like the one on Project2. Keep my usual Symfony preferences. When it is done: write an ADR, add a counter-audit with Claude to my personal todo, update the Jira ticket, and email my CTO a summary.
It names everything and explains nothing. And the agent knows where to look.
Go to /Users/clement/Sites/Project1 — Symfony 7 / PHP 8.3 app, Doctrine. I am the tech lead. Talk to me in French, code and comments in English. Add a cache on the calls to the external API (outgoing HTTP client). The reference pattern is in /Users/clement/Sites/Project2, under src/Service/Cache/ — reuse it exactly as it is. Style: simple monolith, no DDD/CQRS without a real need, PSR-12. Read the Makefile BEFORE any command (make test, make qa). No useless abstraction. Tests: PHPUnit, add coverage, run make test and fix until it is green. Perf: keep the HTTP cache, profile with Blackfire if you touch the hot path. Create an ADR in docs/adr/, in the format of the existing ones (see 0006), status "accepted". Add a task to ~/knowledge/todo.md, Project1 section, with the date. My CTO and their contact details are in ~/knowledge/people/contacts.md. Create the Jira ticket in project "P1", column In Progress, label perf. Email them a summary: recap, risks, validations launched. Security: no hardcoded secret, respect .env.local, do not touch the keys. Git: feature/cache branch, conventional commits.
Same intent. Nobody retypes that wall of text every morning.
On every new session the agent forgets everything: the project, the stack, the conventions, the contacts. It all has to be explained again.
We have been documenting in Markdown for years. Handy: it is exactly the format an agent reads and applies best.
Projet1/ ├── src/ ├── docs/ │ ├── caching.md │ ├── architecture.md │ └── conventions.md ├── AGENTS.md └── Makefile
An old idea: keep your notes, your decisions and your references in one place, so you can find them again and reuse them.
Concept: PKM · Tiago Forte, “Building a Second Brain”
A Markdown file. The rules the agent reads before touching the code.
Projet1/AGENTS.md
## Stack - Symfony 7, PHP 8.3, Doctrine, Twig, PostgreSQL. ## Conventions - Thin controllers, logic in autowired services. - Doctrine migrations; never schema:update. ## Quality - Everything goes through the Makefile: make test, make stan. - PHPStan level 8, php-cs-fixer. Zero warnings.
Every tool already has its file there, at a known path.
~/.claude/CLAUDE.md # Claude Code ~/.codex/AGENTS.md # Codex ~/.gemini/GEMINI.md # Gemini
~/.agents/AGENTS.md # emerging standard
A single file to get the same rules on every project.
~/AGENTS.md
## Me - Clément, tech lead. Answer me in French. ## By default, everywhere - Write code and docs in English. - PHP/Symfony, simple monolith. PHPStan level 4 minimum. - Never git push without my GO.
One single file, symlinked wherever each agent expects it.
$ ln -s ~/AGENTS.md ~/.claude/CLAUDE.md $ ln -s ~/AGENTS.md ~/.codex/AGENTS.md $ ln -s ~/AGENTS.md ~/.gemini/GEMINI.md
The agent reads both and concatenates them: the global one sets the defaults, the local one steers the project.
~/AGENTS.md # global · everywhere — English, PHPStan 4 Project1/AGENTS.md # local · this project — French, PHPStan 8
Too long, too hard to maintain — the agent itself can no longer follow that many lines.
3210 - My name is Clément. I like Symfony and cookies. 3211 - Always answer in French. 3212 - Never commit on a Friday evening. 3213 - Remind me to drink water. 3214 ⌃ … and 3,209 more lines above
Andrej Karpathy described exactly this case: a Markdown base the agent builds and maintains, instead of one giant file.
~/knowledge/ ├── projects/ # index.md = the map of my repos ├── tech/ # symfony-style · agentic-tools · review ├── people/ # contacts (“who is my CTO?”) ├── index.md # THE map, read first └── log.md # what changed, dated
The AGENTS.md and the knowledge base are already centralised. The same reflex applies to skills.
~/.aider/ ~/.claude/ ~/.codeium/ ~/.codex/ ~/.continue/ ~/.cursor/ ~/.gemini/ ~/.windsurf/ ~/.config/opencode/ ~/.config/amp/
The standard already exists — XDG Base Directory. My agent context lives there, like any other Unix tool.
$ ls ~/.config agent-context amp git htop iterm2 opencode uv
➜ ls ~/.config/agent-context/skills # the single source handoff/ todo/ update-context/ low-profile-review/ … ➜ ls -la ~/.{claude,codex,agents}/skills # exposed everywhere ~/.claude/skills -> ~/.config/agent-context/skills # Claude Code ~/.codex/skills -> ~/.config/agent-context/skills # Codex ~/.agents/skills -> ~/.config/agent-context/skills # cross-agent convention
I am on Project1. Add a cache on the calls to the external API, like the one on Project2. Keep my usual Symfony preferences. When it is done: write an ADR, add a counter-audit with Claude to my personal todo, update the Jira ticket, and email my CTO a summary.
Short. And yet the agent knows how to do all of it. How?
I am on Project1. Add a cache, like on Project2. Keep my Symfony preferences. Write an ADR, a counter-audit todo, update the Jira ticket, email my CTO.
When the base really grows, other tools take over:
AGENTS.mdknowledge/index.mdSources: Karpathy “LLM Wiki” · Forte “Building a Second Brain” · ~/knowledge
Hooks can, among other things, load context when a session starts — here, the index of the base.
"SessionStart": [{ "matcher": "startup|resume|clear|compact", "hooks": [{ "command": "… hooks/load_knowledge.py" }] }] # on startup, the agent receives: ✓ Personal knowledge index (auto-loaded from ~/knowledge/index.md)
Clément Bertillon · SensioLabs