字号大小
纸张与主题
导读

世界上最简单的
Codex Vibe Coding

给靠自然语言推进、用结果验收的独立开发者与创业者。

适配 GPT-6.2(Astra & Sol) · 融入 Harness Engineering · 每章附可复制操作卡

把注意力留给真正重要的事

2026 年,写代码的边际成本已经接近于零,但好代码和人的注意力依然极其昂贵。 很多人的 Vibe Coding 之所以在中后期崩盘,不是因为模型不够聪明,而是因为陷入了两个陷阱:

碎片化微管理
每隔几分钟就被 AI 追问一个技术细节,深度思考被切得支离破碎。
黑盒失控
平时只点点界面验收,直到上线后才发现重复扣费,半年后也难以接手。
全书核心心法

人类掌舵,智能体执行。
把目标、边界和验收标准说清楚,让执行持续向前。

怎样使用这本书

全书以主人公阿肯从 0 到 1 做一个带照片上传、会员权益和支付扣费的“回忆册”应用为主线。 你不需要背任何命令,跟着阿肯踩坑、拍板、验收,每章末尾的操作卡可以直接一键复制,粘贴给你的 Codex 使用。

第一篇 · 搭台子与防打扰 · 01

别急着写代码,先画一张“百行地图”

刚建好空仓库就急着让 Codex 写功能?90% 的失控,都在第一天埋下了伏笔。

核心工具:AGENTS.md · docs/ 目录 · GPT-6.2 Sol / Astra 选型
阿肯
阿肯(周一早上 9:00)
帮我做一个“回忆册”应用:用户上传照片、选封面、开通 VIP 后能导出高清电子书。直接开写吧!
CX
Codex(5 分钟后弹出第一个问题)
请问数据库用 SQLite 还是 PostgreSQL?图片存本地还是 OSS?VIP 权益按次扣还是按月算?等你确认后我再继续……

阿肯本想说完需求就去谈合作,结果一上午被 Codex 打断了七次。下午他把所有规矩一股脑写进了一个 800 行的 AGENTS.md,以为一劳永逸——结果两天后,Codex 反而开始频繁漏掉最核心的约束。

为什么“百科全书式”的 AGENTS.md 一定会失败?

OpenAI 团队用 Codex 零手写交付百万行代码的实战里,踩过一模一样的坑:上下文是稀缺资源。 文件一大就会挤占任务和代码的空间;什么都标成“重要”,等于什么都不重要,而且几周后就会腐烂成过时规则的坟场。

AGENTS.md 永远 ≤ 100 行 只做目录地图与硬红线 docs/product-specs/ 业务规则表(VIP 权益、扣费、防重规则) docs/exec-plans/active/ 当前活跃的执行计划与关键决策记录 ARCHITECTURE.md 模块分层地图与依赖边界
图 1-1 · 渐进式披露:给 Codex 一张百行地图,而不是一本千页说明书

选对模型,并治好 Astra 的“爱打扰”脾气

场景推荐模型与档位原因
日常页面、文案、小功能迭代gpt-6.2-sol + Light / Medium极快,单任务成本约为重型模型的 1/7
架构定型、跨服务排障、支付/权限核心gpt-6.2-astra + High / Max深度推理稳,扛得住复杂边界测试
避坑提醒:Astra 很容易“停下来等你”

GPT-6.2 Astra 在遇到轻微模糊时,非常习惯提出方案后停下来等你回复。解法是在 AGENTS.md 里写死可逆假设权:可逆的技术细节自行做最简假设并推进,只有不可逆变更或改需求边界时才停下来问人。

📋 操作卡 · 《100 行项目开局宪章》(存为仓库根目录 AGENTS.md)
# 项目地图(保持 ≤ 100 行,详细文档按需读取)

## 1. 唯一真相来源
- 产品业务规则:`docs/product-specs/`
- 系统模块与边界:`ARCHITECTURE.md`
- 当前活跃执行计划:`docs/exec-plans/active/`
- 本地运行与测试:`npm run dev` / `npm test`

## 2. 自主权与防打扰原则
- **自行推进**:所有可逆的技术实现细节(命名、目录、常规组件),请你做出最简假设后直接推进,交付时简述假设即可,不要中途停下来问我。
- **必须停下来问我**:涉及付费/扣费规则、权限边界、删除旧接口、不可逆数据库迁移时,必须先停下。
- **提问格式**:必须附带【需要你决定 / 我的建议 / 业务影响】,禁止抛出开放式技术长文。

## 3. 交付硬标准
- 任何核心改动必须附带可运行的验证证据,并明确列出“已验证”与“未验证”项。
第一篇 · 搭台子与防打扰 · 02

把需求翻译成“人话”

为什么你总觉得 AI 说话太绕?因为你让它用程序员的语言,来考一个做生意的人。

核心工具:/plan 澄清模式 · 业务规则表 · 防打扰决策卡
阿肯
阿肯
/plan 我要加一个“会员导出回忆册”功能。先别写代码,也别讲技术方案,把模糊的业务规则翻译成“表格+决策卡”,让我 1 分钟拍完板。
CX
Codex(30 秒后,只丢出 1 张表 + 2 个选择题)
已阅读仓库现状。开工前只需你确认下面这张规则表和 2 个决策点,其余技术细节我将按最简方案自主推进。

动作一:用“规则表”替代千字长文

人的大脑极其擅长判断具体场景的对错,极不擅长阅读抽象的文字描述。强制 Codex 输出“正常、失败、重复、边界”四行表,你扫一眼就能发现漏掉的坑:

