从 25 小时实验到可复用的 Skill,我如何让 AI 先写文档,再写代码。

一、思考如何执行长任务

订阅了codex 之后,我一直在想怎么能够让他无监督的执行任务,只有在结束的时候我来验证,搜索了之后,这样就不用我问一句他答一句的来实现我的想法

二、文档先行

在项目 docs 目录下生成四份核心文:

text
1
2
3
4
Prompt.md          # 冻结目标
Plan.md # 里程碑规划
Implement.md # 执行手册
Documentation.md # 状态日志
文件 作用 关键内容
Prompt.md 冻结目标 目标、非目标、约束、交付物、Done when
Plan.md 里程碑规划 可验收的里程碑、验证命令、stop-and-fix 规则
Implement.md 执行手册 主循环、验证命令、代码规则、停止条件
Documentation.md 状态日志 当前状态、决策记录、运行方式、已知问题

Prompt.md 的作用是防止 Agent“造出很厉害但错误的东西”。它必须写清楚:做什么、不做什么、硬约束、交付物、以及“Done when”。

一个具体片段:

1
2
3
4
5
6
7
8
9
10
11
12
13
## 项目目标
构建一个 JLPT N2/N1 刷题网站,支持练习、模考、听力精听、错题本。

## 非目标
- 不提供盗版 PDF/音频下载
- 不做社区、排行榜、付费系统
- MVP 只做一套 N2,50-100 题

## Done when
- 能导入一套 N2,包含题干、选项、答案、解析、音频时间段
- 听力可按题播放,支持变速和 AB 循环
- 错题自动保存,可重做
- `pnpm lint && pnpm typecheck && pnpm test && pnpm build` 通过

Plan.md 把开放式工作切成一个个可独立验收的里程碑。每个里程碑都带验收标准和验证命令。

例如:

1
2
3
4
5
6
7
8
9
10
11
12
13
## M4 听力播放器

目标:按题播放、变速、AB 循环、原文

验收:
- 听力题显示播放器
- 播放范围限制在 audio_start_ms/audio_end_ms
- 支持 0.8/1.0/1.2 变速
- 精听模式可 AB 循环

验证命令:
- pnpm test audio
- pnpm playwright test e2e/listening.spec.ts

最关键的一条规则是 stop-and-fix:验证失败,先修复,再进入下一里程碑。

Implement.md 是 Agent 的 runbook。它告诉 Codex 每次运行前读什么、主循环怎么走。

一个简化片段:

1
2
3
4
5
6
7
8
9
10
11
12
13
## 每次运行前
1. 阅读 docs/Prompt.md
2. 阅读 docs/Plan.md
3. 阅读 docs/Documentation.md
4. 选择 Plan.md 中第一个未完成里程碑

## 主循环
1. 计划本里程碑的最小实现
2. 编辑代码
3. 运行验证命令
4. 修复失败
5. 更新 docs/Documentation.md
6. 进入下一里程碑

Documentation.md 是共享记忆和审计日志。每完成一个里程碑,就更新当前状态、记录关键决策、更新已知问题、添加变更日志。

例如:

1
2
3
4
5
6
7
8
9
10
11
12
13
## 当前状态
- 当前里程碑:M4 听力播放器
- 已完成:M0、M1、M2、M3
- 下一步:M5 答题卡与提交
- 阻塞:无

## 决策记录
### 2026-10-14 音频按题切分
决策:每题存 audio_start_ms / audio_end_ms。
原因:模考模式要求听力只播一次,按题播放更接近真实考试。

## 已知问题
- 部分长音频切分后首尾有 100ms 静音,待优化。

这四份文档不是启动时的一次性计划,而是持续更新的活文件。长任务的可靠性,来自这种“外化的状态”。

三、问题来了:每次新项目都手动写文档,太累

这套方法有效,但有个明显的痛点:每次做新项目或者实现一个新功能,都要手动生成这四份文档,还要保证结构一致、内容完整。想法很多的人,会被这个流程拖死。

更好的做法是:让 Codex 自己先生成这四份文档,然后按文档执行。

有三种实现方式,从轻到重。

方案一:元提示词

每次把一段固定提示词粘给 Codex。它先以“一次一个问题”的方式澄清需求,然后生成四文档,等你确认后再开始执行。

