context beats the prompt

Same ritual at just about every team that picks up AI. I’ve watched it play out over and over. They polish their prompts. Someone lands on a phrasing that gets better answers, someone else starts hoarding templates, and a few weeks in the whole team’s sitting on this impressive stack of instructions. And every answer still comes out generic.

And the reason? Simple. The model still knows nothing about the company. Not how the quoting runs, not which customer gets which exception, not what decision got reversed last month or why. Every session starts from zero. Look, you can hand an intern the perfect brief on day one. They’re still an intern on day one.

So I flip it around. Stop asking smarter, start telling better. Call it context engineering instead of prompt engineering. And that’s not wordplay. It’s the difference between a tool you have to re-explain your whole job to every single time, and a colleague who already knows.

And a colleague who already knows looks like this. I’m working on a project for a client, mid-implementation, and I just ask the model, “can you fill the tenant with demo data?” Purely that. And it’s got all the context of that client, all the context of the project, it knows exactly what I want to demo, because it’s already written down. I can say what the planning is, which training comes first. So instead of writing out a whole prompt going “okay, fill in this demo data, it’s about this client, it covers this, and it’s for this training”, it just fills the whole system with all the data I need.

That only works because the context is already sitting there. Written down, in a form the model reads before it does a thing. Which is the actual craft. So let me get into how you build it.

documentation for machines

The core of how I work is documentation. Not for people, though. For machines. Concretely: a CLAUDE.md or AGENTS.md in the root of every project, and under it a living wiki of markdown files that describes the whole thing.

That first file is well on its way to becoming a standard. More than 60,000 repositories have an AGENTS.md now, and over twenty tools read it automatically before they do a thing. It’s plain text. No schema, no required fields. And what’s in it decides how every AI agent behaves in your project: which commands it runs, what it leaves alone, which conventions hold.

So what is that file, really? It’s where you write your most important instructions to the model. Can be a personal project, can be org-wide, and honestly you end up with both: one CLAUDE.md that lives inside the project, and one that sits on top of the whole organization. A little file the model always reads. Every prompt, it skims it and takes the instructions along. A kind of golden instructions. Mine says things like: always humanise the text, no em-dashes, no arrows. That’s a real rule I’ve got, because I want my writing to read human, not the same AI patterns you see in nine out of ten others. Or: check facts properly, make no assumptions. Keeps the model’s creativity inside the fence.

The wiki underneath is the pattern Andrej Karpathy named the LLM Wiki, back in April 2026. Think less search engine plowing through raw documents on every question, more a lasting set of markdown pages that sits between you and your sources. Every time a new source comes in, the AI reads it, pulls out what matters, folds that into the pages you already have. Contradictions get flagged, summaries get tighter. Connections nobody typed out get drawn. You compile the knowledge once and keep it current, instead of re-deriving it on every single question.

three layers, strictly separated

I structure project knowledge the same way every single time, whatever the project is.

Layer one: the raw sources. Notes, transcripts, exports, articles. This layer is sacred. The AI reads from it and never, ever changes a thing. It’s the source of truth.

Layer two: the wiki. A folder of markdown pages the AI writes and keeps up itself. One page per customer, one per concept, an index that sums up each page in a single line, a running log of everything it’s chewed through. This layer belongs to the AI, all of it. I read, the AI writes.

Layer three: the schema. One instruction file that lays down how the wiki gets built, which conventions apply, and what has to happen when a new source, a question, or a cleanup comes in. That one file? It’s the difference between a disciplined wiki keeper and a random chatbot.

And that separation isn’t cosmetic. Who gets to write where, what counts as the source of truth, how an agent finds its way through hundreds of pages. Those are architecture questions, not writing ones. The index says it best: on every question the AI reads the index first, then dives straight to the right pages. That holds up into the hundreds of pages. No embeddings, no separate search stack. And it works because the structure is right. Has nothing to do with how nicely the text reads.

short beats complete

And the proof this is an architecture discipline, and not some writing trick? It comes from a corner that catches people off guard. ETH Zurich went and tested AGENTS.md files across 138 repositories, 5,694 pull requests. Big sample. And the result stings: most of those files make the agent slower, pricier, and no better at the job. An auto-generated one drops the success rate by about 3 percent and shoves costs up by more than 20 percent. Hand-write it and you claw back all of, what, 4 percent. That’s it.

The why of it is sobering. The agent follows the instructions faithfully. More tests, more checks, more files to read. Thorough, sure, but not always what the task actually needed. And a codebase overview doesn’t help, demonstrably. The agent works that structure out on its own.

So there are hard rules. Stay under 150 to 300 lines, because every line rides along in every session. Write the commands out word for word instead of describing them. One good example beats three paragraphs of explanation. Spell out the boundaries: what the agent never touches. And above all, leave out whatever the agent can find on its own.

I learned that one the hard way, mind you. Got my own CLAUDE.md wrong once. Made it way too big, way too much context. Because here’s the trap: if you keep updating it, treat that as a choice. You’re in a coding project, you want to keep enriching the thing with every new gotcha, every bit of knowledge you pick up. I’d advise against it. I did exactly that, and it ended up 600 lines long. And you can imagine, that eats a load of context, which means a load of tokens, every single session. So keep your CLAUDE.md to 200 lines max. Lower if you can. Under 200 is the line I hold now.

More text isn’t more context. Context engineering is as much about what you leave out as what you put in. Which is exactly what architecture is.

what it delivers, and what it doesn’t yet

In practice the rhythm is simple. Every work session ends with the same instruction: update the wiki with what we learned today. Five minutes. No separate documentation time carved out anywhere. Next session, every agent, whatever the tool, starts with that knowledge already in hand. The context outlives the tool.

The payoff’s in the repetition. Hit a similar process at a second customer, and I don’t have to re-explain my project history. The wiki holds the pattern, the AI carries it over to the new context, and it catches differences I’d long since forgotten.

To be clear, right now this is mostly a personal pattern, and Karpathy frames it that way himself. Writing into the same wiki with a whole team at once, without conflicts, is the thing I haven’t cracked yet. Version control catches part of it. But the real answer? I don’t have it yet.

What sticks with me most is how old this idea actually is. Back in 1945, Vannevar Bush described his Memex: a personal, curated store of knowledge where the links between documents matter as much as the documents themselves. The part Bush never cracked was who keeps it up. People give up on knowledge bases because the upkeep grows faster than the payoff. An LLM doesn’t get bored, doesn’t forget a cross-reference, updates fifteen pages in a single pass. So the thing that let every knowledge base rot for eighty years didn’t get fixed because we finally got disciplined. It got fixed because the upkeep landed with the one employee who never tires of it.