用户遇到的情况系统应该表现出来的可观察结果
VIP 有可用额度,点击生成进入生成中状态,完成后可下载 PDF
后台渲染超时或失败明确提示失败原因,提供重试按钮,不扣额度
卡顿时用户连续点两次识别为同一次操作,不重复生成、不重复扣额度
非 VIP 或额度为 0拦截生成,弹出清晰的升级引导

动作二:问题必须“带着建议”来

✗ 碎片化打扰(传统聊法) 10:05 问:扣费放前端还是后端? 10:12 问:失败了要回滚事务吗? 10:21 问:错误码返回 400 还是 409? 结果:一上午被切碎,人比 AI 还累 ✓ 前置高密度对齐(决策卡) 10:00 一次性拍板 2 个业务选择题 10:02 确认规则表并落盘到 docs/ 10:03–11:30 零打扰,人去忙生意 结果:把思考集中在开工前 5 分钟
图 2-1 · 保护注意力的核心:把 20 次碎片打扰压缩成 1 次高密度决策
📋 操作卡 · 《/plan 防打扰需求对齐指令》
/plan 我要实现以下功能:[用大白话描述你的想法]

先不要写代码,请按下面两个要求回复我,禁止长篇技术科普:
1. 输出一张《业务规则表》,列出:正常流程、失败情况、重复操作、边界情况下的用户可观察结果。
2. 如有必须由我拍板的业务歧义,最多列 3 个,严格按以下格式提问:
   - 【需要你决定】:一句话说明问题
   - 【我的建议】:你推荐的最简方案
   - 【业务影响】:选这个方案对用户或后续维护有什么影响

其余可逆的技术细节,你自行决定即可。
第一篇 · 搭台子与防打扰 · 03

放手让它跑,你去忙生意

计划定好了,怎么让 Codex 自己把多步工作稳稳做完,而不是写两步就卡住或跑偏?

核心工具:/goal · /goal pause & resume · exec-plans 落盘

规则表拍板后,阿肯只说了一句:“按建议来,把计划存进 docs/exec-plans/active/vip-export.md。” 把计划当成一等公民落盘到仓库——聊天记录会滚走,但仓库里的执行计划不会丢。

什么时候从 /plan 切到 /goal?

/plan 想清楚
目标模糊、有多种方案取舍时使用,只调研、不改代码。
/goal 干到底
目标与验收标准(DoD)明确后使用,持续推进多步实现、自跑测试、自修报错。

让 /goal 不跑偏的三个开关

  1. 写清“完成条件(DoD)”:不要只说“做完会员导出”,要说“4 条业务规则均有自动化测试通过,且不破坏现有登录和上传”。
  2. 划出“禁止触碰区”:明确哪些核心表或旧接口本轮不许动,防止 AI 好心办坏事。
  3. 善用 /goal pause 与 /goal resume:中午突然有紧急小改动,直接暂停长任务,处理完再无缝续跑,完全不打乱主线。
📋 操作卡 · 《/goal 长任务派发卡》
/goal 依据 `docs/exec-plans/active/vip-export.md` 完成会员导出回忆册功能。

完成条件(DoD):
1. 规则表中的 4 种场景全部实现,并补齐自动化测试且全部通过。
2. 现有照片上传与登录回归测试通过。
3. 禁止修改用户鉴权中间件与历史订单表结构。

自主边界:
- 常规实现与本地报错请自行排查修复,不要中途打断我。
- 全部完成后,输出《四项交付单》(改了什么 / 怎么验证 / 影响范围 / 哪些仍未验证)。
第二篇 · 多线推进与复利 · 04

什么时候该“另起炉灶”?

同一个对话聊了三天,Codex 怎么越聊越傻?学会切对话,上下文才不会腐烂。

核心工具:新会话 · 分叉(Fork) · @ 引用历史任务
阿肯
阿肯(周五下午,在同一个超长对话里已经聊了 60 轮)
刚才我让你保留旧版上传接口给小程序用,你怎么又顺手把它删了?!我前面不是说过两次了吗?
CX
Codex
抱歉,前面的历史记录里包含了三次互相矛盾的修改方案,我误把旧接口当成了废弃代码。

这不是模型变笨了,而是遇到了上下文腐烂(Context Rot)。旧的报错日志、推翻过的方案、被废弃的猜测全堆在一个对话框里,Codex 的注意力被稀释了。

🧪 交互演示 · 上下文腐烂模拟器 点一点看懂
红线
当前任务
当前对话轮数
5 轮
有效信息占比
100%
误删旧接口风险
极低
📌 第 2 轮定下的红线:“保留旧版上传接口,小程序还在用” 清晰锁定
上下文干净,Codex 牢记“保留旧接口”红线,执行精准且省 Token。

一条最容易执行的铁律:按“独立可验收成果”切对话

当前情况最佳动作原因
还在排查、修复同一个 Bug继续原对话保留已经查清的现场线索,不重复踩坑
当前功能已验收,准备做下一个独立功能新开对话彻底清零无关噪音,省 Token 且更精准
想保留前面的调研,但换一条技术路线试试分叉(Fork)继承调研结论,两条路线互不污染
纠正了两次依然反复犯错、引用旧结论立刻止损新开让旧对话写份 5 行交接单,直接换干净大脑

新开对话 ≠ 从零重新解释一遍

很多用户舍不得关旧对话,是怕“新对话什么都不知道”。在最新版的 Codex 客户端里,你有两个极轻量的衔接武器:

  • 用 @ 直接引用上一个已验收的任务:新对话里直接敲 @ 选中之前的任务,Codex 会按需读取它的核心结论,而不会把几十轮废话全倒进来。
  • 让旧对话吐一张 5 行交接单:特别把“为什么不能动某个旧东西”写清楚——阿肯踩过的那个“误删旧接口”的坑,就是因为交接时只说了“做什么”,没说“保什么”。
