用 Codex + GitHub Spec-Kit 做一次“规格驱动开发”实战
- 用 Codex + GitHub Spec-Kit 做一次“规格驱动开发”实战
用 Codex + GitHub Spec-Kit 做一次“规格驱动开发”实战
——命令行/操作流完整版本（聚焦 spec-kit 用法）
很多人用 AI 写代码是“想到什么问什么”：一句 prompt、生成一段代码、跑一下、再修一下。短期很快，但一旦需求变多、模块变复杂，这种方式很容易失控：方向漂移、上下文断裂、改动不可追踪，最后变成“能跑但不可控”。
这次用 Codex 配合 GitHub 的 Spec Kit（Spec-Driven Development / SDD） 跑了一遍完整链路：
宪法（Constitution）→ 规格（Spec）→ 计划（Plan）→ 任务（Tasks）→ 实现（Implement）。
核心变化不是“写得更快”，而是：每一步都有文件产物、流程可复现、AI 不容易跑偏。
文中只用“一个浏览器扩展项目”作为背景，不展开具体业务细节，重点讲 speckit 的初始化、命令输入方式、产物位置、推进节奏。
1) 初始化：把 spec-kit 工作区真正建起来（多种方式）
推荐是先创建项目目录，再初始化 Spec Kit：
mkdir my-project cd my-project 接下来选一种初始化方式即可（目标一致：生成 .specify/ 等结构，并让 Codex 里出现 /prompts:speckit.* 指令）。
方式 A：uvx 一次性运行（推荐）
适合不想全局安装工具，只想在当前目录把工作区拉起来：
uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai codex 没有uv/uvx的话，先装uv（例如 macOS 可用brew install uv），再跑上面命令。
方式 B：uv tool install（全局安装 specify）
适合频繁使用：
uv tool install --from git+https://github.com/github/spec-kit.git specify specify init --here --ai codex 方式 C：pipx 安装（Python 工具常用法）
如果习惯 pipx 管理 CLI：
pipx install git+https://github.com/github/spec-kit.git specify init --here --ai codex 2) 初始化后，正确的目录结构长什么样（
.specify/：Spec Kit 工作区（模板、脚本、记忆）memory/constitution.md（宪法写在这里）templates/（spec/plan/tasks 的模板）scripts/（辅助脚本）
.codex/：Codex 项目级 homeprompts/✅（关键：speckit 的 prompts 在这里）rules/、skills/、sessions/、log/等
specs/<feature>/：每个功能/迭代的产物目录（spec/plan/tasks 等）src/：代码目录（等 implement 之后才会逐渐长出来）
重点：这套结构里 prompts 在.codex/prompts/，所以命令形式是/prompts:speckit.*。
3) 在 Codex 里跑 speckit：统一输入规则（非常重要）
在 Codex 输入框里执行 speckit 命令时，节奏固定：
- 输入命令（前面一定有
/），例如：/prompts:speckit.plan - 回车发送
- Codex 进入该 prompt 模式后，会要你补充内容（或给模板）
- 粘贴/输入内容
- 再回车发送
也就是：先提交命令 → 再提交内容，两次回车完成一阶段。
4) 标准流水线：Constitution → Spec → Plan → Tasks → Implement
Step 1：立宪法（Constitution）
目的：先把“护栏”写死，避免 AI 自由发挥跑偏。
- 命令（回车）：
/prompts:speckit.constitution - 内容（回车）：写项目原则，不写业务细节，重点是约束与工程规则，比如：
- 隐私/数据边界（本地优先、最小权限等）
- 安全边界（不注入不可信内容、隔离页面环境等）
- 性能边界（不做全量重扫、增量策略、节流等）
- 工程规范（TS、模块边界、lint/test）
- 质量门槛（必须可验收、可测试）
产物通常落在：.specify/memory/constitution.md
Step 2：写规格（Specify）
目的：只写“做什么/为什么”，把 MVP 与验收标准讲清楚，先不谈技术实现。
- 命令（回车）：
/prompts:speckit.specify - 内容（回车）：建议结构是：
- 目标用户/场景（泛化描述）
- MVP 能力边界（做什么）
- 明确不做什么（防膨胀）
- 关键边界情况（输入归一化/异常/权限/失败兜底）
- 验收标准（可以用 checklist 的方式写）
产物通常落在：specs/<feature>/spec.md
Step 2.5（可选）：澄清（Clarify）
目的：把规格里容易分歧的灰区问死，减少返工。
- 命令（回车）：
/prompts:speckit.clarify - 回答它提出的 3–5 个问题（回车提交）。
这一步尤其适合：触发条件、数据口径、失败兜底策略、性能阈值、权限范围这类容易反复的点。
Step 3：写计划（Plan）
目的：把 spec 翻译成工程方案（模块划分、数据流、依赖、风险与降级）。
- 命令（回车）：
/prompts:speckit.plan - 内容（回车）：一句话也够，比如：
基于 constitution + spec，输出工程实现计划：模块边界、数据结构、构建方式、测试策略、风险与降级、里程碑。
产物通常落在：specs/<feature>/plan.md
Step 4：拆任务（Tasks）
目的：把 plan 变成可执行清单，明确依赖顺序与验收条件。
- 命令（回车）：
/prompts:speckit.tasks - 内容（回车）：建议分阶段输出：
请拆成阶段化 tasks：Setup → Foundational → Feature slices → Polish，并为每个任务写验收标准与依赖。
产物通常落在：specs/<feature>/tasks.md
Step 5：按任务实现（Implement）
目的：让 Codex 不是“随便写”，而是“按 tasks 逐条交付”。
- 命令（回车）：
/prompts:speckit.implement - 内容（回车）：最关键的实践：一次只做一个阶段/一小段任务，避免一口气写爆。例如：
先只实现 Phase 1（Setup）相关 tasks，完成后停止，并给出 build/test 的运行方式。
为什么要分阶段？因为这能保证你每一步都能跑起来、可回退、可审查，避免“几十个文件一波流大改动”。
5) 一致性体检：/prompts:speckit.analyze（可随时跑）
当觉得 spec/plan/tasks 之间可能不一致，或者 implement 跑了一段后想检查是否“违宪”，就用 analyze：
- 命令（回车）：
/prompts:speckit.analyze - 内容（回车）：
请检查 spec.md、plan.md、tasks.md 的一致性，是否遗漏验收项，是否违反 constitution 的隐私/性能/安全约束，并给出修订建议。
这一步适合当“质量闸门”，尤其在任务多、模块多时很管用。
6) 总结：这套 speckit 工作流的真正价值
Spec Kit + Codex 的价值不在于写多少代码，而在于把 AI 开发变成可控工程流程：
- 先立宪：把边界与原则锁死（防跑偏）
- 再规格：把 MVP 与验收写清（防需求膨胀）
- 再计划：把实现路线结构化（防架构散乱）
- 再任务：把执行拆到可交付颗粒度（防不可落地）
- 最后实现：严格按 tasks 分阶段推进（防“一波流写爆”）
- 随时 analyze：跨文档一致性与违宪检测（防悄悄偏航）
这套流程的最大收益是：复现性与可迭代性。你以后做任何新 feature，都可以在 specs/<new-feature>/ 里再走一遍同样流水线，工程不会越做越乱。
