Spec Kit 实战 08 · 检查清单与资料来源
预计阅读 14 分钟

Spec Kit 实战 08 · 检查清单与资料来源

教程发布于 2026年9月9日更新于 2026年9月14日

上一章：反模式与故障排查 | 返回索引

阅读指南 这一章没有故事，但大概是最常被翻的一章。上线前后对着第 1 节逐项打勾；核对三个案例的一致性看第 2 节；全部事实来源和调研边界在第 3、4 节。附录性质，不必通读。

1. 项目接入检查清单

安装与初始化

  • 固定 Spec Kit release，并记录安装来源。
  • specify version、specify check 已执行。
  • specify integration list 显示预期 agent。
  • CI 使用 --non-interactive --integration <key>。
  • Brownfield 使用 --force 前已有干净、可回滚基线。
  • 已决定是否需要可选 git 扩展。
  • 团队知道活动 feature 不只由 Git 分支决定。

Constitution

  • 每条原则是长期、真实、可执行的项目规则。
  • 没有把单 feature 的业务规则塞进 Constitution。
  • 原则有人工 owner 和修改治理方式。

Specification 与 Clarify

  • 用户、目标、优先级、边界、验收和成功标准齐全。
  • P1 用户故事可独立测试和演示。
  • 业务时间、并发、重复操作、错误语义已明确。
  • Clarify 答案已回写 spec.md。
  • Out of Scope 覆盖最可能膨胀的内容。

Plan 与设计工件

  • Plan 引用真实仓库路径和现有模式。
  • 技术栈和新增依赖经人工批准。
  • research.md 有 Decision/Rationale/Alternatives。
  • 数据模型包含字段、nullable、unique、check 和状态不变量。
  • Contract 与 Spec 的字段、路径和错误码一致。
  • 迁移有向前、回滚和数据安全说明。
  • Quickstart 是可运行验证步骤，不是重复实现代码。

Checklist、Tasks、Analyze

  • Checklist 由 reviewer 勾选，不是 AI 自评。
  • Tasks 按 Setup、Foundational、用户故事、Polish 组织。
  • 每条任务有 ID、故事标签（需要时）、文件路径和可验证结果。
  • data-model.md 的字段约束已进入任务文本。
  • [P] 任务没有同文件或依赖冲突。
  • 需求到任务到测试有追溯矩阵。
  • Analyze 在 Implement 前运行，问题已回源修正并复查。

Implement 与验收

  • 按阶段实施，不一次吞掉大型任务表。
  • 每阶段记录修改文件、测试命令、退出码、未执行项和风险。
  • 并发、事务和迁移测试使用目标数据库或明确验证边界。
  • Brownfield 原有行为有回归测试。
  • Quickstart 在干净环境实际执行。
  • Converge 追加的任务全部完成，并最终报告 Converged。
  • Implemented、tested、accepted、deployed、online-verified 分开记录。

2. 三个案例的一致性核对

图书管理系统

范围固定标识主要证据
图书维护与角色FR-001、FR-002、FR-010、FR-011/api/book/create、/api/book/updateById，T003-T007
搜索与库存FR-003/api/book/queryPage，T008-T009
借还与并发FR-004..FR-007、FR-011/api/loan/create、/api/loan/returnById，T010-T015
借阅状态与逾期FR-008、FR-009/api/loan/queryMemberPage、/api/loan/queryOverduePage，T016-T019
自动化与并发SC-001、SC-002T006、T008、T010、T011、T014、T016、T018、T020
QuickstartSC-003T020-T021

个人博客

范围固定标识主要证据
设置/改期/取消BFR-001..004BT001-BT007
到点发布/补发/幂等BFR-005..007BT008-BT010
旧行为兼容BFR-008BT011-BT013
明确不做审批、通知、周期发布、新队列Out of Scope 与任务反向审计

老项目接入试点

范围固定标识主要证据
文章标签筛选SFR-001..008POST /api/post/queryPage（tag + PageDTO 分页），ST001-ST007、预计文件和回滚表
低风险试点现有列表、标签关联、既有测试docs/spec-kit/brownfield-inventory.md 与 PostListTest.java

