A5 · chapter overview
The agent brief
A4 wrote the spec — correct by definition. A5 wraps that spec in a brief a Claude Author can run: links first, every reference exact, the runtime shape and build order fixed, the proof gates named — and the practice of running that agent well.
A spec defines what and why and done; it is not, on its own, runnable by an agent.
The agent brief is the layer that fixes every remaining how-to-build decision and turns the spec
into code. It has five parts — references, requirements, topology, agent stories, the implementation
prompt. Select one on the right to read its role, the module that teaches it, and the real
.llms.md it lands on, all practised on the Portal.
Anatomy of an .llms.md brief · pick a part
Where we are
The course is one argument carried across eight parts. The first five are now in place: A0 framed the method, A1 made the case for thin, provable slices, A2 turned a vision into a backlog, A3 planned its delivery, and A4 defined and proved one rung as a spec. A5 is where that spec becomes a brief an agent can run. The remaining parts — reliability and the Portal exemplar — build on the increment A5 produces.
The arc below walks the eight parts. Select one and the readout reports its title, what it delivers, and whether it is built — the same orientation this landing exists to give. The default selection is A5, the part you are reading.
The course arc — eight parts, A0 to A7
A0–A4 settled why, what, the order, and the definition of a rung; A5 settles how a Claude Author turns that definition into running code.
The journey so far
A0 — Foundations named the two roles the course runs on: the human Operator (judgement, decomposition, acceptance) and the Claude Author (fast, well-specified implementation). The Author/Operator loop is the cadence that runs one rung end to end, and A0.2.2 — The four artifacts named the per-rung documents a roadmap line points at.
A3 — The roadmap layer planned delivery without touching the spec, and A4 — The spec layer defined and proved the unit: a thin slice written down as a spec — acceptance criteria, Given/When/Then, invariants, traceability — so “done” is a closure over traced, executed checks, not an opinion. A4 produced a spec that is correct by definition. But a spec says what and why and done; it does not, on its own, become running code.
The principle
A spec defines the work; a brief tells an implementer how to build it — references first, every decision the spec fixed restated for the builder, and none left open for the implementer to invent.
On the Portal
The Portal's f6.1.llms.md is a real brief — references, requirements
F6.1-R1–R8, the topology and task DAG, agent stories F6.1-AS1–AS4, and the implementation
prompt — that an Author runs to ship the web bootstrap over the unchanged facade.
A4 wrote what to build and how to know it is right; A5 writes how a Claude Author builds it.
Orientation dives
Three short dives orient you before the chapter's eight teaching modules. Read them in order: why a brief deserves its own layer, what the chapter covers, and how you write the brief and run the agent here.
Why a brief layer
A spec is not runnable by an agent on its own; the brief fixes every remaining how-to-build decision and leaves the Operator's calls to the Operator.
What the chapter covers
The five parts of an .llms.md — references, requirements, topology, agent stories, the prompt — and the eight modules ahead.
How you learn and build it
Write the brief part by part, run the agent, and review against the spec's Definition of Done — never the agent's self-report.
The chapter modules: A5.1–A5.8
Eight teaching modules carry the brief layer end to end — from how a machine brief differs from documentation for a person, through each of the five parts, to the practice of running an agent and the thesis behind it, closing on a workshop that briefs the Portal's engine chapter and makes a first full pass from spec to running code. They build in order: the convention, the five parts, the practice, the thesis, and the workshop.
Writing for an agent: the llms.txt convention
Why a brief for an agent differs from documentation for a person: links first, prose second, every reference exact.
References and requirements
Numbered, testable requirements, each traced to a story and an invariant — nothing the agent must do left implicit.
Execution topology
The runtime shape, the build-order task DAG, and the exact files the agent touches — a system assembled in the right order.
Agent stories
The executable counterpart of a user story: a Directive the agent runs and an Acceptance gate that closes it.
The comprehensive implementation prompt
The single prompt an agent runs to build the increment in task order, self-checking against the gates.
Running Claude agents well
The practice around the prompt: brief, supervise, and review — knowing when to let it run and when to intervene.
Pragmatic Programming with Claude Agents
The thesis stated plainly: a fast, tireless implementer of well-specified slices; the human owns the judgement.
Workshop — briefing the agent for Portal
Write the engine chapter's briefs and run the build: a first full pass from spec to a verified increment.
The eight modules carry the brief layer end to end — the llms.txt
convention, the five parts (references and requirements, topology, agent stories, the prompt), the practice of
running an agent, the thesis, and the workshop that briefs the Portal engine and makes a first full pass from
spec to running code. Begin with the orientation dive
Why a brief layer, or open
A5.1 · Writing for an agent.
References
The sources this chapter draws on for writing machine-readable briefs and running coding agents, and where the spec it wraps and the loop it runs within are defined in the course.
Sources
- llmstxt.org — The /llms.txt convention — a links-first, machine-readable document format an agent reads before prose; the convention the brief follows.
- Anthropic — Building effective agents — how to brief, structure, and supervise a coding agent over a well-specified task.
- Hunt, A. & Thomas, D. — The Pragmatic Programmer — the tracer-bullet discipline of turning a fixed contract into a built increment.
Related in this course
- A4 · The spec layer — the spec a brief wraps.
- A1.03 · The Author/Operator loop — the cadence the brief runs within.
- A0.2.2 · The four artifacts — the per-rung documents the brief assembles.
- A3 · The roadmap layer — the rung a brief implements.
- Companion · Phoenix (F6) — the real chapter whose
f6.N.llms.mdbriefs A5 grounds on. - Companion · Functional Programming in Elixir — the Portal’s Elixir and OTP foundations.