跪拜 Guibai
← Back to the summary

Spec-Driven Development Puts a Blueprint Under AI-Generated Code

The first time you use an AI Coding Agent to build a project, the experience is often exhilarating.

You just need to say:

Help me build a user authentication system.

A few minutes later, the directory is set up, the interfaces are written, and the pages can be opened. Two thousand lines of code are laid out before you, as if an afternoon has accomplished a week's worth of past work.

But after a few more days of development, problems start to appear:

The first day feels like a 10x efficiency boost, but by the second week, you start concentrated rework.

The problem isn't necessarily that the AI isn't strong enough, but that we only told it "what to do" without providing sufficiently clear, persistent, and verifiable context.

This is precisely the problem SDD aims to solve.

1. What is SDD?

SDD stands for Spec-Driven Development.

Its core is not complicated: First write the intent as a specification, then let the code become the implementation of that specification.

In traditional development, requirements documents and design documents are often just preliminary references. Once the code starts evolving, the documents quickly become outdated, and the code ultimately becomes the single source of truth again.

SDD attempts to reverse this relationship: the specification is no longer scaffolding to be discarded after writing, but the source upon which requirements, design, tasks, testing, and implementation all depend. GitHub's Spec Kit summarizes the core process as:

Spec → Plan → Tasks → Implement

That is, first define "what to do," then decide "how to do it," then break down "in what order to do it," and finally enter the implementation phase.

This doesn't mean developers need to complete a thick requirements specification before writing code. What truly matters is: when the AI is ready to generate code, the key decisions have already been clearly documented, rather than being scattered across dozens of rounds of chat history.

2. Why Does Vibe Coding Easily Spiral Out of Control?

The biggest temptation of Vibe Coding is that the chat box pushes us to immediately jump into implementation.

You think of a feature, immediately have the AI write it; find it's wrong, add another sentence; have a new idea, continue appending. The whole process is very smooth, but the project's real requirements only ever exist in the person's mind.

For example, "build a user authentication system" hides at least these questions:

If this information is not provided, the model can only guess.

When it guesses right, we think the AI is very smart; when it guesses wrong, we enter a cycle of "generate—discover problems—regenerate." Even more troublesome is that even if a round of chat clarifies things, a new session might not retain this context.

So, the problem with Vibe Coding isn't "coding by feeling" itself, but skipping the first creation of the goal and rushing straight into the second creation.

The principle of "Begin with the End in Mind" from The 7 Habits of Highly Effective People can explain SDD well: a result typically undergoes two creations. The first is formed in the mind and plan, the second is built in reality. Construction requires a blueprint before building; AI programming similarly needs a "construction diagram" that can be continuously read.

3. SDD Isn't About Writing More Documents, But Reducing AI's Guessing

A practical set of SDD documents can be organized around four questions:

Document Question Answered Key Content
proposal.md or spec.md Why do it, what to do Users, scenarios, scope, non-goals, acceptance criteria
design.md or plan.md How to do it Tech choices, architecture, data flow, interfaces, exception and security constraints
tasks.md In what order to do it Task breakdown, dependencies, parallelizable items, verification methods
Code and Tests Was it truly achieved Implementation, automated tests, manual acceptance, run results

Large products might add PRDs, research reports, and project principles before these; a weekend project might not need to be this heavy. The number of documents isn't the point; whether they can eliminate key ambiguities is the point.

An effective specification must meet at least three conditions:

  1. Executable: After reading it, the AI knows which modules to modify next.
  2. Verifiable: Every requirement has a clear success or failure criterion.
  3. Traceable: When requirements change, the affected design, tasks, code, and tests can be found.

"The interface should look good," "The API should be stable," "Translation speed should be fast" are not qualified specifications because they cannot be verified.

Better writing looks like this:

At this point, the AI no longer needs to guess what "done well" means.

4. Walking Through SDD with a Chrome Translation Plugin

Let's demonstrate this process with a specific requirement: build a Chrome plugin that, when browsing English technical articles, extracts the main text with one click, calls an AI for translation, and displays and copies it in Markdown format.

Note, the point here is not to immediately have the AI create the project, but to first complete the first creation.

1. Write the Proposal First: Define the MVP's Boundaries

