Agent

Stop AI from Wrecking Your Codebase with Spec-Driven Development

By 古茗前端团队 · Jun 29, 2026 · 365 views · 11 likes · 2 comments

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Without structured specs, AI coding tools amplify inconsistency—they hallucinate requirements, expand change scopes, and forget rules between sessions. SDD shifts the human role from line-by-line reviewer to rule definer, cutting rework and making AI output predictable enough for multi-sprint, multi-developer projects.

Summary

AI coding assistants produce unstable output because they lack organized context—they guess requirements, ignore team conventions, and forget rules across sessions. Spec-Driven Development (SDD) fixes this by front-loading the work: a Spec defines what to build and what not to touch, a Design doc locks in the technical approach, and a Tasks file breaks the work into small, verifiable chunks. The AI then executes within these guardrails rather than improvising.

OpenSpec provides a lightweight on-ramp with a `/opsx` command set that generates, applies, syncs, and archives these documents. MCP servers pull context directly from Figma, Yapi, and internal wikis so the initial Spec draft isn't starved of real business data. After code generation, a three-layer constraint system—Skills for coding habits, AGENTS.md for project-specific rules, and Hooks for automated enforcement—catches the remaining drift, such as hardcoded strings that should use i18n.

Archiving completed changes turns one-off sessions into a growing project knowledge base. The next AI session inherits accumulated boundaries, design decisions, and known pitfalls, so marginal collaboration cost drops over time. The rule of thumb: any task expected to span more than two days justifies the upfront cost of writing a Spec.

Takeaways

— AI coding failures—scope creep, ignored conventions, forgotten context—stem from disorganized requirements, not weak prompts.

— SDD front-loads specification work: a Spec doc defines boundaries and acceptance criteria, a Design doc locks the technical approach, and a Tasks file breaks work into verifiable chunks.

— OpenSpec provides a `/opsx` command set (propose, apply, sync, archive) that wraps this workflow with minimal tooling overhead.

— MCP servers let the AI pull context directly from Figma, Yapi, and internal wikis when generating the initial Spec, reducing manual copy-paste errors.

— Layered Skills encode team conventions: bottom-layer Skills hold universal rules like 'think before coding,' while top-layer Skills capture project-specific architecture and naming habits.

— AGENTS.md acts as an onboarding manual read early by AI tools, suitable for stable, project-wide rules such as directory structure and no-touch zones.

— Hooks enforce hard constraints by running scripts at lifecycle events—for example, a PostToolUse hook that rejects any file containing hardcoded Chinese strings.

— Archiving a completed change with `/opsx:archive` saves confirmed boundaries, abandoned design paths, and discovered pitfalls into the project knowledge base, lowering the cost of future sessions.

— Any task expected to last more than two days justifies writing a Spec; simple style tweaks or one-off scripts do not.

Conclusions

The core shift isn't tooling—it's moving the human from code reviewer to spec author. The AI becomes an executor, not a collaborator.

Soft constraints in prompts and docs fail under long sessions; only Hooks that block non-compliant output make rules stick.

Archive is the most undervalued step. Without it, every new session starts from zero, and the same mistakes repeat.

MCP integration is what makes SDD practical at scale—without it, manually assembling context from scattered tools kills the efficiency gain.

The two-day heuristic is a useful litmus test: below that threshold, the spec overhead exceeds the rework it prevents.

Concepts & terms

SDD (Spec-Driven Development)

A development workflow where specification documents—defining requirements, boundaries, design, and tasks—are written before code and serve as the AI's persistent source of truth, replacing ad-hoc prompting.

OpenSpec

A lightweight open-source tool that structures AI coding workflows into a propose → apply → sync → archive lifecycle, generating and maintaining spec, design, and task documents.

MCP (Model Context Protocol)

A protocol that lets AI coding tools connect to external data sources like Figma, internal wikis, and API docs, so context can be pulled directly into spec generation instead of copy-pasted.

Skills (in AI coding)

Reusable rule layers that constrain AI behavior—bottom-layer Skills encode universal coding habits, while top-layer Skills capture project-specific architecture, naming, and domain knowledge.

AGENTS.md

A project-level file read early by many AI coding tools that serves as an onboarding manual, containing stable rules like directory structure, no-touch zones, and highest-priority conventions.

Hooks

Lifecycle-triggered scripts in AI coding tools (e.g., UserPromptSubmit, PostToolUse, Stop) that enforce hard constraints by running checks or blocking non-compliant output, such as rejecting hardcoded strings.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