一个可用的元提示词开头:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
你是一个项目规划专家。我将描述一个项目需求,请你生成完整的项目文档包。

## 第一步:需求澄清
在生成文档前,先以“一次只问一个问题”的方式向我确认:
1. 项目的核心目标和边界
2. 技术栈偏好和硬约束
3. 交付物的验收标准

每个问题附上你的推荐答案和理由,我可以用“y”确认或提出修改。

## 第二步:生成文档
确认完成后,在 docs/ 目录下生成:
- docs/Prompt.md
- docs/Plan.md
- docs/Implement.md
- docs/Documentation.md

优点是简单,不需要配置。缺点是每次都要粘贴,容易遗漏或变形。适合一次性项目。

方案二:AGENTS.md

在仓库根目录放一份 AGENTS.md。Codex 执行任务前会自动读取它。

例如:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# AGENTS.md

## 文档先行规则
任何新项目必须先有:
- docs/Prompt.md
- docs/Plan.md
- docs/Implement.md
- docs/Documentation.md

没有这四份文档,不写业务代码。

## 工作流
1. 先澄清需求
2. 再生成四文档
3. 用户确认后,从 Plan.md 的 M0 开始执行
4. 每个里程碑必须运行验证命令
5. 验证失败先修复,不进入下一里程碑
6. 每完成一个里程碑,更新 Documentation.md

这样你每次只需要说“我要做一个新项目,需求是……”,Codex 就会按规范自动生成文档并执行。适合单个长期项目。

方案三:Skill(推荐)

如果你有很多想法,会反复做新项目,最彻底的方式是把整套流程封装成一个 Codex Skill。

Skill 的本质是:把一套可重复的工作流程,用自然语言加少量脚本固化成 Agent 可读的指令。它和人类组织的 SOP 文档没有本质区别,只是读者从人变成了模型。

文件结构可以是这样:

text
1
2
3
4
5
6
7
~/.codex/skills/docs-bootstrap/
├── SKILL.md
└── references/
├── prompt-template.md
├── plan-template.md
├── implement-template.md
└── documentation-template.md

SKILL.md 的核心内容:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# docs-bootstrap

## 描述
从一句话需求开始,先澄清需求,再生成四文档,然后按文档执行。

## 需求澄清规则
1. 一次只问一个问题。
2. 每个问题附上推荐答案和理由。
3. 用户可以用 “y” 确认,或提出修改。
4. 能从仓库推断的事实,不要问用户。
5. 非阻塞的不确定项写入 docs/ASSUMPTIONS.md。
6. 阻塞项立刻停下来问。

## 执行流程
1. 读取仓库上下文。
2. 澄清需求。
3. 生成四文档。
4. 生成 AGENTS.md。
5. 输出:“文档已生成,请确认后开始执行。”
6. 用户确认后,读取 docs/Implement.md。
7. 选择 docs/Plan.md 中第一个未完成里程碑。
8. 执行主循环。
9. 每完成一个里程碑,更新 docs/Documentation.md。

以后你只需要说:

用 docs-bootstrap 做一个新项目:我想做……

Codex 会自动澄清、生成文档、等待确认、按计划执行。

Skill 的优势是跨项目复用、可分发、渐进式披露、Token 效率高。它把“每次手写工作手册”变成了“把工作手册本身变成产品”。

现有的 skill goal-pipeline 就是类似的skill

三、需求澄清:一次只问一个问题

无论是元提示词还是 Skill,需求澄清阶段都要有纪律。

规则可以写死:

一次只问一个问题。

每个问题附上推荐答案和理由。

用户可以用 “y” 确认,或提出修改。

能从仓库推断的事实,不要问用户。

非阻塞的不确定项写入 ASSUMPTIONS.md。

阻塞项立刻停下来问。

实际对话可能像这样:

text
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Codex:第一个问题:这个刷题网站是私有部署,还是公开运营?

推荐答案:默认私有部署。
理由:JLPT 真题版权通常归主办方所有,公开上传有风险。
如果你确认,回复 y;如果要公开运营,请说明授权来源。

你:y

Codex:第二个问题:MVP 先做 N2 还是 N1?

推荐答案:先做 N2。
理由:N2 题型更稳定,用户基数更大,适合先跑通流程。
如果你确认,回复 y;如果先做 N1,请说明原因。

你:y

这套规则把“拷问”从风格变成了可重复执行的协议。它确保在写任何代码之前,目标和边界已经对齐。

