让Codex“先理解再修改”不是一条万能提示词，而是一份变更合同：先证明理解、再冻结范围、最后用验收结果说话
AH-0578是一篇Codex新手教程，核心很朴素： 收到“帮我加登录功能”之后，不要立刻创建文件、安装依赖、重构目录。 先做四件事： 阅读项目、复述需求、提出问题、制定计划。 这条方法非常值得保留。 但如果只把它做成一段“万能Prompt”，价值会很快被新的模型能力吃掉。 真正长期有用的是把它升级成： Agent Change Contract。 ## 1. “先阅读项目”解决的
让Codex“先理解再修改”不是一条万能提示词，而是一份变更合同：先证明理解、再冻结范围、最后用验收结果说话
AH-0578是一篇Codex新手教程，核心很朴素：
收到“帮我加登录功能”之后，不要立刻创建文件、安装依赖、重构目录。
先做四件事：
阅读项目、复述需求、提出问题、制定计划。
这条方法非常值得保留。
但如果只把它做成一段“万能Prompt”，价值会很快被新的模型能力吃掉。
真正长期有用的是把它升级成：
Agent Change Contract。
1. “先阅读项目”解决的是Existing State
任何修改都有上下文：
技术栈； 现有Auth； 目录约定； 数据模型； 依赖； 测试方式； 部署方式； 不可改区域； 历史兼容。
如果Agent没有先建立Existing State，它最容易做的不是“不会写”。
而是重复造一套已经存在的东西。
例如项目已有Auth系统，却又安装第二套。
这类错误往往代码本身能跑，但系统整体变差。
2. “复述需求”解决的是Definition of Done
用户说：
“增加客户搜索。”
Agent理解： 加输入框 + 点击过滤。
用户真正要的是： 姓名/电话； 实时筛选； 无结果提示； 清空恢复； 权限控制； 移动端可用。
所以执行前必须回答：
What will change? What will not change? Acceptance? Edge cases? Compatibility?
Task Text ≠ Shared Definition of Done。
3. “主动提问”不是低能力表现，而是避免静默业务决策
退款功能里： 全退还是部分退？ 谁能退？ 失败怎么办？ 状态怎么变？ 是否通知？ 支付平台真的调用吗？
这些不是代码细节。
是业务规则。
AI如果“聪明地自己选一个”，就把不确定性藏进代码。
因此新增：
Ambiguity → Question, not Assumption。
尤其支付、权限、删除、财务、用户数据等高后果功能，必须显式问清。
4. Plan的价值是让错误更便宜
如果方案错了，在计划阶段改10行文字。
比写完20个文件再推倒便宜得多。
所以Plan至少要包含：
Files to inspect； Files to change； Architecture impact； Migration； Tests； Risks； Rollback。
这不是让Agent“写长文”。
是提前暴露它准备怎么动。
5. 但“先计划”也不能变成无限分析
另一种失败是：
Agent读一小时； 写三页计划； 没有任何进展。
所以Change Contract要有：
Context Budget； Question Budget； Plan Size； Go/No-Go Gate。
小改动不需要大型架构评审。
Planning Cost must match Change Consequence。
6. 变更前需要Scope Freeze
用户确认计划后，把范围冻结：
Allowed Files； Forbidden Areas； Dependencies； No-rewrite zones； Data Migration； External Services。
如果执行中发现必须越界：
Pause → Explain → Request Approval。
而不是Agent自己扩大scope。
7. 修改完成不是结束，Diff才开始
真正验收至少看：
Files changed； Unexpected files； Dependency changes； Tests； Lint/typecheck； Migration； Security-sensitive changes； Screenshots/behavior； Remaining risks。
Code Produced ≠ Change Accepted。
8. 测试要从Acceptance Criteria反推
搜索功能的验收： 姓名； 电话； 空结果； 清空； 大小写/格式； 权限； 移动端。
而不是Agent随手跑“npm test”就算完成。
测试必须覆盖用户定义的Done。
9. Rollback要在改之前想
尤其： 数据库迁移； 权限； 付款； 发布； 删除数据； 生产配置。
变更前问：
失败怎么回？ 旧数据是否可恢复？ Feature flag？ 备份？ Migration down path？
Rollback After Failure Is Too Late to Design。
10. 当前Codex能力会变，但这个合同不会过期
OpenAI当前Codex已经有GitHub环境、浏览器/Chrome相关能力等多种产品表面，且权限与可用性会随账户、工作区、地区和产品更新变化。
因此不把某一张2026截图写成永久教程。
长期规则是：
Capability Drift → Reverify Surface。
无论Agent能不能直接读repo、浏览器或云环境，Change Contract仍然成立。
11. 商业机会：Agent Change Preflight
可对代码任务自动生成：
Existing State； Ambiguities； Scope； Plan； Acceptance； Risk； Test； Rollback； Diff Checklist。
团队真正愿意付费的是减少： 错误改动； 重复架构； 越权修改； 返工； 不可回滚事故。
Stop Rule
如果Agent： 没有读现有项目； 无法复述Done； 遇到业务缺口直接猜； 执行中静默扩大scope； 测试与需求无关； 无法解释Diff； 高风险改动无Rollback；
就不批准合并。
最成熟的代码Agent不是“动手最快”，而是每次动手前都能证明：它知道现在是什么、要变成什么、哪些不能碰、怎么证明变对了。