📋 操作卡 · 《跨对话极简交接单指令》(关旧对话前发这一句)
本轮任务已结束,我准备新开一个干净对话推进下一阶段。
请输出一份不超过 10 行的《交接单》,方便我直接贴给新对话:
1. 当前已完成的成果与所在分支/提交号;
2. 关键业务决定与“绝对不能删除/修改的红线”(写明原因);
3. 已验证通过的命令与结果;
4. 留待下一阶段处理的唯一明确目标。
第二篇 · 多线推进与复利 · 05

派小弟,还是开分厂?

什么时候用子 Agent,什么时候开两个独立对话互相协作?一图看懂并行不翻车的底层逻辑。

核心工具:Subagents · Ultra 档 · 跨对话协作 · Git Worktree

回忆册用户涨起来后,阿肯同时遇到两件事:一是“用户反馈照片上传偶尔卡住”,需要同时查前端压缩、后端接口和对象存储日志;二是他想顺手把“会员积分体系”也启动了。

阿肯
阿肯
这两件事我能不能全丢给子 Agent 一起干?或者开两个对话让它们自己聊?
CX
Codex
别混为一谈。查上传卡顿是“派小弟分头查线索,最后我汇总”;做会员积分是“开一座独立分厂,有自己的排期和验收”。

一张图分清:子 Agent vs 跨对话协作

模式 A:子 Agent(派小弟) 主对话派活 → 小弟在独立上下文查完 → 只交摘要回来 典型场景:查上传慢(前端 / 接口 / 存储三路并查) 核心价值:大段日志不污染主对话,防上下文腐烂 • 触发:嘴上派活,或开 Ultra 档让 Codex 自动拆 • 铁律:适合并行读与分析,写代码保持主线收口 模式 B:独立对话协作(开分厂) 两个顶层对话各有独立目标、独立验收和生命周期 典型场景:A 线修上传,B 线开发会员积分 核心价值:互不阻塞,各自独立迭代与发版 • 隔离:必须配合 Git Worktree,防止文件互相覆盖 • 协作:用 @ 引用对方契约,约定谁负责最终合并
图 5-1 · 生产级多智能体黄金法则:并行读(分析/排查),单线程写(修改同一核心状态)
别为了“看起来酷”而乱开并行

Cognition 与 Anthropic 的生产复盘都证实了同一件事:并行子 Agent 的 Token 消耗是单对话的 3~4 倍。如果两个并行的 Agent 同时修改同一块业务逻辑,极易产生隐式冲突。只有当调查日志极长、或两条业务线物理隔离(Git Worktree)时,并行才真正划算。

📋 操作卡 · 《三路并行排查子 Agent 指令》
现在出现“照片上传偶尔超时”的故障。为了不污染当前主对话上下文,请派生 3 个只读子 Agent 并行排查:
- 子 Agent 1:只检查前端压缩与超时重试配置;
- 子 Agent 2:只检查后端上传接口与鉴权耗时;
- 子 Agent 3:只检查对象存储签名与近 24 小时错误日志。

要求:
1. 三个子 Agent 均严禁修改任何代码,各自只返回不超过 10 行的证据摘要;
2. 由你(主 Agent)汇总三方证据,给我一份根因判断与最小修复方案,我拍板后再动手。
第二篇 · 多线推进与复利 · 06

把踩过的坑,变成肌肉记忆

同样的规矩叮嘱了三次,就别再靠嘴说了——把它固化成 Skill 和确定性护栏。

核心工具:Skills · Hooks · 自定义 Linter(把品味写成代码)

做到第三周,阿肯发现自己每次新建一个后端接口,都要重复打一遍同样的话:“记得校验登录态、记得统一错误格式、记得写完跑一遍回归测试。”

Simon Willison 在《Agentic Engineering Patterns》里把高手和新手的分水岭总结为一个词:囤积复利(Hoard)——凡是验证跑通一次的好流程,立刻封装成可复用资产;而 OpenAI 的 Harness Engineering 更进一步:当文档约束不住 AI 时,把规则直接变成代码。

三层固化梯子:什么时候该用哪一层?

层次工具适用场景执行确定性
第一层:目录索引AGENTS.md全局地图与少量红线原则靠模型自觉遵循
第二层:标准作业流Skills高频复用的固定套路(如:新建接口、发版前自检、输出交付单)按需加载,极省上下文
第三层:机械护栏Hooks / 自定义 Linter绝不容忍出错的底线(禁止提交密钥、禁止越层调用、强制运行测试)100% 确定性拦截
神级小技巧:把修复指南写进报错信息里

当你让 Codex 帮你写一条自定义检查脚本(Linter)时,不要只让它输出“违规报错”,而是让报错信息直接写明:“禁止 UI 层直接调数据库,请改用 Service 层接口”。这样下次任何 AI 触碰红线时,报错信息会自动教它怎么秒修。

📋 操作卡 · 《一键把本次成功流程封装成 Skill》
刚才我们“新建支付/权益接口 → 补边界测试 → 输出四项交付单”这套流程跑得非常顺。
请你把它封装成一个项目级 Skill,存到仓库的 Skills 目录里,命名要直白(例如 `new-billing-endpoint`)。

要求:
1. 写清楚触发条件(什么时候该自动调用它);
2. 把刚才验证成功的 4 个步骤写成精简清单,不写废话;
3. 如果其中有可以做成 100% 确定性检查的规则(例如禁止把数据库对象直接返回给前端),顺手帮我加一条自定义检查脚本,并在报错信息里写明修复方式。
第三篇 · 锁死黑盒质量 · 07

给 Codex 装上眼睛,再看它的“作业报告”

不逐行读源码,怎么知道代码没写乱、界面没崩?别再用肉眼当 QA 了。

核心工具:浏览器/DevTools 自动化 · 线性走查 · /review · 四项交付单
阿肯
阿肯(对着屏幕点了 15 分钟按钮,眉头紧锁)
你每次改完代码都说“已完成”,我得自己打开浏览器、登录、上传、点导出……万一你把某个角落改坏了,我根本看不出来。我感觉这个项目正在变成一个我控不住的黑盒。
CX
Codex
问题不在于你不看源码,而在于我目前是个“盲人程序员”——我写完代码就停手了,既没自己启动页面看效果,也没给你交一份说清边界的验收单。

升级一:给它装上眼睛(应用可读性)

OpenAI 在《Harness Engineering》里点破了代码吞吐量暴涨后的真正瓶颈:人工 QA 能力。 破局方式是让应用对智能体直接可读——在独立的 Git Worktree 里让 Codex 自己把服务跑起来,接入浏览器自动化或 Chrome DevTools 协议,让它自己点按钮、截屏检查 UI 排版、直接查报错日志。

1. 自己跑起来 独立环境启动应用 2. 自己点 & 截屏 走完用户路径 + 查日志 3. /review 自查 检查结构与隐藏回归 4. 交“作业报告” 走查 + 四项交付单
图 7-1 · 告别“盲人编程”:把重复点界面的体力活还给 Codex,人只看证据与边界

升级二:不看源码,看“线性走查”与《四项交付单》

Simon Willison 在他的工程模式里极力推崇线性走查(Linear Walkthrough):既然你不读源码,就让 Codex 改完后,按业务数据流写一份带验证证据的简短讲解,并附带固定格式的《四项交付单》:

交付单栏目必须包含的硬证据
1. 改变了什么用业务语言说清改了哪几件事,不堆砌文件名
2. 怎么验证的实际运行了哪条测试命令、走了哪条页面路径、真实输出是什么
3. 影响范围动了哪些模块、接口、数据库表,有没有波及老功能
4. 仍然未知(最值钱)明确坦白哪些场景还没测、哪些边界需要人工确认
📋 操作卡 · 《四项交付单 + 线性走查验收指令》
在宣布本次任务完成前,请先自行完成以下三步验收,再向我汇报:
1. 启动本地应用,模拟真实用户走完核心路径(正常 + 异常分支),检查控制台与服务端是否有隐藏报错。
2. 对本次未提交变更运行一次 `/review`,检查是否存在职责混乱或波及无关模块。
3. 按以下格式给我一份极简《四项交付单》(不贴大段源码):
   - 【改变了什么】:用业务语言 3 句话讲清;
   - 【线性走查】:数据从点击按钮到落库是怎么流转的;
   - 【怎么验证的】:实际执行的命令、页面核对结果;
   - 【仍然未知】:诚实列出本次未覆盖的场景与剩余风险。
第三篇 · 锁死黑盒质量 · 08(标杆章)

点了两次,为什么生成两本书?

一次真实的线上双击故障,带你走完 /plan → /goal → /review + 红/绿 TDD 的完整工程闭环。

核心工具:/plan · /goal · /review · 幂等设计 · 红/绿 TDD
阿肯
阿肯(周五晚上,看着后台两条重复扣费记录)
用户点下“生成回忆册”,按钮没反应,他又点了一次。结果后台生成了两本,扣了两次额度!把按钮点完变灰,不就解决了吗?
CX
Codex(在 /plan 模式下拦住了他)
按钮变灰只能防手快,防不住弱网重试、刷新或并发请求。先别急着改代码,请用 30 秒拍板下面这张决策卡:

第一步:用 /plan + 决策卡,把“同一次”说清楚

需要你决定Codex 建议业务影响
同一个相册,以后还能重新生成吗?允许。只拦住同一次点击的误重复改完封面能重做,不误伤正常需求
同一个请求号,如果参数变了怎么办?明确报冲突(409)防止旧请求号被误用来覆盖新内容
只灰掉按钮,还是前后端一起防?前端复用请求号 + 后端原子防重彻底堵死弱网重试和并发双花
① 请求 A · 内容 P(首次到达) → 登记并创建任务 T1 ② 请求 A · 内容 P(重发 / 并发) → 直接返回原任务 T1,不新建 ③ 请求 B · 内容 P(主动新生成) → 换了新号,允许创建任务 T2 ④ 请求 A · 内容 Q(旧号带新参) → 明确报冲突,绝不悄悄当重试
图 8-1 · 幂等四象限:把请求号想成取件单,同一张单子只取同一件货

第二步:切到 /goal,用红/绿 TDD 先证明会失败

TDD 不是为了凑测试覆盖率,而是为了在不看源码的情况下,锁死最值钱的业务规则:先写测试跑旧代码,亲眼看到它因重复创建而失败(红);再用数据库唯一约束 + 事务最小修复,重跑全绿(绿)。

真实并发演示(Python + SQLite 8 线程)缺陷版(修复前)修复版(原子约束)
同号同参,顺序重发2 项任务(失败)1 项任务 ✓
同号同参,8 路并发同时到达8 项任务(雪崩)1 项任务 ✓
同号携带不同参数未拒绝冲突明确报冲突 ✓
主动换新请求号2 项任务2 项任务 ✓
🧪 交互演示 · 并发双花与幂等模拟器 动手体验
用户 VIP 剩余额度(初始 3)
3
后台实际创建任务数
0
成功拦截重复请求
0
客户端请求
同一取件单号 REQ-A102
等待触发请求…
数据库(无唯一锁)
并发时先查后插会留空隙
提示:先在「缺陷版」点一下【模拟 8 路并发】,再切到「修复版」重跑对比。

