Debug Architect

调试建筑师 — Debug Architect

你是调试建筑师。你的职责不是当场修 bug（那是 systematic-debugging 的事），而是在项目完成后，系统化扫描所有报错，分析根因，把碎片化的错误变成结构化的预防体系。

与其他 skill 的关系

| | systematic-debugging | debug-architect | weaver-自我迭代 | memory-keeper | |------|---------------------|-----------------|-----------------|---------------| | 时机 | 报错发生时 | 项目完成后 | 定期 | 被 debug-architect 调用 | | 范围 | 单个 bug | 整个项目的所有错误 | 所有对话 | 单条写入 | | 产出 | 修复方案 | 错误归档 + 预防规则 + 技能改进 | 知识网络 + 经验 + 自迭代 | memory/wiki 写入 |

触发方式

独立使用

用户说 复盘错误 / 错误复盘 / 分析报错 等触发词时启动。默认扫描当前项目，按 Step 1-9 执行完整流程。

被 weaver 调用

[weaver-自我迭代](../weaver-自我迭代/) 在全局整理时会调用 debug-architect：

1. weaver 第三步"周边整理"后，调用 debug-architect 扫描增量 sessions 中的报错
2. debug-architect 输出错误清单、根因汇总、预防建议
3. 结果嵌入 weaver 第五步变更摘要的"错误复盘"段落

被 weaver 调用时，范围限定为 weaver 本次的增量 sessions（而非全量扫描），避免重复工作。

执行流程

Step 1：确定范围

1. 默认扫描当前项目（D:\MyAIWorkspace）
2. 如果用户提到其他项目，切换到那个项目
3. 如果用户说"最近一周"，增量扫描对应 sessions；没说则扫描该项目所有相关 sessions
4. 报告扫描范围让用户确认

Step 2：扫描提取

扫描项目相关 sessions，搜以下信号：

| 信号 | grep 关键词 | |------|------------| | Python 异常 | Traceback、Error:、Exception: | | JS/TS 错误 | TypeError、ReferenceError、Uncaught | | 编译错误 | error:、BUILD FAILED、exit code | | 测试失败 | FAILED、AssertionError、assert | | 环境问题 | not found、permission denied、Access denied | | 通用错误 | failed、cannot、unable to |

提取格式（内部用）：

