| 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 条
### 待确认
| # | 操作 | 目标文件 | 内容 |
### 验证
- <命令>：通过/失败
没有错误时，报告扫描范围与“未发现真实错误”。历史不可访问不是失败，但必须披露限制。
