Troels Frimodt Rønnow

I open a new Claude Code session. I ask it to refactor the auth flow before the next release. It comes back with a clean, well-structured answer that uses none of my existing helpers, contradicts my session model, and quietly assumes JWTs when I've been on opaque tokens for two years.

The reply isn't wrong. It's disconnected. The model gave me the average answer for "refactor auth flow," because that's all I asked for. I spend twenty minutes pasting in conventions, the actual session shape, and the three constraints I can't violate. Now the answer is useful. Tomorrow I'll do it again.

That loop is where most engineers I talk to are stuck. The instinct is to blame the model — Opus is too cautious, GPT-5.5 is too eager, the new tokeniser is burning context. Switch tools. Try again.

That instinct is wrong. The bottleneck is not the model. It's the workspace.

Prompts are the wrong place to put truth

If you find yourself pasting the same paragraph into a prompt more than twice, you have a design problem, not a prompting problem. You're trying to fit your codebase's truth into the conversation window. That's the worst place for it. It's volatile, unreviewable, and lost the moment the session ends.

The fix is older than AI. Put the truth in files, version it, load it on demand. Andrej Karpathy has been pushing the label context engineering and I think the name is correct, because it draws the line cleanly. Prompt engineering is what you type. Context engineering is what the agent reads before you type. Both AI Maker's context management guide and WhyTryAI's piece on Claude Code and Codex sharing a brain land on the same conclusion from different directions: the file system is the right substrate.

For a working engineer, this means treating your agent like a new contractor who is competent but has never seen your codebase. You wouldn't onboard them by speaking faster. You'd point them at a README, a glossary, an ADR folder, and the conventions doc. Then tell them which task to start on.

That's the whole shape. Two layers.

The two-layer workspace

Layer one is a single routing file at the root. Claude Code reads CLAUDE.md. Codex reads AGENTS.md. Cursor and Cline have their own conventions. Most teams I've seen now keep one canonical file and symlink the rest, or commit all three with identical content.

The routing file is short. Its job is to tell any agent how to behave, where the source of truth lives, and when to consult it. It is not the source of truth itself. The moment your CLAUDE.md grows past about 200 lines, you're abusing it.

Layer two is a folder. Call it context/, foundational/, or .agent/ — the name matters less than the structure. Inside, split the truth by kind of question the agent will face, not by area of the codebase.

For a small team, this is roughly what I'd start with:

your-repo/
  AGENTS.md            # routing: how to work, what to read when
  CLAUDE.md            # symlink to AGENTS.md
  context/
    architecture.md    # services, data flow, why things are split this way
    conventions.md     # naming, error handling, test style, what NOT to do
    glossary.md        # domain terms; the words your PM uses
    constraints.md     # things that look fixable but aren't (legal, infra, legacy)
    current-work.md    # what the team is doing this sprint
    decisions/         # ADRs — one file per non-obvious choice

None of this is theoretical. Most of these files already exist in scattered form across your Notion, your Slack pins, and the heads of two senior engineers. The work is consolidation, not invention.

Why split it at all

The temptation is to dump everything into one big file. Resist it. A monolithic context file drags the whole world into the model's attention, even when the task is a one-line typo fix. Useful information at the wrong moment still degrades the output.

Splitting by intent lets your routing file give instructions like: "Before refactoring code, read conventions.md and any matching decisions/*.md. Before adding a new endpoint, also read architecture.md." The agent loads the slice it needs. The rest stays on disk, ready and silent.

This is the same instinct that produced the gap between package.json and node_modules. You declare what's needed. You don't ship the whole filesystem on every call.

The shared-brain payoff

Once your context is on disk in plain markdown, the agent question becomes uninteresting. Claude Code reads the same files as Codex. Cursor reads them too. If GPT-6 ships next quarter and you want to try it for an afternoon, you don't rebuild your setup. You point it at the same folder.

I run a two-agent loop on the project I'm writing this article inside. Claude Code does the planning and the prose-heavy work. Codex handles the mechanical refactors and runs the tests. The handoff is one sentence ("hand this to Codex") because both agents are reading the same context/ directory. No translation step. No "let me catch you up." The truth is already in the repo.

This is the part that flips the economics. You stop paying for the same context in tokens, over and over, across two providers. You also stop being locked in to whichever agent vendor had the best week. The vendor competes on capability; your workspace stays portable.

The context folder is the new build system

Here's what I think will be obvious in twelve months and is still contested today: the context folder is the new build system.

Teams in 2027 won't be evaluated by how good their prompts are or which agent they pay for. They'll be evaluated by how well their repository teaches an agent to behave. The team with a clean context/, ADRs that explain the why, and a tight routing file will onboard a new agent in an afternoon. The team with everything in their CTO's head will pay for that gap in every single session, forever.

You can push back. The honest counter is that context folders are expensive to maintain, that they rot the moment the codebase changes, and that some senior engineers will hold the context in their heads faster than they can write it down. All of that is real. ADR folders rot in plenty of organisations that already have one.

But the math still favours writing it down. A senior engineer's head doesn't scale to four parallel agents. A markdown file does. And once the context is in version control, it gets the same review pressure as the code — which means it gets corrected when it drifts, instead of silently rotting until somebody notices the agent is making things up.

What to do this week

Don't try to write the whole context/ directory at once. You'll overthink it and ship nothing.

Do this instead. Open the last three Claude Code or Codex sessions where you had to paste in background. Look at what you pasted. That paragraph about how your billing service talks to the auth service? That's architecture.md. The reminder that you don't use exceptions for control flow? conventions.md. The line about not touching the legacy webhook handler because a single customer is grandfathered? constraints.md.

You already have the content. You just keep typing it into the wrong place. Move it once. Then every agent you ever use, including the one that doesn't exist yet, starts the conversation already knowing.

Sources I drew from: