Agentic Scrum, Part 3 of 5: Write Specs a Coding Agent Can Actually Follow

This is part 3 of 5 in the Agentic Scrum series. Part 2 covered value.md and requirements.md, the two files that humans write.

This part follows them into the first agent steps, the specification agent and the coding loop. Part 4 deals with testing.

 

Once requirements.md is approved, the Specification Agent takes over. Its job is to translate requirements written for people into instructions written for a coding agent.

Those are different audiences. People forgive vagueness and fill gaps from context. A Coding Agent fills gaps too, but it does so confidently and in a direction you did not choose. 🙂 

 

What the Specification Agent reads and writes

The agent reads value.md, requirements.md, AGENTS.md and the parts of the codebase the feature touches. It writes agent-spec.md and a first handover.

It does not write feature code. The spec is the contract between the human decisions upstream and the machine work downstream, so it has a fixed structure.

# Invoice export: agent specification
--
## Goal
Let a signed-in user export all invoices of a chosen period in one action.

## Read first
specs/042-invoice-export/requirements.md
guardrails/coding.md
guardrails/limits.md
src/invoices/ (the existing invoice service client)

## Requirements covered
R1, R2, R3, N1, N2, N3, F1, F2, F3

## Tasks, in order
1. Add an export service that reads invoices through the existing client.
2. Add the two format writers behind one interface.
3. Add the export endpoint and wire up access logging.

## Interfaces and contracts
Endpoint: GET /exports/invoices with the parameters from, to and format.
Success: the user downloads a file.
Empty period: the response states that no invoices were found, no file is created.

## Constraints
Follow guardrails/coding.md. No new dependencies. No new tables.

## Definition of done
Build passes. Lint passes. The existing test suite passes.

## Out of scope
Scheduled exports. Any other format.

## Stop and ask when
A requirement contradicts existing code behavior.
A task needs changes outside src/invoices/ and src/exports/.

—

Every section has a job.

• “Read first” tells the agent which context to load instead of letting it wander through the repository.
• “Requirements covered” carries the IDs from Part 2, so Part 4 can trace tests back to them.
• “Tasks, in order” keeps each step small enough to fit the diff limit in limits.md.
• “Definition of done” has to be commands a machine can run, not adjectives.
• “Stop and ask when” turns uncertainty into a break in the loop instead of a guess.

Sounds familiar? This works with any SDLC around, especially with the one I have been using and writing about.

 

How developers validate a spec

Developers review the spec in a pull request on the specs folder, and this is the step that takes the place of code review in this model.

It is shorter and more valuable than reading a diff, because a mistake in a spec costs one sentence to fix and a mistake in code costs a feature.

Reading a spec takes ten minutes. Reading a diff from an agent that burnt a few hundred thousand tokens in the morning takes an afternoon or more.

I ask reviewers to look for five things. Ambiguous words like “appropriate” and “fast”. Assumptions the spec does not state. Failure modes from requirements.md that no task covers. Tasks too big to review as one change. And a definition of done that a machine cannot check. When any of these shows up, the review does not patch the spec by hand. It goes back to the specification agent with the comment, and the spec gets regenerated.

AGENTS.md and the guardrail files

AGENTS.md sits at the repository root and gives every agent the same orientation. A project map, how to build and check, the conventions, and the few non-negotiables.

Keep it under a page. Every agent loads it on every task, so every extra paragraph costs context each time. The commands below are placeholders, so swap in your own.

# AGENTS.md
--
## Project map
src/ application code. 
tests/ test code.
specs/ specifications. 
guardrails/ rules for agents.

## Build and check
Build: make build
Lint: make lint
Existing tests: make test

## Conventions
Follow the structure of the module you are changing.
Prefer the existing client libraries over new ones.

## Non-negotiable
Never edit specs/ or guardrails/.
Never commit secrets.
If the spec and the code disagree, stop and write a handover.
--

guardrails/coding.md holds the coding rules, such as error handling, logging and forbidden APIs, and guardrails/limits.md holds the budgets I showed in Part 1. The same two-layer rule applies as before. The agent reads the rule so it understands it, and CI, protected paths and code owners enforce it so it holds when the agent does not.

The development loop

The coding agent works on its own branch. It reads the spec, the guardrails and the latest handover, then implements one task at a time. After each task it runs the definition of done, fixes what fails, and repeats.

It stops when the work is done, when a limit from limits.md is hit, or when a stop condition from the spec triggers. Or when it runs out of tokens or hits a budget cap.

One design choice here is deliberate. The coding agent does not write or change the tests that count. It runs the build, the linter and the existing tests so it cannot break what is already there, but the new tests belong to the QA agent in Part 4.

If one agent writes both the code and its tests, the tests are derived from the code it just wrote, so they confirm what the code does instead of what the spec asks.

Important

Never ask the coder to do the testing

Never ask the coder to verify its code for security issues

 

The handover

Every stage ends by writing a handover, and the next stage reads that file plus the spec, never the previous chat. This is a realistic one from a loop that stopped early.

# Handover 02: coding agent

## Asked
Implement tasks 1 to 3 of agent-spec.md.

## Done
Tasks 1 and 2. Task 3 partly: the endpoint exists, access logging is missing.

## Deliberately not done
Scheduled exports (out of scope).

## Files changed
src/exports/service.ts, src/exports/writers.ts, src/exports/endpoint.ts

## Checks run
Build: pass. Lint: pass. Existing tests: pass.

## Open questions
R2 says invoices of the signed-in customer account.
The invoice client filters by user id. Which one is correct?

## Stop reason
Open question blocks task 3. Needs a product owner or developer decision.

Look at the stop reason. A handover that says everything went fine is welcome, but a handover that says “I stopped because I did not know” is the reason this pipeline works.

The question reaches a human, gets answered in requirements.md where it belongs, and the spec is regenerated. It never turns into a line of code nobody noticed.

 

Previous: Part 2, Describe the Value. Next: Part 4, Tests Are the New Code Review.

© Copyright 2026 Sorin Mustaca, All rights Reserved. Written For: Sorin Mustaca: Security-AI-Software

---

Want to work with me on this topic?
Check Endpoint Cybersecurity to see the consulting services we offer.