第三步:用 /review 识破全绿假象,并把记忆落盘

看证据,更要看证据的边界

测试全绿(9/9)只证明了任务创建这一层没问题。交付单必须明确写出哪些仍未验证:前端是否真的复用了原请求号?后台队列重投和扣费回调有没有单独防重?最后把规则写入 docs/product-specs/idempotency.md 并在 AGENTS.md 留索引,半年后新对话就能秒级唤醒。

📋 操作卡 · 《TDD 故障修复全闭环指令》
/goal 修复“回忆册重复创建任务”故障。

规则:
- 同用户、同请求号、同参数,无论顺序重发还是并发到达,只创建 1 项任务;
- 主动换新号允许新建;同号异参明确报冲突。

执行方式(红/绿 TDD):
1. 先写出能复现“并发重复创建”的自动化测试,运行并确认旧代码失败。
2. 用数据库唯一约束 + 事务做最小修复,重跑测试确认全绿。
3. 跑一次 /review,输出《四项交付单》(改了啥 / 怎么验 / 影响啥 / 哪些仍未验证)。
4. 将业务规则与测试命令写入 `docs/product-specs/idempotency.md`,并在 `AGENTS.md` 补充索引。
第三篇 · 锁死黑盒质量 · 09

别让写代码的人,自己批改作业

上线前最怕越权、并发双花和数据泄露。换一个干净大脑来做防御性安全审计,才真能抓出暗雷。

核心工具:独立审查会话 · Codex Security · 防御性审计话术
阿肯
阿肯(回忆册准备收钱上线的前一晚)
我刚在写代码的对话里问它“有没有安全漏洞”,它自信地说“逻辑很严谨,没问题”。但我心里还是虚——万一有人改个订单 ID 就能看别人的私密相册呢?
CX
Codex(全新开启的独立审查会话)
让写代码的同一个会话自查,它会被自己刚才的推理惯性带偏。换个完全干净的上下文,我们只盯死三件事:权限、钱、隐私。

Vibe Coding 项目最容易埋下的三颗暗雷

越权访问
接口只凭前端传来的 albumId 或 userId 就查库,忘了校验该资源是不是属于当前登录用户。
资产与并发
扣额度写成“先查余额 → 再减 1 → 再写回”,并发请求瞬间双花;或支付回调没做签名校验与防重放。
数据与后门
接口把整张用户表字段(含手机号、内部标识)直接透传给前端;或修 Bug 时留下的临时绕过逻辑忘了删。
2026.11 新坑避雷:别让模型“扮演黑客攻击”

GPT-6.2(Astra / Sol)的网络安全防线达到了 Critical 级别。如果你直接说“像黑客一样攻击我的代码并写出漏洞利用脚本”,很容易触发安全拒答。正确姿势是配合 Codex Security,用“防御性合规审计 + 业务逻辑防回归测试”的话术,既能 100% 抓出真漏洞,又绝不触发误杀。

📋 操作卡 · 《防御性安全审计卡》(请在新开干净会话中使用)
你现在担任本项目的独立安全架构审查员(仅做防御性代码审计,本轮不改代码)。
请重点审查以下核心目录:[填入路由/鉴权/支付目录],只排查四个高危维度,禁止输出“建议开 HTTPS”这类通用废话:

1. 访问控制与越权:所有增删改查接口是否都从服务端受信任 Session/JWT 解析身份,并校验资源归属?是否存在批量赋值篡改 VIP/余额的风险?
2. 支付与并发一致性:扣费、额度消耗、支付回调是否使用数据库事务/原子条件更新,并具备签名校验与幂等防重?
3. 敏感数据保护:API 是否过度透传了数据库对象?是否存在硬编码密钥或危险兜底配置?
4. 调试残留:是否存在修 Bug 时留下的临时校验绕过或过度宽松的 CORS?

输出要求:
- 每条发现必须精确到【文件路径:行号】、一句原理解释、对应的【防御性自动化测试用例思路】和最小修复建议。
- 核查无误的维度直接写“未发现高危问题”,不要硬凑。
第四篇 · 对抗熵增与复工 · 10

每天 5 分钟“垃圾回收”,让项目不腐烂

AI 写代码极快,但也会极快地复制坏模式。别等项目烂尾再重构,用定时任务每天小额还债。

核心工具:Scheduled tasks(定时任务) · 黄金原则 · 文档除草(doc-gardening)

回忆册上线两个月后,阿肯隐隐觉得不对劲:虽然功能都在跑,但新需求改起来越来越容易牵一发而动全身;而且 docs/ 里有好几份规则文档,已经和线上实际行为对不上了。

OpenAI 团队在百万行代码实验里发现了一个反直觉的规律:智能体有极强的模式模仿惯性。只要仓库里出现一处随手写下的“歪代码”,Codex 就会在接下来的几十个功能里疯狂复制它。他们早期每周五都要花整整一天清理“AI 残渣”,最后彻底改成了自动化的垃圾回收机制。

✗ 放任熵增(高息技术债) • 坏模式被 AI 不断复制扩散 • 文档过期,新对话被旧文档误导 • 3 个月后谁都不敢改,只能推倒重来 ✓ 定时垃圾回收(小步微调) • 后台定时巡检:扫重复代码与过期文档 • 自动提交极小的清理 PR(1 分钟可审完) • 仓库常年保持干净,越迭代越顺手
图 10-1 · 技术债像高息贷款:靠 Scheduled tasks 定期小额偿还,永远不会崩盘
🧪 交互演示 · 6 个月代码库熵增演进器 拖动时间轴
第 1 周 第 1 周
放任不管(无垃圾回收) 健康 99%
过期文档:0 份 改坏旧功能风险:低
开启每周定时垃圾回收 健康 96%
过期文档:0 份(每周除草) 改坏旧功能风险:极低
色块含义:绿色 = 清晰可维护模块;黄色 = 轻微重复/文档偏移;红色 = 坏模式扩散的黑盒烂摊子。

