Codex 自定义指令：让调试可追溯
一组围绕快速失败、根因修复、可观测性与文档同步的 Codex 工作准则。
原始内容
最近长时间用 codex，逐渐形成了这些自定义指令，挺好用的： 1. Fail Fast / Errors Never Pass Silently：不要在代码里藏兜底逻辑来吞掉错误、隐藏问题。出了问题就应该让它爆出来，否则你永远找不到真实问题。 2. Fix the Cause, Not the Symptom / Don't Paper Over Bugs：当一个问题出现时，不要用各种 small fix、针对性补丁来掩盖它。必须定位真实根因，彻底修复。在 bug 上糊纸只会让系统积累你不知道的危险暗病。 3. Make It Observable：即使问题很难定位，也绝不要偷懒做表面修复。应该给项目增加充分的日志和可观测性，保证下次问题再现时你有足够信息去定位。问题无法修复时，只需要诚实告诉我信息不足、需新增日志，不要假装修好了。 4. Design for Debugging / Traceability：始终注意在关键路径上给自己留足排查日志，确保每一个关键节点都是可追溯的。 5. Living Documentation / Single Source of Truth：当项目关键技术栈或产品方向发生变更时，同步更新 agents.md。文档必须随代码一起演进，不能让它变成过时的谎言。 6. Don't Break Mainline：大规模重构或实验性改动前，必须先切新分支。
深度解析
是什么 这是一套长期使用 Codex 后沉淀出的 Agent 工程工作准则，不是具体代码技巧，而是约束问题处理方式：让错误尽早暴露，围绕根因修复，并把诊断信息、文档和变更边界纳入日常开发。
核心设计 六条规则形成一条闭环链路：Fail Fast 阻止兜底逻辑吞错；Fix the Cause 要求从症状回溯根因；Make It Observable 与 Traceability 通过日志和关键节点记录补齐证据；Living Documentation 把 agents.md 作为随代码演进的单一事实源；Don't Break Mainline 则用分支隔离高风险重构和实验。它把“修好”定义为可验证、可复现、可维护，而不是暂时不报错。
关键洞察 对 Agent 协作尤其重要：模型容易倾向于最小补丁、添加 fallback 或声称任务完成，这套指令把诚实暴露不确定性、保留排查路径和控制变更半径设为默认行为，能减少隐性技术债，并提升后续会话的上下文连续性。
边界与风险 规则并非绝对禁用容错、日志或分支；生产系统仍需按业务风险设计错误恢复、日志脱敏和发布流程。过度 Fail Fast 可能损害用户体验，过度记录会增加噪声与成本，agents.md 也必须防止沦为没人维护的形式文档。最佳实践是区分用户侧降级与开发侧吞错，并为关键日志、文档和分支策略设定验证标准。
精选追评与案例
指出这些指令更适合放进 AGENTS.md，并区分个性化与项目规则，属于重要使用边界纠正。
@s1dashu 说实话，这些指令对于现在的模型来说多余了。而且放在个性化里面更不合适。个性化是设定风格的地方。这个比较适合放在 Home 里面的AGENTS.MD
点出要求模型诚实仍可能被硬凑答案，提示第 3 条需要更可验证的约束。
@s1dashu 🙋提问一句 3 这条有测出来非常有效的 prompt 嘛？发现明确要求诚实的情况下，模型有时候还是会硬凑一个答案企图蒙混过关🤦
分享了可参考的 system prompt 及搭配 ponytail 的使用线索，便于读者复用。
@s1dashu 這是我的 system prompt 給你參考，通常我會搭配 ponytail 一起使用 https://t.co/pnby7EoZ7q
中文译文 · 机器翻译
@s1dashu 这是我的 system prompt，供你参考；通常我会搭配 ponytail 一起使用 https://t.co/pnby7EoZ7q
补充了更合适的落点 agents.md，与上一条纠错相互印证。
@s1dashu 挺好的，但感觉还是放在agents.md中更合适。