The repo that explains itself to an agent

What you end up with

The index file is a root file with less than 20 lines, we've added some pointers instead of writing more. The actual content is available in separate documents, they wait in peace until somebody needs them. A pointer file only for the harness that needs one — out of the six we've probed, that was only Claude Code, which doesn't find an AGENTS.md in the root of the repo on its own. Also, the clone-drill script, a test that runs the repo against a fresh clone rather than against our local working copy.

Not implemented: skills, hooks or MCP servers. These are other topics, it's good to have them but they don't help if a new person can't run tests on their first day here.

It took us around half an hour, 50% of which was spent on removing already existing things.

The reader isn't you

Your setup works, and that's the problem, because the context that comes with the repo is indistinguishable from the context that comes with your machine. The repo contains everything git stores (the source code) but not these:

• the conversation we had about deploying

• the instructions file in your home directory

• your shell history

• the configuration you've set up to tell the model what to choose

If you clone the repo, none of this is there. Also, the way your agent differs from your colleague's agent is that it doesn't have any of these.

We've checked six harnesses and two didn't find the AGENTS.md in the root of the repo even though we had one — for Claude Code we needed to create a separate pointer file for it and for Antigravity CLI it ignored it entirely.

It's not only about "less context", it's also about the fact that if sth is there, doesn't mean it will find it. We've created a repo with a real document in it that contains an actual answer (that you run make unstick-staging to deploy to staging) and then asked our agent in this directory what to do before deploying to staging — and it replied UNKNOWN even though the file was in its working dir. Then we've added a single line in the index saying what the file is called and have asked again — and it returned the right answer, with the part copied from the file, also saying that it hasn't found this target in Makefile.

It's all about the same file, the same directory and the same question, the only thing that differed is this line in the index. This way agents don't find things, they find things that are pointed to.

Push and pull

There are two types of pieces of information, everything that can be found in a repo falls into one of these types, and the goal is to assign every fact to one of them:

• push — gets loaded before any prompt (the memory file, its imports, always-active rules), occupies the context until the end of every session that loads it

• pull — everything that's findable and readable when sth needs it, zero cost until read

It's easy to fall into a trap here, because for example Claude Code documentation says that splitting the memory file into @path imports is good to keep things tidy but doesn't change the context as they get loaded with the memory file. An import is push disguised as pull.

On one of our repos Codex answered an index-resident question in 535 tokens, asking it to read a document cost it 4,353 tokens — in that one session.

For push things, they need to be such that if somebody were to make a mistake it would be costly:

• command nobody will think about

• a folder with generated code

• any decision making it hard for the agent to improve smth it's not supposed to improve

For pull things, these are things that might be needed in one out of twenty sessions — specifics of the test suite, conventions used for endpoints, release process or rationale behind the queue configuration.

Write the index, not the manual

The index file contains five headings now:

• Commands

• Landmines

• Decisions

• Where things go

• Where the detail lives

## Where the detail lives
- Running and debugging the test suite: `docs/testing.md`
- Adding a new endpoint: `docs/endpoints.md`
- Why the queue is configured this way: `docs/queue.md`

The fifth one lists question-shaped pointers to paths of documents (about the test suite, about adding an endpoint and about the queue). Remember:

• to point to questions, not subjects — "Running and debugging the test suite" rather than "Testing", agents appear with a question and closer wording means less thinking for them

• to point to paths using backticks — they're code verifiable, titles aren't; in Claude Code backticks also help avoiding treating an @path as a launch-time import which defeats the purpose of it

• to list one thing per line — if you feel like you need to write more than a line, create a document and point to it from the index instead

The documents should be written with a goal to be read, not to make yourself feel better. They should be single-purpose, single-screen and contain the failure sentence — for example, on one of our projects make test alone says could not connect until you run make db once. Every Claude Code run we did printed that sentence next to its answer without being asked, and that sentence is the reason the document exists.

Verbs the agent can read

The most valuable thing when it comes to task runners is that you can have one that has a target list that documents itself. For example, just --list outputs such a thing directly from the recipe's comments. That way you get:

