I keep more than one coding agent on hand. Claude Code does most of the work on this blog. When I want a second pass on a tricky change, or just a different temperament looking at it, I’ll run Codex over the same repo. They’re both good. They’re both, underneath, the same shape of tool: a model wrapped in a loop that reads files, runs commands, and edits code on my behalf.
The friction showed up the first time I pointed Codex at this project. It immediately wanted to know the things Claude Code already knew. How the site builds. How I deploy it. The voice rules for a post. The fact that I never hand-number headings because the CSS does it for me. All of that lives in a file Claude Code reads at the start of every session. Codex doesn’t read that file. It reads its own.
The part of the agent you actually control
It’s worth a short detour on why that file earns so much weight. There’s a useful way to think about these tools: the model is maybe five percent of what makes a coding agent work. The other ninety-five is the harness around it. The loop that feeds it context, the tools it can call, the sandbox it runs in, the logic that decides when it’s done. You don’t get to change most of that. It’s the agent vendor’s job, and they’re the ones iterating on it.
The one piece of the harness you fully own is the project brief — the file the agent loads before it touches anything. It’s where the agent learns what it can’t infer from the code. That a deploy needs two specific environment variables. That “TL;DR” on this site is a deliberately styled card and not an inline note. That the writing voice avoids certain tics. Get that brief right and a stock agent does good work. Leave it empty and even the most capable model spends your time rediscovering what you already knew.
So the brief is the cheap leverage. Which is exactly why having two agents that each read a different one started to bother me.
Two files drift, and a drifted brief is worse than none
Claude Code reads CLAUDE.md. Codex reads AGENTS.md. Same idea, different filename, and that’s becoming the normal state of affairs as more of these tools show up. The obvious move is to keep both files: write the project’s conventions in each, and keep them roughly in step.
I’ve maintained two copies of the same thing by hand before. It never holds. You update one in a hurry and forget the other. A week later the two briefs quietly disagree, and now an agent is confidently working from instructions you abandoned. That’s the failure mode that worries me, because a stale brief is worse than no brief at all. No brief makes the agent ask. A wrong one makes it sure.
So I didn’t want two briefs kept in sync. I wanted one brief, read by both.
One source of truth, and a symlink
The fix is dull, which is usually how I know it’s the right one. CLAUDE.md stays the single source of truth — it already held everything. AGENTS.md becomes a symlink pointing at it. Codex opens AGENTS.md, the filesystem hands it CLAUDE.md, and both agents read the same bytes. There’s no syncing step because there’s no longer a second file to sync. Editing one edits the other, because they are the same one.
ln -s CLAUDE.md AGENTS.mdI weighed the alternatives and didn’t like them. Copying the content is the drift I was trying to escape, just with extra steps. Making AGENTS.md a short pointer that says “go read CLAUDE.md” relies on the agent choosing to follow the breadcrumb, and leaves it with less in context when it doesn’t bother. The symlink removes the choice. Whatever the canonical brief says, both agents get all of it, every time, with no discipline required from me.
The one rule I had to write down for my future self: edit the real file, never the link. If I ever delete the symlink and replace it with a real file, I’ve quietly reintroduced the exact drift this was meant to kill. So that note now lives in the project’s running list of lessons, which is the other half of how I keep this setup from rotting.
Most of the brief was never agent-specific
Here’s the thing that made the symlink obvious in hindsight. Almost nothing in that file is about which agent reads it. How the site builds, how it deploys, the writing voice, the gotcha about heading numbers — that’s all just true about the project. It’s knowledge, and knowledge doesn’t care what’s reading it. When I went looking, only two lines leaned on one specific tool: a mention of a Claude Code command that Codex doesn’t have. I softened those into plain language and the whole brief became portable.
That portability is the part I’ll carry to the next tool, whatever it ends up being called. If the project brief is mostly facts about the project, then the right number of copies to keep is one. The agents will keep changing. The honest description of how this thing actually works should outlast all of them.
