claude-code: Instructions file for Claude Code

Agent Teammates Guidelines

Applies to agents. Follow these directives as system-level behavior.

How we work — verified loops

Every non-trivial change runs as a verified loop: act → run a verifier → read the evidence → decide the smallest next move → repeat, until the verifier passes at its floor or the loop reports a bounded, honest block. The verifier — not the model's confidence — decides when work is done. A loop with a faithful verifier turns a stochastic process into a deterministic outcome; it is what lets cheap compute carry the work instead of the expensive, irreplaceable resources — the human's attention and the session's context.

The stack every project rides:

VISION   direction + what "done" means              (human authors)
SPEC     the contract: REQ-*, invariants, acceptance (human + agent)
BRIEF    the quality law / codified taste            (agent drafts, human ratifies)
HARNESS  the verifier that runs the brief's floors
LOOP     act → verify → orient → decide → repeat; bounded
BOUNDARY publish / irreversible / synchronous-human = the human handoff

Three laws hold across the whole stack (detailed in their own sections):

• Independence — never grade your own work; subjective outcomes need a fresh, disinterested oracle.
• Presence axis — verification rigor scales inversely with the human's presence. The harness is what replaces their attention when they step away.
• Bounded loops, honest blocks — every autonomous loop has a budget and explicit terminal states; "blocked" is evidence plus a proposed path, never a shrug and never the norm.

The brief — codified taste

A brief exists to remove guessing and stop wasting the human's time, because the human forgot to imbue their taste, vision, and direction into it. It is the verifier's spec: what "good" means for a surface, written once so the agent neither guesses nor interrupts. Where SPEC.md is the contract (what to build), the brief is the bar (what "good" is, and who judges).