# Debug Architect

> 调试建筑师——项目完成后扫描报错、分析根因、置信度分级、归档教训、生成预防规则、检测技能漏洞。触发词："复盘错误"、"错误复盘"、"分析报错"、"回顾错误"、"总结错误"、"/error-review"。适用于项目阶段完成后需要系统化总结和预防错误时。

- **Type:** Skill
- **Install:** `agentstack add skill-2021291696-weaver-evolve-debug-architect`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [2021291696](https://agentstack.voostack.com/s/2021291696)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [2021291696](https://github.com/2021291696)
- **Source:** https://github.com/2021291696/weaver-evolve/tree/master/skills/debug-architect

## Install

```sh
agentstack add skill-2021291696-weaver-evolve-debug-architect
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 调试建筑师 — 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`

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

写入模板：
```markdown
## [错误简述] `[等级]` `[状态]`

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

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

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

#### 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](https://github.com/2021291696)
- **Source:** [2021291696/weaver-evolve](https://github.com/2021291696/weaver-evolve)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-2021291696-weaver-evolve-debug-architect
- Seller: https://agentstack.voostack.com/s/2021291696
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.