proposal.md can be written like this first:

# Web Article AI Translation Plugin

## Goal
Help Chinese technical readers complete "extract text—translate—preview—copy" within the current webpage,
reducing the need to switch between the browser, translation tools, and Markdown editors.

## Core Users
Chinese content creators who frequently read English technical blogs, documentation, and news.

## MVP Scope
1. Extract the title and body text from the current webpage;
2. Call a user-configured OpenAI-compatible interface for translation;
3. Display the Markdown result in a sidebar;
4. Support one-click copying;
5. Save the model address, model name, and API key configuration.

## Not Implementing for Now
- User accounts and cloud sync;
- Parsing PDFs, video subtitles, and login-restricted content;
- Batch translation of multiple articles;
- Automatic publishing to WeChat Official Accounts.

## Acceptance Criteria
- After clicking the extension icon on a supported article page, the sidebar can be opened;
- When text extraction fails, the model is not called, and a clear prompt is given;
- After successful translation, titles, paragraphs, lists, and code blocks are preserved;
- After the user clicks copy, the clipboard content matches the original Markdown;
- When the API key is not configured, no network request is initiated.

The value of this document isn't to make the process look professional, but to proactively state "what not to do."

AI is most prone to over-implementing when boundaries are fuzzy. If an MVP simultaneously includes an account system, cloud sync, multi-model routing, and auto-publishing, the code volume will quickly balloon, and the actual core workflow will remain unvalidated for a long time.

2. Then Write the Design: Resolve Technical Risks Early

After the requirements are set, research the technical solution instead of letting the model casually choose dependencies.

This plugin contains at least the following modules:

Current Webpage
  ↓
Content Script: Read and extract the main text
  ↓
Background / Service Worker: Organize requests and state
  ↓
OpenAI-compatible Model Interface: Generate Markdown translation
  ↓
Side Panel: Preview, retry, copy

Key choices can be recorded in design.md:

Here is a very typical value of SDD: the original idea might have been "change the Popup to a right-side full-height floating window," but Chrome already provides the Side Panel as a formal capability. Researching first, then designing, can prevent the AI from using CSS to simulate a fragile floating layer.

The design document should also answer abnormal scenarios:

The sooner these questions are clarified, the lower the cost of rework later.

3. Break Down into Tasks: Let the AI Complete One Verifiable Unit at a Time

With requirements and design in place, you still shouldn't tell the AI to "implement everything" in one sentence.

tasks.md can be broken down like this:

- [ ] T01 Initialize the Manifest V3 extension skeleton, verify it can be loaded locally
- [ ] T02 Create the Side Panel page, verify it can be opened by clicking the extension icon
- [ ] T03 Implement the configuration form and local storage, without connecting to a real model
- [ ] T04 Implement text extraction for the current page, and add test cases for failure states
- [ ] T05 Define the translation service interface, use Mock responses to connect the complete data flow
- [ ] T06 Connect to the OpenAI-compatible interface, handle timeouts, cancellations, and error responses
- [ ] T07 Implement Markdown preview, sanitization, and copy feedback
- [ ] T08 Perform acceptance testing using short articles, long articles, code-heavy articles, and non-article pages
- [ ] T09 Clean up debug logs, redundant code, and unnecessary permissions

Each task should produce a checkable result. This has three benefits:

If multiple tasks have no dependencies, such as the configuration page and text extraction, they can also be advanced in parallel; but "connecting to the real model" should obviously proceed after the basic data flow is working.

5. When Requirements Change, Do You Change the Spec or the Code First?

Suppose the first version of the plugin uses a Popup, but later it's discovered that the translation content is very long, and you want to change it to a right-side full-height panel.

The common Vibe Coding approach is to directly say:

Change the current popup to open from the right side, with the height filling the entire page.

The AI might immediately modify the CSS, or it might rewrite the page structure, or even introduce a new floating layer logic. But what truly needs to be confirmed first is: Does the Chrome extension have a native capability? What is the minimum supported version? What permissions need to be added? Should the original Popup be retained?

In SDD, the change process should be:

Propose Change
  → Research platform capabilities
  → Update requirement scope and acceptance criteria
  → Update technical design
  → Mark affected tasks
  → Modify code and tests
  → Verify documentation and implementation are consistent

