docs: 问题汇报改为根因/修复方案/影响范围三段式

This commit is contained in:
cat-shark
2026-10-09 15:43:24 +08:00
parent e13a19c0c5
commit 7eb346b260
+8 -5
View File
@@ -7,11 +7,14 @@
- 本规则适用于「调研、排查、定位问题」类任务(例如“现象是不是这个改动引起的”“为什么这里变慢了”),不适用于已有明确改法的一次性修改。
- 「1 轮调研」指一条连续的最小验证路径:确认现象范围 → 对比可疑改动 → 拿到可复现/可量化的证据。
- 如果 1 轮调研后仍未定位到根因,必须停止自行扩大调查范围,先向用户汇报,由用户决定是否继续调查或调整方向。
- 汇报必须包含以下内容,缺一不可:
- 已确认的事实与证据(具体命令、文件、提交、返回值,而不是推测)。
- 已排除的可能原因(以及排除依据)。
- 当前卡点:还缺哪个信息、需要谁提供(例如用户登录凭据、某个环境的数据量、一次控制台取样)。
- 建议的后续方案(1-3 个,标注推荐项与各自代价)。
- 汇报必须按以下**固定三段式**表述,顺序不变;只写结论与关键证据,不要罗列调查过程:
1. **根因**:问题的直接原因,以及支撑它的证据(命令、文件、提交、返回值)。没有证据的推测禁止写进这一段。
- 附上已排除的可能原因及排除依据。
2. **修复方案**:怎么改。分为「必做 / 建议做 / 不建议做」三类,每项标注代价、以及由谁执行(我 / 用户)。
- 附上当前卡点:还缺哪个信息、需要谁提供。
3. **影响范围**:受影响的功能、用户、环境与数据;不修会怎样;修了会不会连带影响其它东西。
- 三段式之外不另起新段式;额外信息(已排除项、卡点)归到对应段落下面。
- 先用一句话给出结论,再展开三段;不要让用户从推导过程里自己提炼结论。
- 汇报后等待用户决定,不要一边汇报一边继续发散式尝试;同一方向连续失败两次就转为汇报。
- 禁止把「可能是 X」直接当成结论去改代码;只有拿到证据的结论才允许进入修改阶段。