GPT88 / API Docs
بلاگ پر واپس جائیں

Codex + GitHub Spec Kit：先写清规格、任务和验收，再分步实现

开发工具2026-10-1810 منٹ مطالعہCodexGitHub Spec Kit规范驱动开发需求分析软件工程

X 用户 goan999999 在 原帖中分享了把 GitHub Spec Kit 接入 Codex 的做法：先澄清需求、业务规则和验收标准，再制定计划、拆分任务，最后按任务实现并检查偏差。原帖发布于 2026 年 10 月 17 日，并将返工率降低 90% 作为标题主张；帖子没有给出对照组、样本量或测量方法，因此这个比例应视为作者的宣传性经验，不能当成普遍结果。本文依据 GitHub Spec Kit 当前公开的项目说明和文档，整理一条可审查的上手路径。

Spec Kit 提供什么

GitHub Spec Kit 是一套开源工具包，提供编码 Agent 集成、可复用工作流和项目工件。对功能开发而言，它的规范驱动开发流程会把“要做什么”逐步转成规格、技术计划和任务，并通过实现后的收敛检查发现缺口。它不是只靠一段提示词自动保证权限、数据持久化、业务逻辑或测试正确的框架；这些要求仍要在规格中写清楚，并用代码审查和验证确认。

Spec Kit 还提供独立的缺陷修复和想法评估流程。一次小型 bug 修复不必先走完整的功能开发阶段；应按任务选择流程，而不是把每个改动都变成大型文档工程。

安装并选择 Codex 集成

官方快速开始要求 Python 3.11 或更新版本、uv，以及受支持的编码 Agent。新建项目可在终端执行：

uv tool install specify-cli
specify init my-project --integration codex
cd my-project

codex 是 Spec Kit 官方集成表中的集成键。它会在项目的 .agents/skills 目录生成对应 Skills；在 Codex 对话中按 $speckit-<command> 形式调用，例如 $speckit-specify。详细步骤和支持状态以 官方安装文档及集成列表为准。

接入已有代码库

已有项目可以在仓库根目录初始化，但官方指南要求先留下一份可审查基线。先提交或暂存当前工作，随后才运行：

specify init --here --force --integration codex

这里的 --force 允许在非空目录初始化，并可能替换冲突位置上的托管文件。执行后应检查完整 diff，确认 README、项目指令和自定义 Skill 没有被覆盖，再决定是否保留生成结果。Spec Kit 会添加它需要的 .specify/ 工件和集成文件，不会自动反向规格化整个旧系统。

参考：Adopting Spec Kit in an Existing Project。

按阶段推进一个功能

一个实用的功能流程可以这样走。命令通过 Codex 集成以 $speckit-<name> Skills 调用；具体可用命令和参数以当前生成文件与官方参考为准。

1. 先记录真实项目原则

项目级 constitution 通常建立一次。只写仓库和团队已经采用的约定，例如公共 API 兼容要求、数据迁移回滚要求、现有测试命令和安全边界。不要为了填模板而发明不真实的“原则”，否则后续规划只会生成噪声。

2. 把功能写成可验证规格

用 $speckit-specify 描述用户要达成的结果、受影响角色和明确排除项。避免只给技术实现指令；先说明行为。例如：

为订单页面增加 CSV 导出。沿用现有筛选条件和授权规则；用户只能导出自己有权查看的行；不要改变现有 JSON API 响应。

再用 $speckit-clarify 处理会影响实现的未知项：无数据时如何反馈、导出列顺序是否固定、导出是否受页面筛选影响。没有业务证据的决定应标为待确认，而不是交给 Agent 猜测。

3. 评审方案和任务再开始编码

用 $speckit-plan 让 Agent 对照现有架构、依赖和测试惯例提出实现方案；用 $speckit-tasks 拆成边界清楚、能独立检查的任务。需要时再运行 $speckit-analyze 检查规格、计划和任务之间的矛盾。

如果团队希望在编码前人工把关，应明确要求 Codex 先展示规格、计划、任务及未决问题，并停下来等评审通过。Spec Kit 提供工作流工件，但是否暂停、谁来批准，仍由你的项目流程和 Codex 当前权限设置决定。

4. 对照验收逐项实现并收敛

评审后运行 $speckit-implement，按拆分任务推进。每完成一段，就依据规格运行与变更相关的测试，检查 diff，并记录尚未解决的边界。运行 $speckit-converge 汇总规格与实现之间的差距；若它指出缺项或生成新任务，继续修复，再次检查，直到问题关闭或明确记录为未解决。

把“按钮能点”改成验收证据

原帖指出的典型问题是表面交互看起来完成，但授权、持久化和业务规则没有落实。把这些写进验收条目，才能让评审和测试检查同一份约定：

维度规格中要回答的问题可核对的证据
权限哪类用户能执行，哪些数据不可见？授权逻辑、允许与拒绝用例
数据保存在哪里，事务或失败重试如何处理？持久化代码、迁移和读写测试
业务规则正常、边界和冲突输入分别怎样处理？规则表和对应测试
失败路径超时、无数据或依赖不可用时用户看到什么？错误处理和失败用例
兼容性旧接口、已有数据和旧工作流需保持什么？契约测试、迁移验证或回归检查
完成条件哪些检查通过才能称为完成？明确的命令、输出或人工评审记录

“补齐测试”并不意味着每次都跑整个测试套件。测试范围应与变更和风险相符；报告中要区分实际运行的检查、未运行的检查，以及尚未覆盖的风险。

可以直接交给 Codex 的阶段提示

使用当前仓库已安装的 GitHub Spec Kit Codex Skills，按规范驱动流程处理这个功能。

先检查相关代码、README、架构约定和已有测试，不要预先假设项目规则。明确目标、角色、边界条件、权限、数据行为、失败路径和可验证的验收标准；存在会改变实现的重要未知项时先提问。

依次产出或更新规格、技术计划和任务清单，检查它们是否符合当前代码结构与项目惯例。完成后先展示这些工件、关键取舍、未决问题和验证计划，暂停等待我评审；在我确认前不要开始大范围编码。

获批后按任务实现，每阶段检查 diff 并运行与变更相符的测试。最后执行收敛检查，报告实际完成项、运行过的验证、剩余差距和未覆盖风险。不要把未验证的推测写成已完成。

提示词能说明协作约定，不能替代仓库权限设置或人工审查。即使流程有规格和任务文档，最终代码仍要经过适当的测试与 diff review。

什么时候值得采用

任务建议
多角色、多模块功能，涉及权限、状态或数据迁移适合先规格、澄清和计划，再分阶段实现
产品需求尚有多个关键未知先做澄清或想法评估，不要让 Agent 把猜测写进代码
已有系统中的单一、可复现缺陷采用诊断、修复、测试这类更短流程
拼写修正或风险很低的局部改动用简短任务和对应检查即可，完整 SDD 可能不划算

是否降低返工，应在自己的项目里用相似任务衡量：记录需求变更、实现后的缺陷、返工次数、交付时间和评审发现的问题。原帖的 90% 数字没有公开测量依据，不宜直接作为预期收益。

来源与核验范围

文中的 Spec Kit 命令、要求和集成方式依据上述官方页面核对，访问日期为 2026-10-18；未来版本可能调整命令和初始化行为。返工率、播放量等原帖表述没有独立验证，不作为教程保证。