context beats the prompt

I see the same ritual at nearly every team that starts working with AI. People polish their prompts. Someone discovers a phrasing that gives better answers, someone else builds a library of templates, and after a few weeks the team has an impressive collection of instructions. And still every answer comes out generic.

The reason is simple. The model still knows nothing about the company. Not how the quoting process runs, not which customer has which exception, not what decision got reversed last month and why. Every session starts from zero. You can hand an intern the perfect brief on their first day; they’re still an intern on their first day.

My reversal: stop asking smarter, start telling better. Not prompt engineering but context engineering. That’s not wordplay. It’s the difference between a tool you have to re-explain your work to every single time, and a colleague who already knows.

documentation for machines

The core of how I work is documentation that isn’t written for people but for machines. Concretely: a CLAUDE.md or AGENTS.md in the root of every project, and underneath it a living wiki of markdown files that describes the project.

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

The wiki underneath is the pattern Andrej Karpathy named the LLM Wiki in April 2026. Not a search engine that plows through raw documents on every question, but a persistent set of markdown pages that sits between you and your sources. With each new source the AI reads it, pulls out the essence, and folds that into the existing pages. Contradictions get flagged, summaries get sharper, connections get drawn. Knowledge is compiled once and then kept current, not re-derived on every question.

three layers, strictly separated

How I structure project knowledge is always the same, whatever the project.

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

Layer two: the wiki. A folder of markdown pages the AI writes and maintains itself. One page per customer, one page per concept, an index that sums up each page in a single line, a chronological log of everything that’s been processed. This layer belongs entirely to the AI. I read, the AI writes.

Layer three: the schema. A single instruction file that lays down how the wiki is built, which conventions apply, and what has to happen when a new source, a question, or a cleanup comes along. This one file is the difference between a disciplined wiki keeper and a random chatbot.

That separation isn’t cosmetic. Who’s allowed to write where, what’s the source of truth, how does an agent find its way through hundreds of pages. Those are architecture questions, not writing questions. The index is the best example of this: on every question the AI reads the index first, then dives straight into the right pages. That holds up into the hundreds of pages, without embeddings and without a separate search stack. Not because the text reads so nicely, but because the structure is right.

short beats complete

The proof that this is an architecture discipline and not a writing trick comes from a corner that surprises a lot of people. ETH Zurich tested AGENTS.md files across 138 repositories and 5,694 pull requests. The outcome: most of those files make the agent slower and more expensive, not better. An auto-generated file lowers the success rate by 3 percent on average and pushes costs up by more than 20 percent. Even a hand-written file only buys you 4 percent.

The explanation is sobering: the agent follows the instructions faithfully. More tests, more checks, more files to read. Thorough, but not necessarily what the task needed. And a codebase overview demonstrably doesn’t help; the agent works out that structure on its own.

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

More text is not more context. Context engineering is just as much deciding what stays out as what goes in. That’s 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. The next session, every agent, whatever the tool, starts with that knowledge. The context outlives the tool.

The payoff is in the repetition. When I run into a similar process at a second customer, I don’t have to re-explain my project history. The wiki holds the pattern, the AI applies it to the new context, and spots differences I’d long forgotten.

Fair is fair: at this stage this is mostly a personal pattern, and Karpathy frames it that way himself too. Writing into the same wiki with a whole team at once, without conflicts, is something I haven’t solved yet. Version control catches part of it, but I don’t have the real answer yet.

What occupies me most is how old this idea actually is. In 1945 Vannevar Bush described his Memex: a personal, curated knowledge store where the connections between documents are as valuable as the documents themselves. The part Bush never solved was who does the upkeep. People give up on knowledge bases because the maintenance load grows faster than the value. An LLM doesn’t get bored, doesn’t forget a cross-reference, and updates fifteen pages in one pass. The problem that let every knowledge base rot for eighty years wasn’t solved because we got more disciplined, but because the upkeep landed with the one employee who never gets tired of it.