That is to say, a requirement change is not a supplementary sentence in the chat history, but a traceable specification change.

Documents and code should enter version control together. Only then can you answer: Why was this permission added? From which version was the sidebar solution adopted? Which requirement does a certain piece of compatibility logic correspond to?

If the document says Popup, but the code has already become a Side Panel, then document drift is itself a defect.

6. How to Cooperate with an AI Coding Agent?

SDD is not tied to any specific tool. Claude Code, Codex, Cursor, Copilot, or other Agents can all read the Markdown documents in the repository.

The key is not to let a single conversation simultaneously handle the four tasks of research, decision-making, implementation, and verification.

You can collaborate with the AI according to the following rhythm.

Phase 1: Discuss Requirements Only

Read the current project. Analyze user scenarios around "webpage text extraction, AI translation, Markdown copying,"
list the scope, non-goals, abnormal situations, and verifiable acceptance criteria.
Only generate proposal.md, do not modify code.

Phase 2: Do Technical Research and Design Only

Based on proposal.md, research Chrome extension text extraction, Side Panel, model requests,
and Markdown secure rendering solutions. Compare alternatives, record trade-offs and risks.
Only generate design.md, do not modify code.

Phase 3: Break Down Tasks

Generate tasks.md based on proposal.md and design.md.
Each task must be small enough, containing dependencies, completion conditions, and verification methods, marking parallelizable tasks.

Phase 4: Implement Item by Item

Only implement T04. Read the specification and related code before starting; run the corresponding verification after completion,
report the modified files, verification results, and unresolved issues. Do not implement subsequent tasks ahead of time.

This approach seems slightly slower, but it actually reduces the probability of generating large blocks of code and then having to tear everything down and start over.

7. Don't Let SDD Become New Formalism

SDD also has its own traps: documents can be written very long but have no effective constraints; the AI simultaneously generates three files with highly repetitive content; the code changes, but no one maintains the specification.

To avoid these problems, you can adhere to a few simple principles.

1. Match Document Scale to Risk

Changing a button label doesn't require writing a full PRD; developing authentication, payment, or permission systems cannot just leave a single prompt sentence. The higher the complexity, the larger the impact surface, and the higher the irreversible cost, the more rigorous the specification should be.

2. Write Acceptance Criteria Before Implementation Methods

If a requirement cannot be judged as complete, it means it's not clear enough. Acceptance criteria force us to change "good," "stable," and "fast" into observable behaviors.

3. Explicitly State Non-Goals

"What we are not doing this time" is just as important as "what we are doing." Non-goals prevent both people and AI from continuously expanding the scope during implementation.

4. Write Research Conclusions into the Design, Not Just Leave Links

Links will break, chats will be lost. You should record the final choice, the reasons for abandoning other options, and the versions and constraints upon which this conclusion depends.

5. Commit in Small Steps, Verify Constantly

The faster the AI generates code, the more frequently you need to check differences, run tests, and save recoverable versions. Version control is not a tool used only when uploading code at the end, but a safety rope during the Agent development process.

6. Treat Specification Drift as a Defect

When the code and specification are inconsistent, either the implementation is wrong, or the specification is outdated. Both should be fixed, rather than defaulting to "the documentation will be supplemented later."

8. Code is Getting Cheaper, Clear Intent is Getting More Expensive

AI is rapidly driving down the cost of code generation, but the truly difficult parts of software development have not disappeared: we still need to understand users, define boundaries, choose architectures, handle exceptions, and judge whether the results are correct.

In the past, developers spent a lot of time translating clear plans into code; now, this work can increasingly be handed over to Agents. The resulting change is that clear, executable, and verifiable intent is becoming a new scarce resource.

SDD's significance is not to force everyone back to heavy waterfall-style documentation, but to give the AI a stable project memory:

Vibe Coding can help us explore quickly, and SDD allows the explored direction to be stably built, maintained, and iterated upon.

The next time you are about to say "help me build a system" to an AI, it's worth pausing for ten minutes first to write down four things clearly: why do it, what to do, how to do it, and how to prove it's done.

Those ten minutes will very likely save you days of rework later.