调试建筑师（Codex）

把已经发生的错误转化为可复用的诊断、修复证据和预防措施。它不是实时修 bug 的替代品；根因未定位时先调试，再复盘。

边界

• 错误日志固定为项目 <项目根>/.codex/ERROR_LOG.md。
• 项目预防规则写项目或最近子目录的 AGENTS.md；跨项目规则才考虑 ~/.codex/AGENTS.md。
• Codex 配置问题写入 ~/.codex/config.toml 或项目 .codex/config.toml 前，必须验证配置项并获得相应授权。
• 技能漏洞针对 ~/.agents/skills 或项目 .agents/skills；建议修改时使用 $skill-name 表述。
• 不自动修改规则或技能。ERROR_LOG 的已验证归档可在用户要求复盘时写入；规则、配置、技能变更先展示并确认。

错误分类参考 references/error-patterns.md；审计技能规则时读取 references/skill-audit-guide.md。

工作流

1. 确定项目与时间范围

• 识别项目根、适用 AGENTS.md 和 Git 仓库。
• 用户给出日志/报错/提交范围时优先使用。
• 被 $weaver-自我迭代 调用时，只处理其提供的增量证据，不扩大扫描范围。

2. 收集证据

优先级：

1. 当前任务中的报错、命令输出、堆栈、截图转录和修复结果；
2. 用户指定日志、测试报告、CI 输出和项目 .codex/ERROR_LOG.md；
3. Git diff、相关提交、变更时间线；
4. 项目 docs、issues、已有复盘；
5. 可访问的 Codex 历史数据。

对 Codex 历史只做能力探测：解析 CODEX_HOME，检查用户授权范围内是否存在可读的 session/history 数据；先抽样识别实际格式，不假定固定路径、文件名或 JSONL schema。不存在或不可读时，明确说明并使用前四类来源。

不要把源码中的普通 error 字样、测试用例中的预期异常或文档示例直接算作真实事故。

每个错误记录：时间/范围、原始症状、关键证据、影响、修复动作、验证结果、是否复现、来源路径或命令。

3. 分类与去重

分类：语法/类型、配置/依赖、逻辑/状态、环境/权限、第三方、流程/验证、其他。

合并同一错误的重复输出；区分：

• 一个根因的多种症状；
• 修复 A 后暴露出的独立错误 B；
• 临时环境失败与稳定代码缺陷；
• 已修复、未修复、无法确认。

4. 三层根因分析

对每个错误回答：

1. 直接原因：哪个条件或操作触发失败？
2. 系统原因：哪个假设、接口、流程或边界设计有问题？
3. 预防缺口：哪项检查、测试、规则或可观测性本可更早发现？

证据不足时写“推测”，并给出最小验证方法；不要把相关性写成因果性。

5. 关联分析

检查：

• 时间上的因果链；
• 多错误是否同根；
• .codex/ERROR_LOG.md 中是否重复发生；
• 相关 AGENTS.md、配置或技能是否缺少边界/验证规则。

仅在证据明确时建立关联。没有关联则省略。

6. 置信度与价值分级

同一存疑模式在日志中重复出现时，可升级为“推测·高价值”，仍需验证后才能成为确定规则。

7. 写入 .codex/ERROR_LOG.md

若文件不存在且本次有应归档项，可创建父目录 .codex/ 与文件。保持条目简洁、可搜索：

## YYYY-MM-DD — 错误简述

- 等级：确定·高价值
- 状态：已修复 / 未修复 / 待验证
- 类型：环境/权限
- 症状：<关键报错，不粘贴大段日志>
- 影响：<范围>
- 直接原因：<原因>
- 系统原因：<原因>
- 修复：<动作>
- 验证：<实际命令与结果>
- 预防：<可操作措施>
- 证据：<相对路径、提交或命令>
- 关联：<已有条目，可选>

规则：

• 先搜索已有条目；同根错误更新原条目的频率、证据和状态，不重复新增。
• 不记录密钥、完整环境变量、私人数据或无关日志。
• 未验证的修复不能标“已修复”。
• 使用绝对路径向用户报告，用相对路径写项目内证据以便迁移。

8. 形成预防建议

仅对“确定·高价值”提出规则写入建议：

• 当前项目通用 → 项目根 AGENTS.md；
• 仅模块适用 → 最近子目录 AGENTS.md；
• 跨项目且副作用低 → ~/.codex/AGENTS.md；
• Codex 行为设置 → 对应作用域 config.toml，先核验配置项；
• 技能流程缺口 → 对应 skill 的 SKILL.md，按 references/skill-audit-guide.md 给出位置和改法。

预防规则必须具体、可执行、带触发条件，例如“在递归删除前解析绝对路径并验证位于工作区内”，而不是“以后小心”。

9. 确认与执行改进

把所有待操作项合并到一个表中：

用户确认后再修改规则、配置或技能。修改后读回、运行相关检查，并核对 Git diff 未越界。

10. 输出摘要

## 错误复盘完成 — <项目>（YYYY-MM-DD）

### 数据源与限制
- 已读取：当前报错、测试日志、Git diff
- 未读取：Codex 历史（未发现可访问数据）

### 分级汇总
| 等级 | 数量 | 处理 |

### 根因与关联
- <结论>

### 文件变更
- 更新：<绝对路径> — 新增/更新 N 条

### 待确认
| # | 操作 | 目标文件 | 内容 |

### 验证
- <命令>：通过/失败

没有错误时，报告扫描范围与“未发现真实错误”。历史不可访问不是失败，但必须披露限制。