spec-driven

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec-Driven Development

规格驱动开发（Spec-Driven Development）

Structured development workflow: Initialize -> Plan -> Tasks -> Implement + Validate.

结构化开发工作流：Initialize -> Plan -> Tasks -> Implement + Validate.

Workflow

工作流

initialize --> plan --> tasks --> implement --> validate --> archive

initialize --> plan --> tasks --> implement --> validate --> archive

Project Structure

项目结构

.specs/
├── project/
│   ├── PROJECT.md          # Vision, goals, constraints
│   ├── ROADMAP.md          # Planned features, milestones
│   └── CHANGELOG.md        # Feature implementation history
├── codebase/               # Brownfield analysis (optional)
│   ├── STACK.md
│   ├── ARCHITECTURE.md
│   ├── CONVENTIONS.md
│   ├── STRUCTURE.md
│   ├── TESTING.md
│   └── INTEGRATIONS.md
├── research/               # Research cache (optional)
│   └── {topic}.md
└── features/
    └── {ID}-{name}/
        ├── spec.md         # WHAT: Requirements
        ├── plan.md         # HOW: Architecture
        └── tasks.md        # WHEN: Tasks

docs/
└── features/
    └── {name}.md           # Consolidated implementation

.specs/
├── project/
│   ├── PROJECT.md          # 愿景、目标、约束条件
│   ├── ROADMAP.md          # 规划的功能、里程碑
│   └── CHANGELOG.md        # 功能实现历史
├── codebase/               # 遗留系统分析（可选）
│   ├── STACK.md
│   ├── ARCHITECTURE.md
│   ├── CONVENTIONS.md
│   ├── STRUCTURE.md
│   ├── TESTING.md
│   └── INTEGRATIONS.md
├── research/               # 研究缓存（可选）
│   └── {topic}.md
└── features/
    └── {ID}-{name}/
        ├── spec.md         # WHAT：需求说明
        ├── plan.md         # HOW：架构设计
        └── tasks.md        # WHEN：任务安排

docs/
└── features/
    └── {name}.md           # 整合后的实现文档

Context Loading Strategy

上下文加载策略

Base load (~15k tokens):

PROJECT.md (context)
Current feature spec.md

On-demand:

codebase/*.md (brownfield)
plan.md (implementing)
tasks.md (executing)
research/*.md (new technologies)

Never simultaneous:

Multiple feature specs
Archived features

基础加载（约15k tokens）：

PROJECT.md（上下文信息）
当前功能的spec.md

按需加载：

codebase/*.md（遗留系统相关）
plan.md（实现阶段）
tasks.md（执行阶段）
research/*.md（新技术相关）

禁止同时加载：

多个功能规格说明
已归档的功能

Triggers

触发条件

Project-Level

项目级触发

Trigger Pattern	Reference
Initialize project, setup project	project-init.md
Create roadmap, plan features	roadmap.md
Map codebase, analyze codebase	codebase-mapping.md

触发模式	参考文档
Initialize project, setup project	project-init.md
Create roadmap, plan features	roadmap.md
Map codebase, analyze codebase	codebase-mapping.md

Feature-Level

功能级触发

Trigger Pattern	Reference
Create new feature, new feature	initialize.md (greenfield)
Modify feature, improve feature	initialize.md (brownfield)
Create technical plan	plan.md
Research technology, cache research	research.md
Create tasks	tasks.md
Implement task	implement.md
Validate	validate.md
Archive	archive.md
List features, show status	status-specs.md

触发模式	参考文档
Create new feature, new feature	initialize.md（全新项目）
Modify feature, improve feature	initialize.md（遗留项目）
Create technical plan	plan.md
Research technology, cache research	research.md
Create tasks	tasks.md
Implement task	implement.md
Validate	validate.md
Archive	archive.md
List features, show status	status-specs.md

Guidelines

指南类触发

Trigger Pattern	Reference
How to write specs	spec-writing.md
How to decompose tasks	task-decomposition.md
Codebase exploration	codebase-exploration.md
Research patterns	research.md
Baseline discovery	baseline-discovery.md
Extract from PRD/docs	doc-extraction.md
Coding principles	coding-principles.md
Status workflow, when to update status	status-workflow.md

触发模式	参考文档
How to write specs	spec-writing.md
How to decompose tasks	task-decomposition.md
Codebase exploration	codebase-exploration.md
Research patterns	research.md
Baseline discovery	baseline-discovery.md
Extract from PRD/docs	doc-extraction.md
Coding principles	coding-principles.md
Status workflow, when to update status	status-workflow.md

Cross-References

交叉引用

project-init.md ----> roadmap.md
project-init.md ----> codebase-mapping.md
initialize.md ------> plan.md (when spec complete)
plan.md ------------> tasks.md
plan.md ------------> research.md (if new tech)
tasks.md -----------> implement.md
implement.md -------> coding-principles.md (loaded before coding)
implement.md -------> validate.md
validate.md --------> implement.md (if issues)
validate.md --------> archive.md (if passed)

project-init.md ----> roadmap.md
project-init.md ----> codebase-mapping.md
initialize.md ------> plan.md (when spec complete)
plan.md ------------> tasks.md
plan.md ------------> research.md (if new tech)
tasks.md -----------> implement.md
implement.md -------> coding-principles.md (loaded before coding)
implement.md -------> validate.md
validate.md --------> implement.md (if issues)
validate.md --------> archive.md (if passed)

Guidelines

指南

Content separation: spec=WHAT, plan=HOW, tasks=WHEN
Status flow: draft -> ready -> in-progress -> to-review -> done -> archived
Feature IDs: sequential (001, 002), never reused
Research cache: Reusable across features in .specs/research/
Archive generates: docs/features/{name}.md (no ID)

内容分离：spec=要做什么（WHAT），plan=怎么做（HOW），tasks=何时做（WHEN）
状态流转：草稿 -> 就绪 -> 进行中 -> 待评审 -> 完成 -> 已归档
功能ID：按顺序编号（001、002），不得重复使用
研究缓存：可在.specs/research/中跨功能复用
归档时生成：docs/features/{name}.md（不含ID）

Error Handling

错误处理

No .specs/: Suggest initialize project first
Spec not found: List available features
Open questions blocking architecture: Resolve before planning
Plan not found: Suggest plan before tasks
Tasks not found: Suggest tasks before implement

无.specs/目录：建议先初始化项目
未找到规格说明：列出可用功能
架构存在未解决的问题：规划前需先解决
未找到规划文档：建议先完成规划再创建任务
未找到任务文档：建议先创建任务再开始实现