Available recipes:
    db   # Start the test database container
    test # Run the test suite (needs `just db` first)

and a Makefile gets you the same thing — a ## comment per target and a help that greps them out:

help:  ## List tasks
	@grep -E '^[a-z-]+:.*##' $(MAKEFILE_LIST) | sed 's/:.*##/ —/'

db:  ## Start the test database container
	@docker compose up -d postgres

test:  ## Run the test suite (needs make db first)
	@cargo test

because the CI runs the same targets so the list can't lie, but prose documentation in the repo can be outdated for a year. Also, we've asked a cold agent what tasks are available and it turned out make help needed an approval it couldn't get in that session, so it read the Makefile instead and returned the same three targets.

It's all about the fact that the list is placed somewhere readable rather than just runnable. Well, not always — Antigravity headless mode denied a file read outright for want of an allow rule — but wherever the gate is on running the command, a readable target list walks straight past it.

The clone drill

We've created a script called clone-drill, it's a test that runs the repo against a fresh clone of its HEAD in a temp directory and asks a cold agent questions that you ask on your first week here:

• There are two sources of local self-deception — files you haven't commited and files you've added to .gitignore. A clone doesn't have any of these.

• The one it doesn't address is the home-directory configuration, because a clone on your machine is still on your machine — for that one, give the drill to somebody else and see what they get.

It's a two-part script:

• It runs the free part which makes sure that every backticked path in the index points to an existing file in the clone (you might need to tweak this part to suit your index)

• Then it runs the billed part asking these questions, we've limited it to three or four

You can run it like this:

./scripts/clone-drill.sh

Or:

AGENT='codex exec' ./scripts/clone-drill.sh

And it costs around one credit to ask three questions in the harness that shows price. In the harness that shows tokens it's 1.5k–4.4k per question so you can't run it on every commit but if you ever change the shape of the repo, it's reasonable to do. Also, we've set this script up to assess the minimum:

• If the repo doesn't have an answer to a question, we instruct the agent to reply with UNKNOWN and the script checks if it says that

• That way we can say if the answer is there or not but we can't say how good it is — that part is your eyes, not the exit code

In the first version we were checking the entire response but it turns out that Codex includes the prompt in its transcript so two correct answers were marked as failed. That's why we changed it to check only the last line.

Loaded and sufficient are different failures

The canary is a different kind of test, it's good to have one (to make sure the file makes it to the model) but this test aims for sth else — to make sure that the context that comes with the repo and the context that's findable in it is enough. A repo might pass the canary and still won't be able to answer any question:

• Loading sth is binary, this or that, it either makes it or doesn't

• The other one, having enough context, is where the week goes

When six people edit it

If you have multiple maintainers, the index becomes an infrastructure and the problem changes from potential mistakes to potential lack of ownership. To address these things:

• List the context files in CODEOWNERS so the review request lands on somebody automatically and they notice the stale pointer — not to block the merge, that's a separate branch-protection setting you don't need here

• Attach the free part of this script to some other push automation so somebody can run it even when the team is busy (it doesn't need any model, any credentials or the network), keep the billed part for cases when you change the shape of the repo

• Make sure that every new line in the index replaces an existing one or is a pointer (so it doesn't turn into a manual and each future session becomes a bill)

• Find out which of your files are personal — in most harnesses there's one you commit with the project and another you keep in your home directory, and the block above names the ones we could verify for yours. If you skip this, there might happen:

  • A — your personal preferences in the index file will change people's sessions without them noticing

  • B — your project's facts in your home-directory configuration won't be in the repo and therefore won't be in their sessions

What we'd leave out

We don't think these are good ideas:

• A per-person private context file — if a repo only explains itself to the people who already know it, it doesn't explain anything

• Importing documents as an insurance — it turns the pull layer into push at full price in every session, and you don't notice it because nothing breaks

• Pointing to an unwritten document — we expected it to sink the answer, instead the agent went looking, found the right document anyway and told us the pointer was stale, so the cost is a search rather than an answer. Still good to add to the free part of the script so somebody doesn't pay for it

• Running the drill on every commit — it bills a model, so run it when the shape changes and leave the everyday load to the pointer check