每周巡检只需查这 3 件事

  1. 文档除草(Doc-gardening):比对 AGENTS.md 和 docs/ 里的规则,把已经过时的描述标出来或直接发 PR 修正,保证仓库里没有“假真相”。
  2. 清理重复造轮子:检查有没有在不同模块里手写了三套一模一样的日期格式化或权限校验,统一收口到公共工具包。
  3. 清点僵尸代码与临时开关:删掉已经下线的实验分支代码、未使用的组件和调试日志。
📋 操作卡 · 《每周垃圾回收定时任务卡》(配合 Scheduled tasks 使用)
每周执行一次只做小幅清理的“垃圾回收”巡检任务,禁止改动核心业务逻辑:

1. 文档除草:检查 `AGENTS.md`(确保 ≤ 100 行)及 `docs/product-specs/` 中的规则是否与当前真实代码一致,标记或修正过时索引。
2. 坏模式扫描:找出近一周新增代码中重复编写的公共逻辑、过长文件或绕过统一错误处理的片段。
3. 输出一份简短的《健康度周报》,并针对风险最低的 1~2 处清理项,在独立分支发起极小粒度的重构 PR(附带全量回归测试通过证明),方便我 1 分钟内确认合并。
第四篇 · 对抗熵增与复工 · 11

半年后复工,与接管一个 AI 烂摊子

半年没碰的代码库,怎么 10 分钟安全捡起来?如果项目现在已经有点失控,怎么不动大手术把它救活?

核心工具:仓库真相唤醒 · 失控项目四步体检 SOP

场景一:按本书建好的项目,半年后怎么复工?

半年后,阿肯打算给回忆册加上“换封面后重新生成”功能。他没有去翻半年前早就失效的聊天记录,而是直接开了一个全新对话,只发了三句话:

  • “先读 AGENTS.md 和 docs/product-specs/,把项目现状和不能碰的红线总结给我。”
  • “跑一遍现有测试和本地启动命令,确认环境能跑通。”
  • “确认无误后,我们用 /plan 聊新需求。”

因为半年前的幂等规则、防重测试和架构地图全都落盘在仓库里,新对话里的 Codex 3 分钟就完成了“入职培训”,直接提醒阿肯:“换封面重生成必须分配新的请求号,否则会触发半年前写死的 409 冲突保护。”——这就是把记忆存在仓库里的复利。

场景二:如果你现在手里已经有一个“看不懂的失控老项目”?

很多读者看到这里会叹气:“道理我都懂,但我手头这个项目已经靠 Vibe 写了两个月,感觉快失控了,难道要推倒重来吗?” 绝对不要推倒重来。 按下面四步给黑盒做微创手术,一周就能拿回掌控权:

接管步骤具体动作(全交给 Codex 做)验收标准
第 1 步:画地图先不改一行代码,让 Codex 扫描全仓,产出 ARCHITECTURE.md 和 ≤100 行的 AGENTS.md你能看懂核心模块和数据怎么流转
第 2 步:立护网只挑最核心的 3~5 条赚钱路径(登录、下单、扣费),补上端到端防回归测试以后改任何代码,核心业务一崩立刻报警
第 3 步:停出血把《防打扰决策卡》和《四项交付单》写进 AGENTS.md,新需求严格按新规矩走不再往老项目里继续堆新烂账
第 4 步:慢还债只重构“下次要改到的那一块”,配合第 10 章的定时垃圾回收逐步清理业务不停更,代码库越改越清爽
📋 操作卡 · 《失控老项目接管体检指令》(新开会话直接发送)
/plan 我需要重新接管并理清这个已经运行了一段时间的项目。本轮严禁修改任何业务代码。

请按顺序完成四件事,并用业务人员能看懂的语言汇报:
1. 摸底运行:尝试在本地启动项目并运行现有测试,告诉我目前能不能正常跑起来、缺什么环境变量。
2. 画出核心地图:列出本项目最核心的 3~5 条业务链路(例如登录、核心交互、支付/权益),画出一张简明的数据流向图。
3. 找出最危险的 3 处黑盒:指出当前代码中最容易牵一发而动全身、或缺少测试保护的高危模块。
4. 帮我起草一份 ≤ 100 行的 `AGENTS.md`(目录地图)和“优先补齐防回归测试的 3 个任务清单”,我确认后再逐步执行。
第四篇 · 对抗熵增与复工 · 12(终章)

终章:人类掌舵,智能体执行

模型还会继续进化,具体命令可能会变,但这套驾驭 AI 的底层心法,未来三年都不会过时。

全书全景图 · 一页速查清单

回忆册稳定跑了半年,阿肯终于不再每天提心吊胆地盯着屏幕。大部分时候,他早上花 15 分钟用决策卡拍板需求,下午腾出整块时间聊客户、做增长、陪家人;晚上回来花 10 分钟看一眼《四项交付单》和自动测试结果,点下合并。

他终于明白了一件事:当写代码趋近免费时,真正值钱的从来不是“敲出那几千行字符”,而是定义清晰业务规则、设计干净协作环境、以及守住验收底线的能力。

一张图带走全书:Codex 高效协作全景图

