Methodology · 4 minute read
Spec-Driven Development With Coding Agents
Spec-driven development with coding agents makes the specification the unit of work: engineers write intent, scope, interfaces, constraints, prohibited changes, acceptance criteria, and risk class; agents implement against it; the acceptance criteria become automated verification gates; and humans review the change against the spec and the spec against the intent.
FISTA's methodology has always started from the specification: if a system cannot be specified, it cannot be safely built or delegated. Coding agents turn that principle from a discipline into a necessity. An agent given a ticket guesses at everything the ticket leaves out, and its guesses are plausible enough to pass a tired reviewer. An agent given a specification implements it. This guide applies spec-driven development to agent-produced code inside the agentic SDLC.
What does a specification for a coding agent contain?
| Section | Content | Purpose |
|---|---|---|
| Intent | The outcome in a paragraph and why it matters | Lets the agent and reviewer judge trade-offs |
| Scope and non-scope | Files, modules, behaviors in and out | Bounds what the agent may touch |
| Interfaces | Signatures, contracts, data shapes, error semantics | Encodes architecture; removes guessing |
| Constraints | Performance budgets, allowed and forbidden dependencies, style and layering rules | Enforces standards |
| Prohibited changes | What must not be modified: auth paths, migrations, public APIs, tests, gate configuration | A control, enforced by diff policy where possible |
| Acceptance criteria | Tests and checks that define done, written before implementation | Become verification gates |
| Risk class | Low, medium, high, critical | Selects the review policy |
| Context | Links to related specs, decisions, and docs | Reduces rediscovery |
Why do acceptance criteria come first?
Because they are the gates. Writing them before implementation forces the intent to be concrete, gives the agent a target it can verify against while iterating, and gives reviewers something objective to check. Acceptance criteria that cannot be automated should be rare and flagged; they mark the parts of the change that need human judgment. The evaluation discipline behind this is described in the evaluation-driven development whitepaper.
What does the loop look like?
- Specify: an engineer writes the spec; a peer reviews it for completeness and risk class.
- Plan: the agent proposes an implementation plan; the engineer reviews it for architectural fit before code is written.
- Implement: the agent implements, runs the gates, and iterates on failures within the spec's bounds.
- Verify: gates pass or the change is blocked; agents cannot edit gates for their own change.
- Review: per risk class, humans check the change against the spec and the spec against the intent.
- Learn: first-pass gate success, review findings, and escaped defects feed the spec template and the constraints library.
Plan review, step two, is inexpensive and catches most architectural drift before it is written.
How are scope and prohibited changes enforced?
Scope and prohibited changes should be more than text. Repository protections, diff policies that fail a change touching files outside scope, and the rule that tests and gate configuration require separate human-reviewed changes turn the spec's boundaries into mechanical controls. Access boundaries on the agent's identity complete the picture; see the AI-generated code security checklist.
What do good and bad specs look like?
| Bad | Good |
|---|---|
| "Add rate limiting to the API" | Intent: protect the public API from abuse without affecting internal callers. Scope: api/middleware, config. Non-scope: internal service routes. Interface: middleware signature and config shape stated. Constraints: no new dependencies; latency budget stated. Prohibited: auth middleware untouched. Acceptance: tests for limit behavior, bypass for internal callers, config validation. Risk: medium. |
| "Fix the flaky test" | Intent: make the test deterministic without weakening coverage. Scope: the test and its fixture. Prohibited: skipping or deleting assertions. Acceptance: passes 50 consecutive runs; assertions unchanged. Risk: low. |
| "Migrate to the new logging library" | Intent, scope by module, interface mapping table, constraint that log formats are unchanged, prohibited: no behavior changes, acceptance: log output snapshot tests, risk: medium. |
How do constraints encode architecture?
Every organization has rules that live in senior engineers' heads: layering, allowed dependencies, error-handling conventions, naming. Agents do not know them and will violate them plausibly. Write them into a shared constraints library referenced by every spec, and encode as many as possible as static-analysis rules so the gates enforce them. Each violation caught in review is a candidate for a new rule.
What metrics show the practice is working?
- First-pass gate success per specification, rising over time.
- Review findings that are spec gaps versus implementation errors; the former should fall.
- Escaped defects traced to unstated constraints.
- Time from spec to verified change.
The broader measurement approach is in measuring AI developer productivity.
What are the common mistakes?
- Tickets pasted as specs.
- Acceptance criteria written after the code, from whatever the code does.
- Scope as suggestion, unenforced.
- Over-specified implementation, wasting the agent's strength.
- Constraints unwritten, rediscovered in every review.
How does FISTA Solutions help?
FISTA Solutions builds software this way and installs the practice in client teams through forward deployed engineers and AI enablement engagements: the template, the constraints library, the gate configuration, and the review policy, applied on your codebases. FISTA has delivered 150+ projects for 50+ companies across 12+ countries.
To bring spec-driven development to your agent workflow, message FISTA on WhatsApp, or read spec-driven development in practice for the wider method.
Share-ready article cover
Download the generated social format.
Clear answers
Questions raised by this field note.
Straightforward guidance for evaluating scope, fit, and the next step.
01What is the difference between a ticket and a specification?
A ticket says what is wanted; a specification says what correct looks like: intent, scope and non-scope, interfaces, constraints, prohibited changes, and acceptance criteria an engineer can turn into tests. Agents guess when given tickets and implement when given specifications; the guesses are what reviewers catch or miss.
02How detailed should a spec for a coding agent be?
Detailed enough that two engineers would produce equivalent changes and that the acceptance criteria can be automated. Interfaces, constraints, and prohibited changes are stated explicitly; the implementation approach can be left open unless architecture demands a particular one. Over-specifying implementation wastes the agent's strength; under-specifying intent wastes the reviewer's time.
03Who writes specifications?
Engineers, usually the ones who would have written the code, with product or domain input on intent and acceptance criteria. Writing specifications becomes a core engineering skill, and senior engineers spend more time on it because their knowledge of architecture and constraints is what the agent lacks.
04What happens when the agent's change fails verification?
First ask whether the specification was wrong or incomplete; most repeated failures trace to a missing constraint or an unstated interface. Fix the spec, rerun. If the spec is sound and the agent still fails, the change may need a human, or the risk class was wrong. Track first-pass gate success per spec to see the pattern.
Continue exploring
Related capabilities
Start with the hard problem
Need the outcome owned, not merely analyzed?
Tell us where delivery is constrained. We’ll map the fastest credible path from intent to verified production.