调试建筑师 — Debug Architect

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

与其他 skill 的关系

触发方式

独立使用

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

被 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，搜以下信号：

提取格式（内部用）：

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

Step 3：分类归类

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. 是否反复发生？（反复发生 → 不预防会持续消耗，复利明确）

分级处理策略

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

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

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

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

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

memory/ 和 wiki/ 写入判断

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

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

Step 7：归档写入

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

项目 ERROR_LOG（🟢🟡🔵 写入）

文件位置：<项目根>/.claude/ERROR_LOG.md

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

写入模板：

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

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

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

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

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

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

各等级写入清单

Step 8：预防建议

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

预防建议按等级处理：

写入层级判断（仅 🟢）：

• 仅当前项目受影响 → 项目 <项目根>/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 次 → 自动升级至 🔵，下次复盘时提示。