OpenSpec 增量变更演练

范围固定标识主要证据
图书系统交付登记FR-001..FR-012 的行为版openspec/specs/circulation/spec.md、openspec validate --specs（第 3 章交付收尾）
存量行为回填现行查询能力的 Requirement/Scenarioopenspec/specs/post-query/spec.md、openspec validate --specs（第 5 章试点收尾）
多标签组合筛选（AND）MFR-001..004第 5 章 §7：openspec/changes/add-multi-tag-filter/（proposal、delta、design、tasks）、交集子查询与 PostListTest 场景
规格同步闭环ADDED 追加、MODIFIED 替换openspec validate --strict、changes/archive/2026-09-12-add-multi-tag-filter/、validate --archived CI gate
并行与协作约束不同能力/不同 Requirement 可并行，同 Requirement 串行第 6 章两阶段 PR 映射与并行变更、第 7 章 OpenSpec 反模式

3. 主要资料来源

除单独标注外，以下链接均于 2026-09-09 访问。

官方规范与源码

  1. github/spec-kit：项目定位、README、源码与模板。
  2. Spec Kit v1.0.5 Release：本指南版本基线，2026-09-08 发布；Release notes 明确包含 PR 4430 的 tasks 约束修复。
  3. Quick Start：短路径、完整路径、活动 feature 解析和命令顺序。
  4. Agentic SDD：Constitution、Specify、Clarify、Checklist、Tasks、Analyze、Implement、Converge 的读写边界。
  5. Core Commands：init 参数、环境变量、版本和检查命令。
  6. Installation：安装渠道、Python/uv/pipx 与脚本类型。
  7. Integrations：agent key、skills/commands 布局和调用差异。
  8. Existing Projects：Brownfield 基线、原地初始化和有界首个 feature。
  9. Spec Persistence Models：Flow-back、Flow-forward、Living spec。
  10. Spec Template、Plan Template、Tasks Template：工件字段、phase 和任务格式。
  11. Git Extension：可选分支、校验和 auto-commit。

官方背景文章

  1. GitHub Blog: Spec-driven development with AI，2025-09-02。
  2. Microsoft for Developers: Diving Into Spec-Driven Development，2025-09-15。

公开项目与社区实践

  1. NASA Hermes Go/React Brownfield Demo，2026-03-16 创建；用于说明薄 spec、无指导 plan、跳过 analyze 后的运行问题。
  2. ASP.NET CMS Brownfield Demo，2026-03-05 创建；用于说明大型旧项目、分次 implement 和人工步骤。
  3. IBM IaC Spec Kit，2025-11-14 创建；展示 Spec Kit 流程的领域化衍生，不等于 GitHub 官方能力。
  4. Spec Kit Community Walkthroughs：官方站点收录的社区案例索引；页面明确说明案例不由 GitHub 审核、背书或支持。
  5. Martin Fowler / Thoughtworks: Understanding Spec-Driven Development，2025-10-15；对可定制性与规格生命周期的独立观察。
  6. OrangeLoops Case Study，2026-05-19；生成与稳定化投入的作者自报案例。
  7. Matsen Group Walkthrough，2026-02-10；完整流程与轻量 issue flow 的个人实践。

Issue 与 Pull Request

  1. Issue 1926：Kiro $ARGUMENTS，当前已关闭。
  2. Issue 4431：Constitution Sync Impact Report 累积，访问时开放。
  3. Issue 4433：Windows OpenSSL DLL 冲突，访问时开放。
  4. Issue 4443：隔离安装与 PyYAML 解释器差异，访问时开放。
  5. PR 4430：Tasks 保留 data-model 字段约束，2026-09-08 合并并进入 v1.0.5 Release notes。

OpenSpec 官方资料

以下链接均于 2026-09-10 访问，对应 @fission-ai/openspec 1.13.0：

  1. Fission-AI/OpenSpec：定位、Quick Start、/opsx:* 工作流与各工具拼写差异、openspec/ 目录约定。
  2. docs/cli.md：init/list/validate/archive 等命令的参数、退出码与 --strict、--archived、--yes 行为。
  3. docs/concepts.md：specs 与 changes 的语义、Requirement/Scenario 语法（RFC 2119 关键字）、delta 的 ADDED/MODIFIED/REMOVED 合并规则、proposal/design/tasks 章节约定。
  4. npm @fission-ai/openspec：版本确认与安装要求（Node.js 20.19.0+）。

