Spec-driven agentic development

For the past six months, my development team has been experimenting with spec-driven software development using a lightweight spec framework inspired by OpenSpec. We adopted it to make LLM-assisted development more traceable, reviewable, and verifiable. This post explains the needs that led us there and the workflow that emerged.

Needs

1. Deliberately use LLMs to gain on-hands experience with agentic development.

   • Explore the capacity of LLMs
   • Stop writing code by hand
   • See how LLMs could fit into our development workflow

2. Keep a structured, traceable record of the LLM’s input.

   • Avoid ad-hoc prompting. If an LLM is used to produce the output, instructions should be tracked as well.
   • The spec becomes the source of truth; code is a side-effect. Update the spec first, then code follows.
   • Context is easily lost or distorted among LLM sessions. The spec preserves the working context.

3. Provide a clear context for both human and agentic developers during review.

   • A spec makes the intended change set explicit before implementation starts.
   • It can also capture architectural decisions early, serving a similar role to an ADR or RFC.
   • Specs themselves can be reviewed by LLM agents.

4. Define a clear validation strategy and acceptance criteria.

   • LLM agents need to know when to stop and how to verify that the work is correct.
   • Explicit validation criteria help limit drift and reduce hallucinations.

5. Ensure the generated artifacts remain useful to humans.

   • The output should be documentation, code, and tests that people can read, maintain, and debug. We remain the primary consumer of the code.
   • This also avoids AI lock-in and keeps the workflow grounded in conventional tools and practices.
   • When incidents happen, we want to be familiar with the codebase we are troubleshooting.

Spec

A spec is a change proposal that is ready to be implemented by an LLM agent. It consists of the following files:

1. proposal.md – user story with clear scope and acceptance criteria (for humans)
2. design.md – high-level technical plan, replaces ADR/RFC (for humans)
3. tasks.md – task break-down of the implementation (for agents)

See an example template for proposal.md and design.md, and the “spec” agent skill.

Workflow

Observations:

• Changes to user stories and architectural decisions are now documented alongside the implementation.
• Human effort shifts earlier in the process, toward clarifying scope, constraints, and design decisions.
• Technical feedback during PR reviews arrived too late or devolved into nitpicking. Pair programming used to bring that feedback sooner; now it is replaced by architecture discussions.
• This makes key architectural decisions explicit sooner. What used to be a best practice becomes a prerequisite.
• Agents run a tight build-test-fix loop during coding, reducing human review to design approval and final sign-off.
• For agentic verification, automated test suites, especially end-to-end tests, are crucial. Good news: LLMs are good at writing test cases. Bonus: TDD is easy now.