先说结论
我之前扫过本机 Claude / Codex 会话,结论很硬:大约六成失败发生在写业务代码之前,是环境前置没就绪。 那篇统计已经发过。
近两天我做的下一步更土:把那些高频失败,写成一份双端共用的硬约束——Codex 读 AGENTS.md,Claude Code 读 ~/.claude/CLAUDE.md,两边内容同步。今天几乎每个 Codex 会话开头都会先吃到这份说明。这篇写「怎么写才真的会挡住失败」,不写具体项目路径。
为什么「再叮嘱一遍」没用
Agent 不缺礼貌提醒。缺的是:
- 可复现的失败条目,对应真实日志里反复出现的那一类。
- 命令级约束,而不是「请注意环境」。
- 双端同步。你只改 Claude 侧,Codex 照样踩同一坑;只改 Codex,Claude Code 的 shell 还是老毛病。
我在硬约束文件头写明了数据来源口径:Claude 约 587 个会话、Codex 约 2,281 个会话上的失败归因。目的不是吓人,是告诉后来的我(和后来的 Agent):这些不是风格偏好,是统计过的高频故障。
硬约束里真正管用的几类
下面只写类型,不贴本机绝对路径。
1. 先承认:Agent 的 shell 不是你日常终端
登录 shell 里配好的 PATH、版本管理器、代理变量,Agent 开出来的非登录 shell 常常没有。表现很统一:
command not found- 找到了错误的运行时版本
- 以为走了代理,其实直连失败
对策不是「请你用登录 shell」,而是:写明要用哪个绝对命令、如何加载版本管理器、代理变量叫什么。 Agent 按条目执行,比它自己猜 ~/.zshrc 靠谱。
2. 工作目录与 worktree
多 Agent、多 worktree 时,最常见的事故是:在 A 树里改文件,在 B 树里跑测试;或者 cwd 还在家目录就开始 git status。硬约束里要写:
- 开工前打印
pwd和当前 git 根 - 禁止跨 worktree 混跑测试
- 需要隔离时,明确用哪棵树
3. 密钥与网络
这条既是工程也是安全:
- 不把密钥写进对话
- 需要鉴权的命令,优先走本机已有的凭证机制,而不是让模型「发明」一个 token
- 外网失败时,先区分 DNS / 代理 / 鉴权,不要一上来重试十次换模型
4. 失败要归因到环境还是代码
硬约束里我加了一条操作习惯:工具连续失败两次,先做环境自检清单,再怀疑业务逻辑。 这直接对应那 60% 的数字。否则 Agent 会在错误假设上改代码,越改越远。
怎么维护,才不会变成废纸
- 一条约束对应一类可复现失败。 没有日志支撑的「最佳实践」不进硬约束文件。
- Claude 与 Codex 两边同步改。 文件头写明同源,改一处就必须改另一处。
- 控制长度。 太长会被会话开头的说明淹没真正任务。我的做法是:硬约束只留高频项;项目特有的规则放进项目内说明,不塞进全局。
- 用真实会话验收。 改完后看新会话是不是还在同一类
command not found上栽倒。还栽,说明条目不够可执行。
有没有用
有用,而且体感很直接:
- 新会话少问「你本地有没有某某命令」
- 少把环境问题误判成模型变笨
- 多 Agent 并行时,大家遵守同一套机器事实
没用的幻觉也要拆穿:硬约束不会提高模型智商,只会减少「还没写代码就失败」的比例。业务 bug、产品判断、审查标准,还是得另写。
相关阅读:《我统计了 2,281 个 Codex 会话,发现失败大多发生在写代码之前》、《Harness 才是真模型:我的 Claude Code / Codex 交接包模板》。
口径:会话量与约 60% 环境失败比例,来自 2026-09-10 对本机 Claude / Codex / WorkBuddy 日志的扫描,并已写进当前双端硬约束文件头;近两天观察来自 2026-11-04 至 11-05 的 Codex 会话开头都会注入该文件。不公开本机绝对路径与具体命令清单全文。
COMMENTS
读者评论