spec-kit 社区实战 Walkthrough：七种真实场景拆解规范驱动开发的绿场、棕场与定制玩法
【免费下载链接】spec-kit💫 Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit
Community Walkthroughs 是 spec-kit 仓库中专收社区贡献实战案例的入口文档（docs/community/walkthroughs.md），它收录了七个完整跑通 Spec-Driven Development（SDD）工作流的演示项目，覆盖从零搭建（greenfield）与存量代码扩展（brownfield）两大场景，并分别验证了 preset 与 extension 两种官方定制机制。读完本篇，你不仅能快速判断哪个 walkthrough 与自己的技术栈和场景匹配，还能理解这些演示背后依赖的 preset 模板解析、extension 命令注册等底层机制，把"照着看"升级为"照着做"。
一、社区 Walkthrough 是什么、不是什么
在进入具体案例之前，必须先明确 docs/community/walkthroughs.md 中对这类内容的官方定位，这决定了你使用它们时的正确姿势：
- 独立创作与维护：每个 walkthrough 由其作者独立创建和维护，未经官方审查、背书或支持。跟做之前请先审阅其内容，风险自负。
- 只读示例而非黄金输出：它们是"已完成流程"的有用只读示例（useful read-only examples of completed flows），但不是对 spec、plan、tasks 产物的官方黄金输出。也就是说，演示项目中生成的
spec.md、plan.md、tasks.md只是"某一次运行"的结果，官方并不保证这些产物是最优写法。 - 学习价值在于流程形态：每个案例真正值得研究的是它如何把 constitution → specify → plan → tasks → implement 这条主线（以及 clarify、analyze 等质量门）套用到不同约束条件上——不同语言、不同体量、不同起点。
二、七个 Walkthrough 全景
docs/community/walkthroughs.md 当前收录的七个案例可以按"起点"与"机制验证点"两个维度归纳：
| # | 案例 | 起点 | 技术栈 | 核心演示点 |
|---|---|---|---|---|
| 1 | Greenfield .NET CLI 工具 | 空白目录 | .NET 单二进制 CLI | 完整走通 constitution → specify → plan → tasks → 多轮 implement，使用 GitHub Copilot agents |
| 2 | Greenfield Spring Boot + React 平台 | 从零搭建 | Spring Boot + React + PostgreSQL + Docker Compose | 构建 LLM 性能分析平台（REST API、图表、迭代追踪），额外加入 clarify 步骤和跨产物一致性分析 |
| 3 | Brownfield ASP.NET CMS 扩展 | 存量开源 CMS（CarrotCakeCMS-Core，约 30.7 万行 C#/Razor/SQL/JS/配置） | ASP.NET | 为存量系统加两个新特性：跨平台 Docker Compose 基础设施 + 令牌认证的 headless REST API，演示无 spec、无 constitution 前提下的落地方式 |
| 4 | Brownfield Java 运行时扩展 | 存量开源 Jakarta EE 运行时（Piranha，约 42 万行 Java/XML/JSP/HTML/配置，180 个 Maven 模块） | Java | 增加带密码保护的 Server Admin Console，演示大型多模块 Java 工程在无既有 spec/constitution 时如何使用 spec-kit |
| 5 | Brownfield Go / React 仪表盘 | 存量开源系统（NASA Hermes 地面支持系统，Go） | Go + React | 全程仅在终端内通过 GitHub Copilot CLI 驱动spec-kit，为 Hermes 扩展轻量级 Web 遥测仪表盘，证明 constitution → specify → plan → tasks → implement 全流程可以在终端完成 |
| 6 | Greenfield Spring Boot MVC + 自定义 preset | 从零搭建 | Spring Boot MVC | 使用自定义"海盗语"preset 重塑整个 spec-kit 体验：spec 变成 "Voyage Manifests"、plan 变成 "Battle Plans"、tasks 变成 "Crew Assignments"，全篇海盗腔生成而不改动任何工具链 |
| 7 | Greenfield Spring Boot + React + 自定义 extension | 从零搭建 | Spring Boot 4 + React 19 + PostgreSQL + Docker Compose | 走通社区 AIDE 扩展——用"高层 spec（vision）+ 低层 spec（work items）"组织 7 步迭代生命周期（vision → roadmap → 进度追踪 → 工作队列 → 工作项 → 执行 → 反馈回路），以家庭交易平台为场景，演示不碰核心工具链即可换一种 SDD 风格 |
其中案例 1、2、5 分别对应"标准流程"、"标准流程 + 质量门"、"纯终端流程"三种执行形态；案例 3、4 展示棕场大工程；案例 6、7 则是对 spec-kit 两大扩展机制（preset / extension）的端到端验证。
三、绿场案例：从空白目录到多轮实现
3.1 标准主线：.NET CLI 工具演示
第一个案例（Timezone Utility）的看点在于它完整覆盖了 docs/quickstart.md 中"较短路径"的四步主线，并用 GitHub Copilot agents 执行：
/speckit.constitution → /speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement（多轮）"多轮 implement"（multi-pass implement）是实践中的关键技巧。docs/reference/agentic-sdd.md 对/speckit.implement的说明指出：小功能可以一次跑完；大功能应分阶段执行，每轮用参数圈定范围、验证结果后再继续。例如：
/speckit.implement Implement only the Setup and Foundational phases: project scaffolding and the data model with basic CRUD. Stop before the user-story features./speckit.implement Now implement the Kanban board user story: drag-and-drop between columns.这样做的目的是避免一次性吞掉 agent 的全部上下文窗口，让每一轮实现都可独立验证。
3.2 加入质量门：Spring Boot + React 平台演示
第二个案例在标准主线上插入了两个质量门，这也是 docs/quickstart.md 中"完整路径"的形态：
/speckit.constitution/speckit.specify/speckit.clarify—— 针对欠规格部分提出定点问题并把答案回写进 spec/speckit.plan—— 技术栈与架构归属此步/speckit.checklist—— "需求的单元测试"/speckit.tasks/speckit.analyze—— 只读跨产物一致性检查/speckit.implement/speckit.converge—— 只追加不删改的收敛检查
该案例额外做了一次"跨产物一致性分析"（cross-artifact consistency analysis），即对spec.md、plan.md、tasks.md三者做冲突/缺口/歧义扫描。这正是/speckit.analyze的定义行为：从源码结构看，它被设计为从不编辑文件——只产出报告并可选给出修复建议，发现问题时回到负责该问题的上游命令（需求问题回 specify/clarify，设计问题回 plan，任务问题回 tasks）在源头修复后重跑，直到报告干净。
3.3 纯终端形态：Go / React 仪表盘演示
第五个案例的特殊性在于交互入口：它没有依赖 IDE 集成，而是完全在终端中使用 GitHub Copilot CLI驱动整个流程。该案例证明了两件事：
- spec-kit 的工作流不绑定特定宿主环境，命令序列在任何能执行
/speckit.*（或 agent 暴露的等价形式，如$speckit-*、/skill:speckit-*）的界面中都能运行； - 棕场对象是一个真实的开源系统（NASA Hermes，Go 语言），新增的 React 遥测仪表盘只是"下一个有界变更"，而非对存量系统的整体重写——这与 docs/guides/existing-projects.md 的主张完全一致。
四、棕场案例：无 Spec、无 Constitution 的存量工程
案例 3（ASP.NET CMS）与案例 4（Piranha Java 运行时）是棕场实践的范本。它们共同验证了 docs/guides/existing-projects.md 给出的棕场接入方法论：
4.1 原地初始化，不做逆向规格化
该指南开宗明义：不需要先用规格重建整个现有系统。棕场的正确起点是原地初始化：
specify init --here --force --integration <key>--here指向当前目录；--force允许在非空目录初始化，并可能替换冲突管理路径下的文件，因此指南要求在运行前先 commit/stash 现有工作、开一个分支，保证所有生成文件都能出现在一次正常的代码评审 diff 中；- 初始化只会添加共享的
.specify/项目文件和所选集成所需的命令/技能文件，不会重写你的应用，也不会为既有行为推断规格。
4.2 用仓库证据写 Constitution
/speckit.constitution应只写"对仓库已经为真"或"团队明确同意采纳"的原则，证据来源是 README、架构决策、贡献指南和 CI 配置。指南中的示例：
/speckit.constitution Preserve public API compatibility. Follow the existing service boundaries. Every database migration must include a rollback plan. Run the repository's established unit and integration test suites.指南明确警告：不要为了填满 constitution 模板而发明标准——不切实际的规则会在后续 plan/analyze 阶段制造噪音而非有用的约束。
4.3 选择"有界"的首个变更
两个棕场案例都选择了可独立评审的变更切片：案例 3 选了"Docker Compose 基础设施 + headless REST API"两个特性，案例 4 选了"Server Admin Console"。/speckit.specify的描述同时给出期望结果与兼容边界，例如：
/speckit.specify Add CSV export to the existing orders page. Preserve current filters and authorization behavior. Export only the rows visible to the signed-in user, and do not change the existing JSON API response.代码库在此扮演"实现上下文"（implementation context）角色：新的spec.md定义的是你打算做的变更，而不是对每个既有行为的追溯规格化。
完成首个变更之后，团队还需按 docs/guides/existing-projects.md 第 5 节决定"规格如何随时间演化"（特性目录作为不可变历史记录 / spec.md 作为活契约 / 允许发现回流后重新调和全套产物），这部分可继续对照 docs/concepts/spec-persistence.md 与 docs/guides/evolving-specs.md。
五、机制深挖（一）：Preset 如何"重塑整个体验"
案例 6（海盗语 preset）演示了 spec-kit 的定制能力上限：不 fork、不改核心文件，仅靠一个 preset 就让所有产物和命令以海盗口吻运转。这背后是仓库内实现完整的模板解析栈。
5.1 运行时解析栈
按 presets/README.md 与 presets/ARCHITECTURE.md，当 spec-kit 需要某个模板（如spec-template）时，PresetResolver会自顶向下走一个解析栈：
| 优先级 | 来源 | 路径 | 用途 |
|---|---|---|---|
| 1（最高） | Override | .specify/templates/overrides/ | 项目本地一次性微调 |
| 2 | Preset | .specify/presets/<preset-id>/templates/ | 可分享、可叠加的定制（按 priority 排序） |
| 3 | Extension | .specify/extensions/<ext-id>/templates/ | 扩展提供的模板 |
| 4（最低） | Core | .specify/templates/ | 随 spec-kit 分发的默认模板 |
注意两个要点：
- 解析发生在运行时：preset 文件虽在安装时拷贝进
.specify/presets/<id>/，但每次模板查找都重新走解析栈，而不是合并到单一位置。 - 组合策略（composition strategies）：preset 不必全量替换。
preset.yml中每个条目可声明strategy——
| 策略 | 行为 | template | command | script |
|---|---|---|---|---|
replace（默认） | 完全替换低优先级内容 | ✓ | ✓ | ✓ |
prepend | 内容置于低优先级模板之前（空行分隔） | ✓ | ✓ | — |
append | 内容置于低优先级模板之后（空行分隔） | ✓ | ✓ | — |
wrap | 内容中的{CORE_TEMPLATE}（脚本为$CORE_SCRIPT）占位符被低优先级内容替换 | ✓ | ✓ | ✓ |
多个组合型 preset 会递归链式叠加，例如一个prepend的安全 preset 加一个append的合规 preset，最终产出"安全头部 + 核心内容 + 合规尾部"。
解析逻辑在三种运行时各有一份实现以保证一致：Python 的PresetResolver（位于 src/specify_cli/presets/init.py，类定义约在 L4999，resolve_content()约在 L5715）、Bash 的resolve_template()（scripts/bash/common.sh）、PowerShell 的Resolve-Template（scripts/powershell/common.ps1）。
5.2 命令覆盖：安装期注册
模板定义"产出什么"，命令定义"LLM 如何产出"。与模板的运行时解析不同，preset 中的type: "command"条目是安装期生效的：安装时注册进所有被检测到的 agent 目录（.claude/commands/、.gemini/commands/等）并按各 agent 格式渲染（Markdown、TOML 或 Copilot 的.agent.md + .prompt.md，参数占位符也随格式切换）；卸载 preset 时注册的文件会被清理。安全细节：命令名形如speckit.<ext-id>.<cmd>且含 3 段以上时，系统会先检查对应扩展是否已安装，未安装则跳过注册，避免产生指向不存在扩展的孤儿文件。
仓库自带可参照的实现样本：
- presets/lean/preset.yml —— 官方"精简工作流" preset，仅覆盖
speckit.specify、speckit.plan、speckit.tasks、speckit.implement、speckit.constitution五个核心命令，示范了最典型的"纯命令覆盖"preset； - presets/scaffold/preset.yml —— 用于创建自有 preset 的脚手架，内含 strategy、
replaces字段、命令覆盖、extension 模板覆盖等全部要点的注释； - presets/catalog.json 与 presets/catalog.community.json —— 官方与社区 preset 目录，对应 CLI 侧的
specify preset search/specify preset add。
5.3 海盗语 preset 说明了什么
结合 docs/community/walkthroughs.md 的描述，案例 6 的价值在于证明：改模板名、改命令提示词、改产物措辞，足以让"整个 spec-kit 体验"换一副面孔，而工具链零改动。这正是"preset 不 fork 核心文件"这一设计目标的直接回报——定制的是内容层，不变的是 templates/ 中 core 模板的分发与 scripts/python/ 等自动化脚本的执行逻辑。
六、机制深挖（二）：Extension 换一种 SDD 风格
案例 7 走通的 AIDE 扩展，是 spec-kit 扩展机制的端到端示范：扩展带来一条替代性的规范驱动工作流——高层 spec（vision）与低层 spec（work items）分两层，按 7 步迭代生命周期推进（vision → roadmap → 进度追踪 → 工作队列 → 工作项 → 执行 → 反馈回路），全程不触碰核心工具链。
仓库内扩展机制的一手资料包括：
- extensions/README.md 与 extensions/EXTENSION-DEVELOPMENT-GUIDE.md —— 扩展的目录约定、
extension.yml元数据、命令与脚本布局； - extensions/EXTENSION-API-REFERENCE.md —— 扩展可挂载的命令与钩子接口；
- extensions/catalog.json 与 extensions/catalog.community.json —— 官方与社区扩展目录。官方收录的扩展自带
commands/、scripts/（bash/powershell/python 三平台对等实现）与extension.yml等结构，仓库内的 extensions/git/（版本分支与自动提交）、extensions/assess/（intake/research/shape 等评估命令）都是可直接阅读的参考实现； - docs/community/extensions.md —— 社区扩展清单，AIDE 即在其中（类别
process，效果 Read+Write）。
从 docs/community/walkthroughs.md 原文的措辞看，作者有意用这个案例来兑现项目名中"Kit"的含义：spec-kit 的"kit"不仅是命令集合，还是一套可插拔机制——preset 定制内容与措辞，extension 换流程骨架。
七、如何从这些 Walkthrough 中取用
结合 docs/community/walkthroughs.md 的定位声明与仓库内的配套文档，建议的取用路径是：
- 按起点选型：新项目从案例 1/2 入手，对照 docs/quickstart.md 的 Taskify 运行示例逐命令跟做；存量项目从案例 3/4/5 入手，先读 docs/guides/existing-projects.md 的五步方法（可评审基线 → 仓库证据写 constitution → 有界首个变更 → 对仓库规划 → 决定规格演化策略）；
- 按机制选型：想改产物风格/措辞，研究 preset 体系（presets/README.md、presets/ARCHITECTURE.md）；想加新的工作流步骤或命令，研究 extension 体系（extensions/EXTENSION-DEVELOPMENT-GUIDE.md）；
- 保持正确预期：walkthrough 产物是只读示例而非官方黄金输出，命令的完整参数、输出与交互语义以 docs/reference/agentic-sdd.md 为准；跟做社区内容前自行审阅，因为社区案例独立于官方审查与支持体系之外。
八、小结
docs/community/walkthroughs.md 收录的七个社区 walkthrough 构成了一张实用的场景地图：三个绿场案例分别验证标准主线、质量门加强线与纯终端执行线，两个棕场大工程（约 30.7 万行与约 42 万行代码的存量系统）证明无 spec 与 constitution 前提下的接入路径，另两个案例则把 preset 与 extension 两大定制机制推到了"不改任何工具链即可重塑体验"的极限。配合 docs/quickstart.md 的命令级快速上手、docs/guides/existing-projects.md 的棕场方法论，以及 presets/ARCHITECTURE.md、extensions/EXTENSION-DEVELOPMENT-GUIDE.md 等仓库内的一手机制文档，你可以把这些演示从"看一遍"落实为"在自己项目中跑一遍"。
【免费下载链接】spec-kit💫 Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
