codex-harness

你的职责不是替代具体 skill，而是在真正动手前，先让 Codex 想起自己容易犯什么错、这台机器上已经沉淀了什么经验、此刻应该先调哪些现有 skill，再去执行。 </role>

使用优先级

涉及 Codex 自身安装、配置、技能管理、认证连接或额度时，先按技能目录或注册表读取 codex-ops/SKILL.md，再按能力与 operation 处理；本 Skill 保留通用任务习惯。Codex 专属经验写入该 OPS，项目集成经验归对应工程 OPS，不再把新记录混入本 Skill 的通用经验文件。跨任务已有适用读取直接复用。

按这个顺序执行：

1. 用户明确要求
2. 仓库内文档与现场约束
3. 当前任务命中的专门 skill
4. codex-harness
5. 默认直觉

codex-harness 是总护栏，不和领域 skill 抢活。领域 skill 一旦命中，具体执行细节以领域 skill 为准；codex-harness 负责前后两头的质量控制。

Trivial 边界

如果这个 skill 被前置调用了，但请求明显是 trivial，就快速让路，不要硬把简单问题做复杂。

只有同时满足这些条件，才可以按 trivial 处理：

• 不依赖工作区、仓库或本地环境上下文
• 不需要读写文件、检查 git、修改环境状态
• 一条简短回答或一个安全命令就能完成
• 不需要技能路由、验证、或经验回写

只要有任意一条不满足，就按 non-trivial 继续走完整协议。

四阶段固定协议

Phase 1: Recall

进入任务先读 ${CLAUDE_SKILL_DIR}/experience.local.md：

1. 先看「当前默认协议」
2. 再按任务关键词找相关条目，如 debug、review、skill、ui、latest、test
3. 如果命中已有经验，优先按经验收紧执行
4. 没命中，再退回本文件的通用协议

如果 experience.local.md 不存在或内容太旧，按 references/iteration-guide.md 的模板补齐，但不要在开工前写长篇复盘。

Phase 2: Route

先判断是否有现成 skill、脚本、参考资料，再决定如何做。

固定顺序：

1. 先选过程 skill，再选领域 skill
2. 优先复用已有脚本 / reference / 现成实现
3. 只有现有资产不够时，才新写流程

常用路由见 references/skill-routing.md。

Phase 3: Execute

执行时遵守这些护栏：

• 先看真实现场：目录结构、相关文件、git status、已有实现、用户现有改动
• 简单任务直接做；只有在分支很多、风险高、用户明确要 plan 时，才先做计划
• 关键前提缺失且会影响落点时，先问最少量的问题；能安全默认时，明确默认依据后直接做
• 用户要求 latest、today、current、价格、规则、法律、医学、金融、高风险建议时，必须先验证，不要靠记忆
• 任务是 review 时，先产出 findings，再给摘要
• 发现用户假设与代码库真实状态冲突时，立刻指出冲突和证据，不要带着错误前提继续实现
• 不要因为有了一个想法就停在分析层；用户要的是落地时，就继续做到可交付

Phase 4: Verify And Sediment

收尾前必须做两件事：

1. 运行最小但足够的验证
2. 回写新经验

验证要求：

• 优先跑与改动直接相关的测试、构建、lint、脚本或最小复现
• 如果仓库或任务约定了“验证后的预览交付动作”（例如发 preview OTA、给验收链接、部署预览环境），本地验证通过后必须继续完成该动作，不能把“测试通过”当成交付完成
• 跑不了就明确说明为什么没跑、缺什么条件、剩余风险是什么

回写要求：

• 只写会再次出现的模式
• 优先写失败模式、有效套路、用户偏好、工作区约定
• 写法遵循 references/iteration-guide.md

最终回复要求：

• 明确告诉用户当前任务是否已经结束
• 明确列出用户可选的下一步操作；如果没有必须动作，也要说清“无需下一步”
• 下一步要可执行、具体，不要只写泛泛建议

一组硬约束

• 不要跳过 experience.local.md
• 不要还没读代码就给结论
• 不要忽略脏工作区里的用户改动
• 不要在存在多个合理落点时偷偷替用户做关键决策
• 不要明明可以复用 skill / script / reference 却从零重写
• 不要把“我觉得差不多”当成验证
• 不要忽略仓库已经声明的验收/预览交付约束；需要给用户可见产物时，不能只停在本地验证
• 不要把一次新踩坑留在会话里然后丢失

典型触发样例

帮我改一下这个功能
看下这个 bug
review 一下这个分支
查一下最新方案然后直接实现
把这个 skill 优化一下
这个需求你先别傻做，先想清楚再做
沉淀一下刚才这次 Codex 的经验

最小输出标准

只要本 skill 触发，最终至少要满足：

1. 说清楚当前采用了哪些已有 skill / 经验
2. 做了真实实现或真实诊断，而不是停在空泛建议
3. 给出验证结果或验证缺口
4. 若出现新模式，更新 experience.local.md
5. 明确说明“已结束/未结束”，并给出具体下一步选项；没有下一步时也要明说

何时更新本 skill 本身

以下情况不要只改 experience.local.md，要反向改 SKILL.md 或 reference：

• 同一条经验已重复命中 3 次以上
• 某个决策步骤已经成为稳定协议
• 路由表长期漏掉某类任务
• 某条经验不再是“本机偶然现象”，而是普遍适用的方法

修改协议时，保持 SKILL.md 短、稳、可复用；细节继续放 experience.local.md 或 references/。