Spec Kit 开发指南：仓库结构、核心文档地图与 Specify CLI 的本地开发验证流程

本文基于 Spec Kit 仓库的 DEVELOPMENT.md 展开，面向计划修改 Spec Kit 本身的贡献者与开发者：先给出项目核心文档的导航地图与五大仓库组件的职责划分，再结合 CONTRIBUTING.md、AGENTS.md 与 pyproject.toml 等仓库内真实文件，补齐本地开发环境搭建、自动化检查、手动工作流测试和发布流程，读完即可独立完成一次可被审查的 Spec Kit 修改。

Spec Kit 是什么：一组协同的提示词、模板与 CLI 资产

DEVELOPMENT.md 对 Spec Kit 的定义是：一个面向规格驱动开发（Spec-Driven Development, SDD） 的工具集，其核心是一组相互协调的提示词、模板、脚本以及 CLI/集成资产，共同定义并交付 AI 编码代理的规格驱动工作流。换句话说，Spec Kit 不是单一程序，而是"文档模板 + 辅助脚本 + 命令行工具 + 代理集成"四位一体的系统：

• 提示词与模板（templates/）定义 /speckit.specify、/speckit.plan、/speckit.tasks 等斜杠命令的行为；
• 辅助脚本（scripts/）在工作流中完成目录创建、模板解析、前置检查等确定性操作；
• Specify CLI（src/specify_cli/）负责把上述资产安装到用户项目并接入各类 AI 编码代理；
• 扩展与预设（extensions/、presets/）提供可插拔的增强命令与流程变体。

DEVELOPMENT.md 的定位是"修改 Spec Kit 本身的起点"——它本身不展开实现细节，而是为开发者提供一份紧凑的文档地图 + 仓库结构导览。以下各节在完整继承其骨架的同时，用仓库内其他文件补齐每个条目背后的实操细节。

核心项目文档地图

DEVELOPMENT.md 列出了六份关键文档及其分工，这是理解整个仓库的入口：

文档	角色
README.md	Spec Kit 及其工作流的主要用户侧概览
DEVELOPMENT.md	本文件，面向修改 Spec Kit 本身的人
spec-driven.md	规格驱动开发工作流的端到端说明
.github/workflows/RELEASE-PROCESS.md	发布流程、版本规则与 CHANGELOG 生成过程
docs/index.md	docs/ 文档集的入口
CONTRIBUTING.md	贡献流程、审查预期、测试与必需的开发实践

从这张表的分工可以推断出一条清晰的阅读路径：想理解方法论读 spec-driven.md，想跑通发布读 .github/workflows/RELEASE-PROCESS.md，想提交 PR 则必须先读 CONTRIBUTING.md——后者规定了分支命名、自动化检查与手动测试要求，是 DEVELOPMENT.md 之后最重要的一份文档。值得注意的是 RELEASE-PROCESS.md 位于 .github/workflows/ 目录下，与它描述的 release-trigger.yml、release.yml 两个工作流文件放在一起，便于维护者就近修改。

仓库五大核心组件

DEVELOPMENT.md 用一张表划分了仓库的主干目录，下面逐一展开并给出仓库内的佐证。

templates/：定义核心工作流行为的提示资产

templates/ 存放提示词资产与模板，决定斜杠命令的行为和生成产物的形态。目录内包含 spec-template.md、plan-template.md、tasks-template.md、constitution-template.md、checklist-template.md 等页面模板，以及 templates/commands/ 下的核心命令模板：specify、plan、tasks、implement、clarify、analyze、checklist、constitution、converge、taskstoissues。

以 templates/commands/plan.md 为例，其 YAML frontmatter 展示了模板资产的典型结构：description 声明命令用途，handoffs 定义执行后可交接的下一步命令（如 speckit.tasks），scripts: 块则声明该命令调用的辅助脚本的三种语言变体：

scripts:
  sh: scripts/bash/setup-plan.sh --json
  ps: scripts/powershell/setup-plan.ps1 -Json
  py: scripts/python/setup_plan.py --json

正文中的 {SCRIPT} 占位符会在安装时按项目选择的脚本类型（--script sh|ps|py）替换为对应条目，$ARGUMENTS 则承载用户输入。这一机制在 AGENTS.md 的 "Script Types and Migration" 一节中有完整说明。

scripts/：工作流与仓库工具使用的辅助脚本

scripts/ 提供工作流、初始化和仓库工具使用的辅助脚本。从目录结构看，bash/、powershell/、python/ 三个子目录一一对应，各包含 check-prerequisites、create-new-feature、resolve-template、setup-plan、setup-tasks 等配对脚本。

