exhaustive-systems-analysis

全面系统分析

系统化审计方法，用于排查代码库中的潜在问题，尤其适用于需要在投入生产使用前进行验证的 Agent 编写代码。

核心原则

1. 子系统隔离 — 分别分析每个子系统，避免上下文相互干扰
2. 基于证据的问题发现 — 每个问题都必须引用具体的代码位置
3. 按严重程度确定优先级 — 先处理严重问题，最后处理外观问题
4. 假设所有问题都会修复 — 不要含糊其辞；直接指出问题所在

工作流

阶段 1：系统拆解

分析前，先梳理系统的子系统。通过以下方式自动发现：

1. 阅读项目结构 — 找出主要模块、包或目录
2. 追踪数据流 — 跟踪数据如何进入、转换和输出
3. 识别副作用 — 文件 I/O、网络、数据库、IPC、状态变更
4. 梳理依赖关系 — 找出各子系统之间的依赖

输出子系统表：

| # | Subsystem | Files | Side Effects | Priority |
|---|-----------|-------|--------------|----------|
| 1 | Lock System | lock.rs | FS: mkdir, rm | High |
| 2 | API Layer | api/*.rs | Network, DB | High |
| 3 | Config Parser | config.rs | FS: read | Medium |

优先级判断准则：

• 高：副作用、状态管理、安全、并发
• 中：业务逻辑、数据转换、验证
• 低：纯工具、格式化、日志记录

阶段 2：顺序分析

按优先级顺序分析子系统。对于大型代码库（>5 个子系统或每个子系统 >3000 LOC），建议在分析子系统之间清除上下文，以避免分析偏移。

根据子系统类型，对每个子系统应用相应的检查清单。

阶段 3：汇总

分析完所有子系统后：

1. 合并重复的跨领域问题
2. 按严重程度排列所有问题
3. 根据建议的处理顺序生成最终报告

---

分析检查清单

根据子系统特征选择检查清单。适用时可同时应用多份清单。

有状态系统（文件、数据库、缓存、锁）

检查项	问题
正确性	代码是否实现了文档所述的功能？
原子性	部分写入是否会破坏状态？
竞态条件	并发访问是否会导致状态不一致？
清理	是否在所有退出路径（成功、错误、panic）上释放资源？
错误恢复	发生故障后，系统是否仍处于有效状态？
过时的文档	注释是否与实际行为相符？
死代码	是否存在可能令维护人员困惑的未使用代码路径？

API 与网络（HTTP、gRPC、WebSocket、IPC）

检查项	问题
输入验证	使用前是否验证了所有输入？
错误响应	错误是否泄露了内部细节？
超时处理	网络操作是否设有时限？
重试安全性	操作是否幂等，或是否有适当的防护？
身份验证	是否一致地执行身份验证检查？
速率限制	API 是否可能遭到滥用？
序列化	格式错误的负载是否会导致 panic？

并发（线程、异步、通道、锁）

检查项	问题
死锁风险	锁的获取顺序是否可能导致死锁？
数据竞争	共享的可变状态是否得到适当同步？
饥饿	是否有任务可能被无限期阻塞？
取消	取消/关闭路径是否处理妥当？
资源泄漏	是否妥善等待或分离已生成的任务/线程？
panic 传播	任务中的 panic 是否会导致整个系统崩溃？

UI 与呈现（视图、组件、模板）

检查项	问题
状态一致性	UI 是否可能显示过时或不一致的状态？
错误状态	是否以适当方式呈现了所有错误情况？
加载状态	是否正确显示异步操作的状态？
无障碍性	是否可通过键盘/屏幕阅读器访问交互？
内存泄漏	是否清理了订阅/观察者？
重新渲染效率	是否避免了不必要的重新渲染？

数据处理（解析器、转换器、验证器）

检查项	问题
边界情况	是否处理了空值、null 和边界值？
类型强制转换	隐式转换是否安全？
溢出/下溢	数值运算是否有界？
编码	文本编码是否得到一致处理（UTF-8）？
注入	不可信输入能否逃逸其上下文？
不变量	是否强制执行并记录了数据不变量？

配置与设置（配置文件、环境、初始化）

检查项	问题
默认值	默认值是否安全且有文档说明？
验证	是否会及早拒绝无效配置并给出清晰的错误信息？
密钥	是否安全地处理密钥（不记录日志、不提交到 VCS）？
热重载	如果支持，重载是否原子且安全？
兼容性	是否对破坏性变更进行版本管理或迁移？

---

严重程度分类

为每项发现分类。假设用户很快会修复所有问题。

严重程度	标准	示例
严重	数据丢失、安全漏洞、生产环境崩溃	未处理的 panic、SQL 注入、文件损坏
高	用户会注意到的错误行为	计算错误、竞争条件导致 UI 状态错误、超时时间过短
中	会造成困惑或引发未来 Bug 的技术债	文档过时、名称具有误导性、代码路径冗余
低	外观问题或轻微改进	未使用的参数、次优算法（但运行正确）

---

发现项格式

每项发现都必须遵循此结构：

### [SUBSYSTEM] Finding N: Brief Title

**Severity:** Critical | High | Medium | Low
**Type:** Bug | Race condition | Security | Stale docs | Dead code | Design flaw
**Location:** `file.rs:line_range` or `file.rs:function_name`

**Problem:**
What's wrong and why it matters. Be specific.

**Evidence:**
Code snippet or reasoning demonstrating the issue.

**Recommendation:**
Specific fix. Include code if helpful.

---

输出结构

根据项目组织结构调整输出。常见模式：

模式 A：审计目录（适用于 5 个以上子系统）

.claude/docs/audit/
├── 00-analysis-plan.md      # Subsystem table, priorities, methodology
├── 01-subsystem-name.md     # Individual analysis
├── 02-another-subsystem.md
└── SUMMARY.md               # Consolidated findings, action items

模式 B：单份文档（适用于较小的系统）

.claude/docs/audit/system-name-audit.md
# Contains: plan, all findings, summary

模式 C：在现有文档中内联

如果项目已有 docs/ 或类似目录，请将审计资料放在那里。

始终创建摘要，其中包含：

• 按严重程度统计的发现总数
• 最严重的 5 个问题
• 建议的修复顺序

---

会话管理

为确保分析彻底：

• 小型系统（<1000 LOC、<3 个子系统）：可以使用单个会话
• 中型系统（1000-5000 LOC、3-7 个子系统）：在各阶段之间清理上下文
• 大型系统（>5000 LOC、>7 个子系统）：每个子系统使用单独的会话

清理上下文时，请在分析计划文件中记录进度，以便下一个会话继续。

---

分析前：已知问题排查

深入分析前，先检查已记录的问题：

1. 检查 CLAUDE.md / README 中是否有“注意事项”或“已知问题”
2. 搜索 TODO/FIXME/HACK 注释
3. 查看近期提交中的 Bug 修复（可能表明相关区域较脆弱）
4. 如果可以访问，检查问题跟踪器

将这些作为初始假设，并在分析期间验证或证伪。

---

应避免的反模式

反模式	问题所在	应采取的做法
浏览代码	会遗漏细微 Bug	阅读范围内的每一行代码
想当然地认为代码正确	Agent 代码通常存在边界情况 Bug	验证每条代码路径
发现描述含糊	“这看起来不对”无法指导行动	指出具体行，解释原因
范围过大	导致分析陷入瘫痪	严格界定子系统边界
忽略测试	测试能揭示假设	阅读测试以了解预期意图

---

完成标准

满足以下条件时，分析即告完成：

1. ✅ 已分析所有高优先级子系统
2. ✅ 每项发现均包含严重程度、位置和建议
3. ✅ 已创建摘要文档，其中包含按优先级排列的待办事项
4. ✅ 不再有“待定”或“需要进一步调查”的事项
5. ✅ 已添加相关发现之间的交叉引用