Chapter 7: Context

Notes for one session are easy. Knowledge that should outlast all your sessions needs a home.

Docs in the repo

Keeping decisions, plans and how-tos as plain files next to the code, not in a wiki or a chat. The agent can search them with the same tools it uses on code, they change in the same commit as the code, and review covers them.

For an agent, a stale doc is worse than none: it believes what it reads, and states it with confidence. So docs in the repo need the same discipline as code, and the discipline can be a check. An agent can also keep them current, if you ask it to in the same commit.

Say it to your agent

“Move the deploy steps out of the wiki into docs/deploy.md, with the commands as they really run today. Then add a CI step that fails if a file path mentioned in docs/ no longer exists.”

The workshop

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