debugging

调试

永久性修复应基于有证据支持的因果解释。假设可以作为开展范围明确、可逆实验的依据；在验证之前，应将其标记为实验。在事故处理中，经授权的回滚或功能禁用可能在根因尚未查明时恢复服务。记录尚存的不确定性，并继续调查修复问题：缓解措施并不能证明修复有效。

范围和模式

对于仅要求诊断的请求，应在调用方授权范围内检查源代码／制品并执行安全的只读检查；不要进行修复，也不要违反禁止构建的限制。诊断可以在找到有证据支持的原因后结束，即使提出的修复仍未验证。仅在缺少的信息会阻碍所请求的工作时，才使用 NEEDS_CONTEXT。

将编辑限制在假设涉及的狭窄文件范围内；扩大范围前，应先修订假设。保留其他工作。在分享诊断信息或进行外部搜索之前，应酌情移除凭据、客户数据、主机名、IP、路径和 SQL 片段；使用从环境中获取的凭据，而不要嵌入密钥。对于分支／构建比较或诊断数据共享，请阅读 baseline-and-data-handling.md。

流程

1. 读取并复现。 阅读完整错误信息和汇总数据，而不只是筛选后的匹配项。会话恢复后确认 HEAD，再信任沿用的文件内容。编辑前先运行已提供的复现程序。精确匹配报告的问题；相近的故障不算同一复现。使用成本最低的实际触发方式。对于间歇性错误，限制尝试次数并报告触发条件和频率；有限次数的正常运行不能证明不存在竞态。构建、精简或检测复现程序时，请阅读 reproduction-and-investigation.md。
2. 以证据为依据提出假设。 提出 2 到 3 个候选假设，每个都引用一条观察结果。对于已确认的简单拼写错误，只需简短检查因果关系；仅凭导入错误无法确定导入失败的原因。在保留实际触发条件的同时，精简无关输入。如果无法循环测试，请报告缺少的访问权限、构件、凭据或步骤，并继续独立调查源代码，但不要声称已复现。
3. 追踪并区分。 说明被违反的不变量和触发条件，不要强加固定的调用栈深度。比较代码、输入、状态、时序、环境和构建配置。在另一个构建中通过的相同源代码仍可能包含未定义行为或竞态。进行反向追踪或调查测试污染时，请使用 root-cause-tracing.md；收集相关环境信息时，请使用 collect-diagnostics.sh。探测前先说明要验证的问题和判定规则；在信任结果前，确认对照条件和构建身份。修复前，列出所有观察到的问题，包括报告者称为无关的问题；原因必须解释每个问题，未解释的问题意味着存在第二个原因或假设尚未完成（请说明是哪一种）。当观察结果与日志或探测结果矛盾时，先考虑是否存在未检测到的路径，再决定是否舍弃该观察结果。
4. 每次只测试一项更改。 使用最小实验验证一个明确命名的因果假设。若实验未能证实假设，在进行下一项实验前先还原；适当时使用二分查找定位引入回归的更改。补救措施失败，可能意味着修复不完整或构建不正确，而不一定证明原因不成立。开始下一项实验前，重新评估实际证据。对于涉及多个组件且彼此竞争的解释，请阅读 competing-hypotheses.md。
5. 修复并验证。 对于已授权的修复，请阅读 repair-and-escalation.md。创建能触发真实问题的回归测试：修复前失败，修复后通过。如果不存在可达的测试接入点，请报告这一情况，不要用无法复现所报告缺陷的测试代替。在 ia-verification-before-completion 下，使用新的证据验证原始入口点；不要削弱断言、吞掉失败或针对测试输入特殊处理。使用能到达相同错误状态的相近输入进行绕过自检；如果它能绕过更改，请回到根因分析。与安全相关的修复需要依据 specialized-patterns.md 进行新的对抗性攻击复测。然后检查是否存在相同类型的缺陷：在整个仓库中搜索与修复特征相同的代码（跳过生成代码和第三方引入代码），如调用、缺失的保护条件或锁缺失，并将每处匹配归类为同一缺陷、安全（说明原因）或不确定。仅在假设涉及的文件范围内修复匹配项，并为每项修复单独进行红灯/绿灯验证；列出其余匹配项，或请求扩大范围。精简已验证的修复，并移除诊断检测代码。
6. 三个失败周期后重新评估。 停止编辑，重新阅读相关路径，列出未能成立的假设，并升级证据。三个周期是重试上限，不是架构存在问题的证明。在仅诊断模式下，如果三个周期后仍无法缩小到相关组件，请提供阶段性发现和下一步检测措施。坦诚说明原因未知。通过 Claude Code 中的 AskUserQuestion、Codex（如支持）中的 request_user_input，或在其他情况下通过聊天询问会造成实质影响的缺失信息；无人值守的子 Agent 应将阻塞事项反馈给其父级。 对于 CI 失败、渲染／异步方面的初步改动、性能问题、间歇性故障、事后复盘或反复出现的模式，请阅读 specialized-patterns.md。对于多层验证缺陷，请阅读 defense-in-depth.md。出现诊断反模式或修复反复失败时，请遵循详细的修复参考。

调试报告与完成状态

针对请求的范围，填写以下七个字段：

SYMPTOM:    Observed failure
ROOT CAUSE: Evidenced causal conclusion with file:line covering every symptom, or remaining uncertainty
FIX:        Verified repair; use PROPOSED FIX and validation command in diagnosis-only mode
EVIDENCE:   Causal evidence and, for repairs, actual verification results
REGRESSION: Actual regression, or proposed test/missing seam when no repair was performed
RELATED:    Same-shape sweep (N checked, N same-shape, fixed/listed, or not run and why); prior bugs, risks, architecture
STATUS:     DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT

DONE 表示修复已验证，或已通过证据完成所请求的诊断；绝不表示未经测试的拟议补救方案已获证实。DONE_WITH_CONCERNS 说明已完成的范围及剩余的不确定性。BLOCKED 说明阻碍因素；NEEDS_CONTEXT 说明所需但缺失的信息。仅采取缓解措施并不代表修复请求已完成。

完成修复前，请检查因果证据、实际回归测试覆盖范围或其明确限制、绕过／再次攻击的结果，以及是否已移除诊断日志。对于非简单的生产环境 Bug，请使用专门的参考文档记录简要的时间线、原因、影响、修复方案和预防措施，进行事后复盘。