Spec-driven development with an AI coding agent

Spec-driven development is a way of working with AI coding agents in which a written specification is agreed before any code is generated. The spec describes the intended behaviour, the technical approach, the parts of the codebase it touches, the risks and how it will be tested. The agent implements against that spec, and the spec, not a one-line prompt, is what its work is judged by.

It exists because an AI agent does what it is told, quickly and confidently. When the instruction is vague, the misunderstanding only surfaces in review, after the code is written. A spec moves that conversation to the start, where changing course costs a sentence instead of a rewrite.

1. Intake. A request arrives as a note, a meeting, an alert or a few lines typed into CodeLynq.
2. Spec draft. CodeLynq writes a technical spec against your codebase: functional interpretation, technical approach, affected components, data-model and API impact, risks, test strategy and assumptions.
3. Open questions. Anything the request leaves unclear is asked in a validation chat instead of guessed.
4. Approval. Someone on your team approves the spec. No run can start on a task that has not been approved.
5. Implementation. The agent builds against the approved version, runs your tests, reviews and security-scans its own diff, and checks your architecture rules.
6. Pull request. The PR links back to the task and the exact spec version it was built from.

• Misunderstandings are caught in a paragraph, not in a 400-line diff.
• The person who approves the spec does not need to read code to know what will be built.
• Reviewers check the code against an agreed intent, which makes review faster and less subjective.
• Every change has a written reason that outlives the chat it came from.

A spec is only as good as what its author knows about the code. CodeLynq reads the structure of your repositories, your conventions and what earlier reviews taught it, so 'affected components' names real files and dependencies rather than guesses. The architecture rules your team has set are part of every spec and every run.

Does writing a spec first slow the team down?

Less than reviewing the wrong change. CodeLynq drafts the spec in minutes; approving one that reads right is a click. The time goes into the decisions that would otherwise be made, badly, during code review.

Who approves the spec?

Whoever your team decides: a tech lead, the product owner or the developer who asked for the change. The approval is logged with the spec version.

What if the spec turns out to be wrong?

Edit it and approve the new version, or send the run back with feedback. The next run builds against the latest approved version.

Is this the same as test-driven development?

They work well together. The spec includes a test strategy, and the run executes your test suite before it opens a pull request.

• Architecture map and UML →
• How it works →
• Compared to Devin →
• Claude Code for teams →