Spec-driven development with AI: turning intent into reviewable work

Spec-driven development gives an AI coding session a durable record of intended behaviour, constraints and checks. It is not an industry standard, a security control or evidence that a team will deliver better software. This article compares named tool workflows with independent security and requirements-engineering limits, then offers a testable local heuristic rather than a universal recipe.

What the term means in the tools examined here

GitHub’s Spec Kit documents a sequence of project principles, a specification, a technical plan, tasks, implementation and convergence. The project instructs users to repeat implementation and convergence until the result is reported as converged.^[1]

Kiro documents a related set of artefacts: requirements or bug analysis, design, and tasks. Its requirements file can contain user stories and acceptance criteria; its design file can cover architecture, data flow, error handling and testing; its tasks file holds discrete work items.^[3]

These descriptions establish what the two products document. They do not establish one common industry process, or show that the process improves delivery, review quality or security in another team. The same limit applies to Spec Kit’s template: independently testable user stories, Given-When-Then scenarios, functional requirements and measurable outcomes are fields to complete, not evidence that completion makes a decision correct.^[2]

A systematic literature review of generative AI in requirements engineering examined 238 articles published between 2019 and 2025. Its authors report recurring challenges around reproducibility, hallucinations and interpretability, and say that only 1.3% of the reviewed studies reached production-level integration.^[8] That result is not an evaluation of Spec Kit or Kiro. It is a reason to treat generated requirements as material requiring review rather than as settled product knowledge.

A specification does not make an agent safe

A feature specification answers questions about intended software behaviour. It does not define what an agent may read, which tools it may call, which credentials it may use, or who may approve a release.

OWASP’s guidance for AI-assisted coding identifies separate trust boundaries around repository content, external pages, MCP tool responses and CI/CD agents. It advises teams to treat repository content as untrusted input when an agent processes it, minimise the context supplied to the agent and audit actions after external content has been processed.^[4]

NIST’s Secure Software Development Framework makes a related, wider point: secure development practices normally have to be added to each SDLC model because few lifecycle models address security in enough detail.^[7] A spec-first workflow can organise intent. It is not a replacement for secure-development practices.

For an AI-assisted change, keep two records rather than one. The specification record names the user-visible outcome, unchanged behaviour, constraints, acceptance evidence and a decision owner. The authority record names the permitted repository, trust level of inputs, allowed tools and credentials, dependency checks, CI/CD permissions, release approver, rollback path and audit evidence. The first record explains what should change. The second limits what the agent can do while making the change. This split is an editorial synthesis of the cited guidance, not a standard.

A worked decision trace

Consider an illustrative request: “Add CSV import to the customer portal.” This is not a case study or a measured result. It is a compact trace that shows how the two records change the work.

The specification record asks: what fields may be imported; what happens to duplicate records; which existing customer data must not change; which errors are shown; and which acceptance cases prove the result. A feature that accepts malformed rows but preserves existing records has a different acceptance case from one that rejects the entire file.

The authority record asks different questions: does the agent read a real customer export; may it install a parser; can it change a database migration or an import worker; may its test run write to shared storage; and who approves a release that handles personal data? OWASP identifies untrusted repository and external content, tool descriptions, dependency material and CI/CD as potential agent-facing attack surfaces.^[4]

In this example, the request should not go straight from a sentence to an autonomous implementation. It crosses input validation, persistent state, dependencies and potentially sensitive data. A short specification plus an authority record provides a reviewable boundary. That is a local risk judgement, not a claim that every CSV feature requires the same paperwork.

When a full chain is unnecessary

More artefacts can cost time, become stale or merely repeat what an existing test already states. Kiro’s Quick Spec mode is aimed at well-understood features and rapid prototypes, and its documentation says a standard feature spec is more suitable when requirements need iteration or review gates add value.^[5]

The Agile Manifesto likewise values working software over comprehensive documentation and responding to change over following a plan, while acknowledging that the items on the right still have value.^[6] A specification should therefore remain proportional to the uncertainty and authority involved in a change. It should not become a fixed document quota.

A practical local rule is to start with the smallest record that lets a reviewer answer two questions: can we observe the intended behaviour, and can we account for the agent’s authority? Escalate the record when either answer is unclear. Add a design section when an interface, persistence model, performance constraint or cross-service interaction must be chosen. Add release controls when the agent can reach credentials, external tools, CI/CD or production-adjacent systems. This is a working hypothesis for local evaluation, not a proven threshold.

How to evaluate the heuristic locally

Treat the rule as an experiment in process, not as a result to assume. For a defined period, a team can record every AI-assisted change that reaches review. For each change, record its class, the chosen record size, the agent and tool configuration, the source of any external context, requested permissions, acceptance evidence, review outcome and release decision.

Define the unit before collecting data. For example, a “material behaviour change” might mean a change to a public API, persistent data, access control, money movement or a user-visible workflow. A late requirement discovery should mean a review or incident finding that identifies a behaviour missing from the record, not simply a later preference change.

Compare those records with a baseline period or a comparable team, but do not attribute a difference to the specification alone. Model choice, reviewer availability, change complexity, test coverage and release policy can all move at the same time. The useful output is a decision log that shows where the record was too thin, too heavy or missing an authority boundary.

Failure modes that the record must expose

A requirement can be testable yet incomplete. A passing suite generated by the same agent that produced the code does not provide independent assurance, and tests may assert generated behaviour rather than correct behaviour.^[4] A design can be accurate when written and still become stale after an interface, dependency or operating condition changes. A repository check can pass while a data migration, external service, performance target or rollback procedure has not been exercised.

Kiro’s Quick Spec documentation explicitly allows a team to edit requirements after auto-generation when something important was missed.^[5] OWASP separately calls for human ownership, approval and attributable review of AI-assisted changes.^[4] These are different controls: one repairs the stated intent; the other assigns responsibility for an action.

The useful question is therefore narrower than “Should every agent use specs?” For a named change, can a reviewer see the intended behaviour, the evidence, the authority boundary and the person who accepts the residual risk? If not, another page of generated code is not the missing artefact.