Spec Kit 实践指南

从零上手 GitHub Spec Kit：安装、初始化、九步命令链逐一拆解，配中文示例与落地建议。本文基于对 spec-kit 仓库（README.md、spec-driven.md、templates/、docs/）的实际阅读整理，版本以 1.0.0 之后的形态为准。

1. 项目定位与核心理念

1.1 一句话定位

Spec Kit 是 GitHub 开源的规范驱动开发（Spec-Driven Development, SDD）工具包：一个 specify CLI + 一套斜杠命令模板，让你在任意 AI 编码 agent（Claude Code、Copilot、Gemini CLI 等 40+ 种集成）中，走一条"先定义要构建什么，再构建"的结构化流程。

1.2 核心理念：规格即源码

spec-driven.md 称之为 The Power Inversion（权力反转）：传统开发中代码是真理之源，规范只是脚手架，写完即弃；SDD 把这个关系倒过来——

• 规范不服务于代码，代码服务于规范。spec 是 source of truth，代码是从 spec 生成的、可再生的表达物。
• 可执行规范（Executable Specifications）：spec 必须精确、完整、无歧义到足以生成可工作的系统，从而消除"意图与实现之间的鸿沟"。
• 维护软件 = 演进规范。调试意味着修复产生错误代码的规范；加新功能意味着重访 spec 并生成新的实现计划。过程是 0 → 1, (1', ...), 2, 3, N。
• 持续求精而非一次性门禁：一致性验证贯穿全程；生产反馈（指标、事故）回流为新的非功能需求。

README 的 "Core Philosophy" 概括为四条：意图驱动开发（先说 what 再说 how）、带护栏的富规范创建、多步求精而非一次性 prompt 生成、深度依赖先进 AI 模型的规范理解能力。

1.3 模板如何"驯化" LLM

spec-driven.md 专门用一节说明模板是对 LLM 的约束性提示，关键点：

• 阻止过早陷入实现细节：spec 模板明确要求"✅ 聚焦 WHAT 和 WHY，❌ 避免 HOW（技术栈、API、代码结构）"。
• 强制显式的不确定性标记：不允许 LLM"合理地瞎猜"，必须标 [NEEDS CLARIFICATION: 具体问题]（如认证方式未指明 - 邮箱密码 / SSO / OAuth？）。
• 清单即"英语的单元测试"：质量检查清单迫使 LLM 系统性自审。
• 宪法门禁（Constitution Gates）：plan 模板中有 Phase -1 前置门禁（简洁性门禁、反抽象门禁等），未通过必须在 "Complexity Tracking" 中书面说明理由。
• 测试先行排序：文件创建顺序为 contracts → 契约测试 → 集成测试 → e2e → 单元测试 → 源码。

1.4 Constitution：不可违抗的架构约束

宪法（.specify/memory/constitution.md）是项目的"架构 DNA"。spec-driven.md 描述了九条纲领（Nine Articles）的参考结构：

• Article I 库优先：每个功能必须先以独立库的形态存在；Article II CLI 接口强制：一切功能可通过文本 in/out 的 CLI 触达（可观测、可测试）；Article III 测试先行（NON-NEGOTIABLE）：先写测试、用户批准、确认测试失败（Red）后才写实现。
• Article IV–VI 由项目自定义：Spec Kit 只给占位与示例（集成测试、可观测性、版本化等），各项目填入自己的不可协商标准。/speckit.analyze 会按项目实际的宪法做合规检查。
• Article VII/VIII 简洁与反抽象：初始实现最多 3 个项目、直接使用框架而非包装；Article IX 集成测试优先：真实数据库优于 mock。

2. 安装与初始化

2.1 前置条件

• Linux/macOS/Windows（PowerShell 脚本原生支持，无需 WSL）
• Python 3.11+、uv（推荐）或 pipx
• Git（可选——只有启用 git 扩展时才必需）
• 一个受支持的 AI 编码 agent

2.2 安装 Specify CLI

# 推荐：从 GitHub 源码安装，pin 到具体 release tag（保留前导 v，例如 v0.12.11）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

# 或者从 PyPI 安装
uv tool install specify-cli

# 验证
specify version

# 后续升级（self 子命令，自动识别 uv tool / pipx 安装方式）
specify self check              # 只读检查是否有新版本
specify self upgrade --dry-run  # 预览升级动作
specify self upgrade            # 原地升级到最新稳定版

2.3 初始化项目

specify init my-project --integration claude
cd my-project

# 在已有仓库中原地初始化（brownfield）：
# 先提交/暂存现有工作、建一个可评审的分支，然后：
specify init --here --force --integration claude

# CI / 无键盘环境：加 --non-interactive，未指定的选择走文档化默认值而不是卡在方向键选择器
specify init my-project --non-interactive --ignore-agent-tools

--integration 指定 agent 集成，内置目录里有 40+ 个：claude、copilot、gemini、codex、cursor-agent、codebuddy、kimi、qwen、opencode、trae、kiro-cli、pi、omp 等。运行 specify integration list 查看你安装版本支持的全部集成。交互式终端会让你现场选；非交互（CI、管道）默认选 GitHub Copilot，除非显式传 --integration。

自动化脚本有三种变体：--script sh（Linux/macOS 默认）、--script ps（Windows 默认）、--script py。对支持 skills 模式的集成，可用 --integration-options="--skills" 安装 agent skills 而非斜杠命令 prompt 文件。

2.4 初始化后的目录结构

my-project/
├── .specify/
│   ├── memory/
│   │   └── constitution.md      # 项目宪法（/speckit.constitution 生成）
│   ├── templates/               # spec/plan/tasks/checklist/constitution 模板
│   │   └── overrides/           # 项目级一次性模板覆盖（优先级最高）
│   ├── scripts/
│   │   └── bash/                # setup-plan.sh、check-prerequisites.sh 等
│   ├── feature.json             # 记录"当前活跃特性目录"的状态文件
│   └── init-options.json        # 初始化选项（如 feature_numbering）
├── specs/                       # 各特性的工件目录（运行后生成）
└── .claude/commands/ 等         # 按所选集成写入的斜杠命令文件

2.5 命令的调用形式

大多数 agent 把 Spec Kit 暴露为 /speckit.* 斜杠命令（如 /speckit.specify）；Codex CLI 和 Command Code 的 skills 模式用 $speckit-*；Kimi 用 /skill:speckit-*；GitHub Copilot CLI 用 /agents 选择 agent。README 的命令表里同时列出了两种写法（如 /speckit.specify 对应 skill 名 speckit-specify）。本文统一用 /speckit.* 形式，请按你的 agent 实际暴露的形式替换。

3. 完整工作流命令链

官方 quickstart 给出两条路径：

converge 与 implement 构成循环：重复 implement → converge，直到 converge 报告 Converged（已收敛）。下面按全路径逐步拆解。

3.1 /speckit.constitution — 立规矩（每项目一次）

做什么：根据你传入的原则文本，填充 constitution-template.md，生成 .specify/memory/constitution.md。该命令有明确的范围护栏：只做宪法更新，绝不碰应用代码；若你的输入里夹带了"顺手实现某功能"之类的非治理意图，它会被列为 deferred intent 而不执行。

产出：.specify/memory/constitution.md（含版本号、批准日期、修订日期）。被谁读：specify、plan、tasks、analyze、converge 都会在执行时加载它作为治理约束。

中文示例：

/speckit.constitution 本项目"安全优先"：所有用户输入必须校验；
数据库迁移必须附回滚方案；遵循现有服务边界，不引入新框架；
所有 PR 必须通过既有的单元与集成测试套件。

3.2 /speckit.specify — 描述要构建什么

做什么：把一句自然语言特性描述变成结构化 spec。命令内部流程（见 templates/commands/specify.md）：

1. 从你的描述提炼 2–4 个词的短名（如 user-auth、analytics-dashboard）；
2. 在 specs/ 下创建特性目录——编号方式由 init-options.json 的 feature_numbering 决定：sequential（默认，扫描已有目录取下一个三位数）或 timestamp（YYYYMMDD-HHMMSS 前缀），目录形如 specs/003-user-auth/；并把路径写入 .specify/feature.json；
3. 复制 spec 模板为 spec.md 并填充：用户场景（按 P1/P2/P3 优先级排序）、Given/When/Then 验收场景、边界情况、编号功能需求（FR-001...）、关键实体、可度量成功标准（SC-001...）、假设；
4. 自动生成质量清单 checklists/requirements.md 并逐项自检，最多迭代 3 轮修复；
5. 歧义处理：最多标 3 个 [NEEDS CLARIFICATION]，只用于影响范围/安全/体验且无合理默认的关键决策；有遗留标记时，会以"选项 A/B/C/自定义"的表格形式向你提问，用你的回答回填。

产出：specs/<NNN-特性名>/spec.md + specs/<NNN-特性名>/checklists/requirements.md。被谁读：clarify、plan、tasks、analyze、converge。

中文示例 —— 从一个产品想法到 spec.md：

/speckit.specify 做一个团队待办看板：预设的五名成员可以创建项目、
在"待办/进行中/待评审/已完成"四列之间拖拽任务卡片、在卡片下评论。
第一阶段不做登录，预置三个示例项目。

生成的 specs/001-team-kanban/spec.md 大致长这样（节选，注释为本文所加）：

# Feature Specification: 团队待办看板

**Feature Branch**: `001-team-kanban`
**Status**: Draft

### User Story 1 - 看板拖拽管理任务 (Priority: P1)

成员在看板上把任务卡片在四列之间拖动，直观反映任务状态。

**Why this priority**: 这是产品的核心价值，仅这一条就能构成可演示的 MVP。

**Independent Test**: 创建任务并拖入"进行中"，刷新页面后状态保持。

**Acceptance Scenarios**:

1. **Given** 看板存在一个"待办"任务, **When** 成员将其拖入"进行中", **Then** 卡片移动且状态持久化
2. **Given** 卡片已在"已完成", **When** 成员拖回"待办", **Then** 允许回退且评论保留

### User Story 2 - 任务评论 (Priority: P2)
...

### Edge Cases

- 两个成员同时拖动同一张卡片时如何处理？[NEEDS CLARIFICATION: 并发策略未指定 —— 后写覆盖还是冲突提示？]

### Functional Requirements

- **FR-001**: 系统 MUST 提供四个固定状态列：待办、进行中、待评审、已完成
- **FR-002**: 用户 MUST 能够通过拖拽改变任务状态
- **FR-003**: 系统 MUST 持久化任务状态与评论
- **FR-006**: 系统 MUST 记录操作者身份 [NEEDS CLARIFICATION: 无登录阶段如何标识成员——会话选择还是固定账号？]

### Measurable Outcomes

- **SC-001**: 成员可在 10 秒内完成一次状态变更
- **SC-002**: 拖拽操作反馈延迟小于 300ms
- **SC-003**: 95% 的新成员无需培训即可完成首次任务移动

3.3 /speckit.clarify — 消除歧义（推荐在 plan 之前）

做什么：对当前 spec 做结构化的"歧义与覆盖度扫描"，覆盖功能范围、领域数据模型、交互/UX、非功能属性（性能/可靠性/安全）、外部依赖、边界与失败处理、约束取舍、术语一致性、完成信号等类目，然后最多提 5 个高针对性问题，把你的回答编码回 spec（更新对应需求条目并在 Clarifications 小节留痕），同时维护 checklists/requirements.md。

产出：更新后的 spec.md（原地修改）。如果你明确说这是探索性 spike 要跳过澄清，命令允许继续，但会警告下游返工风险上升。

/speckit.clarify 聚焦任务卡片行为——状态变更、评论权限与成员指派

3.4 /speckit.plan — 技术方案与设计工件

做什么：这是"实现细节该出现的地方"。命令读取 spec + 宪法，运行 setup-plan.sh --json 拿到上下文后按 plan 模板执行：

1. 填 Technical Context（语言/依赖/存储/测试/平台/性能目标/约束/规模，未知项标 NEEDS CLARIFICATION）；
2. Constitution Check 门禁：Phase 0 研究前必须过，Phase 1 设计后复查；违规且不书面论证则 ERROR；
3. Phase 0 研究：每个未知项/技术选型派发研究任务，结论汇入 research.md（格式：Decision / Rationale / Alternatives considered），解决所有 NEEDS CLARIFICATION；
4. Phase 1 设计：从 spec 抽取实体生成 data-model.md（字段、关系、校验规则、状态迁移）；为对外接口生成 contracts/（REST 端点、CLI 命令 schema、库 API 等，纯内部项目可跳过）；生成 quickstart.md——可运行的端到端验证场景指南（前置条件、运行命令、预期结果），不含实现代码。

产出：plan.md、research.md、data-model.md、contracts/、quickstart.md。被谁读：tasks、analyze、implement、converge。

/speckit.plan 前端用 React + Vite，后端 Node.js + Express，SQLite 持久化；
拖拽用原生 HTML5 Drag API；REST API 暴露项目/任务/评论资源。

生成的 plan.md 骨架（节选）：

# Implementation Plan: 团队待办看板

**Branch**: `001-team-kanban` | **Date**: 2026-09-15 | **Spec**: [spec.md](spec.md)

## Summary
单页看板应用：React 前端 + Express REST API + SQLite，原生拖拽。

## Technical Context

**Language/Version**: TypeScript 5.x（前后端统一）
**Primary Dependencies**: React 19, Vite, Express, better-sqlite3
**Storage**: SQLite（本地文件）
**Testing**: Vitest + Playwright
**Target Platform**: 现代浏览器（桌面优先）
**Performance Goals**: 拖拽反馈 < 300ms
**Constraints**: 无登录；单机部署

## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
- [x] 输入校验：所有 API 入口校验任务字段 ✓
- [x] 无新框架引入 ✓

## Project Structure
### Documentation (this feature)
specs/001-team-kanban/
├── plan.md              # 本文件（/speckit.plan 产出）
├── research.md          # Phase 0 产出
├── data-model.md        # Phase 1 产出
├── quickstart.md        # Phase 1 产出
├── contracts/           # Phase 1 产出
└── tasks.md             # Phase 2 产出（由 /speckit.tasks 生成，不是本命令）

## Complexity Tracking
> 仅当 Constitution Check 有需论证的违规时填写

3.5 /speckit.checklist — 给需求写"单元测试"（可选质量门）

做什么：按你指定的领域（如 UX、安全、无障碍）生成自定义质量清单到 checklists/ 目录。关键概念（命令原文）：清单是"需求写作的单元测试"——验证的是需求的完整性/清晰度/一致性，不是验证代码或实现是否符合 spec。条目编号为 CHK001、CHK002…。

3.6 /speckit.tasks — 拆解为可执行任务

做什么：读取 plan.md（必需）、spec.md（必需，取用户故事优先级）、以及可选的 data-model.md / contracts/ / research.md / quickstart.md，生成按用户故事组织的 tasks.md——每个故事一个 Phase，可独立实现、独立测试、独立交付 MVP 增量。

严格格式（命令文件强调为 REQUIRED）：

- [ ] [TaskID] [P?] [Story?] 带确切文件路径的描述

• 复选框：永远以 - [ ] 开头；实现完成后由 implement 标成 [X]；
• Task ID：按执行顺序编号 T001、T002…；
• [P]：仅当任务可并行（不同文件、不依赖未完成任务）；
• [Story]：仅用户故事阶段的任务必须带（[US1]、[US2]…）；Setup/Foundational/Polish 阶段不带；
• 描述：必须含确切文件路径；data-model 中的字段约束（最大长度、必填、枚举值）要逐字引用进任务描述，不留给实现时自由发挥。

阶段结构：Phase 1 Setup（项目初始化）→ Phase 2 Foundational（阻塞所有故事的前置设施：数据库 schema、鉴权框架、错误处理等）→ Phase 3+ 每个用户故事一个阶段（故事内顺序：测试（如要求）→ 模型 → 服务 → 端点 → 集成）→ 最终 Polish 阶段（文档、清理、跑 quickstart.md 验证）。

中文示例 tasks.md（节选）：

# Tasks: 团队待办看板

## Phase 1: Setup (Shared Infrastructure)

- [ ] T001 按 plan.md 创建项目结构
- [ ] T002 初始化 Vite + React 前端与 Express 后端依赖
- [ ] T003 [P] 配置 ESLint 与 Prettier

## Phase 2: Foundational (Blocking Prerequisites)

- [ ] T004 建立 SQLite schema 与迁移框架（tasks/projects/comments 表）
- [ ] T005 [P] 实现 Express 路由与统一错误处理中间件
- [ ] T006 [P] 创建全局日志配置

**Checkpoint**: 基础设施就绪 —— 用户故事可并行开工

## Phase 3: User Story 1 - 看板拖拽管理任务 (Priority: P1) 🎯 MVP

**Independent Test**: 创建任务拖入"进行中"，刷新后状态保持

### Implementation for User Story 1

- [ ] T007 [P] [US1] 创建 Task 模型 src/models/task.ts（status 枚举: todo|doing|review|done）
- [ ] T008 [P] [US1] 实现任务 CRUD API src/routes/tasks.ts
- [ ] T009 [US1] 实现看板拖拽组件 src/components/Board.tsx（依赖 T007）
- [ ] T010 [US1] 接入拖拽持久化：drop 后调用 PATCH /tasks/:id

**Checkpoint**: US1 可独立演示 —— 即 MVP

## Phase 4: User Story 2 - 任务评论 (Priority: P2)
- [ ] T011 [P] [US2] 创建 Comment 模型 src/models/comment.ts
- [ ] T012 [US2] 实现评论列表与提交组件 src/components/Comments.tsx

## Phase N: Polish & Cross-Cutting Concerns
- [ ] T0XX [P] 更新 README 运行说明
- [ ] T0XX 跑 quickstart.md 全部验证场景

tasks.md 还会附"依赖与执行顺序"、"并行机会"、"实现策略（MVP 优先 / 增量交付 / 多人并行）"三节。执行策略的建议是：先 Setup + Foundational，然后只完成 US1 就停下来独立验证——那已是 MVP。

3.7 /speckit.analyze — 跨工件一致性分析（只读）

做什么：在 implement 之前，对 spec.md / plan.md / tasks.md 三份核心工件做非破坏性交叉分析：不一致、重复、歧义、覆盖缺口（哪条 FR 没有任务承接、哪个任务不对应任何需求）、术语漂移，以及宪法冲突（自动判为 CRITICAL）。

产出：结构化分析报告 + 可选的修复建议。它不修改任何文件——发现问题要回到源头（spec/plan/tasks）修好再重跑。宪法冲突的修复方向是调整工件，而不是稀释或重新解释原则；原则本身要改，必须单独走宪法更新流程。

3.8 /speckit.implement — 执行任务

做什么：

1. 先跑前置检查脚本，确认 tasks.md 齐备；
2. 清单门禁：扫描 checklists/ 下所有清单，输出勾选状态表（Total/Checked/Unchecked/Status）；只要有未勾选项就 STOP 并询问"是否仍要继续？(yes/no)"——它只读不改勾选；
3. 加载 tasks.md + plan.md + 全部设计工件 + 宪法；校验/创建 .gitignore、.dockerignore 等忽略文件（按检测到的技术栈）；
4. 按 Phase 执行：尊重依赖顺序、[P] 任务并行、同一文件的任务串行、测试先于实现（TDD）；每完成一个任务在 tasks.md 中把 - [ ] 标成 - [X]；非并行任务失败即中止并报告。

可以一次跑完全部任务，也可以按 Phase 分次执行（大特性推荐后者）。

3.9 /speckit.converge — 收敛验证（与 implement 循环）

做什么：以 spec.md / plan.md / tasks.md 为唯一意图来源（宪法为治理约束），评估当前代码库状态：哪些 FR、验收标准、计划决策、既有任务仍未满足或部分满足，然后把每项剩余工作追加为 tasks.md 底部的新 ## Phase N: Convergence 任务段，交给下一轮 implement 完成。

铁的纪律（APPEND-ONLY）：唯一允许的写操作是向 tasks.md 追加新任务；绝不修改 spec.md / plan.md，绝不重排/重编号/删除既有任务，绝不改应用代码。若代码已满足一切，tasks.md 保持逐字节不变并报告干净结果。这不是 diff 工具——不看 git、不比分支、不追历史，只评现状。

3.10 工件引用关系一览

/speckit.constitution ──► .specify/memory/constitution.md ─┐
                                                           │（被后续所有命令读取为治理约束）
/speckit.specify ──► specs/NNN-x/spec.md ─┐                │
                   └► specs/NNN-x/checklists/requirements.md│
/speckit.clarify ──（原地更新 spec.md + requirements.md）   │
/speckit.plan ──► plan.md, research.md, data-model.md,     │
                  contracts/, quickstart.md                │
/speckit.checklist ──► checklists/<领域>.md（评审者所有）   │
/speckit.tasks ──► tasks.md ◄── 读 spec + plan + 全部设计工件
/speckit.analyze ── 只读交叉检查 spec/plan/tasks           │
/speckit.implement ── 执行 tasks.md（勾选 [X]）◄── 读 checklists 作门禁
/speckit.converge ── 对照 spec/plan/tasks 评代码现状 ──► 追加任务到 tasks.md
        │                                                  │
        └──────────── 循环 ◄────────────────────────────────┘

另有 /speckit.taskstoissues：把 tasks.md 转成 GitHub issues 用于跟踪执行（需要相应的 agent 环境与权限）。

3.11 扩展机制（简述）

核心流程之外，Spec Kit 有三层定制机制：

• Extensions（specify extension add <名>）：加新命令/新能力。官方捆绑了两个可选扩展——bug（/speckit-bug-assess → -fix → -test：评估→修复→验证的修 bug 流程）和 assess（/speckit-assess-intake → -research → -define → -shape → -decide：把原始想法变成 go / needs-clarification / kill 决策，go 可交接给 /speckit.specify）。还有 git 扩展提供编号特性分支。
• Presets（specify preset add <名>）：覆盖核心与扩展的模板/命令——改工件格式、术语、方法论适配，甚至整套流程本地化。模板在运行时按优先级栈解析：项目本地覆盖（.specify/templates/overrides/）> presets > extensions > 核心默认。
• Bundles（specify bundle install <id>）：把一组 extensions + presets 打包成面向角色（产品经理、安全研究员…）的一键配置。

命令模板里还能看到 hooks 机制：.specify/extensions.yml 可注册 before_specify / after_plan 等命令前后钩子，分 optional（提示用户可选执行）与 mandatory（自动执行并等待结果）两类——这是扩展插入确定性行为的入口。

4. 实践建议与常见坑

以下均来自仓库文档与命令定义本身，非经验杜撰：

1. spec 阶段忍住不谈技术栈。模板明确禁止在 spec 中出现语言/框架/API；技术选型留给 /speckit.plan 的参数。spec 里混入实现细节会被质量清单判为不合格项。
2. [NEEDS CLARIFICATION] 最多 3 个。specify 命令硬性限制，且只给"影响范围/安全/体验且无合理默认"的问题；其余做合理猜测并记入 Assumptions。别指望 agent 把所有含糊处都问你——也不要全让它猜，关键分歧主动说清。
3. 别跳过 clarify 直接 plan。clarify 命令自己声明"预期在 plan 之前运行"；显式跳过会得到返工风险警告。
4. analyze 是只读的，别指望它帮你改。它只出报告；修复要回到源工件改完再跑。同样，converge 只追加任务不写代码——代码永远是 implement 的职责。
5. implement 的清单门禁会拦你。checklists/ 里有未勾选项时它会停下来问 yes/no。流程上应在 tasks 之前把该评审的清单评审完（勾选是评审者的动作，不是实现的完成标记）。
6. 活跃特性 ≠ git 分支。命令定位特性靠的是 .specify/feature.json；想切换特性就改它（或设 SPECIFY_FEATURE_DIRECTORY），git checkout 无效。没装 git 扩展时整个流程不依赖 git。
7. tasks.md 的格式红线：缺复选框、缺任务 ID、用户故事阶段缺 [USn] 标签、描述缺文件路径——都是命令文件点名的错误写法。手写或改任务时保持 - [ ] T001 [P] [US1] 描述+路径。
8. 测试任务默认不生成。tasks 命令明确：除非 spec 或用户显式要求测试/TDD，否则不生成测试任务。想要契约测试/集成测试先行，就在 specify 或 tasks 时说出来。
9. 宪法要写实。brownfield 指南强调：用仓库现有的 README、架构决策、CI 配置做证据，写真实成立的原则；为了填满模板编造标准，会在每次 plan 的 Constitution Check 和 analyze 里变成噪音。
10. brownfield 的正确姿势：先在可评审基线上 specify init --here --force（会覆盖受管路径但不会动你的应用代码），再 /speckit.constitution 固化既有护栏，第一个特性选"可独立评审的有界改动"，而不是"给整个存量系统补写 spec"。Spec Kit 工具文件升级与 specs/ 工件演进分开管理（见 docs/guides/evolving-specs.md）。
11. spec 目录名与分支名相互独立。specify 命令每次只创建一个特性；目录编号取下一个可用序号（或时间戳），与 git 分支命名是两回事。

5. 与 AI-Native SDLC Playbook 工件链的对应

对照 Anthropic《The AI-Native SDLC playbook》的工件链 intent.md → spec.md → plan.md → diff+tests → PR+review findings：

治理分层上也对得上：模板与命令提示是建议性控制（advisory），脚本前置检查、implement 的清单门禁、宪法 CRITICAL 判级是更强的约束，而宪法本身与最终 PR 的人工评审保留在人类手中。区别在于 playbook 的闭环由生产环境违规触发新的 intent.md；Spec Kit 的闭环目前收敛在特性内部（implement↔converge），生产反馈回流到 spec 仍靠人发起新一轮 specify。

6. 速查表

参考来源：github/spec-kit 仓库的 README.md、spec-driven.md、docs/quickstart.md、docs/installation.md、docs/guides/existing-projects.md、templates/ 下各模板与 templates/commands/ 下各命令定义（2026-09 阅读）。命令细节以你所安装版本的 specify integration list 与官方文档站（github.github.io/spec-kit）为准。