AGENTS.md 对贡献者规定了一条三元并行规则（parity rule）：三个脚本类型都是一等的，任何对工作流脚本的修改必须同时更新 sh、ps、py 三个变体并保持测试（parity 与 unit 测试）通过。这也解释了 tests/ 目录中大量 test_*_python_parity.py 测试文件的存在——它们正是验证 Python 移植版与 shell 版本 stdout 契约一致性的产物。

src/specify_cli/：specify CLI 的 Python 源码

src/specify_cli/ 是 specify 命令行的 Python 源码，pyproject.toml 中的 [project.scripts] 将其入口声明为 specify = "specify_cli:main"，并要求 Python >= 3.11。当前工作树中的开发版本号为 1.0.3.dev0。

几个对贡献者重要的实现细节：

• 集成注册表：各 AI 代理都是 src/specify_cli/integrations/<key>/ 下的自包含子包，由 src/specify_cli/integrations/__init__.py 的 _register_builtins() 统一注册进全局 INTEGRATION_REGISTRY；新增一个代理集成只需创建子包、按字母序添加 import 与 _register() 调用，并配套 tests/integrations/test_integration_<key>.py 测试文件，完整五步流程见 AGENTS.md 的 "Adding a New Integration"；
• 离线资产打包：pyproject.toml 的 [tool.hatch.build.targets.wheel.force-include] 段把 templates/、scripts/、extensions/git|agent-context|assess|bug、workflows/speckit、presets/lean|constitution-sync 以及社区 bundle 目录快照全部内嵌进 wheel 的 specify_cli/core_pack/，使 specify init 在无网络的隔离环境中也能工作——修改这些目录意味着修改了 wheel 的打包内容，需要跑 tests/contract/test_wheel_bundled_presets.py、test_wheel_core_pack_scripts.py 等契约测试；
• 安全姿态：[tool.ruff.lint] 启用了 S602/S604/S605 规则锁定 subprocess 安全，任何重新引入 shell=True 的代码都必须显式 # noqa 标注，使偏离在审查中可见。

extensions/ 与 presets/：可扩展的命令与流程变体

• extensions/ 存放扩展相关的文档、目录（catalog）与配套资产。仓库内自带 agent-context（维护上下文文件中的 Spec Kit 区段）、git（特性分支/自动提交）、assess、bug 等扩展，每个扩展由 extension.yml 清单 + commands/ 模板 + 可选 scripts/ 组成；
• presets/ 存放预设相关的文档、目录与资产，内置 lean、constitution-sync 等预设，可经 specify init --preset <name> 或 specify preset add <name> 安装。

两类资产都采用 catalog.json 与 catalog.community.json 的双目录结构（内置与社区），相关说明分别见 extensions/README.md 与 presets/README.md。

本地开发环境搭建

CONTRIBUTING.md 规定了测试代码前的一次性安装项：Python 3.11+、uv（包管理）、Git，以及一个可用的 AI 编码代理。标准开发循环如下：

# 1. Fork 并克隆仓库后，安装含测试依赖的环境
uv sync --extra test

# 2. 确认 CLI 可用
uv run specify --help

# 3. 按 <type>/<number>-<short-slug> 建分支
git checkout -b feat/1234-short-slug

# 4. 修改 + 测试后，在本地以可编辑模式安装 CLI，
#    确保代理跑的是你正在修改的工作树
uv pip install -e .

# 5. 用本地改动初始化一个测试项目
uv run specify init <temp-dir>/speckit-test --integration <agent>
cd <temp-dir>/speckit-test
# 6. 在你的 AI 代理中打开，手动运行受影响的斜杠命令

分支命名采用 <type>/<number>-<short-slug>，<number> 为 issue 或 PR 号（以先产生者计），<type> 取值为 feat/、fix/、docs/、community/、chore/ 五类；由于项目使用 squash merge，git branch --merged 无法检出已合并分支，带上编号的分支名因此成为可追溯性的关键（见 CONTRIBUTING.md 的 "Branch naming" 一节）。

验证流程：先自动化检查，后手动工作流测试

CONTRIBUTING.md 推荐的验证顺序是"先跑聚焦的自动化检查，再跑手动工作流测试"。

自动化检查

全量测试套件：把测试依赖装进项目自己的虚拟环境，并通过该环境的解释器运行 pytest：

uv pip install -e ".[test]"
.venv/bin/python -m pytest tests -q   # Windows: .venv\Scripts\python -m pytest tests -q

