Docs in Code

Bad mental models of your codebase are one of the biggest problems with coding agents today. What can we do about that?

One idea is to just tell the model how your codebase works. Distill those mental models into concise text explanations and feed them into the model. Anyone working with coding agents regularly will know that this works pretty well on models like Claude Opus 4.5 and GPT-5.2. They might struggle to figure out what your code is supposed to do by reading it, but if you spend some time explaining how everything fits together they can usually get it.

As a wise woman once said: “Ain’t nobody got time for that!” My fingers are tired already.

We need a way to explain how the system works once, then re-use that explanation. Wait, isn’t this a thing we already do for humans? It’s called documentation! We’ll make a bunch of markdown files explaining how the various high-level aspects of our system work, and have the agent read those.

There are a few problems with that:

1. The agent doesn’t update the markdown files. No automated tests will sound an alarm if they aren’t updated, so we’re relying on the agent remembering. Agents love to jump the gun and declare a victory at the first sign of progress. The agent is not going to remember to update the documentation and, honestly, neither am I.
2. The agent doesn’t read the markdown files. Most of the time it isn’t even aware they exist. It might pick them up in an initial exploration of the codebase, but it’s not going to search for relevant docs every time it opens a new file.

Wouldn’t it be great if we could just inject the relevant documentation into the agent’s context?

Actually, we can do that. It’s called AGENTS.md (or CLAUDE.md). The entire content of your AGENTS.md file is injected into the agent’s context verbatim (perhaps with some string replacements) every conversation. This has a couple of its own issues, though:

1. Everything gets injected. Every line adds to your agent’s cognitive load. Add enough and you’ll start making a dent in your context budget.
2. It gets buried by newer context. Since AGENTS.md is static content, it is injected at the start of the prompt for caching purposes. New messages, files, and tool outputs are appended to the context after it. This makes it far less salient to the LLM, which has a bias towards things at the end of the context.

We can do better.

Just write the documentation in the files, alongside the code itself. Ideally in docstrings, doc comments, or some similar mechanism.

We usually don’t do this because it doesn’t match how humans consume codebases. Generally, we first build a mental model of how a system works at a high level via documentation or a verbal rundown, then zoom in on the code itself to see how that model is implemented. LLM agents work differently; they are given a rough overview of the codebase by AGENTS.md, then get stuck in reading code files and snippets, then infer the model of the system from those snippets.

For a human coder, this would be laborious to maintain, but coding agents throw themselves at the task enthusiastically.

With documentation alongside code:

• Only docs relevant to the content being read are added to the context.
• Docs relevant to the current content are always at the front of the context.
• Agents remember to update them because they do so in the same edit tool call that edits the code.
• Agents actually read the documentation. They have no choice, it’s right there!
• Finding docs is easy, just look for the definition.
• It makes sure you understand the codebase. When you’re reviewing the code, the high-level purpose of every element of the codebase is plainly stated. If either the agent or yourself has a misunderstanding, it’s plain as day.

This is something I’ve been trialing lately in FreedomRPG, and it seems like a very promising approach. Expect a follow-up with more practical details and more objective results.

- omegastick