spec-driven

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec-Driven Development

规范驱动开发

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

结构化开发工作流：初始化 -> 规划 -> 任务 -> 实现 + 验证。

Workflow

工作流

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

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

Project Structure

项目结构

.artifacts/
├── 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

.artifacts/
├── 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         # 内容：需求
        ├── plan.md         # 方案：架构设计
        └── tasks.md        # 时间：任务安排

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

Templates

模板

Context	Template
Project initialization	PROJECT.md
Roadmap	ROADMAP.md
Feature changelog	CHANGELOG.md
Feature spec	spec.md
Technical plan	plan.md
Task breakdown	tasks.md
Archive document	archive.md
Codebase exploration	exploration.md
Research cache	research.md

场景	模板
项目初始化	PROJECT.md
路线图	ROADMAP.md
功能变更日志	CHANGELOG.md
功能规范	spec.md
技术方案	plan.md
任务拆分	tasks.md
归档文档	archive.md
代码库探索	exploration.md
研究缓存	research.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	tasks.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	tasks.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

指南

DO:

Separate content by purpose: spec=WHAT, plan=HOW, tasks=WHEN
Follow status flow: draft -> ready -> in-progress -> to-review -> done -> archived
Use sequential Feature IDs (001, 002)
Reuse research cache across features (.artifacts/research/)
Archive to docs/features/{name}.md (without ID prefix)

DON'T:

Reuse Feature IDs from previous features
Mix spec, plan, and task content in a single file
Skip status transitions (e.g., jumping from draft to done)
Create feature-specific research files outside .artifacts/research/

应做：

按用途区分内容：spec=需求内容、plan=实现方案、tasks=时间安排
遵循状态流转：草稿 -> 就绪 -> 进行中 -> 待评审 -> 完成 -> 归档
使用连续的功能ID（001、002）
在功能间复用研究缓存（.artifacts/research/）
归档至docs/features/{name}.md（不带ID前缀）

不应做：

复用之前功能的功能ID
在单个文件中混合spec、plan和task内容
跳过状态流转（例如从草稿直接跳至完成）
在.artifacts/research/之外创建功能专属的研究文件

Error Handling

错误处理

No .artifacts/: 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

无.artifacts/目录：建议先初始化项目
未找到规范：列出可用功能
存在阻碍架构设计的未解决问题：先解决问题再进行规划
未找到方案文档：建议先规划再创建任务
未找到任务文档：建议先创建任务再开始实现