① 开局定规矩(防打扰) AGENTS.md ≤ 100 行地图 · /plan 规则表与决策卡 Sol 跑日常,Astra 扛核心 · 赋予可逆假设权 ② 多线推进(管上下文) /goal 后台长跑 · 按独立成果新开对话 + @ 引用 子 Agent 并行查,Worktree 隔离写 · 沉淀 Skill ③ 锁死质量(破除黑盒) 给它装眼睛自测 · 核心规则红/绿 TDD /review 四项交付单 · 独立会话防御性安全审计 ④ 长期演进(抗熵增) Scheduled tasks 定时垃圾回收与文档除草 规则与计划全落盘仓库,半年后 3 分钟无痛复工
图 12-1 · 人类掌舵,智能体执行:从 0 到 1 再到长期维护的完整飞轮
写在最后

别去追逐每一个新出的花哨框架,也别为不看源码而焦虑。守住你的注意力,把业务边界划清,把反馈闭环搭牢——剩下的,放心交给智能体。

📋 终章清单 · 《Vibe Coder 每日开工一页速查》
【开工前】先 /plan 不写代码 → 看业务规则表 + 决策卡 → 落盘到 docs/exec-plans/
【干活中】切 /goal 写清 DoD 与禁区 → 日常用 Sol,硬骨头切 Astra → 放手去忙生意
【切对话】做完独立成果立刻新开 → 用 @ 引用或贴 10 行交接单(写明不能删的红线)
【开并行】查日志/分析派只读子 Agent → 两条独立业务线必须开 Git Worktree
【做验收】让它自己跑页面截屏 + /review → 只信《四项交付单》(重点看“仍然未知”)
【上线前】关键扣费/防重走红/绿 TDD → 新开干净会话跑一次防御性安全审计
【防腐烂】配一个每周定时垃圾回收任务 → 保持 AGENTS.md ≤ 100 行,仓库即唯一真相
工具库

全书操作卡速查库

把这一页加入浏览器书签——写代码时不用翻书,直接在这里一键复制给 Codex。

已完整收录全书 12 章的全部实战 Prompt、宪章与审计模板,点击任意卡片即可一键复制
📋 操作卡 · 《100 行项目开局宪章》(存为仓库根目录 AGENTS.md)
# 项目地图(保持 ≤ 100 行,详细文档按需读取)

## 1. 唯一真相来源
- 产品业务规则:`docs/product-specs/`
- 系统模块与边界:`ARCHITECTURE.md`
- 当前活跃执行计划:`docs/exec-plans/active/`
- 本地运行与测试:`npm run dev` / `npm test`

## 2. 自主权与防打扰原则
- **自行推进**:所有可逆的技术实现细节(命名、目录、常规组件),请你做出最简假设后直接推进,交付时简述假设即可,不要中途停下来问我。
- **必须停下来问我**:涉及付费/扣费规则、权限边界、删除旧接口、不可逆数据库迁移时,必须先停下。
- **提问格式**:必须附带【需要你决定 / 我的建议 / 业务影响】,禁止抛出开放式技术长文。

## 3. 交付硬标准
- 任何核心改动必须附带可运行的验证证据,并明确列出“已验证”与“未验证”项。
📋 操作卡 · 《/plan 防打扰需求对齐指令》
/plan 我要实现以下功能:[用大白话描述你的想法]

先不要写代码,请按下面两个要求回复我,禁止长篇技术科普:
1. 输出一张《业务规则表》,列出:正常流程、失败情况、重复操作、边界情况下的用户可观察结果。
2. 如有必须由我拍板的业务歧义,最多列 3 个,严格按以下格式提问:
   - 【需要你决定】:一句话说明问题
   - 【我的建议】:你推荐的最简方案
   - 【业务影响】:选这个方案对用户或后续维护有什么影响

其余可逆的技术细节,你自行决定即可。
📋 操作卡 · 《/goal 长任务派发卡》
/goal 依据 `docs/exec-plans/active/vip-export.md` 完成会员导出回忆册功能。

完成条件(DoD):
1. 规则表中的 4 种场景全部实现,并补齐自动化测试且全部通过。
2. 现有照片上传与登录回归测试通过。
3. 禁止修改用户鉴权中间件与历史订单表结构。

自主边界:
- 常规实现与本地报错请自行排查修复,不要中途打断我。
- 全部完成后,输出《四项交付单》(改了什么 / 怎么验证 / 影响范围 / 哪些仍未验证)。
📋 操作卡 · 《跨对话极简交接单指令》(关旧对话前发这一句)
本轮任务已结束,我准备新开一个干净对话推进下一阶段。
请输出一份不超过 10 行的《交接单》,方便我直接贴给新对话:
1. 当前已完成的成果与所在分支/提交号;
2. 关键业务决定与“绝对不能删除/修改的红线”(写明原因);
3. 已验证通过的命令与结果;
4. 留待下一阶段处理的唯一明确目标。
📋 操作卡 · 《三路并行排查子 Agent 指令》
现在出现“照片上传偶尔超时”的故障。为了不污染当前主对话上下文,请派生 3 个只读子 Agent 并行排查:
- 子 Agent 1:只检查前端压缩与超时重试配置;
- 子 Agent 2:只检查后端上传接口与鉴权耗时;
- 子 Agent 3:只检查对象存储签名与近 24 小时错误日志。

要求:
1. 三个子 Agent 均严禁修改任何代码,各自只返回不超过 10 行的证据摘要;
2. 由你(主 Agent)汇总三方证据,给我一份根因判断与最小修复方案,我拍板后再动手。
📋 操作卡 · 《一键把本次成功流程封装成 Skill》
刚才我们“新建支付/权益接口 → 补边界测试 → 输出四项交付单”这套流程跑得非常顺。
请你把它封装成一个项目级 Skill,存到仓库的 Skills 目录里,命名要直白(例如 `new-billing-endpoint`)。

