---

用 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 项目级 home

  • prompts/ ✅（关键：speckit 的 prompts 在这里）
  • rules/、skills/、sessions/、log/ 等

• specs/<feature>/：每个功能/迭代的产物目录（spec/plan/tasks 等）

• src/：代码目录（等 implement 之后才会逐渐长出来）

重点：这套结构里 prompts 在 .codex/prompts/，所以命令形式是 /prompts:speckit.*。

---

3) 在 Codex 里跑 speckit：统一输入规则（非常重要）

在 Codex 输入框里执行 speckit 命令时，节奏固定：

1. 输入命令（前面一定有 /），例如：/prompts:speckit.plan
2. 回车发送
3. Codex 进入该 prompt 模式后，会要你补充内容（或给模板）
4. 粘贴/输入内容
5. 再回车发送

也就是：先提交命令 → 再提交内容，两次回车完成一阶段。

---

4) 标准流水线：Constitution → Spec → Plan → Tasks → Implement

Step 1：立宪法（Constitution）

目的：先把“护栏”写死，避免 AI 自由发挥跑偏。

1. 命令（回车）：

/prompts:speckit.constitution

2. 内容（回车）：写项目原则，不写业务细节，重点是约束与工程规则，比如：

• 隐私/数据边界（本地优先、最小权限等）
• 安全边界（不注入不可信内容、隔离页面环境等）
• 性能边界（不做全量重扫、增量策略、节流等）
• 工程规范（TS、模块边界、lint/test）
• 质量门槛（必须可验收、可测试）

产物通常落在：.specify/memory/constitution.md

---

Step 2：写规格（Specify）

目的：只写“做什么/为什么”，把 MVP 与验收标准讲清楚，先不谈技术实现。

1. 命令（回车）：

/prompts:speckit.specify

2. 内容（回车）：建议结构是：

• 目标用户/场景（泛化描述）
• MVP 能力边界（做什么）
• 明确不做什么（防膨胀）
• 关键边界情况（输入归一化/异常/权限/失败兜底）
• 验收标准（可以用 checklist 的方式写）

产物通常落在：specs/<feature>/spec.md

---

Step 2.5（可选）：澄清（Clarify）

目的：把规格里容易分歧的灰区问死，减少返工。

1. 命令（回车）：

/prompts:speckit.clarify

2. 回答它提出的 3–5 个问题（回车提交）。
   这一步尤其适合：触发条件、数据口径、失败兜底策略、性能阈值、权限范围这类容易反复的点。

---

Step 3：写计划（Plan）

目的：把 spec 翻译成工程方案（模块划分、数据流、依赖、风险与降级）。

1. 命令（回车）：

/prompts:speckit.plan

2. 内容（回车）：一句话也够，比如：

基于 constitution + spec，输出工程实现计划：模块边界、数据结构、构建方式、测试策略、风险与降级、里程碑。

产物通常落在：specs/<feature>/plan.md

---

Step 4：拆任务（Tasks）

目的：把 plan 变成可执行清单，明确依赖顺序与验收条件。

1. 命令（回车）：

/prompts:speckit.tasks

2. 内容（回车）：建议分阶段输出：

请拆成阶段化 tasks：Setup → Foundational → Feature slices → Polish，并为每个任务写验收标准与依赖。

产物通常落在：specs/<feature>/tasks.md

---

Step 5：按任务实现（Implement）

目的：让 Codex 不是“随便写”，而是“按 tasks 逐条交付”。

1. 命令（回车）：

/prompts:speckit.implement

2. 内容（回车）：最关键的实践：一次只做一个阶段/一小段任务，避免一口气写爆。例如：

先只实现 Phase 1（Setup）相关 tasks，完成后停止，并给出 build/test 的运行方式。

为什么要分阶段？因为这能保证你每一步都能跑起来、可回退、可审查，避免“几十个文件一波流大改动”。

---

5) 一致性体检：/prompts:speckit.analyze（可随时跑）

当觉得 spec/plan/tasks 之间可能不一致，或者 implement 跑了一段后想检查是否“违宪”，就用 analyze：

1. 命令（回车）：

/prompts:speckit.analyze

2. 内容（回车）：

请检查 spec.md、plan.md、tasks.md 的一致性，是否遗漏验收项，是否违反 constitution 的隐私/性能/安全约束，并给出修订建议。

这一步适合当“质量闸门”，尤其在任务多、模块多时很管用。

---

6) 总结：这套 speckit 工作流的真正价值

Spec Kit + Codex 的价值不在于写多少代码，而在于把 AI 开发变成可控工程流程：

• 先立宪：把边界与原则锁死（防跑偏）
• 再规格：把 MVP 与验收写清（防需求膨胀）
• 再计划：把实现路线结构化（防架构散乱）
• 再任务：把执行拆到可交付颗粒度（防不可落地）
• 最后实现：严格按 tasks 分阶段推进（防“一波流写爆”）
• 随时 analyze：跨文档一致性与违宪检测（防悄悄偏航）

这套流程的最大收益是：复现性与可迭代性。你以后做任何新 feature，都可以在 specs/<new-feature>/ 里再走一遍同样流水线，工程不会越做越乱。