The Core — Context, Spec, Loop, Gate, Verify

2.1 The five principles

1. Correctness comes from the machine, not the model

An LLM is an unreliable judge of its own work. It will happily report “done, all tests pass” without having run them. This principle means every claim an agent makes needs an artifact behind it: an exit code, test output, a diff, a log. If the agent says it passed and there is no output, it did not pass.

2. State lives in files, not in the context window

The context window is temporary memory that vanishes at the end of a session and degrades as it lengthens. Anything that must persist — rules, decisions, things that were tried and failed — is written to a file immediately. The target is that a fresh session with no history can read the repository and continue correctly.

3. Work must be small enough for the loop to close

A good unit of work has a clear passing criterion and takes the agent 5 to 30 minutes. “Build the payment system” is not one task, it is eight. If the loop cannot close in the expected time, the task is too large or the spec is unclear: stop and split it, rather than letting the agent keep spinning.

4. Every loop needs a ceiling and a stop condition

An agent looping on errors without a ceiling burns tokens, damages code that was previously fine, and sometimes “solves” the problem by deleting the failing test. You need a maximum iteration count, a no-progress detector, and tripwires for forbidden behaviour: editing tests to make them pass, adding skip, or lowering a threshold.

5. Humans own three things, always

The specification, the acceptance criteria, and the approval to go to production. These are never delegated to an agent, however capable the model, because all three are where responsibility to users lives.

2.2 The shape of the loop

HUMAN
  SPEC     docs/specs/xxx.md    business rules + cases that must be rejected
  CONTEXT  AGENTS.md, skills/   architecture + conventions + prohibitions
  GATE     scripts/verify.sh    a repeatable definition of "passing"
     │
     ▼
AGENT LOOP — runs unattended
  1  Read the spec and the relevant context
  2  Write tests from the spec and run them. They must be red.
     If they are green immediately, the tests are testing nothing.
  3  Write the smallest implementation that makes them pass
  4  Run verify.sh
     red   → read the error → fix → back to 3 (ceiling of N rounds)
     green → go to 5
  5  GREEN — the whole gate passed, with real output
  6  Record what was learned in memory/pitfalls.md and an ADR
  7  Open a PR with the gate output attached
     │
     ▼
HUMAN
  REVIEW   the spec, the quality of the tests, the blast radius — not every line
  SHIP     canary → watch guardrail metrics → roll out or roll back

2.3 What one iteration is made of

Component	Its job	What happens without it
Goal	What must be true at the end, in one sentence	The agent works past its scope and edits unrelated files
Context	Relevant files, conventions, prohibitions	The agent invents a new pattern over the existing one
Action space	Which commands it may run, which files it may touch	The agent runs something dangerous, or edits config it should not
Feedback	Machine-readable results: exit codes, stderr	The agent guesses it got it right and loops indefinitely
Stop condition	Green, or ceiling reached, or no progress	Unbounded token burn, and code that degrades each round
Persistence	Results and lessons written to files	The next round repeats the same mistake

The most important rule about feedback

The quality of an agent loop is set by the quality of its feedback, not by the intelligence of the model. An error that says only AssertionError forces the agent to guess. An error that says expected discount=90.00 (10% of 900) got 100.00 — tax applied after discount? gets it fixed in one round. The highest-return investment in agentic work is making your test failures more articulate.

What this chapter settles

The five principles are one set: the machine judges, knowledge lives in files, work is small enough to close, every loop has a ceiling, and a person keeps the spec, the criteria and the approval. Drop any one of them and the loop becomes token burn rather than work.

The next chapter covers the repository layout that lets an agent opening a fresh session get it right immediately, with nobody explaining anything.