spec-kit 社区实战 Walkthrough：七种真实场景拆解规范驱动开发的绿场、棕场与定制玩法

spec-kit 社区实战 Walkthrough七种真实场景拆解规范驱动开发的绿场、棕场与定制玩法【免费下载链接】spec-kit Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kitCommunity Walkthroughs 是 spec-kit 仓库中专收社区贡献实战案例的入口文档docs/community/walkthroughs.md它收录了七个完整跑通 Spec-Driven DevelopmentSDD工作流的演示项目覆盖从零搭建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 当前收录的七个案例可以按起点与机制验证点两个维度归纳#案例起点技术栈核心演示点1Greenfield .NET CLI 工具空白目录.NET 单二进制 CLI完整走通 constitution → specify → plan → tasks → 多轮 implement使用 GitHub Copilot agents2Greenfield Spring Boot React 平台从零搭建Spring Boot React PostgreSQL Docker Compose构建 LLM 性能分析平台REST API、图表、迭代追踪额外加入 clarify 步骤和跨产物一致性分析3Brownfield ASP.NET CMS 扩展存量开源 CMSCarrotCakeCMS-Core约 30.7 万行 C#/Razor/SQL/JS/配置ASP.NET为存量系统加两个新特性跨平台 Docker Compose 基础设施 令牌认证的 headless REST API演示无 spec、无 constitution 前提下的落地方式4Brownfield Java 运行时扩展存量开源 Jakarta EE 运行时Piranha约 42 万行 Java/XML/JSP/HTML/配置180 个 Maven 模块Java增加带密码保护的 Server Admin Console演示大型多模块 Java 工程在无既有 spec/constitution 时如何使用 spec-kit5Brownfield Go / React 仪表盘存量开源系统NASA Hermes 地面支持系统GoGo React全程仅在终端内通过 GitHub Copilot CLI 驱动spec-kit为 Hermes 扩展轻量级 Web 遥测仪表盘证明 constitution → specify → plan → tasks → implement 全流程可以在终端完成6Greenfield Spring Boot MVC 自定义 preset从零搭建Spring Boot MVC使用自定义海盗语preset 重塑整个 spec-kit 体验spec 变成 Voyage Manifests、plan 变成 Battle Plans、tasks 变成 Crew Assignments全篇海盗腔生成而不改动任何工具链7Greenfield Spring Boot React 自定义 extension从零搭建Spring Boot 4 React 19 PostgreSQL Docker Compose走通社区 AIDE 扩展——用高层 specvision 低层 specwork 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多轮多轮 implementmulti-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 HermesGo 语言新增的 React 遥测仪表盘只是下一个有界变更而非对存量系统的整体重写——这与 docs/guides/existing-projects.md 的主张完全一致。四、棕场案例无 Spec、无 Constitution 的存量工程案例 3ASP.NET CMS与案例 4Piranha 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 repositorys 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/项目本地一次性微调2Preset.specify/presets/preset-id/templates/可分享、可叠加的定制按 priority 排序3Extension.specify/extensions/ext-id/templates/扩展提供的模板4最低Core.specify/templates/随 spec-kit 分发的默认模板注意两个要点解析发生在运行时preset 文件虽在安装时拷贝进.specify/presets/id/但每次模板查找都重新走解析栈而不是合并到单一位置。组合策略composition strategiespreset 不必全量替换。preset.yml中每个条目可声明strategy——策略行为templatecommandscriptreplace默认完全替换低优先级内容✓✓✓prepend内容置于低优先级模板之前空行分隔✓✓—append内容置于低优先级模板之后空行分隔✓✓—wrap内容中的{CORE_TEMPLATE}脚本为$CORE_SCRIPT占位符被低优先级内容替换✓✓✓多个组合型 preset 会递归链式叠加例如一个prepend的安全 preset 加一个append的合规 preset最终产出安全头部 核心内容 合规尾部。解析逻辑在三种运行时各有一份实现以保证一致Python 的PresetResolver位于 src/specify_cli/presets/init.py类定义约在 L4999resolve_content()约在 L5715、Bash 的resolve_template()scripts/bash/common.sh、PowerShell 的Resolve-Templatescripts/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五个核心命令示范了最典型的纯命令覆盖presetpresets/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 扩展机制的端到端示范扩展带来一条替代性的规范驱动工作流——高层 specvision与低层 specwork 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效果 ReadWrite。从 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），仅供参考