四、执行循环:计划 → 实现 → 验证 → 修复 → 更新文档

文档生成后,Codex 进入执行循环:

阅读 Prompt.md、Plan.md、Documentation.md

选择 Plan.md 中第一个未完成里程碑

计划最小实现

编辑代码

运行验证命令

修复失败

更新 Documentation.md

进入下一里程碑

每个里程碑都必须有可执行的验证命令,比如:

1
2
3
4
5
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm playwright test

一次实际的执行日志可能像这样:

text
1
2
3
4
5
6
7
8
9
10
11
12
[M4 听力播放器]
1. 读取 docs/Prompt.md、docs/Plan.md、docs/Documentation.md
2. 选择第一个未完成里程碑:M4
3. 实现 AudioPlayer 组件,支持 start_ms / end_ms
4. 运行 pnpm test audio
-> 失败:AB 循环边界未处理
5. 修复 AB 循环边界
6. 重新运行 pnpm test audio
-> 通过
7. 运行 pnpm playwright test e2e/listening.spec.ts
-> 通过
8. 更新 docs/Documentation.md:M4 完成,下一步 M5

更严格的做法是让每个任务携带 TDD 契约:先写的失败测试、预期的失败信号、最小通过实现的边界、验证命令。强制垂直切片的 RED → GREEN → REFACTOR,拒绝“加 model”“加 API”这类横向切片。这把质量保证从“事后验证”前移到了“任务定义本身”。

你只需要在两个节点介入:需求澄清阶段和里程碑验收阶段。中间过程由 Codex 按文档自动推进。

五、文档要“活”起来

Documentation.md 不是摆设。每完成一个里程碑,必须更新:

当前状态:当前里程碑、已完成、下一步、阻塞

决策记录:日期、决策、原因

如何运行项目

Demo 流程

已知问题

变更日志

一次更新示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
## 当前状态
- 当前里程碑:M5 答题卡与提交
- 已完成:M0、M1、M2、M3、M4
- 下一步:M6 错题本、收藏、笔记
- 阻塞:无

## 决策记录
### 2026-10-14 答题卡采用服务端保存
决策:每次作答后立即写入 answers 表。
原因:防止浏览器崩溃导致进度丢失,也方便跨设备恢复。

## 变更日志
- 2026-10-14:完成 M4 听力播放器,支持变速和 AB 循环。
- 2026-10-14:修复 AB 循环边界问题。

每次修复非平凡 bug 后,记录问题和修复方式。每次新增依赖时,记录依赖名、版本、引入原因。

这样即使你离开几小时,回来只需要读这一份文件,就能恢复全部上下文。长任务的可靠性,来自这种持续的状态外化。

六、关于 Skill 与随机性的思考

Skill 就是自然语言写的 SOP。每个人写的不一样:语言不同,思路不同,描述方式不同。这些差异会实质影响大模型的运行结果。

指令的明确性、结构的清晰度、示例的有无、边界的定义、术语的一致性,都会改变 Agent 的执行路径。同一个 Skill 多次执行,结果也不会完全一样,因为推理是采样的。即使 temperature 设为 0,由于浮点运算和硬件差异,也未必完全可复现。

但这不意味着结果是混乱的。好的 Skill 不追求路径一致,而追求终点合格。它用验证命令、验收标准、里程碑检查点,保证每次输出都落在可接受的范围内。

Skill 有相对好坏,但没有绝对第一。好坏必须绑定到具体优化目标才有客观意义:

优化目标 更优的 Skill 设计
长任务不漂移 带里程碑验收 + 持续状态日志
省 Token 渐进式披露,按需加载
跨模型可移植 不依赖特定模型特性
减少返工 强制 TDD 契约 + 垂直切片
快速原型 轻量元提示词,少文档

所以,Skill 的质量不该用“写得好不好”来评价,而该用“在多次执行下的成功率分布”来评价。你可以对同一个 Skill 跑 10 次,看里程碑通过率、漂移次数、返工次数,用数据判断它好不好。

例如:

text
1
2
3
4
Skill A:10 次运行,8 次全部里程碑通过,平均返工 1.2 次
Skill B:10 次运行,5 次全部里程碑通过,平均返工 3.4 次

结论:在“长任务不漂移”这个目标下,Skill A 更优。