Spec Kit 实战指南用 Specify CLI 落地可扩展的 Spec-Driven Development 全流程【免费下载链接】spec-kit Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit本文以 Spec Kit 官方 README 为主干完整覆盖 Spec-Driven DevelopmentSDD的核心方法论、七步工作流constitution → specify → plan → tasks → implement → converge、bug 修复与想法评估两条增值流程以及 Extensions / Presets / Bundles 三级定制体系。读完本文你将能够安装 Specify CLI、初始化一个与 AI 编码代理集成的 SDD 项目并结合仓库源码理解各命令模板、扩展清单与捆绑包目录栈的底层实现。一、什么是 Spec-Driven DevelopmentSpec Kit 的定位是一句话在构建之前先定义要构建什么——并且可以与任意 AI 编码代理配合使用。它是一个面向整个组织的、社区驱动的、可持续扩展的开源工具包提供开箱即用的 spec-driven 流程或自带流程。SDD 颠覆了传统开发中代码为王、规格文档只是脚手架的几十年惯例规格文档不再是写完就丢的指导材料而是可执行的executable——直接驱动生成可运行的实现而不只是指导实现。README 将其核心哲学归纳为四点意图驱动开发规格先定义做什么what再谈怎么做how富规格创建利用项目原则constitution和组织级 guardrails 来约束规格质量多步精炼用多轮 refine 取代一次性 prompt 出码深度依赖大模型能力把规格的解释与执行交给先进 AI 模型完成。对应仓库结构核心 SDD 命令的提示词模板全部位于 templates/commands/ 目录包含constitution.md、specify.md、plan.md、tasks.md、implement.md、converge.md等十个文件构建配置 pyproject.toml 显示这些模板、脚本bash/powershell/python 三套以及内置扩展、预设、workflow 会被打进 wheel 包的core_pack使specify init在无网络的隔离环境中也能工作。二、环境准备与 CLI 安装前置条件Linux / macOS / Windows均可任一受支持的 AI 编码代理CLI 工具或 IDE 助手30 种包管理工具uv推荐或 pipxPython 3.11pyproject.toml 中requires-python 3.11Git。安装 Specify CLI将vX.Y.Z替换为最新 release tag保留前缀v例如v0.12.11而非0.12.11uv tool install specify-cli --from githttps://github.com/github/spec-kit.gitvX.Y.Z更倾向于从 PyPI 安装的话specify-cli包也发布在那里uv tool install specify-cli当前仓库开发版本为1.0.3.dev0见 pyproject.toml项目已在 1.0.0 里程碑上运行1.0.0 的意义被定义为只是一个数字——当智能体让适应变化的成本大幅降低时价值从稳定性转向适应性。其他安装方式一次性运行、air-gapped 离线安装等见 安装指南与 install 目录、离线安装。初始化项目specify init my-project --integration copilot cd my-project针对 CI 或无键盘的 Agent harness 场景使用--non-interactive避免 init 挂在交互式选择器上向非空目录初始化时叠加--forcespecify init my-project --non-interactive --ignore-agent-tools specify init --here --force --non-interactive --integration claude从源码看默认集成由 src/specify_cli/_agent_config.py 定义硬编码默认值为copilot可通过环境变量SPECKIT_INTEGRATION_DEFAULT覆盖值非法时向 stderr 打印警告并回退而非静默失败。specify init的完整实现在 src/specify_cli/commands/init.py。自管理命令检查与升级# 检查是否有新版只读不修改任何东西 specify self check # 预览将执行的操作不真正升级 specify self upgrade --dry-run # 原地升级到最新稳定版自动识别 uv tool 与 pipx 安装方式 specify self upgrade # 或钉住特定 release tag specify self upgrade --tag vX.Y.Z[suffix]裸specify self upgrade会立即执行与pip install -U、npm update的无提示行为一致。对uv tool安装其内部执行uv tool install specify-cli --force --from git ref因此钉住的 tag 可以带 dev、alpha/beta/rc 或 build 元数据后缀uvx临时运行与源码 checkout 场景会被识别并给出针对性的路径指引而不是运行安装器。可用SPECIFY_UPGRADE_TIMEOUT_SECS限制安装子进程的最长运行时间默认无超时必要时CtrlC中断。这些命令由 src/specify_cli/_version.py 中的self check/self upgrade提供并通过 CLI 入口 的app.add_typer(_self_app, nameself)挂载。详见 升级指南。三、SDD 核心工作流从宪法到收敛在specify init之后启动你的编码代理按以下顺序执行斜杠命令大多数代理以/speckit.*形式暴露Codex CLI 与 skills 模式下的 Command Code 使用$speckit-*GitHub Copilot CLI 通过/agents选择代理或在提示词中直接寻址1. 建立项目原则一次性/speckit.constitution创建整个项目后续开发都要遵循的治理原则与开发指南每个项目只需执行一次/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements2. 写规格Specify/speckit.specify描述要构建的东西聚焦 what 和 why不谈技术栈/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.从源码看templates/commands/specify.md 的 front matter 中定义了handoffs下一步可移交speckit.plan或speckit.clarify且正文内置了扩展钩子检查执行前会检查项目根.specify/extensions.yml中hooks.before_specify的注册项区分 optional 与 mandatory 钩子——mandatory 钩子必须先执行完毕才进入正文流程specify.md 前 55 行。这意味着扩展不仅加命令还能介入核心命令的前置执行链。3. 制定技术实现计划Plan/speckit.plan提供技术栈与架构决策/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.4. 拆解任务Tasks/speckit.tasks5. 执行实现Implement/speckit.implement6. 收敛Converge/speckit.converge将当前代码库与 spec、plan、tasks 三方对齐评估把尚未完成的工作作为新任务追加到 tasks.md/speckit-converge注意重复执行 implement 与 converge直到/speckit-converge报告Converged为止。templates/commands/converge.md 的 front matter 显示该命令在执行前会调用三平台check-prerequisites脚本--require-spec --require-tasks --include-tasks确保 spec 与 tasks 产物存在后再进入收敛评估——这就是可执行规格的脚本化落点之一脚本本体在 scripts/。斜杠命令全表specify init后代理将获得以下结构化开发命令。对支持 skills 模式的集成传--integration agent --integration-options--skills会以 agent skills 形式安装而非斜杠命令提示词文件skills 描述常量见 SKILL_DESCRIPTIONS核心命令命令Agent Skill说明/speckit.constitutionspeckit-constitution创建或更新项目治理原则与开发指南/speckit.specifyspeckit-specify定义要构建的内容需求与用户故事/speckit.planspeckit-plan基于选定技术栈生成技术实现计划/speckit.tasksspeckit-tasks生成可执行的任务清单/speckit.taskstoissuesspeckit-taskstoissues将任务清单转为 GitHub issues 以便追踪/speckit.implementspeckit-implement按计划执行全部任务构建该特性/speckit.convergespeckit-converge对照 spec/plan/tasks 评估代码库把剩余工作追加为新任务可选命令增强质量与校验命令Agent Skill说明/speckit.clarifyspeckit-clarify澄清规格中的欠定区域建议在/speckit.plan之前执行曾用名/quizme/speckit.analyzespeckit-analyze跨产物一致性与覆盖度分析在/speckit.tasks之后、/speckit.implement之前执行/speckit.checklistspeckit-checklist生成自定义质量检查清单校验需求的完整性、清晰度与一致性类似给英语写单元测试逐行深入的完整流程说明见 Spec-Driven Development 方法论全文与 快速入门。四、内置增值流程一Bug 修复bug 扩展当代理不经诊断验证、不确认修复真正解决原始症状就直接从 bug 报告跳到补丁时风险很高。Spec Kit 内置的、按需安装的bug 扩展提供可复现的assess → fix → test工作流让每个修复都有范围约束、证据支撑并从根因到验证全程留痕。uv tool install specify-cli --from githttps://github.com/github/spec-kit.gitvX.Y.Z specify init my-project --integration copilot cd my-project specify extension add bug启动代理后依次执行评估bug/speckit-bug-assess bug report sluglogin-crash修复已评估的成因/speckit-bug-fix sluglogin-crash测试修复/speckit-bug-test sluglogin-crash实现佐证extensions/bug/extension.yml 声明扩展 id 为bugBug Triage Workflowspecify_cli-core作者、要求speckit_version 0.9.0provides.commands恰好对应上面三条命令描述为针对代码库评估 bug 报告并在.specify/bugs/slug/下按 bug 存报告。该扩展与 git、agent-context、assess 一起被 pyproject.toml 打包进 wheel所以specify extension add bug可以离线从内置 core_pack 安装。方法论细节另见 Agentic Bugfix 参考。五、内置增值流程二想法评估assess 扩展好想法值得在投入之前先拿到证据——无论它最终是否变成软件。内置的assess 扩展把原始想法转化为一份有记录的go / needs-clarification / kill决策流程为intake → research → define → shape → decidespecify extension add assess/speckit-assess-intake idea slugoffline-mode # 1. 接收想法 /speckit-assess-research slugoffline-mode # 2. 收集支持与反对证据 /speckit-assess-define slugoffline-mode # 3. 定义问题、目标与成功指标 /speckit-assess-shape slugoffline-mode # 4. 探索可行方案与取舍 /speckit-assess-decide slugoffline-mode # 5. 决策继续 / 待澄清 / 终止想法评估是独立流程若最终决策为go可以直接把结果移交给/speckit-specify进入正式构建。五个命令模板位于 extensions/assess/commands/扩展元数据见 extensions/assess/extension.yml。六、支持的 AI 编码代理集成Spec Kit 支持30 种 AI 编码代理CLI 工具与 IDE 助手两类。运行specify integration list可查看当前安装版本支持的全部集成。从源码结构看集成注册表位于 src/specify_cli/integrations/每个代理一个子包claude、copilot、codex、gemini、qwen、opencode、goose、kimi、zed 等共 38 个子目录另含 generic 兜底公共能力命令查询、脚手架、安装、迁移集中在_query_commands.py、_scaffold_commands.py、_install_commands.py、_migrate_commands.py与 base.py。CLI 侧的specify check命令实现会逐一探测各代理 CLI 是否已安装IDE 型代理则标记为跳过检查。完整集成清单与使用说明见 integrations 参考代理集成目录数据在 integrations/catalog.json。七、定制体系Extensions、Presets 与模板优先级栈Spec Kit 通过两套互补机制加项目级覆盖来适配不同团队扩展extensions与预设presets。模板解析采用固定优先级栈优先级组件类型位置1项目本地覆盖Project-Local Overrides.specify/templates/overrides/2预设——定制核心与扩展.specify/presets/templates/3扩展——增加新能力.specify/extensions/templates/4Spec Kit 核心——内置 SDD 命令与模板.specify/templates/关键规则模板在运行时runtime解析——Spec Kit 自顶向下遍历栈取第一个匹配项目本地覆盖.specify/templates/overrides/允许对单个项目做一次性调整无需创建完整 preset扩展/预设的命令在安装时install time生效——执行specify extension add或specify preset add时命令文件会写入代理目录如.claude/commands/若多个预设/扩展提供同名命令最高优先级版本胜出移除时自动恢复次高优先级版本没有任何覆盖时Spec Kit 使用核心默认。源码印证specify init的模板解析walks the full priority stack (project overrides → installed …)见 commands/init.py 注释预设命令注册逻辑在 integrations/_helpers.py 中为每个激活集成登记所有启用 preset 的命令覆盖。扩展Extensions——增加新能力当核心能力不够时用扩展它引入新命令与新模板例如领域专属工作流、外部工具集成或全新的开发阶段。扩展扩展的是Spec Kit 能做什么# 搜索可用扩展 specify extension search # 安装扩展 specify extension add extension-name例如扩展可以实现 Jira 集成、实现后代码评审、V 模型测试追溯、项目健康诊断。完整命令指南见 Extensions 参考开发一份自己的扩展参考 扩展开发指南 与 扩展 API 参考。预设Presets——定制既有工作流当你想改变Spec Kit 怎么工作而不新增能力时用预设预设覆盖核心及已安装扩展的模板与命令——例如强制合规导向的规格格式、领域术语、组织级计划/任务标准。它定制的是 Spec Kit 与扩展产出的产物与指令# 搜索可用预设 specify preset search # 安装预设 specify preset add preset-name预设可用于为 spec 模板加入监管追溯要求、适配方法论Agile / Kanban / Waterfall / JTBD / DDD、在计划中强制安全评审门、强制测试先行的任务排序、或把整个流程本地化为另一种语言。多个预设可以按优先级叠加。内置预设见 presets/catalog.json仓库自带lean、constitution-sync、scaffold、self-test四个样例presets/。完整指南含解析顺序与优先级叠加见 Presets 参考。何时用哪个目标选用增加全新命令或工作流扩展定制 spec / plan / tasks 的格式预设集成外部工具或服务扩展执行组织或监管标准预设分发可复用的领域模板皆可——纯模板覆盖用预设随新命令捆绑模板用扩展一条命令装配完整的角色化配置捆绑包Bundle八、Bundles角色化一键装配扩展与预设是单个积木。**捆绑包bundle**把一套精选组件——扩展、预设、步骤、工作流——打包为单个版本化的、面向角色的安装单元产品负责人、业务分析师、安全研究员、开发者等整个人设可以用一条命令装配完成。每个 bundle 由手工编写的bundle.yml清单描述为每个组件钉住版本可选指定目标集成未声明integration的 bundle 是**集成无关agnostic**的继承项目已有的集成。消费端命令# 在激活的目录栈中搜索 bundle specify bundle search [query] # 查看某 bundle 将添加的确切组件集与 install 行为一致 specify bundle info bundle-id # 一次安装 bundle 的完整组件集 specify bundle install bundle-id # 查看已安装项非破坏式更新或移除 specify bundle list specify bundle update bundle-id # 或 --all specify bundle remove bundle-id # 只移除该 bundle 自己的组件bundle 从一个按优先级排序的目录栈project user built-in解析每个来源携带安装策略install-allowed来源可安装discovery-only来源在search/info中可见但拒绝安装。用specify bundle catalog list|add|remove管理目录栈实现见 src/specify_cli/bundler/。作者端本地验证与打包发布只需托管产物并添加目录来源社区提交走 Bundle Submission issue 模板附组件目录与安装证据供审查specify bundle validate --path ./my-bundle # 结构 引用检查 specify bundle build --path ./my-bundle # 产出带版本的 .zip 产物仓库内提供四份可直接阅读的角色化示例清单examples/bundles/product manager、business analyst、security researcher、developer。以 developer/bundle.yml 为例其provides段同时钉住了agent-context扩展1.0.0、implementation-planning预设priority 10、append 策略、两个 workflow steps 和spec-to-implementation工作流直观展示了一个 bundle 如何编排多类组件。核心保证info展示的与install添加的完全一致透明性安装幂等且限定在项目根内remove绝不动其他已安装 bundle 仍需要的组件全部消费/作者命令在本地或钉住的来源上离线可用。九、核心哲学、开发阶段与实验目标开发阶段阶段焦点关键活动0 到 1 开发Greenfield从零生成高层需求 → 生成规格 → 规划实现步骤 → 构建生产级应用创意探索并行实现探索多样方案支持多技术栈与架构实验 UX 模式迭代增强Brownfield棕地现代化迭代加功能现代化遗留系统流程适配对既有项目建议把 Spec Kit 工具更新与特性产物演进分开升级时刷新受管项目文件行为意图变化时更新specs/产物。演进规格指南给出了推荐的棕地循环存量项目接入见 existing-projects 指南monorepo 场景见 monorepo 指南。实验目标技术无关性验证 SDD 是不绑定特定技术、语言或框架的流程企业约束演示关键任务应用开发纳入云厂商、技术栈、工程实践等组织约束支持企业设计系统与合规要求用户为中心面向不同用户群与偏好支持从 vibe-coding 到 AI 原生开发的多种开发方式创意与迭代过程验证并行实现探索、提供稳健的迭代特性开发流程、扩展到升级与现代化任务。十、Spec Kit 自己用 Spec Kit 吗是的——开发 Spec Kit 时 dogfood Spec Kit尤其针对重量级特性与工作流变更贡献者被要求通过 SDD 命令验证相关变更。当前的自动化 dogfood 路径是 feature assessment workflow其 setup 用当前 checkout 的 CLI 初始化 Copilot 并安装assess扩展随后 Copilot 依据生成的评估 skills 对特性请求执行评估。其他 agentic workflow 目前独立于 Specify CLI 运行。这并不意味着所有变更都走完整流程小修复仍走常规的 issue / PR / 评审 / 测试流程。dogfood 脚手架与产物.github/agents/、.github/prompts/、.github/copilot-instructions.md、.grok/、.specify/、specs/被有意 gitignore自动化评估流程是临时的既不 commit 也不 push 生成的 Copilot skills其输出不进入仓库历史。验证预期详见 CONTRIBUTING 中的开发工作流。十一、继续学习的路径完整 SDD 方法论全流程深度剖析快速入门/CLI 参考逐步操作与完整命令参数参考文档核心、agentic SDD、bug 修复、扩展、预设、bundles、工作流、集成、认证社区资源扩展、预设、捆绑包、走查、Friends。社区贡献由各自作者独立创建与维护安装前请审查源码。遇到问题时在仓库 open issue 即可欢迎 bug 报告、特性请求与 SDD 使用问题。项目采用 MIT 许可LICENSE。【免费下载链接】spec-kit Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考