这里有一个容易踩的坑：不要使用裸 uv run pytest。如果共享/全局环境中注册过另一个 Spec Kit 检出目录的可编辑安装（editable install），uv run pytest 会把 specify_cli 解析到那个工作树，变成部分命名空间包，导致新添加的子包导入失败。通过本项目 .venv 运行才能确保解析到当前检出的 src/——该坑同时记录在 AGENTS.md 的 "Common Pitfalls" 第 6 条中。

Shell 脚本检查（与 CI 的 lint.yml shellcheck job 对齐，只拦截 error 级发现）：

git ls-files -z -- '*.sh' | xargs -0 shellcheck --severity=error

依赖安全审计：审计的是提交到仓库的哈希锁定快照 .github/security-audit-requirements.txt，PR/push/手动 CI 使用同一快照以保证结果确定：

uvx --from pip-audit==2.10.0 pip-audit --disable-pip --require-hashes -r .github/security-audit-requirements.txt --progress-spinner off

若 pyproject.toml 的依赖元数据发生变化，需先重新生成并提交快照再审计：

uv pip compile pyproject.toml --extra test --universal --upgrade --generate-hashes --quiet --no-header --output-file .github/security-audit-requirements.txt

由于上游包会持续发布漂移，即使无关 PR 触碰了 pyproject.toml 也可能在 dependency-audit 检查上失败，直到快照按上述命令重新生成。定时 CI 审计则会在支持的 Python 与 OS 矩阵上解析运行时 + test 依赖集，捕捉新发布的漏洞通告。

手动测试：改动斜杠命令必须走代理实测

任何影响斜杠命令行为的改动，都要通过编码代理手动测试该命令并把结果随 PR 提交。CONTRIBUTING.md 给出了完整的映射规则，例如：

• templates/commands/X.md → 它定义的命令；
• scripts/bash/Y.sh（或 .ps1）→ 每个调用该脚本的命令（grep templates/commands/），并检查传递依赖——如 common.sh 被 create-new-feature.sh、check-prerequisites.sh、setup-plan.sh source，那么调用这些下游脚本的所有命令都受影响；
• src/specify_cli/*.py → CLI 命令（specify init、specify check、specify extension *、specify preset *），脚手架类改动至少补测 /speckit.specify；
• extensions/X/commands/*、extensions/X/scripts/*、presets/*/* 分别映射到对应扩展命令与预设脚手架测试。

依赖顺序必须遵守前置链：/speckit.tasks 依赖 /speckit.plan，后者依赖 /speckit.specify。测试完成后按 PR 报告模板粘贴结果：

## Manual test results

**Agent**: [e.g., GitHub Copilot in VS Code]  |  **OS/Shell**: [e.g., macOS/zsh]

| Command tested | Notes |
|----------------|-------|
| `/speckit.command` | |

发布流程：双工作流保证版本一致性

DEVELOPMENT.md 指向的 .github/workflows/RELEASE-PROCESS.md 描述了自动发布机制，其设计目标是"git tag 永远指向 pyproject.toml 中版本正确的提交"，因此拆分为两个工作流：

1. Release Trigger（release-trigger.yml，手动 workflow_dispatch 触发）：确定版本（留空则自动递增 patch 位，如 0.1.10 → 0.1.11，或手填 major/minor 版本）、检查 tag 是否已存在、创建 chore/release-vX.Y.Z 分支、更新 pyproject.toml、从 git 提交信息自动生成 CHANGELOG.md 新段落、推送分支与 tag、并开一个 PR 把版本提交合并回 main；
2. Release Workflow（release.yml，tag push v* 触发）：在 tag 处检出、构建全部代理 × shell/powershell 的发布包变体、从提交生成 release notes、创建 GitHub Release。

由此推导出对贡献者的直接约束：写好 commit message 就是写好 CHANGELOG——描述性、可关联 issue（(#123)）、一行为宜（如 fix: prepend YAML frontmatter to Cursor .mdc files (#1699)）。版本约束方面，tag 必须为 v{MAJOR}.{MINOR}.{PATCH} 格式，自动递增只升 patch 位，重复 tag 会直接使工作流失败。

小结

DEVELOPMENT.md 为修改 Spec Kit 本身的人提供了一份紧凑的方位图：以六份核心文档为导航、以 templates/、scripts/、src/specify_cli/、extensions/、presets/ 五大组件为骨架。围绕它展开，贡献者还应掌握 CONTRIBUTING.md 规定的 uv 环境搭建与"自动化检查先行、代理手动测试随后"的验证顺序，AGENTS.md 中的集成注册模式与三元脚本并行规则，以及 .github/workflows/RELEASE-PROCESS.md 描述的 tag 与版本一致性机制。这些文件相互引用、边界清晰，构成了 Spec Kit 自身可持续演进的开发者基础设施。