4. 调研边界与版本差异

已多来源确认

  • Spec Kit 是 CLI、agent 集成、Markdown 模板和脚本组成的过程工具，不是独立代码生成模型。
  • 核心工件链是 Spec -> Plan -> Tasks -> Implement；Clarify、Checklist、Analyze、Converge 提供质量闭环。
  • 新项目和已有项目都支持；已有项目不需要先为全部旧代码补规格。
  • 人工业务决策、架构评审、真实测试和 code review 不可替代。
  • OpenSpec 的 specs（现行能力）与 changes（提案）分离、delta 按 ADDED/MODIFIED/REMOVED 在归档时合并、validate 的结构校验与 MODIFIED 对照、validate --archived 的任务勾选检查，均来自官方 README 与 docs/cli.md、docs/concepts.md。

工具实际行为与本指南建议

  • /speckit.analyze 只读、/speckit.converge 只可能追加任务：官方行为。
  • 两阶段 PR、分阶段 Implement、需求追溯矩阵：工程建议，不是 CLI 强制。
  • 需求简报/Backlog、Planning Brief、实施报告：本指南的工作方法补充，不是 Spec Kit 标准产物。
  • 示例代码统一采用 Java 8、Spring Boot 2、MyBatis-Plus 3.4、MySQL、Maven 多模块、ResultDTO/CodeEnum 统一响应、xxl-job 定时任务的工程基线；该基线是示例载体选择，Spec Kit 对技术栈保持中立。
  • “10 分钟 quickstart”：案例成功标准，不是 Spec Kit 通用指标。

尚未确认或可能变化

  • v1.0.5 之后的命令、集成列表、skills/commands 布局、扩展/预设 API 可能改变。
  • PR 4430 已列入 v1.0.5 Release notes；旧案例和社区文章仍可能基于 v1.0.4 或更早行为，使用时按本地 specify version 复核。
  • 本调研没有实机初始化和验证所有 30+ agent。
  • 三个教学案例没有在当前目录实际构建和部署；代码片段不能作为生产正确性证据。
  • OpenSpec 相关内容基于 1.13.0（2026-09-10）；1.x 内 CLI 参数与 /opsx:* 命令形态仍在演进，store、workset 等能力官方标注 beta，使用时以本地 openspec --version 与官方文档为准。
  • 社区文章中的时间、任务数和收益是作者自报，不是受控基准。
  • 社区扩展、预设和衍生项目不等于 GitHub 官方审计或支持。

5. 文档维护检查

  • 运行链接检查，内部相对链接和外部来源可访问。
  • 所有代码围栏成对闭合并带合适语言标记。
  • Mermaid 能解析且节点文字不依赖 HTML 专有扩展。
  • 新增版本事实有来源和访问日期。
  • 不把 open Issue 或 merged-after-release PR 写成当前 release 行为。
  • 案例编号、接口和任务变更时同步更新追溯矩阵。
  • 不再维护内容重复的单文件汇总或 HTML 副本。
  • OpenSpec 用法与所引版本（1.13.0）一致，命令参数变化时同步更新。

返回索引

继续阅读

推荐阅读

教程2026年9月9日Spec Kit 中文实战指南（系列导读）系列导读：这套资料写给准备把 Spec Kit 用进真实项目的开发者。图书管理系统走完整流程；个人博客定时发布解释增量变更；老项目接入章再用文章标签筛选做小范围试点。教程2026年9月9日Spec Kit 实战 01 · 认识 Spec Kit：从一个开发问题开始Spec Kit 实战系列第 1/8 章：先看产物如何流动、命令在哪里运行。教程2026年9月9日Spec Kit 实战 02 · 安装与项目初始化Spec Kit 实战系列第 2/8 章：安装 v1.0.5，分别初始化新项目和已有项目。
Spec Kit 实战 08 · 检查清单与资料来源 | 博击长空