| name | debug-architect |
| description | Codex 错误复盘与预防技能。用于“复盘错误、分析报错、总结踩坑、回顾失败、建立预防规则”等请求;从当前任务、可访问历史、Git 和项目日志提取证据,分析根因并写入项目 .codex/ERROR_LOG.md。显式调用:$debug-architect。 |
调试建筑师(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. 收集证据
优先级:
- 当前任务中的报错、命令输出、堆栈、截图转录和修复结果;
- 用户指定日志、测试报告、CI 输出和项目
.codex/ERROR_LOG.md;
- Git diff、相关提交、变更时间线;
- 项目 docs、issues、已有复盘;
- 可访问的 Codex 历史数据。
对 Codex 历史只做能力探测:解析 CODEX_HOME,检查用户授权范围内是否存在可读的 session/history 数据;先抽样识别实际格式,不假定固定路径、文件名或 JSONL schema。不存在或不可读时,明确说明并使用前四类来源。
不要把源码中的普通 error 字样、测试用例中的预期异常或文档示例直接算作真实事故。
每个错误记录:时间/范围、原始症状、关键证据、影响、修复动作、验证结果、是否复现、来源路径或命令。
3. 分类与去重
分类:语法/类型、配置/依赖、逻辑/状态、环境/权限、第三方、流程/验证、其他。
合并同一错误的重复输出;区分:
- 一个根因的多种症状;
- 修复 A 后暴露出的独立错误 B;
- 临时环境失败与稳定代码缺陷;
- 已修复、未修复、无法确认。
4. 三层根因分析
对每个错误回答:
- 直接原因:哪个条件或操作触发失败?
- 系统原因:哪个假设、接口、流程或边界设计有问题?
- 预防缺口:哪项检查、测试、规则或可观测性本可更早发现?
证据不足时写“推测”,并给出最小验证方法;不要把相关性写成因果性。
5. 关联分析
检查:
- 时间上的因果链;
- 多错误是否同根;
.codex/ERROR_LOG.md 中是否重复发生;
- 相关
AGENTS.md、配置或技能是否缺少边界/验证规则。
仅在证据明确时建立关联。没有关联则省略。
6. 置信度与价值分级
| 等级 | 条件 | 处理 |
|---|
| 确定·高价值 | 根因有证据且可复用 | 写 ERROR_LOG;推荐规则/配置/技能改进 |
| 确定·低价值 | 根因明确但一次性或局部 | 写 ERROR_LOG,不上升为规则 |
| 推测·高价值 | 可能复发但证据不足 | 写待验证记录和验证步骤,不写规则 |
| 存疑/一次性 | 证据弱且复用价值低 | 仅在本次摘要列出 |
同一存疑模式在日志中重复出现时,可升级为“推测·高价值”,仍需验证后才能成为确定规则。
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 条
### 待确认
| # | 操作 | 目标文件 | 内容 |
### 验证
- <命令>:通过/失败
没有错误时,报告扫描范围与“未发现真实错误”。历史不可访问不是失败,但必须披露限制。