阅读指南 这一章回答两个问题：为什么不能把需求直接丢给 AI 去写代码，以及 Spec Kit 用什么机制把“想清楚”变成可审查的工件。顺带认识本资料的第二个工具 OpenSpec——它和 Spec Kit 一个管从 0 到 1，一个管从 1 到 N。读完你应该能说清 Constitution、Spec、Plan、Tasks 各管什么、由谁拍板。
场景：为什么不能直接让 AI 写代码
团队提出：“做一个图书管理系统。”如果直接交给 coding agent，它必须猜测用户、登录、库存模型、借期、异常语义、技术栈和验收方法。代码可以很快出现，但评审者无法判断“做完”究竟对应哪个需求。
Spec Kit 管的就是这条上下文链。它由 Python CLI、agent command/skill、Markdown 模板和辅助脚本组成，不提供新的编程语言、IDE 或模型。
【官方能力】核心思路是先明确 intent（意图），再逐步生成并审查规格、计划、任务和实现。每个阶段产出的 Markdown 是下一阶段的输入。
产物如何连接
1flowchart LR
2 A[constitution.md<br/>项目原则] --> B[spec.md<br/>需求与验收]
3 B --> C[plan.md<br/>技术方案]
4 C --> D[research.md / data-model.md<br/>contracts / quickstart]
5 D --> E[tasks.md<br/>依赖有序任务]
6 E --> F[代码与测试]
7 B -. analyze .-> E
8 C -. analyze .-> E
9 F -. converge .-> E| 产物 | 回答的问题 | 图书系统示例 | 主要确认人 |
|---|---|---|---|
.specify/memory/constitution.md | 哪些原则不可违反？ | 借还与库存更新必须同一事务 | 团队/架构负责人 |
spec.md | 用户需要什么，怎样算完成？ | 最后一本并发借阅只能一个成功 | 产品、工程、测试 |
plan.md | 在当前仓库中怎样实现？ | 条件更新库存、稳定错误码、DDL 与回滚 | 工程负责人 |
research.md | 为什么选择该方案？ | MySQL 单库并发边界与目标环境差异的验证路径 | 工程负责人 |
data-model.md | 实体和约束是什么？ | Book、Loan | 工程、数据负责人 |
contracts/ | 外部接口是什么？ | /api/book/*、/api/loan/* | 前后端/调用方 |
quickstart.md | 如何端到端验证？ | 导入样例数据并完成一次借还 | 开发、测试 |
tasks.md | 以什么顺序交付？ | T001 到 T021 | 实施者、评审者 |
把上下文分层，不要混成一份“大文档”
经验材料需要分层：能核对的证据、待确认的需求草稿、已批准的规格、技术方案各归其位。放到 Spec Kit 项目里，材料可以分成四层：
| 层 | 保存什么 | 不应该替代什么 |
|---|---|---|
| 证据层 | 用户访谈、旧接口、代码、测试、日志、参考资料原文 | 不能直接冒充已批准需求 |
| 需求简报 | 当前问题、目标、范围、未知项、Backlog | 不能替代可验收的 spec.md |
| 规格层 | 用户故事、规则、边界、验收和成功标准 | 不负责框架、数据库和目录 |
| 技术层 | Plan、Research、Data Model、Contract、Tasks | 不能擅自改写业务目标 |
这样分层有个直接好处：旧文档或外部资料里出现一句话时，团队知道它只是证据、候选需求，还是已经批准的规格。AI 也不必从一份混杂的长文里猜哪些句子具有约束力。
开发、验收和运行是三个阶段
对普通 Web 项目，实用的划分是：
| 阶段 | 允许的动作 | 结果如何生效 |
|---|---|---|
| 开发 | 修改代码、反复运行局部测试 | 尚未形成候选版本 |
| 验收 | 在固定候选版本上执行测试和人工场景 | 发现问题先停止验收，修复后换新候选版本 |
| 运行 | 使用已发布版本处理真实请求 | 不在用户请求执行中顺手改代码 |
当 Agent 在验收途中直接改代码，旧测试结论立刻失效，因为验收对象已经变了。团队需要重新跑相关测试和全量回归，再建立新的版本基线。这是团队工程纪律，不是 Spec Kit CLI 自动强制的行为。
完整工作流与每步所有者
【官方能力】v1.0.5 的完整路径如下。只有 /speckit.specify 是 /speckit.plan 的严格前置；其余质量 gate 是否采用可按风险决定，但生产功能建议保留。
| 步骤 | 工具行为 | AI 可以做 | 人必须做 |
|---|---|---|---|
| Constitution | 创建/更新项目治理原则 | 根据输入起草 | 确认原则真实且可执行 |
| Specify | 从自然语言生成 spec.md | 展开故事、边界、成功标准 | 确认业务语义和范围 |
| Clarify | 最多提出 5 个针对性问题并回写 spec | 找歧义 | 给出确定答案 |
| Plan | 生成 plan 与设计工件 | 调研、设计候选方案 | 批准技术决策、迁移和风险 |
| Checklist | 生成需求质量检查项 | 找需求缺口 | 评审后勾选，不让 AI 自批 |
| Tasks | 生成依赖有序的 tasks.md | 拆分任务 | 检查约束、依赖、粒度 |
| Analyze | 只读检查 spec/plan/tasks | 报告冲突、遗漏、歧义 | 回到源工件修正 |
| Implement | 按任务依赖实施 | 写代码、测试、跑命令 | 审查 diff 与证据 |
| Converge | 对照工件检查实现，仅可向 tasks 追加缺口 | 找漏项 | 完成新增任务并最终验收 |
首次出现的术语
- SDD（Spec-Driven Development）：规格驱动开发。先把目标和约束变成可审查工件，再让工件驱动实现。
- Constitution：项目级原则。它约束所有 feature，不等同于某个需求的验收标准。
- Specification：需求规格。描述 what/why、用户故事、边界和成功标准，不负责选框架。
- Plan：技术计划。说明 how，包括技术栈、结构、数据、接口、迁移、测试和风险。
- Artifact：工件。这里主要指仓库内可版本控制的 Markdown、契约文件和任务清单。
- Quality gate：进入下一阶段前的质量门。Clarify、Checklist、Analyze 都属于此类。
- Brownfield：已有代码和行为约束的项目，与从空目录开始的 greenfield 相对。
- 现行规格（specs）：OpenSpec 中按能力域组织的"系统现在怎么表现"，是变更提案的对照基准。
- 变更提案（change proposal）：OpenSpec 中一次增量的提案目录，含 proposal、delta、design、tasks 四类工件。
- Delta（需求差异）：变更对现行规格声明的 ADDED/MODIFIED/REMOVED 部分，归档时合并回 specs。
短路径与完整路径
【官方能力】小而清晰的功能可以走：
1specify
2-> plan
3-> tasks
4-> implement
5-> converge生产功能或存在明显歧义时走：
1constitution
2-> specify
3-> clarify
4-> plan
5-> checklist
6-> tasks
7-> analyze
8-> implement
9-> converge【人工决策】“短路径”不是让 AI 跳过审查。即使不执行 checklist/analyze，团队也要读 spec.md、plan.md 和 tasks.md。
从 0 到 1 与从 1 到 N：Spec Kit 与 OpenSpec
Spec Kit 的完整路径管的是"从一个想法到一次交付"。交付之后项目进入维护期，小增量不断到来：每次都走完整 feature 目录偏重，直接改代码又会让规格和代码静默分叉。本资料的第二个工具 OpenSpec 管这个阶段，核心机制只有两条：
openspec/specs/是现行能力的唯一事实来源：按能力域组织（如specs/post-query/spec.md），始终描述系统"现在"的行为，不是一次性 feature 快照；openspec/changes/是变更提案：每次增量先落成提案目录（proposal、需求差异 delta、design、tasks），评审通过后落地，归档时 delta 合并回 specs，规格跟着代码一起演进。
它的命令链与 Spec Kit 的 command/skill 一一对应：
1/opsx:explore -> /opsx:propose ->（人工评审）-> /opsx:apply -> /opsx:archive【版本相关】OpenSpec 是独立的 npm CLI（@fission-ai/openspec），安装与初始化见第 2 章；agent 内命令规范名为 /opsx:*，Codex 显示为 $openspec-*。
两件工具不是二选一：
| 维度 | Spec Kit | OpenSpec |
|---|---|---|
| 强项 | 从 0 到 1 的全流程：Constitution、Clarify、Analyze、Converge 等质量 gate | 从 1 到 N 的增量变更：提案、差异合并、规格同步 |
| 规格观 | feature 目录（flow-forward 倾向） | 现行能力目录（living spec 倾向，由归档动作强制同步） |
| 工件 | spec/plan/research/data-model/contracts/tasks | proposal/design/tasks + specs 增量（delta） |
| 适用时机 | 新系统、大 feature、需要治理原则时 | 日常小增量、存量项目的规格补课 |
各章的安排是这样：第 2 到 4 章以 Spec Kit 为主线，两套 CLI 在第 2 章一起装好，第 3 章交付收尾和第 4 章增量对照时 OpenSpec 会先露几面；第 5 章是它的主场，老项目接入、存量回填、第一个变更提案都在那里完成；第 6、7 章再把它放回团队协作与反模式的语境里看。
当前版本容易误解的行为
- 【版本相关】活动 feature 由
.specify/feature.json或SPECIFY_FEATURE_DIRECTORY选择，不由当前 Git 分支自动决定。 - 【官方能力】Git 初始化与 feature 分支由可选
git扩展提供，不是核心初始化的必备条件。 - 【官方能力】
/speckit.analyze是只读报告，不会替你修文档。 - 【官方能力】
/speckit.converge不改代码；它只可能向tasks.md追加缺口任务。 - 【人工决策】AI 产出的 PASS、完成或 Converged 都不等于产品批准、CI 通过、已部署或线上验证。
本章完成检查清单
- 能说明 Constitution、Spec、Plan、Tasks 的区别。
- 知道终端命令与 agent 内命令不是同一套入口。
- 知道 Analyze 与 Converge 的写入边界。
- 不再把 Git 分支当成当前 feature 的唯一来源。
- 能说清 Spec Kit 与 OpenSpec 在"从 0 到 1"与"从 1 到 N"上的分工。