Spec Kit 中文实战指南（系列导读）

阅读指南这套资料写给准备把 Spec Kit 用进真实项目的开发者。主线是三个案例：图书管理系统从零走一遍完整流程，博客的定时发布演示在已有仓库里做增量，标签筛选试点之后接入 OpenSpec，把规格维护交到工具手里。每一章都从手头的问题出发，写清输入、产物、人工判断，以及进入下一阶段的条件。 第一次读建议按章节顺序走；已经在项目里上手的人，可以把第 7 章当地图、第 8 章当检查表来翻。正文里的五种【标记】帮你区分“工具保证的”和“需要你拍板的”，约定见下一节。

版本基线：GitHub Spec Kit v1.0.5（2026-09-08 发布）。 OpenSpec 基线：@fission-ai/openspec 1.13.0（2026-09-10 确认）。资料访问日期：2026-09-09（Asia/Shanghai）。示例技术栈基线：Java 8、Spring Boot 2、MyBatis-Plus、MySQL、Maven 多模块、ResultDTO/CodeEnum 统一响应、xxl-job 定时任务。Spec Kit 本身对技术栈保持中立，该基线只是本资料的示例载体。

内容标记

标记	含义
【官方能力】	工具官方仓库、文档、模板或脚本明确提供的行为（Spec Kit 与 OpenSpec 均适用）
【AI 产出】	AI 根据输入与仓库上下文生成的内容，不代表自动正确
【人工决策】	必须由开发者、产品、测试、安全或团队负责人确认
【社区实践】	来自公开项目、Issue、PR 或技术文章的经验
【版本相关】	可能随 Spec Kit 版本、集成工具或平台变化

阅读顺序

认识 Spec Kit：先看产物如何流动、命令在哪里运行，并认识 OpenSpec 的定位与分工。
安装与项目初始化：安装 Spec Kit v1.0.5 与 OpenSpec 1.13.0，分别初始化新项目和已有项目。
图书管理系统实战：从 Constitution 一直走到实现、测试、Converge、规格回溯和交付登记。
个人博客增量需求实战：在 brownfield 仓库中增加定时发布，控制兼容边界和需求膨胀。
老项目接入 Spec Kit：以已有博客做一次低风险试点，试点收尾接入 OpenSpec 并走完第一个变更提案。
团队协作与规格维护：组织评审、Git、并行开发和需求变更，并约定 OpenSpec 的并行变更与 CI 门禁。
反模式与故障排查：按症状定位流程和工具问题。
检查清单与资料来源：实施前后核对，并查看事实来源与调研边界。

三个案例的分工

三个案例各管一段：主案例走全流程，博客做增量，标签筛选当试点。贯穿全书的编号（FR、BFR、SFR、MFR 和任务号）在这里固定下来，后面各章和第 8 章的追溯表都对这份清单核对。

主案例：图书管理系统

角色：图书管理员和普通会员；身份由应用上下文提供，登录系统不在本期范围。
P1：图书录入与编辑、查询、借阅与归还、个人借阅状态。
P2：查看逾期借阅。
不做：登录、细粒度权限配置、预约、罚款、采购、多分馆和通知。
贯穿标识：需求 FR-001..FR-012，成功标准 SC-001..SC-003，任务 T001..T021。

补充案例：个人博客定时发布

已有能力：草稿、预览、立即发布、稳定文章 URL、现有 xxl-job 每分钟调度。
新能力：草稿可设置未来时间，到点后仅发布一次。
不做：周期发布、社交分发、失败通知、审批流、用户自选时区。

老项目接入试点：个人博客标签筛选

先盘点技术栈、目录、模型、接口、测试和不能破坏的行为；
只给公开文章列表增加标签筛选与分页；
不做全文搜索、缓存、搜索引擎或无关重构；
重点验证接入步骤、影响文件、回滚和规格同步。

延伸演练：OpenSpec 多标签筛选

两件工具的定位与分工在第 1 章一并介绍；两套 CLI 在第 2 章一起安装（OpenSpec 初始化图书系统）；
第 3 章交付收尾把借还能力登记进 openspec/specs/；第 4 章末尾对照同一次增量在两种工作流下的形态；
第 5 章试点收尾时博客接入 OpenSpec：存量回填查询能力，再以"多标签组合筛选"完整走一遍提案、评审、落地、归档合并的闭环；
第 6、7 章补充并行变更、两阶段 PR 映射、CI 门禁与反模式。

命令记法

同一件事有两套入口。终端里敲 specify ...；AI 编程工具里用的是 command/skill。本文统一写官方文档的 /speckit.* 形式，Codex 这类 skills 集成里可能显示成 $speckit-*，以初始化后实际出现的命令为准。OpenSpec 同理：规范名 /opsx:*，Codex 里显示为 $openspec-*，以 openspec init 后的实际输出为准。

TEXT

1/speckit.constitution 
2-> /speckit.specify 
3-> /speckit.clarify
4-> /speckit.plan 
5-> /speckit.checklist 
6-> /speckit.tasks
7-> /speckit.analyze 
8-> /speckit.implement 
9-> /speckit.converge

阅读完成标准

读完后，至少应该能把下面几件事做起来：

在新仓库或已有仓库中安全初始化 Spec Kit；
把模糊需求写成独立可验收的用户故事；
区分 specification 的 what/why 与 plan 的 how；
让 tasks 保留需求、数据和接口约束；
在实施前用 analyze 找跨文档缺口；
在实施后用测试、人工验收和 converge 分别确认不同层面的完成状态；
选择适合团队的规格维护方式，而不是让文档和代码静默分叉；
在维护期用变更提案和归档合并，维持一份与代码同步的现行规格。