exhaustive-systems-analysis

全面系统分析

将此技能用于完整系统正确性工作。任务是梳理系统、识别风险最高的行为、证实或驳斥具体的故障假设，并留下报告，让其他工程师无需重新阅读整个代码库也能据此采取行动。

需要预防的故障模式

1. 只扫描文件、不端到端追踪行为的表面审查
2. 错误的确定性：证据不足，却将疑虑报告为缺陷
3. 大型审查涉及多个子系统时出现上下文偏移
4. 流于表面的审查，遗漏真正的正确性和发布准备风险

工作模式

• 默认采用 chat-first 输出。除非用户要求提供文档，或审查明显需要跨多个会话的材料，否则直接在对话中给出发现。
• 对大型或可续接的审查，切换到 artifact mode。使用 docs/audit/ 或 .claude/docs/audit/，并遵循仓库现有约定。
• 除非用户明确要求修复，否则审查时不要开始修改代码。此技能用于诊断、举证和确定优先级。

工作流程

0. 校准审查范围

深入阅读前，使用 references/templates.md 中的模板，撰写一份一屏可读的范围说明。

记录：

• 待审查的系统或领域
• 最重要的用户可见工作流或契约
• 可能的高风险领域：状态、副作用、并发、身份验证、持久化、外部集成
• 范围之外的领域
• 输出模式：chat-first 或 artifact mode

如果请求范围较广，应将其缩小到真正可能影响用户结果或发布准备状态的模块。

1. 先了解意图，再看代码

只阅读能够明确预期行为的材料：

• README、CLAUDE.md、架构文档、ADR
• 描述用户可见行为或契约的测试
• 涉及目标领域的近期提交
• TODO、FIXME、HACK 和“已知问题”
• 可用时的事故记录、错误报告或问题跟踪项

提取：

• 关键工作流
• 外部接口
• 热点和近期变更
• 无法仅凭代码全面验证、只能手动检查的领域

2. 建立覆盖台账

深入分析前，先将系统划分为多个子系统。使用 references/templates.md 中的覆盖台账模板。

为每个子系统记录：

• 名称
• 入口点
• 范围内的文件或目录
• 不变量或承诺的行为
• 副作用
• 风险等级
• 状态：planned | in_progress | done | follow_up

优先级应首先依据用户影响，其次考虑副作用、并发、权限和近期变更。文件夹结构本身不能作为优先级体系。

3. 深入审查前提出假设

针对每个高风险或中风险子系统，在深入分析前写出 2-3 个具体假设。好的假设可以证伪，并且与某个行为边界相关。

示例：

• “写入 A 和写入 B 之间发生故障，可能导致持久化状态不一致。”
• “重试路径会重复执行副作用，因为没有强制幂等性。”
• “文档承诺行为 X，但实现遇到无效输入时会落入行为 Y。”

随着证据出现，更新或舍弃假设。此步骤可避免漫无目的地扫描。

4. 一次审查一个子系统

端到端阅读子系统：

• 从入口点开始，追踪正常流程
• 追踪错误路径、清理路径、取消或关闭流程，以及重试流程
• 将实现与测试、文档、类型和公开契约进行比较
• 在有助于强化证据时，执行有针对性的搜索、命令或测试
• 如果某项发现依赖特定命令、搜索或范围，应准确记录

仅选择 references/checklists.md 中相关的检查清单部分。如果子系统只需要一两份检查清单，就不要加载全部清单。

如有可用的子 Agent，可为每个子 Agent 分配一个边界明确、文件互不重叠的子系统，并要求其提供：

• 已检查的假设
• 附有精确引用的发现
• 覆盖缺口
• 建议的下一步验证措施

5. 使用证据、状态和置信度对发现进行分类

每项发现都必须将观察结果与推断分开。

必填字段：

• Severity：Critical | High | Medium | Low
• Status：Confirmed | Likely | Needs follow-up
• Confidence：High | Medium | Low
• Type：Bug | Race condition | Security | Stale docs | Dead code | Design flaw | Reliability
• Location：精确的文件路径和行号或函数
• Impacted behavior：面临风险的用户可见工作流、不变量或契约
• Observed evidence：代码引用、命令输出、测试结果、日志或搜索结果
• Inference：说明这些证据为何能证明所报告的问题
• What I checked：说明检查过的搜索、测试、文档、提交，或排除的其他解释
• Recommendation：最小且可信的后续操作
• Next verification step：状态为 Needs follow-up 时必填

只有在代码、失败测试、复现路径或明确矛盾直接证实问题时，才使用 Confirmed。推理有力但未直接复现时，使用 Likely。存在可疑之处但证据不完整时，使用 Needs follow-up。

6. 执行收敛检查

完成各子系统审查后：

• 去重跨领域发现
• 根据严重性和用户影响重新排序
• 最后扫描残留项，包括过时文档、已弃用名称、无人调用的辅助函数、临时标志、TODO 或 FIXME 集中点，以及风险较高的 API
• 如果精确的残留项搜索查询和计数会影响结论，就记录下来
• 明确列出覆盖缺口，不要假装已完成未完成的审计

证据标准

优先采用更有力的证据，而不是更多文字。按证据强度从高到低排列：

1. 失败测试或针对性测试
2. 带有精确步骤的可复现路径
3. 带有精确引用的直接代码矛盾
4. 日志、遥测数据或命令输出
5. 带有计数的限定范围搜索结果
6. 静态推理

静态推理本身也有价值，但通常应得出 Likely，而非 Confirmed。

对于死代码或过时文档，务必说明搜索了什么，以及为何认定代码或文档已过时。没有搜索调用方就声称代码已死，证据并不完整。

报告规则

• 先列出发现，不要先复述方法。
• 优先报告影响用户的正确性问题，而非风格清理。
• 除非相关发现有相同的根本原因，否则应分开报告。
• 如果没有严重问题，应直接说明，并继续报告剩余风险和未经验证的部分。
• 不要只说“看起来不对”或“可能有问题”，而不说明检查了什么，以及什么证据能证实或排除此问题。

以下内容请使用 references/templates.md 中的模板：

• 范围简述
• 覆盖情况记录
• 发现格式
• 对话优先摘要
• 产物模式审计目录

会话管理

小型审计使用单会话模式。对于大型审计或上下文有限的情况，请建立轻量级控制层：

• 00-plan.md：范围简述和覆盖情况记录
• 仅在审计规模足以证明其必要时，才为每个子系统单独创建文件
• SUMMARY.md：汇总发现和修复顺序
• 若工作将在之后继续，创建 HANDOFF.md

良好的交接内容应包括：

• 已覆盖的内容
• 当前认为属实的事项
• 尚未验证的内容
• 当前阻碍
• 精确的后续步骤

反模式

• 未识别入口点或不变量就扫描目录
• 将每个代码异味都报告为发现
• 未搜索调用方就声称某段代码已死
• 未说明被破坏的行为或违反的契约就声称存在 Bug
• 将多个子系统合并成一份庞大的报告
• 隐瞒不确定性，而不标记为 Needs follow-up

完成标准

满足以下条件时，审计即告完成：

1. 高风险子系统均有记录条目和最终状态
2. 每项报告的问题均包含证据、置信度和具体位置
3. 最终报告包含修复顺序和未经验证的部分
4. 横切问题和残留问题已整合
5. 报告如实说明了哪些内容尚未得到证实