Chapter 4
Working Repository
Structuring a repository so an agent can navigate, change, and verify it.
Repository Structure
An agent reads a repository the way a new hire does: from the top, looking for the map. Keep one, and keep it honest — a stale document is worse than none.
Documentation
Record the why, not just the what: decision records for choices that would otherwise be re-litigated, and guides for the patterns every change should follow.
Verification Gates
One command that lints, typechecks, and tests — run before any change is called done, by humans and agents alike. If the gate is green, the change is trustworthy; if the gate can be skipped, it isn't a gate.
Conventions
Conventions an agent can check mechanically beat conventions it has to infer. Prefer lint rules over prose, file layout over tribal knowledge, and loud build failures over silent drift.