Chapter 7: Context

The repo as the system of record

Also called System of record

The rule that anything the work depends on lives in the repo, in a form the agent can read. A decision in a meeting, a chat thread or your head doesn't exist for the agent until someone writes it where the agent looks.

It changes what counts as finishing a discussion: a decision isn't made until it is committed. It helps new people as much as agents. It has limits. Peter Naur argued in 1985 that part of a program's theory never gets written down, and a repo can't hold what nobody can say.

Say it to your agent

“We agreed in Slack that refunds over $500 need a second approver. Write that in docs/decisions/refund-approval.md with the date and the reason, link it from AGENTS.md, and add a failing test for it so the rule exists in code too.”

The workshop

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