从模糊需求到可运行软件：把 Harness Engineering、Spec Kit 和 Codex /goal 串成一条实操链

很多人第一次用 Codex 或其他代码 Agent 做项目，会直接说：“帮我做一个软件。”这句话能启动对话，但通常不能稳定交付。真正能让 Agent 长时间工作的，不是一句大 prompt，而是一套工程环境：需求放在哪里、计划怎么拆、测试怎么证明、做到什么程度算完成。

这就是 OpenAI 在 Harness Engineering 文章里强调的方向：能力不是只来自模型本身，还来自模型周围的工程环境。Agent 看不到的上下文，等于不存在；没有测试和约束，它就容易在长任务里漂移。

这篇教程给你一套可直接照抄的流程：

1. 用 Harness 把项目变成 Agent 看得懂的工作台
2. 用 GitHub Spec Kit 把模糊需求拆成规格、计划、任务
3. 用测试和验收清单定义“完成”
4. 用 Codex /goal 让长任务持续围绕目标推进
5. 用完成审计防止“看起来做了很多，其实没交付”

先记住一个核心原则

不要把 /goal 当成“自动写完整软件”的魔法按钮。

更稳的理解是：

• Harness Engineering 负责“项目环境可读、可测、可修”
• Spec Kit 负责“需求拆解成规格和任务”
• 测试/验收标准负责“判断是否真的完成”
• /goal 负责“让 Codex 在长任务中不丢主线”

这四个组合起来，才是一条完整的软件工程链。

第一步：搭一个最小 Harness

新项目先建这样的结构：

my-app/
├── AGENTS.md
├── ARCHITECTURE.md
├── README.md
├── docs/
│   ├── PRD.md
│   ├── acceptance.md
│   ├── test-cases.md
│   └── deploy.md
├── specs/
├── src/ 或 app/
├── tests/
└── scripts/
    ├── verify.sh
    └── smoke.sh

每个文件只承担一个职责：

• AGENTS.md：告诉 Agent 怎么工作、哪些命令能跑、完成前必须验证什么。
• ARCHITECTURE.md：系统地图，写清模块边界、数据流、依赖方向。
• docs/PRD.md：产品需求，不写实现细节，重点写用户、场景、范围。
• docs/acceptance.md：验收标准，写“什么结果算通过”。
• docs/test-cases.md：测试用例，写正常路径、异常路径、边界情况。
• scripts/verify.sh：一键跑测试、类型检查、构建。
• scripts/smoke.sh：启动后检查页面、接口、健康状态。

最小版 AGENTS.md 可以这样写：

# Agent 工作规则

1. 先读 `docs/PRD.md`、`docs/acceptance.md`、`ARCHITECTURE.md`。
2. 代码改动必须保持模块边界清晰。
3. 每完成一个阶段，运行 `scripts/verify.sh`。
4. 涉及可运行应用时，运行 `scripts/smoke.sh`。
5. 最终回复必须包含：完成了什么、验证证据、未完成风险。

这一步的目的不是写文档给人看，而是把项目知识放到 Agent 每次都能读取的位置。

第二步：把模糊需求变 PRD

先不要急着实现。把模糊想法交给 Codex，让它先写 PRD。

请把下面的模糊需求整理成 `docs/PRD.md`。

需求：
我想做一个图片生成任务管理 Web App。用户可以输入提示词创建任务，查看任务状态，保存历史结果，可以重新生成。先做本地 MVP，不接真实付费接口，用 mock adapter。

PRD 必须包含：
1. 目标用户
2. 核心场景
3. MVP 范围
4. 明确不做什么
5. 页面和接口
6. 数据结构
7. 验收标准
8. 风险和开放问题

好的 PRD 不需要很长，但必须能回答三个问题：

• 这个软件给谁用？
• 用户完成什么任务？
• 第一版做到什么程度算交付？

第三步：用 Spec Kit 拆规格、计划和任务

GitHub Spec Kit 是目前最适合和 Agent 配合的规格驱动工具之一。它的核心链路是：

constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement

初始化示例：

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
specify init my-app --integration codex --integration-options="--skills"
cd my-app

如果是在已有项目里：

specify init --here --integration codex --integration-options="--skills"

然后在 Codex 里按顺序执行：

/speckit.constitution Create principles focused on code quality, testing standards, simple deployment, security boundaries, and agent-readable documentation.

/speckit.specify Build a local MVP image task manager. Users can create image-generation tasks from prompts, see task status, view history, retry tasks, and use a mock image adapter first. Focus on what and why, not the tech stack.

/speckit.clarify

/speckit.plan Use React frontend, FastAPI backend, SQLite storage, mock image adapter, local-first development, and simple Docker deployment later.

/speckit.tasks

/speckit.analyze

/speckit.implement

如果你的 Codex 安装的是 Spec Kit skills 模式，命令名可能显示为 $speckit-specify、$speckit-plan 这类技能名。实际原则不变：先规格，后计划，再任务，最后实现。

第四步：把测试前置

不要等软件写完才问“能不能用”。在实现前就让 Codex 生成测试用例：

根据 `docs/PRD.md` 和当前 spec，生成 `docs/test-cases.md`。
每个核心功能必须包含：
- Given/When/Then
- 正常路径
- 异常路径
- 边界情况
- 可以自动化验证的检查点

示例：

