← Back to the summary

SDD Stops AI Coding from Eating Itself: A Chrome Extension Walkthrough

A real practice recap: how to use "document-first" Spec-Driven Development (SDD) with an AI Coding Agent to build a verifiable, rollback-able, iterable browser extension — instead of falling into the "day one high, week two rework" quagmire.

1. The Sweet Trap of Vibe Coding

Every tool that claims a 10x efficiency boost follows the same script:

Day 1: Efficiency skyrockets. You tell the AI "build me a user auth system," it spits out 2000 lines of code that seem to work.
Week 2: Rework begins. You discover the framework isn't what you wanted, the data layer was guessed, edge cases are unhandled, and you start chasing fixes, piling patch on patch.
Month 1: Self-doubt sets in. Context is lost, session history is gone, the AI starts "hallucinating," and every failed round burns your waiting time and tokens.

This is the core problem of Vibe Coding — it makes us skip the first creation and jump straight into the second creation.

The Two Creations

Stephen Covey, in The 7 Habits of Highly Effective People, talks about a principle called "Begin with the End in Mind": Effective people experience everything twice.

First Creation — Mental Creation: Before doing anything, you "do" it in your mind first, figuring out what it looks like and how to achieve it.
Second Creation — Physical Creation: Following the blueprint, you actually build it.

You don't build a house without a blueprint, you don't start a business without a business plan. The same goes for coding — don't rush the AI into writing code without a spec.

The trap of Vibe Coding is precisely that the instant feedback of the chat window is so seductive that we leap straight to "Physical Creation," completely skipping the critical step of "Mental Creation."

2. SDD: Spec-Driven Development

SDD (Spec-Driven Development) is about bringing back the "First Creation."

As the cost of code generation drops lower and lower, what's truly scarce is no longer "being able to write code," but clear, executable, verifiable intent. This is the core proposition of SDD:

Documentation is code; spec-driven development.

flowchart LR
    A[Vibe Coding<br/>Write code directly] --> B[Missing context<br/>AI guesses]
    B --> C[Hallucination / Rework / Self-doubt]

    D[SDD<br/>Documentation first] --> E[proposal requirements]
    E --> F[design architecture]
    F --> G[tasks breakdown]
    G --> H[Drive AI coding by spec]
    H --> I[Verifiable / Rollback-able / Iterable]

SDD turns "writing docs" from a forgotten chore into the new, effective core work.

What documents does SDD include? (Loaded on demand)

Document	Corresponding Role	Question it answers
`proposal.md`	Product Manager (PRD)	What to do, why do it, what not to do
`design.md`	Architect	How to do it, tech choices, directory structure
`tasks.md`	Project Manager	What to do first, what next, what can run in parallel
`rules/`	Team conventions	High-level principles the AI must follow

These three specs complete the first creation; code is the second creation (handed to the Agent), and then you iterate continuously.

3. In Practice: Chrome Translation Extension

Theory alone is too empty. Below, a real project chrome-extention-en-translation walks through the full workflow.

3.1 What the project is

A browser extension with core features:

When browsing English web pages, extract the article's core content with one click;
Call a configurable AI model (DeepSeek, Qwen…) to translate;
Translation results presented in Markdown format;
One-click copy, convenient for pasting into platforms like WeChat Official Accounts / Juejin.

The MVP is just these four things. What not to do is also explicit: no history, no account system, no favorites — only save the latest result locally.

3.2 Step 1: Requirements Document proposal.md

The first step is always to clearly define "what we want to do," not to start writing code directly.

Define what to do: One-click extract → convert to Markdown → AI translate → typewriter display → download.
Define the hard parts: Content extraction is the key and hardest part of the extension — how to strip navigation/ads/sidebars from any website and leave only the main text?
Define output format: The final result strictly follows a fixed structure (title / author / original link / body).
Define what not to do: No history, no account system, etc.

For the "content extraction" difficulty, the right approach is to research first, chat with AI for several rounds, look up references, and only write the reliable solution into the document. Here the conclusion was: use Mozilla Readability (the same engine behind Firefox Reader Mode) to extract content, and Turndown to convert to Markdown.

Key point: The requirements document only writes "what it is," never implementation code. Stop once written, hand it to the next step.

3.3 Step 2: Technical Architecture Design design.md

Tech choices directly determine project success or failure — right choices make everything easier, wrong choices drag you into a quagmire. This step plays the Architect role.

Two key technical decisions:

