spec-driven-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec-Driven Development

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

Specs live in

.claude/specs/

. They are the source of truth for architectural decisions, API contracts, and implementation scope. Implementation and specs must stay in sync — neither leads exclusively.

规范文件存储于

.claude/specs/

目录下，是架构决策、API契约以及实现范围的唯一可信来源。实现与规范必须保持同步——二者并非单向主导关系。

Core Loop

核心循环

Read spec → Implement → Verify alignment → Update spec or code → Repeat

阅读规范 → 实现开发 → 验证一致性 → 更新规范或代码 → 重复执行

Before Starting Work

开始工作前

Find the spec. Search
```
.claude/specs/
```
for files matching the feature:

bash

ls .claude/specs/

Read the full spec. Understand scope, decisions, API contracts, and open questions before writing code.
If no spec exists and the task is non-trivial (new module, new API, architectural change), ask the user whether to create one first.

查找规范：在
```
.claude/specs/
```
目录下搜索与目标功能匹配的文件：

bash

ls .claude/specs/

通读完整规范：在编写代码前，充分理解功能范围、决策依据、API契约以及待解决问题。
若不存在对应规范且任务较为复杂（如新模块、新API、架构变更），请先询问用户是否需要先创建规范文件。

During Implementation

开发过程中

Reference spec decisions — don't re-decide what the spec already settled.
When you diverge from the spec (better approach found, user requested change, constraint discovered), update the spec immediately in the same session. Don't leave spec and code out of sync.
Tick off TODO checkboxes (
```
- [ ]
```
→
```
- [x]
```
) as items are completed.
Strike through or annotate items that were deliberately skipped or replaced, with a brief reason:
markdown
```
- [x] ~~OpenRouter proxy~~ → Direct execution: nodes call OpenRouter directly
```

遵循规范决策——不要重新制定规范中已明确的内容。
当与规范出现偏差时（如发现更优方案、用户要求变更、遇到约束限制），请在同一工作会话中立即更新规范。切勿让规范与代码脱节。
完成项勾选：随着任务推进，将TODO复选框从
```
- [ ]
```
改为
```
- [x]
```
。
标注跳过或替换项：对于故意跳过或替换的内容，使用删除线并附上简短说明：
markdown
```
- [x] ~~OpenRouter代理~~ → 直接执行：节点直接调用OpenRouter
```

After Completing Work

工作完成后

Run a spec verification pass:

Re-read the spec alongside the implementation.
Check each section:
- Do API endpoints in spec match the controller?
- Do config/env vars in spec match the config class?
- Does the module structure in spec match the actual file tree?
- Do type definitions in spec match
```
@n8n/api-types
```
  ?
- Are all TODO items correctly checked/unchecked?
Update the spec for any drift found. Common drift:
- New files added that aren't listed in the structure section
- API response shapes changed during implementation
- Config defaults adjusted
- Architectural decisions refined
Flag unresolved gaps to the user — things the spec promises but implementation doesn't deliver yet (acceptable for MVP, but should be noted).

执行规范验证流程：

对照实现重新阅读规范。
逐一检查各部分：
- 规范中的API端点是否与控制器实现一致？
- 规范中的配置/环境变量是否与配置类匹配？
- 规范中的模块结构是否与实际文件目录一致？
- 规范中的类型定义是否与
```
@n8n/api-types
```
  匹配？
- 所有TODO项的勾选状态是否正确？
针对偏差更新规范：常见偏差包括：
- 新增文件未在结构章节中列出
- 开发过程中API响应格式发生变更
- 配置默认值被调整
- 架构决策被优化
向用户标记未解决的差距——规范中承诺但尚未实现的内容（MVP版本中可接受，但需明确标注）。

Spec File Conventions

规范文件约定

One or more markdown files per feature in
```
.claude/specs/
```
.
Keep specs concise. Use tables for mappings, code blocks for shapes.
Use
```
## Implementation TODO
```
with checkboxes to track progress.
Split into multiple files when it helps (e.g. separate backend/frontend), but don't enforce a rigid naming scheme.

每个功能对应
```
.claude/specs/
```
目录下的一个或多个Markdown文件。
规范需简洁明了。使用表格呈现映射关系，代码块展示数据结构。
使用
```
## 实现TODO
```
章节搭配复选框跟踪进度。
必要时可拆分为多个文件（如前后端分离），但无需强制遵循严格的命名规则。

When the User Asks to "Self-Review" or "Verify Against Spec"

当用户要求“自我审查”或“对照规范验证”时

Read all relevant specs.
Read all implementation files.
Produce a structured comparison:
- Aligned: items where spec and code match
- Drift: items where they diverge (fix immediately)
- Gaps: spec items not yet implemented (note as future work)
Fix drift, update specs, report gaps to the user.

阅读所有相关规范文件。
阅读所有实现代码文件。
生成结构化对比结果：
- 一致项：规范与代码匹配的内容
- 偏差项：二者存在差异的内容（需立即修复）
- 差距项：规范中已定义但尚未实现的内容（标注为未来工作）
修复偏差，更新规范，并向用户报告差距情况。