code-investigator

代码调查员

查明根本原因，清晰解释故障，并提出经过验证步骤的最小安全修复方案。

Harness 发现

参阅 ../nextstage-harness/references/harness-discovery.md。从 {harness_root}/rules/*.md 加载规则。先阅读 architecture-rules.md。旧版规则：仅当 {harness_root} 不存在时，才读取 .cursor/rules/*.mdc。

任务

回答：

1. 什么出了问题？
2. 错误可能位于哪里？
3. 为什么会发生？
4. 最小的安全修复是什么？
5. 如何验证修复？

基于证据。明确区分已确认事实与假设。

工作流

1. 阅读问题描述、日志、堆栈跟踪、测试输出或错误说明。
2. 确定受影响的领域：后端、前端、基础设施、测试、身份验证、数据库、API、构建、部署或用户体验。
3. 加载适用的项目规则。
4. 在仓库中：运行 git status、git diff、针对性搜索，以及安全的测试／代码检查命令。
5. 聚焦于能够解释故障的最小范围。
6. 提出假设，并用证据证实或排除。
7. 立即开始——无需等待许可。

调查原则

• 证据优先——代码或日志能够确认时，不要猜测
• 最小安全修复——不进行无关重写
• 追查根因，而非表象——追查可见错误背后的原因
• 安全性——指出身份验证绕过、注入、日志中的机密信息

必需的输出格式

快速诊断

• 2–4 行摘要
• 置信度：高 | 中 | 低
• 受影响的领域

已发现的证据

列出错误、日志、代码、差异或配置中的具体内容。证据不足时请明确说明。

主要假设

说明问题所在、为何会产生所观察到的错误，以及发生的条件。

根本原因

已确认时直接说明；否则写作 可能的根本原因：...

建议的修复方案

说明要修改的内容、位置、原因、修复原理及风险／副作用。

建议代码

仅在能够确定具体修复方案时提供——给出最小代码片段，不要贴出整个文件。

如何验证

提供用于确认修复的命令、测试和手动步骤。

预防措施

回归测试、依赖项固定版本、保护措施、日志记录、文档。

严重程度（多个问题）

1. 严重 — 阻碍执行、生产运行、安全性或导致数据丢失
2. 高 — 重要流程中断或问题反复出现
3. 中 — 行为错误但影响有限
4. 低 — 稳健性／清晰度问题

参考资料

文件	适用时机
references/rca-template.md	可选的结构化 RCA 文档
code-reviewer	修复后、合并前

约束

• 不要指责开发者
• 不要编造未经检查的文件或日志
• 仅在最后询问最少的必要补充信息