Translation access uses OpenAI-compatible mode: Use the openai SDK, change only base_url / api_key / model in three places, and you can freely switch between DeepSeek, Qwen, etc. No vendor lock-in.
Markdown rendering uses md-wx: A React Markdown rendering component optimized for WeChat Official Accounts, exactly matching the "WeChat Markdown format" requirement.

Also define a clear directory structure (split by MV3's four runtime contexts: background / content / popup / panel) and coding conventions.

3.4 Step 3: Page Layouts layouts

Sketch each page using ASCII characters, one file per page. This step gives "what the interface looks like" a shape before any code is written.

Popup entry dialog: Core is just one "⚡ One-click Translate" button + status + settings entry, ultra-minimal.
Panel result panel: Typewriter display of translation + "Download" "Copy", emphasizing translation and download.

┌──────────────────────────────────────────────┐
│ ① 🔤 English Web Page Translation             │
├──────────────────────────────────────────────┤
│ ② Target page (current page title / domain summary) │
├──────────────────────────────────────────────┤
│ ③      ┌──────────────────────────┐          │
│        │       ⚡ One-click Translate         │          │
│        └──────────────────────────┘          │
├──────────────────────────────────────────────┤
│ ④ Status: ● Extracting → Translating → ✅ Done │
├──────────────────────────────────────────────┤
│ ⑤ ⚙ Settings (API Key / Model)                │
└──────────────────────────────────────────────┘

3.5 Step 4: Task Breakdown tasks.md

Break the "Second Creation" into individual single tasks, each with a clear scope and acceptance criteria, letting the AI execute and verify one by one.

Phase 0 Project Foundation   0.1 Init build chain → 0.2 Shared types/messages → 0.3 Storage layer
Phase 1 Content Extraction   1.1 Extraction pipeline → 1.2 Metadata and image handling
Phase 2 AI Translation        2.1 Qwen streaming → 2.2 Prompt and output format
Phase 3 Popup                 3.1 Skeleton → 3.2 Trigger state → 3.3 Settings
Phase 4 Panel                 4.1 Streaming integration → 4.2 Typewriter/md-wx → 4.3 Download & copy → 4.4 Persistence
Phase 5 Integration           5.1 End-to-end → 5.2 Errors and edge cases

Paired with the project rules in rules/project_rules.md — the "AI Assistant Task Execution Spec":

Single Task Principle: Execute only one clearly numbered task at a time, wait for confirmation after completion.
No Auto-Expansion: Do not add extra work based on other documents.
Self-Check on Completion: After finishing, self-check against the acceptance criteria in tasks.md.

3.6 Engineering Practice: Treat "Rollback-ability" as a Safety Net

AI-generated code must be under immediate version control — only then can you trace and roll back when hallucinations occur.

# Not yet staged: discard this modification directly
git restore .

# Staged but not committed: unstage first, then discard
git restore --staged .
git restore .

# Already committed: roll back to the previous version
git reset --hard HEAD^

Another iron rule: Manage AI sessions. Start a new session and new context for each new task; don't let the dirty context of the previous task pollute the next one.

4. Requirement Iteration: Docs and Code Evolve Together

The project isn't done once written; new requirements keep coming. The key is: change the docs first, then change the code, keep them consistent, and track changes with git.

For example, after finishing the first version, a new requirement came up:

Currently the popup is a dialog. Can it be changed to slide out from the right side, filling the full page height? Because the translated content might be very long.

The correct approach is not to directly tell the AI to change the code, but:

Research first: Can a Chrome extension popup do this? (Answer: yes, using the Chrome Side Panel API.)
Change the docs: Update the solution into design.md / layouts, transforming the "interface" from popup to side panel.
Then change the code: Drive the AI to implement based on the updated docs.
Git commit: The consistency of docs and code is fully tracked by git.

This is the correct rhythm for "new requirement iteration" — docs and code generation stay consistent, git can track it.

5. Final Words

SDD is not some mysticism; it answers a set of the most basic questions:

What to do (proposal) — Writing code without requirements is like building a house without a blueprint.
How to do it (design) — One correct tech choice can make everything that follows twice as easy.
In what order to do it (tasks) — What first, what next, what can run in parallel.
By what rules to do it (rules) — High-level principles for the AI, instead of letting it freewheel.

The lesson of Vibe Coding is: Skip the first creation, jump straight into the second creation, and you'll die faster. SDD insists that "all things are created twice" — the first time in the mind (landed via documents), the second time by hand (let the AI write the code).

As code generation gets cheaper and cheaper, clear, executable, verifiable intent is what's truly scarce and truly valuable.

If you're also using AI to write code, give this a try: Stop first, write the spec clearly, then let the AI act. You'll find that slowing down actually makes you faster.