Skip to content
Canon

Volume X

Field Operations

How coding agents actually work

AGENTS.md is the constitution. Skills are progressive expertise. Plan/act, diffs, repo maps, and verification loops are the job. Distill traces back into skills. Cost and cache are design constraints, not afterthoughts.

  1. X.1AGENTS.md as ConstitutionAGENTS.md (and CLAUDE.md, and the Cursor rules file) is the repo's standing prompt. It is owned policy: how to build, test, and stop. Keep it short, imperative, and true, or the agent will ignore it and invent a culture.7 min
  2. X.2Writing Skills That TriggerA skill that does not trigger is documentation nobody opened. The description is a search query the model will match against the user's request. Write it as if under-triggering were the only bug — because it is.8 min
  3. X.3Plan Mode and Act ModeLong-horizon work has two speeds. Plan mode is a deny-writes session that produces a revisable document. Act mode is a budgeted loop against that document. Mixing them is how agents wander and how humans lose the veto.6 min
  4. X.4Diffs, Repo Maps, Edit FormatsThe coding agent's tools are not 'read and write files'. They are a repo map for orientation, grep for search, and a patch format for change. Whole-file dumps are how context dies and how reviews fail.7 min
  5. X.5Verification as ArchitectureThe product of a coding agent is not code. It is code that passed a verifier the harness ran. Tests, typecheck, build, browser smoke, and a human gate are stages of the loop, not a ceremony after it.7 min
  6. X.6Distill Traces into SkillsA trace is a lesson the agent already paid for. Compiling it into a skill, a rubric, or a golden eval is how the system gets cheaper and less lost. Uncompiled traces are landfill.6 min
  7. X.7Cost, Cache, and Model RoutingTokens are inventory. Prefix cache, model routing, and 'do not resend the PDF' are design, not FinOps after the bill. A correct small model on a tight window beats a frontier model on a dump.6 min
  8. X.8Spec-Driven DevelopmentWrite the contract before the agent writes the code: a spec, an interface, a failing test, a rubric. The agent fills a shape you can verify. 'Build me X' with no shape is a wish, not a task.6 min
  9. X.9The Named FailuresThe field repeats itself. Unbounded loops, context rot, mega-tools, unsandboxed exec, eval-by-demo, multi-agent theater. Name the failure, refuse it, and point at the fix. Unnamed failures come back next sprint.6 min