Chapter 7: Context

Searching only works if the agent has some idea of where to start.

Codebase map

Also called Repo map

A short description of how a repo is laid out: which folder does what, and where to begin. It gives the agent a picture of the project without reading it, so its first search is aimed at something.

Without one, an agent can spend its first tokens wandering. But this is the most disputed advice in the chapter. Measured evidence says overviews often don't help, because agents find their way with ls and search anyway. So write down only what those can't show: the real entry point, what is generated, what owns what.

Say it to your agent

“Add at most 10 lines to AGENTS.md: the entry point, which folders own the database and auth, and which folder is generated and must not be edited. Anything ls would tell you stays out. Then start a new session and ask it where login is handled.”

The workshop

Name a word, or describe what you mean in everyday language.