Part 1 · 1 chapters · ~10 min

Specs as Working Memory

The three layers of context an agent reads (standing context, the task spec and the working state), personas that set judgement for a role, skills as packaged procedures, and keeping all of it current, with a complete executable spec for a verification endpoint.

2

Writing specs agents can execute

everything the agent needs, written where it can read it
  1. Standing context: the project, its build, boundaries and hard rules.
  2. The task spec: goal, constraints, edge cases, and how to verify the result.
  3. Working state: the plan, decisions and open questions, kept current.
  4. Personas set the standards and judgement for a role.
  5. Skills are procedures loaded only when they are needed.
  6. Keep it alive: update rules alongside the code they describe.
code
# spec: clearance-letter verification endpoint
## goal
A third party can verify a clearance letter by its reference: GET /v1/letters/{ref}/verify.
## context
Letters are issued by the clearance service (docs/clearance.md). Reference format: CLR-YYYY-XXXXXXXX.
## behaviour
- 200 { valid: true, issuedAt, customerName (masked: "A*** O***"), loanRef } for an issued, unrevoked letter
- 200 { valid: false, reason: "REVOKED" | "NOT_FOUND" } otherwise  (never 404: no enumeration signal)
- rate limit: 30/min per IP; 429 beyond
## constraints
- no PII beyond the masked name; no balance information ever
- p99 < 300 ms; read from the replica is acceptable (letters are immutable once issued)
## edge cases
- revoked after issue; ref with wrong checksum; letter issued in the last second (replica lag → retry primary once)
## out of scope
- revocation UI; webhook notifications
## verify
- tests in test/verify.test.ts for every bullet above (names start with the requirement id CLR-V-*)
- npm run typecheck && npm test; one manual curl against the preview URL in the PR description
the test of a spec
Could a capable engineer new to the team build this without asking a question? If not, the agent will guess the missing answer, confidently. Every question you would have been asked belongs in the spec.
SPECS AS WORKING MEMORY
three layers of context an agent reads: the standing context, the task spec, and the live working state
swipe the figure sideways, or tap expand for full screen
1/6
standing context
Layer 1, standing context: a file at the root (CLAUDE.md, AGENTS.md, a contributing guide) with what the project is, how to build and test it, the architecture and boundaries, conventions, and hard rules ("never edit generated files", "money is integer kobo", "do not touch the ledger schema without approval"). Short, current, and the first thing the agent reads.