Ajiang Debug

---
name: ajiang-debug
description: 排查和修复 bug：先复现问题、验证原因，再做最小修复，并用原来的操作流程确认结果。
license: MIT
---

# 排查与修复 Bug

目标是恢复用户原来失败的任务，并让结论与实际证明的范围一致。

## 复现问题

- 区分报告中的可观察现象、预期行为和归因猜测。报告者提供的是有价值的线索，猜测需要实验核验。
- 确认待修改仓库、实际工作区、版本/commit 与启动入口；参考仓库只作为参考。记录与问题有关的环境、有效配置、输入规模和历史状态，敏感值只记录配置是否存在或脱敏身份。
- 尝试从用户入口复现，保存准确步骤、错误与预期结果。能安全建立修前失败的自动回归时优先建立；简单问题不必生成额外文档。

## 验证原因

不要只寻找支持第一个解释的证据。对竞争假设设计实验，每次尽量改变一个关键条件。沿调用链、配置优先级、状态生命周期及数据规模定位实际差异。

复杂调查可在任务工作目录维护表格：

| 假设 | 可区分实验 | 实际结果/证据位置 | 状态 | 适用环境与版本 |
|---|---|---|---|---|

排除记录用于避免重复探索；版本、输入或条件改变后可以重新打开假设。问题暂时消失不等于修复。第一个原因成立后，仍从原入口检查是否存在叠加原因。

暂时无法完整复现时，继续读取相关代码、日志，缩小环境差异，或添加必要诊断。代码路径与定向失败测试可以证明局部缺陷，但不能冒充用户环境复现。用户明确要求“复现后才能修改”时，保持该执行边界。不要无限增加负载或扩大修改范围来强求复现。

## 修复并复测

只修改证据支持的原因，保留不相关的已有行为。独立旧问题记录为后续事项；本次引入的回归应修复。

修后重跑原入口、原关键条件及失败输入，不用更小数据、另一个入口或新配置代替原验收。增加与改动相关的相邻路径检查，例如恢复、取消、边界输入或配置覆盖；不默认全量扩展测试。

按待证明的边界选择测试：纯逻辑用确定性测试；超时/竞态可控制时钟或上游；真实 provider、系统或发布入口有实际变化时补对应真实验证。准确说明模拟测试与实际运行各自覆盖的范围。

断言用户可观察结果、持久化状态或真实产物，避免只检查 AI 回复里的“成功”。新增回归测试应能在旧行为或受控回归下失败。

## 交付

先说原流程是否恢复，再给：根因链、修改、修前/修后证据和未验证条件。明确区分实测确认、代码路径确认、推断及未复现。未运行的命令不能算验证。

如果复现消失但无因果证据，报告“本次未再复现，根因未确认”；如果仅局部回归通过，报告其范围。新证据推翻此前判断时明确更正。

复杂调查可按 [排障记录](assets/task-record.md) 保存复现、假设实验与同条件复测。