Agile Agent Workflow · course overview
The agile agent workflow
Pragmatic Programming with Claude Agents — a way of building software in which a human supplies judgement, taste, and acceptance, and a Claude agent supplies fast, exact implementation. Paired over thin, provable increments, the two ship reliable systems neither would reach alone. The course opens with the framework you will build — two layers, four artifacts, one loop — then teaches each part in depth and proves it on one running project.
The practical project is the Portal: a learning platform carried from an empty repository to a deployed, multi-surface system — a branded store, an event-sourced engine behind one facade, a Phoenix web application, a Telegram bot, and a student dashboard. Every idea in the six modules is practised on it, and the exemplar runs the whole loop, from zero to production.
The course arc
Start with A0 — Foundations: the framework the rest of the course fills in. Its three pages are the whole method in miniature — the two layers, the four artifacts, and the loop — and they are built and readable now. A1 makes the case for that framework. A2 and A3 teach decomposition into user stories and the roadmap that sequences them; A4 and A5 define the spec and the agent brief that turn a rung into running code; A6 hardens every increment for reliability and correctness. The exemplar, A7, then runs the whole loop on Portal. The through line: a Claude agent is a fast, tireless implementer of well-specified thin slices, and the human is the source of decomposition, judgement, and acceptance.
The framework, then the workflow, then the proof
A workflow earns its keep at the boundary: A6 keeps each increment correct, and A7 proves the method ships.
A0 · Foundations — what we are building
Before the six chapters, the blueprint. This short foundations chapter lays out the framework the whole course runs on — its structure, its vocabulary, and its motion — in three pages that are the A0.2 · What we are building module. They are built and readable now; read them first, and each later module fills in one part of the picture in depth.
The two-layer model
The structure: a roadmap layer that plans delivery over a spec layer that defines and proves each rung — both on the framework-free core, the spec the single source of truth. Taught in depth by A3 and A4.
The four artifacts
The vocabulary: a roadmap.md, a spec, the user stories, and the agent brief — four files, and the distinct question each answers. Each gets its own module: A3, A4, A2, and A5.
The Author/Operator loop
The motion: the human sharpens and accepts, the agent specifies and builds, the increment ships thin but robust, and feedback edits the spec. The loop A1 makes the case for, and A7 runs end to end.
These three pages are the A0.2 module hub; the wider foundations chapter (A0 · why, what, and who) frames them. Read the framework first, then climb the ladder below.
The six chapters
Six chapters carry the workflow from an idea to a correct, shipped increment. Each pairs a principle with practice on the Portal, and ends in a workshop that advances the project.
Why an Agile Agent Workflow
The philosophy and the thesis: the two roles, the two layers, and what “done” means.
- A1.01The two failure modes: vibe coding and big-bang specs
- A1.02Pragmatic Programming, revisited for agents
- A1.03The Author/Operator loop
- A1.04Two layers: roadmap and specs
- A1.05Correct by definition
- A1.06Meet the project: Portal
Decomposition: from vision to user stories
Turning a product vision into a ladder of small, valuable, testable units.
- A2.01Value, not tasks
- A2.02The Connextra form and the three Cs
- A2.03INVEST: what a good story looks like
- A2.04Acceptance criteria with Given/When/Then
- A2.05Splitting stories that are too big
- A2.06The value ladder
- A2.07Workshop: decomposing Portal
The roadmap layer: Agile delivery & iteration
Planning delivery as thin, robust increments in a roadmap.md.
- A3.01Agile, distilled
- A3.02Extreme Programming for small batches
- A3.03Anatomy of a roadmap.md
- A3.04Thin but robust
- A3.05Milestones and iterations
- A3.06The program roadmap
- A3.07Tracer bullets and walking skeletons
- A3.08Workshop: roadmapping Portal
The spec layer: specifications & acceptance
Specifications that are precise, traceable, and accepted only when proven.
- A4.01Specification by Example
- A4.02The triad: spec, stories, agent brief
- A4.03Anatomy of a spec
- A4.04From stories to a .stories.md
- A4.05Invariants: properties that must always hold
- A4.06Traceability — correct by definition
- A4.07Workshop: specifying Portal’s engine
The agent brief (.llms.md) & the implementation workflow
The agent-facing brief and how a Claude agent turns it into working code.
- A5.01Writing for an agent: the llms.txt convention
- A5.02References and requirements
- A5.03Execution topology
- A5.04Agent stories
- A5.05The comprehensive implementation prompt
- A5.06Running Claude agents well
- A5.07Pragmatic Programming with Claude Agents
- A5.08Workshop: briefing the agent for Portal
Reliability and correctness
The Elixir/OTP and functional techniques that make each increment sound.
- A6.01Let it crash: OTP supervision
- A6.02Boundaries: functional core, imperative shell
- A6.03The master invariant
- A6.04Parse, don’t validate
- A6.05Make illegal states unrepresentable
- A6.06Railway-oriented error handling
- A6.07Event sourcing and the Decider
- A6.08Property-based testing
- A6.09Quality gates as code
- A6.10Workshop: making Portal correct
The series opens with A1 — Why an Agile Agent Workflow, then climbs the ladder. The companion course, Functional Programming in Elixir, builds the Portal’s Elixir and OTP foundations that this workflow puts to work.
Portal Exemplar · A7
Everything the six chapters teach converges here. Portal is built the way the course prescribes — one value ladder per chapter, each rung decomposed into stories, planned in a roadmap, defined in a spec, briefed to a Claude agent, and accepted only when its invariants hold — and carried from an empty repository to a clustered, deployed platform. The exemplar is seven steps, each run through the same loop.
Decompose into stories, plan a roadmap, write the spec and the agent brief, build, and prove — correct by definition.
A branded store, an event-sourced engine behind one facade, a web application, a bot, and a dashboard — supervised, gated, and live.
- A7.01
- The starting line: the branded store — the given foundation and branded Snowflake ids.
- A7.02
- The engine — a supervised, event-sourced core behind one facade, built end to end.
- A7.03
- The web — contexts, server-rendered pages, LiveView, real-time, auth, and deployment.
- A7.04
- A second surface: the Telegram bot — a parallel surface over the same facade.
- A7.05
- The student dashboard — a new domain dimension, entitlements, where paid becomes unlocked.
- A7.06
- Shipping to production — releases, runtime configuration, clustering, and migrations.
- A7.07
- Retrospective — what the workflow bought, and where human judgement still decided.
From zero to production is not a slogan here — it is the seven steps above, each carried through the same loop the six chapters teach.
References
The canon this course distils and extends, grouped by the workflow layer it informs.
Stories, specifications & acceptance
- Cohn, M. — User Stories Applied — the story form, INVEST, and splitting.
- Adzic, G. — Specification by Example — living documentation that cannot drift.
- Gherkin — Given / When / Then — executable acceptance scenarios.
Agile delivery and iteration
- Beck, K. — Extreme Programming Explained — small batches, short loops.
- Hunt & Thomas — The Pragmatic Programmer — tracer bullets and walking skeletons.
- Humble & Farley — Continuous Delivery — releasing thin increments safely.
The agent and implementation workflow
- The
llms.txtconvention — machine-readable briefs. - Anthropic — Claude Code best practices.
- Anthropic — Building effective agents.
Reliability and correctness
- Wlaschin, S. — Railway Oriented Programming — a closed error discipline.
- King, A. — Parse, don’t validate.
StreamData— property-based testing for Elixir.