Given 用户输入一条 prompt
When 点击创建任务
Then 系统创建一条 queued 状态任务，并显示在任务列表顶部

再要求它创建验证脚本：

#!/usr/bin/env bash
set -euo pipefail

npm test
npm run lint
npm run build
pytest

把它保存为：

scripts/verify.sh

冒烟测试可以检查：

- 后端 `/health` 返回 ok
- 前端页面可打开
- 创建任务接口可用
- 任务列表能返回刚创建的数据

这就是 Harness 的关键：让 Agent 不只是“写代码”，还能自己证明代码工作。

第五步：用 /goal 锁住长任务目标

当 PRD、spec、测试用例、验证脚本都准备好，再设置 /goal。

推荐写法：

/goal 按照仓库里的 `docs/PRD.md`、`specs/`、`docs/test-cases.md` 完成图片任务管理 Web App MVP。必须保持文档、代码、测试同步；每个阶段运行 `scripts/verify.sh`；最终启动本地服务，运行 `scripts/smoke.sh`，并给出完成审计报告。

注意：不要把几千字 PRD 全部塞进 /goal。更好的方式是把 PRD 写进文件，然后在 /goal 里引用文件路径。这样目标更短、更稳定，也更容易跨上下文恢复。

然后发起执行：

从当前仓库开始。先读取 `AGENTS.md`、`ARCHITECTURE.md`、`docs/PRD.md`、`docs/test-cases.md` 和 `specs/`。制定计划后直接实现。遇到产品歧义再问我；遇到测试失败先定位根因再修。

第六步：长任务要分阶段，不要一口吞

推荐让 Codex 按这个节奏推进：

第一轮：整理 PRD、验收标准、测试用例、架构文档。

第二轮：实现后端 API、数据库、mock adapter、后端测试。

第三轮：实现前端页面、任务状态流、历史记录、重试功能。

第四轮：补齐验证脚本、README、部署说明和冒烟测试。

第五轮：运行完整验证，修复失败，启动服务，完成交付审计。

这样做的好处是：每一轮都有可检查产物，不会把失败堆到最后。

第七步：完成审计模板

不要只接受“我完成了”。让 Codex 最后必须按这个模板交付：

请做完成审计：

1. 重述目标
2. 列出所有显式需求
3. 每条需求对应到具体文件、命令或验证证据
4. 列出运行过的测试和结果
5. 检查是否有未覆盖需求
6. 检查是否有只写了文档但没实现的地方
7. 检查是否有只通过测试但没有覆盖验收标准的地方
8. 给出本地启动命令和访问地址
9. 给出剩余风险

这一步非常重要。长任务最常见的问题不是完全失败，而是“看起来做了很多，但某些显式需求没有覆盖”。完成审计就是防止这种假完成。

GitHub 上能学到的几个实践点

结合 GitHub Spec Kit 和 openai/codex 公开 issue，可以总结出几条实用规则：

1. /goal 适合保存短而明确的长期目标，不适合承载完整需求文档。
2. 详细需求应该放在仓库文件里，例如 docs/PRD.md、specs/*/spec.md。
3. Spec Kit 适合把“我要做什么”拆成 spec、plan、tasks，再交给 Agent 实现。
4. /goal 仍然是实验能力，长任务中可能遇到权限等待、上下文压缩、完成判定等边界问题。
5. 所以必须给 Agent 明确的完成审计，而不是只要求“继续直到做完”。
6. 验证脚本要成为项目的一等公民。没有 verify.sh 的项目，很难稳定长期自动开发。

一条可复制的总 Prompt

下面这段可以直接放进 Codex：

/goal 从模糊需求交付一个可运行软件 MVP。流程必须是：模糊需求 -> PRD -> 验收标准 -> 测试用例 -> 技术方案 -> 任务拆分 -> 实现 -> 自动化验证 -> 本地启动 -> 部署说明 -> 最终完成审计。

工作规则：
1. 先把需求写入 `docs/PRD.md`
2. 再生成 `docs/acceptance.md` 和 `docs/test-cases.md`
3. 再生成 `ARCHITECTURE.md` 和任务清单
4. 实现时保持模块清晰，业务逻辑不要堆在入口文件里
5. 必须创建 `scripts/verify.sh` 和 `scripts/smoke.sh`
6. 每完成一阶段都运行验证
7. 最后启动本地服务，给出访问地址
8. 最终报告必须包含：完成了什么、怎么验证、怎么部署、还有什么风险

然后继续输入：

我的模糊需求是：
这里粘贴你的需求。

请先生成 PRD 和测试用例，然后按阶段开始实现。

最后一句话

真正稳定的 Agent 软件工程，不是“把需求扔给模型”，而是“把需求、约束、验证、完成标准都放进一个 Agent 能反复读取和执行的 Harness 里”。Spec Kit 负责把需求拆清楚，测试负责定义完成，/goal 负责长任务主线。三者合起来，才接近一个可以长期工作的工程代理。

参考资料

• OpenAI: Harness engineering: leveraging Codex in an agent-first world
  https://openai.com/index/harness-engineering/
• OpenAI Developers: Codex use cases
  https://developers.openai.com/codex/use-cases
• GitHub Spec Kit
  https://github.com/github/spec-kit
• Spec Kit Core Commands
  https://github.github.io/spec-kit/reference/core.html
• OpenAI Codex repository
  https://github.com/openai/codex