Why AI‑Driven Development Must Be Spec‑Driven to Reach Production

Spec‑Driven Development (SDD) for AI‑Generated Code

Imagine asking an AI agent to implement an "order export" feature. The agent quickly writes front‑end buttons, back‑end endpoints, and a downloadable file, but it also leaks raw phone numbers, exports the entire table, and embeds core logic in the front end. The problem is not the AI itself but an ill‑defined requirement.

AI coding failures often start before the first line of code: vague goals, missing contracts, undefined database boundaries, and acceptance criteria limited to "looks usable" cause the agent to guess, and its guess‑error rate is high.

Spec‑Driven Development (SDD) adapts the traditional software‑engineering specification approach to the AI era. Before the AI touches any code, the team writes a clear, executable spec that defines goals, constraints, and acceptance criteria, turning the spec into a hard contract the model must follow.

1. Spec as an Engineered Prompt

In SDD, a prompt is no longer a single sentence like "please implement X"; it becomes a structured specification containing the goal, constraints, I/O definitions, prohibited paths, acceptance standards, and verification methods—essentially a high‑quality spec.

Writing a natural‑language requirement is a "bad prompt"—ambiguous and open‑ended. Converting it into a structured spec gives the AI a deterministic prompt, reducing field guessing, unnecessary dependencies, and architecture violations.

The spec also improves reproducibility: the same spec, project rules, and verification commands let different agents or iterations produce similar implementations, provided the spec granularity and model capability are sufficient.

2. Spec Prevents Uncontrolled Inference

In the opening scenario, the AI exposed phone numbers because the requirement did not mention data masking; the agent chose the simplest solution. Human engineers would ask clarifying questions, but an AI defaults to a plausible path, increasing later rework.

SDD turns these "default solutions" into explicit constraints. Clear business goals stop functional drift; precise I/O definitions keep fields and boundaries stable; explicit API and database contracts keep the implementation aligned with existing systems.

3. The Seven Required Elements

Feature description : a clear business goal without prescribing implementation details, guiding the model’s trade‑offs.

Input/Output definition : data formats, types, required fields, ranges, null handling, and edge conditions, reducing field‑guessing and type drift.

Architecture constraints : layering rules, dependency direction, communication mode, module boundaries, and prohibited actions, preventing the model from bypassing system structure.

Database constraints : entities, relationships, index strategy, migration rules, compatibility and rollback requirements, controlling data‑layer risk.

API contract : endpoint, request/response format, error codes, permission and idempotency rules, ensuring front‑end and back‑end share the same contract.

Acceptance criteria : testable completion conditions covering user‑visible results and internal state, turning the definition into a verification checklist.

Edge cases : abnormal inputs, concurrency scenarios, retry logic, degradation strategies, and security limits, approximating real production paths.

4. Spec Review Is More Critical Than Prompt Tuning

Many teams spend effort polishing prompts while neglecting whether the spec itself is sound. Prompt engineering can improve expression but cannot replace business decisions about boundaries, data risk, and acceptance standards—these determine quality.

Because the spec is the AI’s execution contract, its review must involve product, engineering, testing, and security roles to verify goal clarity, stable interfaces, manageable database changes, testable acceptance, and complete exception handling.

After review, the spec becomes an "execution contract"; subsequent planning, code generation, testing, and self‑checks all reference this contract.

5. Context Injection Packs All Constraints for the Agent

Only after a spec passes review is it injected into the AI’s context. Context injection is not a dump of all materials but a well‑structured package containing four layers:

Feature spec: goals, I/O, API contract, acceptance criteria.

Project rules: architecture layering, coding standards, permission boundaries, dependency constraints.

Code context: related modules, similar implementations, migration scripts, existing tests.

Verification plan: automated tests, build checks, linting, and manual review commands.

This package determines how the agent works: with only a requirement it will find its own path; with a full spec and rules it plans, implements, and delivers evidence.

6. Automated Verification Closes the Loop

After AI generates code, the SDD flow does not stop at "implementation complete". Automated verification directly maps to the acceptance criteria in the spec: unit tests for logic, integration tests for contracts, migration checks for database changes, and end‑to‑end or manual checks for critical user paths.

If verification fails, the cause is classified as implementation deviation, spec gap, or verification gap. Each class has a distinct remediation: fix code, revise spec, or adjust the test.

Manual review covers aspects not covered by automation—coding style, architectural integrity, permission handling, data risk, and user‑experience judgments—and its feedback is fed back to the spec or implementation.

7. Keep Specs in the Same Repository as Code

Spec documents should live in the same version‑controlled repository as the code, reviewed together with feature branches. When architecture, database, API, or acceptance criteria change, the spec is updated first, then the AI updates the implementation.

This eliminates the gap where code moves forward while documentation lags. Reviewers can see spec diffs, code diffs, and test results side‑by‑side to decide whether the change still meets the original goal.

Spec changes must be disciplined: wording edits should not broaden implementation scope; new API fields must be synchronized with contracts and tests; database migrations must include compatibility and rollback notes; acceptance changes must add corresponding verification evidence.

8. Start with a Medium‑Complex Feature

The first SDD adoption should not begin with a large refactor. A suitable entry point is a medium‑complex feature that involves front‑end and back‑end interaction, an API contract, data constraints, and error paths, and can be verified within a day or two.

Run the full loop—spec writing, review, context injection, AI generation, automated verification, manual review, and merge. Once the loop is proven, template the process in the repository and expand to more modules.

Over subsequent development cycles, the value of SDD becomes evident: specs are reusable, agents inherit existing constraints, newcomers understand system boundaries faster, and reviewers can more easily judge whether implementations overstep.

Spec 片段示例：订单导出

Feature
订单管理页支持按创建时间导出当前筛选结果。

Business Goal
运营人员需要在日常对账中快速获得订单明细。
本期目标是减少手工复制和后台临时查询。

Input
start_time: ISO 8601 时间字符串，必填。
end_time: ISO 8601 时间字符串，必填。
status: paid / unpaid / refunded，可选。
单次时间范围最长 31 天。

Output
返回 xlsx 文件。
字段包括订单号、创建时间、支付状态、订单金额、收货人、手机号脱敏值。
空结果导出只包含表头。

Architecture Constraints
导出逻辑放在 order application service。
controller 只负责参数校验和响应转换。
不得在前端拼接导出数据。

Database Constraints
复用 orders 表和现有订单查询条件。
确认 created_at + status 组合索引可覆盖导出查询。
本期不新增订单快照表。

API Contract
GET /api/admin/orders/export
权限：order:export。
错误码：
403 无导出权限。
422 时间范围超过 31 天。
500 文件生成失败。

Acceptance
具备 order:export 权限的用户可以导出 31 天内订单。
无权限用户看不到导出入口，直接请求接口返回 403。
空结果文件只包含表头。
超过时间范围时不生成文件，并返回 422。

Edge Cases
导出过程中接口超时，前端展示可重试提示。
同一用户连续点击导出按钮时，前端禁用按钮直到请求结束。
订单金额按后端标准格式输出，避免前端二次计算。