要求:
1. 写清楚触发条件(什么时候该自动调用它);
2. 把刚才验证成功的 4 个步骤写成精简清单,不写废话;
3. 如果其中有可以做成 100% 确定性检查的规则(例如禁止把数据库对象直接返回给前端),顺手帮我加一条自定义检查脚本,并在报错信息里写明修复方式。
📋 操作卡 · 《四项交付单 + 线性走查验收指令》
在宣布本次任务完成前,请先自行完成以下三步验收,再向我汇报:
1. 启动本地应用,模拟真实用户走完核心路径(正常 + 异常分支),检查控制台与服务端是否有隐藏报错。
2. 对本次未提交变更运行一次 `/review`,检查是否存在职责混乱或波及无关模块。
3. 按以下格式给我一份极简《四项交付单》(不贴大段源码):
   - 【改变了什么】:用业务语言 3 句话讲清;
   - 【线性走查】:数据从点击按钮到落库是怎么流转的;
   - 【怎么验证的】:实际执行的命令、页面核对结果;
   - 【仍然未知】:诚实列出本次未覆盖的场景与剩余风险。
📋 操作卡 · 《TDD 故障修复全闭环指令》
/goal 修复“回忆册重复创建任务”故障。

规则:
- 同用户、同请求号、同参数,无论顺序重发还是并发到达,只创建 1 项任务;
- 主动换新号允许新建;同号异参明确报冲突。

执行方式(红/绿 TDD):
1. 先写出能复现“并发重复创建”的自动化测试,运行并确认旧代码失败。
2. 用数据库唯一约束 + 事务做最小修复,重跑测试确认全绿。
3. 跑一次 /review,输出《四项交付单》(改了啥 / 怎么验 / 影响啥 / 哪些仍未验证)。
4. 将业务规则与测试命令写入 `docs/product-specs/idempotency.md`,并在 `AGENTS.md` 补充索引。
📋 操作卡 · 《防御性安全审计卡》(请在新开干净会话中使用)
你现在担任本项目的独立安全架构审查员(仅做防御性代码审计,本轮不改代码)。
请重点审查以下核心目录:[填入路由/鉴权/支付目录],只排查四个高危维度,禁止输出“建议开 HTTPS”这类通用废话:

1. 访问控制与越权:所有增删改查接口是否都从服务端受信任 Session/JWT 解析身份,并校验资源归属?是否存在批量赋值篡改 VIP/余额的风险?
2. 支付与并发一致性:扣费、额度消耗、支付回调是否使用数据库事务/原子条件更新,并具备签名校验与幂等防重?
3. 敏感数据保护:API 是否过度透传了数据库对象?是否存在硬编码密钥或危险兜底配置?
4. 调试残留:是否存在修 Bug 时留下的临时校验绕过或过度宽松的 CORS?

输出要求:
- 每条发现必须精确到【文件路径:行号】、一句原理解释、对应的【防御性自动化测试用例思路】和最小修复建议。
- 核查无误的维度直接写“未发现高危问题”,不要硬凑。
📋 操作卡 · 《每周垃圾回收定时任务卡》(配合 Scheduled tasks 使用)
每周执行一次只做小幅清理的“垃圾回收”巡检任务,禁止改动核心业务逻辑:

1. 文档除草:检查 `AGENTS.md`(确保 ≤ 100 行)及 `docs/product-specs/` 中的规则是否与当前真实代码一致,标记或修正过时索引。
2. 坏模式扫描:找出近一周新增代码中重复编写的公共逻辑、过长文件或绕过统一错误处理的片段。
3. 输出一份简短的《健康度周报》,并针对风险最低的 1~2 处清理项,在独立分支发起极小粒度的重构 PR(附带全量回归测试通过证明),方便我 1 分钟内确认合并。
📋 操作卡 · 《失控老项目接管体检指令》(新开会话直接发送)
/plan 我需要重新接管并理清这个已经运行了一段时间的项目。本轮严禁修改任何业务代码。

请按顺序完成四件事,并用业务人员能看懂的语言汇报:
1. 摸底运行:尝试在本地启动项目并运行现有测试,告诉我目前能不能正常跑起来、缺什么环境变量。
2. 画出核心地图:列出本项目最核心的 3~5 条业务链路(例如登录、核心交互、支付/权益),画出一张简明的数据流向图。
3. 找出最危险的 3 处黑盒:指出当前代码中最容易牵一发而动全身、或缺少测试保护的高危模块。
4. 帮我起草一份 ≤ 100 行的 `AGENTS.md`(目录地图)和“优先补齐防回归测试的 3 个任务清单”,我确认后再逐步执行。
📋 终章清单 · 《Vibe Coder 每日开工一页速查》
【开工前】先 /plan 不写代码 → 看业务规则表 + 决策卡 → 落盘到 docs/exec-plans/
【干活中】切 /goal 写清 DoD 与禁区 → 日常用 Sol,硬骨头切 Astra → 放手去忙生意
【切对话】做完独立成果立刻新开 → 用 @ 引用或贴 10 行交接单(写明不能删的红线)
【开并行】查日志/分析派只读子 Agent → 两条独立业务线必须开 Git Worktree
【做验收】让它自己跑页面截屏 + /review → 只信《四项交付单》(重点看“仍然未知”)
【上线前】关键扣费/防重走红/绿 TDD → 新开干净会话跑一次防御性安全审计
【防腐烂】配一个每周定时垃圾回收任务 → 保持 AGENTS.md ≤ 100 行,仓库即唯一真相