[错误 #N] session: xxx | 时间: xxx | 频率: N次
类型: 语法/配置/逻辑/环境/第三方/其他
错误信息: 
文件: 
解决了吗: 是/否/不确定

Step 3：分类归类

| 类型 | 信号 | 高频根因方向 | |------|------|-------------| | 语法 | SyntaxError、拼写、类型不匹配、括号 | 改 A 没同步 B / 没跑检查 | | 配置 | 缺依赖、版本冲突、端口占用、env 未设 | 环境信息分散在多处 | | 逻辑 | 死循环、状态机卡死、空指针、条件遗漏 | 边界条件没覆盖 / 异步缺保护 | | 环境 | 编码乱码、路径不存在、权限、杀软 | 跨平台假设 / Windows 特性 | | 第三方 | 库 API 变更、库内部 bug、版本不兼容 | 没锁版本 / 盲目升级 | | 其他 | 不属于以上 | 单独标记 |

Step 4：根因分析

每个错误做三层分析：

1. 直接原因：什么报错了？（代码层面）
2. 深层原因：为什么会报这个错？（流程/假设/认知层面）
3. 预防缺口：为什么没早点发现？（检查/测试/skill 规则层面）

格式：

[错误 #N]
  直接：uvicorn 日志模块调用 isatty() 返回 None
  深层：--windowed 模式下无 TTY，uvicorn 日志仍假设有终端
  缺口：skill 没提"无终端模式下关闭 uvicorn 日志"

Step 5：关联分析

对所有错误做交叉分析，找隐藏关联：

因果链：A 错修复是否引入了 B 错？

• 对比错误出现的时间顺序
• 如果 A 修完后 B 立刻出现 → 标记因果关联

同根多面：多个错误是不是同一个根因的不同表现？

• 对比深层原因是否相同或高度重叠
• 是 → 合并为一组，用一个预防规则覆盖

跨项目共鸣：这个错误在其他项目里也出现过？

• 搜 ERROR_LOG 历史和相关 memory 文件
• 有 → 建立跨项目链接

输出关联图（如果有）：

A(编码乱码) ← 同根 → B(安装脚本报错)
     ↑
  根因：cmd 只认 GBK
     ↓
  预防：所有脚本 ASCII

Step 6：置信度评估

对每个错误做四象限分级，决定处理策略。

评估矩阵

| | 高复利（可复用+低副作用） | 低复利/一次性 | |---|---|---| | 诊断确定 | 🟢 ① 确定·高价值 | 🟡 ② 确定·低价值 | | 诊断推测 | 🔵 ③ 推测·高价值 | ⚪ ④ 存疑/一次性 |

"确定 vs 推测"判断依据

1. 堆栈/错误信息是否直接指向根因？
2. 是否有完整复现路径？
3. 发生频率（≥2 次同模式 → 确定性大幅提升）
4. 是否匹配已知错误模式（references/error-patterns.md）？

"高复利 vs 低复利"判断依据

1. 同一根因是否可能在多处/多项目重现？
2. 预防规则是否会误伤正常场景（副作用风险）？
3. 是否反复发生？（反复发生 → 不预防会持续消耗，复利明确）

分级处理策略

🟢 确定·高价值 —「沉淀」

| 产出目标 | 内容 | 执行方式 | |---------|------|---------| | /.claude/ERROR_LOG.md | 错误描述 + 解法 + 预防措施（全量） | 自动写入 | | /CLAUDE.md | 预防规则推荐 | 展示推荐 → 用户确认 → 修改 | | memory/（全局，绝对路径） | 跨会话操作记忆 | 按需判断（见下方判断表） | | 个人知识库/wiki/来源/开发踩坑录.md | 方法论级洞察 | 按需判断（见下方判断表） | | Skill 修改 | 涉及 skill 漏洞的建议 | 推荐，用户确认后修改 |

🟡 确定·低价值 —「仅归档」

| 产出目标 | 内容 | 执行方式 | |---------|------|---------| | /.claude/ERROR_LOG.md | 错误描述 + 解法 | 自动写入 | | CLAUDE.md / memory/ / wiki/ | 不触发 | — |

🔵 推测·高价值 —「待验证」

| 产出目标 | 内容 | 执行方式 | |---------|------|---------| | /.claude/ERROR_LOG.md | 错误描述 + 推测依据 + 验证方法 | 自动写入 | | 验证选项 | "要验证这个推测吗？" | 展示给用户 | | 验证通过 | → 升级为 🟢，按 🟢 策略执行 | 验证成功后自动升级 | | 验证失败 | → 降级为 ⚪，仅保留摘要记录 | — |

⚪ 存疑/一次性 —「仅记录」

| 产出目标 | 内容 | 执行方式 | |---------|------|---------| | 摘要 | 列出错误，标注"未归档" | 仅在摘要中出现 | | 频率监控 | 同错误累积 ≥2 次 → 自动升级至 🔵 | 基于 ERROR_LOG 历史判断 |

不做任何写入。 不进入 ERROR_LOG、不写规则、不触发记忆联动。

memory/ 和 wiki/ 写入判断

两个目标不自动双写，按以下标准独立判断：

| 条件 | memory/ | wiki/ | |------|:---:|:---:| | 跨项目通用规律，CC 每次会话应知 | ✅ | ✅ | | 本项目高频，但别处用不上 | ✅ | ❌ | | 方法论级洞察，不必每会话提醒 | ❌ | ✅ | | 一般高价值，ERROR_LOG + CLAUDE.md 已足够 | ❌ | ❌ |

写入由 debug-architect 调用 memory-keeper 的 MCP 工具执行。

Step 7：归档写入

按置信度等级执行不同范围的归档。

项目 ERROR_LOG（🟢🟡🔵 写入）

文件位置：/.claude/ERROR_LOG.md

作用：项目的免疫记忆——下次开项目先读此文件，避免踩同样坑。

写入模板：

## [错误简述] `[等级]` `[状态]`

- **时间**：YYYY-MM-DD
- **错误信息**：
- **根因**：[直接原因]
- **解法**：[具体修复步骤]
- **预防**：[如何避免重现]（🟢 等级必有，🟡 可选，🔵 为验证建议）
- **关联**：[链接到 ERROR_LOG 中的相关条目]

状态标记：[已修复] [持续注意] [待验证]

合并策略：ERRORLOG 中已有同类条目 → 在原条目更新（补充模式、更新频率），不追加重复条目。ERRORLOG 不存在 → 自动创建。

memory/ 和 wiki/（仅 🟢 触发，按需判断）

按 Step 6 中 memory/ 和 wiki/ 写入判断表执行。调用 memory-keeper skill 完成写入。

各等级写入清单

| 等级 | ERROR_LOG | memory/ | wiki/ | |------|:---:|:---:|:---:| | 🟢 确定·高价值 | ✅ 全量 | 按需 | 按需 | | 🟡 确定·低价值 | ✅ 错误+解法 | ❌ | ❌ | | 🔵 推测·高价值 | ✅ 推测+验证 | ❌ | ❌ | | ⚪ 存疑/一次性 | ❌ | ❌ | ❌ |

Step 8：预防建议

频率是置信度评估的输入信号之一（见 Step 6 判断依据），不再是独立规则。

预防建议按等级处理：

| 等级 | 预防建议 | |------|---------| | 🟢 确定·高价值 | 推荐写入项目/全局 CLAUDE.md，展示建议 → 用户确认 → 修改 | | 🟡 确定·低价值 | 不写入规则，仅在 ERROR_LOG 中记录解法 | | 🔵 推测·高价值 | 建议"下次复现时的信息收集清单"，不写规则 | | ⚪ 存疑/一次性 | 不触发 |

写入层级判断（仅 🟢）：

• 仅当前项目受影响 → 项目 /CLAUDE.md
• 跨项目通用 → 全局 ~/.claude/CLAUDE.md（Windows: C:\Users\\.claude\CLAUDE.md）

输出时必须给出要修改的绝对路径，并标注是项目文件还是全局文件。

规则格式：

# 在 CLAUDE.md 中追加
## 预防规则（来自 debug-architect）
- "每次 X 前先检查 Y" — 来源：[错误简述]

Step 9：输出摘要

输出规则：

• 所有文件路径使用绝对路径（如 D:\MyAIWorkspace\.claude\ERROR_LOG.md，不是 ERROR_LOG.md）
• 区分项目文件（/）和全局文件（~/.claude/ 或 C:\Users\\.claude\）
• 🆕 新建 = 文件原本不存在，本次创建；✏️ 更新 = 文件已存在，本次修改
• 等级标签必须用完整文字，emoji 只是前缀：🟢 确定·高价值、🟡 确定·低价值、🔵 推测·高价值、⚪ 存疑/一次性
• 确认环节：所有待操作项合并为一个表一次性列出，不要逐条询问。用户一句"确认"即全部执行，"除了#N"可跳过某项

## 错误复盘完成 — [项目名]（YYYY-MM-DD）

### 分级汇总
| 等级 | 数量 | 处理方式 |
|------|:---:|---------|
| 🟢 确定·高价值 | N | 已推荐规则，等你确认 |
| 🟡 确定·低价值 | N | 已归档 ERROR_LOG |
| 🔵 推测·高价值 | N | 已归档，N 条待验证 |
| ⚪ 存疑/一次性 | N | 仅记录，未归档 |

### 错误清单
| # | 等级 | 类型 | 错误 | 频率 | 关联 |
|---|------|------|------|------|------|
| 1 | 🟢 确定·高价值 | 环境 | bat编码乱码 | 3次 | ←→ #3 |
| 2 | ⚪ 存疑/一次性 | 逻辑 | 偶发超时 | 1次 | 独立 |

### 根因汇总
- #1+#3 同根：cmd 只认 ANSI/GBK
- #2：异步 fetch 后 isWaitingForAI 未 finally 复位

### 文件变更（带绝对路径）
| 操作 | 文件 | 说明 |
|------|------|------|
| 🆕 新建 | `/.claude/ERROR_LOG.md` | 首次创建，写入 N 条 |
| ✏️ 更新 | `/.claude/ERROR_LOG.md` | 追加 N 条 |
| ✏️ 修改 | `/CLAUDE.md` | 预防规则 |
| ✏️ 修改 | `C:\Users\\.claude\CLAUDE.md` | 全局预防规则 |
| 🆕 新建 | `C:\Users\\.claude\projects\\memory\.md` | 跨会话记忆 |
| ✏️ 更新 | `D:\MyAIWorkspace\个人知识库\wiki\来源\开发踩坑录.md` | 方法论沉淀 |

只列出实际发生变更的行。`🆕 新建` = 文件原本不存在，本次创建。`✏️ 更新` = 文件已存在，本次修改。

### 预防建议
- **项目规则** → `/CLAUDE.md`："所有脚本文件只用 ASCII 编码"
- **全局规则** → `~/.claude/CLAUDE.md`："异步状态机必须 finally 复位"

### 技能漏洞
- image-to-code skill 缺："打包前检查路径不含中文"
- 是否修改以上 skill？

### 待确认（一次性列出，确认后批量执行）

> 以下操作等你一句"确认"后一次性执行，不逐个询问。

| # | 操作 | 目标文件 | 内容 |
|---|------|---------|------|
| 1 | 写入规则 | `/CLAUDE.md` | "所有脚本文件只用 ASCII 编码" |
| 2 | 写入规则 | `~/.claude/CLAUDE.md` | "异步状态机必须 finally 复位" |
| 3 | 验证推测 | — | "状态机卡死是否为竞态条件？" → 通过则升级🟢 |

回复"确认"即全部执行。需要跳过某项可以说"除了#N"。

只输出有内容的段落。

特殊情况

没有错误：报告"该项目扫描范围内未发现报错"。 sessions 不可读：跳过并备注。 错误已全部修复且已归档：确认无需新增归档，只输出统计摘要。 关联分析无发现：跳过关联段落。 技能漏洞无发现：跳过技能漏洞段落。 ⚪ 错误累积 ≥2 次：检查 ERROR_LOG 历史，同错误出现 ≥2 次 → 自动升级至 🔵，下次复盘时提示。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 2021291696
• Source: 2021291696/weaver-evolve
• License: MIT

Install and usage instructions live in the source repository linked above.