From 0d7400734ba6d91b9b24bae4342470b51f679d5f Mon Sep 17 00:00:00 2001 From: Peter Zhang <18501667167@qq.com> Date: Tue, 2 Jun 2026 19:55:06 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20DEV=5FAGENT.md=20=E5=A2=9E=E5=8A=A0=20Is?= =?UTF-8?q?sue=20=E5=85=B3=E9=97=AD=E8=A7=84=E8=8C=83=20+=20=E7=A0=94?= =?UTF-8?q?=E7=A9=B6=E5=9E=8B=E4=BF=AE=E5=A4=8D=20+=20=E7=A6=81=E6=AD=A2?= =?UTF-8?q?=E6=A8=A1=E5=BC=8F=20-=20Closes=20#79?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Issue 关闭规范: 必须包含问题/根因/修复/验证四要素 - 研究型修复流程: 根因不明时开 investigation Issue 阻断原 Issue - 禁止模式: 反复小改动试错、不跑 pipeline 关质量 Issue 等 Co-Authored-By: Claude Opus 4.7 --- agents/DEV_AGENT.md | 96 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 95 insertions(+), 1 deletion(-) diff --git a/agents/DEV_AGENT.md b/agents/DEV_AGENT.md index 79a388c..c8dd4fb 100644 --- a/agents/DEV_AGENT.md +++ b/agents/DEV_AGENT.md @@ -285,6 +285,48 @@ QE-Agent 开 Issue (qe-feedback / bug / ci-failure) --title "[test] issue 标题" --labels test-code --body "..." ``` - 多个 label 用逗号分隔，如 `--labels "ci-failure,product-code"` +- **研究调查 Issue** → `investigation` label（根因不明、需实验验证的探索性工作） + ```bash + python scripts/agent_poller.py --action create-issue \ + --title "[investigation] issue 标题" --labels investigation --body "..." + ``` + 研究 Issue 的用途见下方"研究型修复流程"。 + +## 研究型修复流程 + +**当根因不明确时，禁止反复做小改动试错。** 必须走研究 → 确认 → 修复 的路径。 + +### 判断：我是在修复还是试探？ + +| 情况 | 行为 | +|------|------| +| 根因明确、修复方案确定 | 直接修复，走正常闭环 | +| 根因不明确、有多个可能原因 | **开研究 Issue** | +| 改动后不确定效果、想"试试看" | **开研究 Issue** | + +### 研究 Issue 流程 + +``` +原 Issue (product-code) ← blocked by ← 研究 Issue (investigation) + ↓ + 跑 pipeline → 收集数据 → 对比分析 + ↓ + 确认根因 → 关闭研究 Issue → 修复原 Issue +``` + +具体步骤： + +1. **创建研究 Issue**：`--labels investigation`，描述要验证的假设和实验方法 +2. **阻断原 Issue**：研究 Issue 创建后，在原 Issue 评论"阻塞: #研究Issue" +3. **实验验证**：在研究分支上跑 pipeline，收集 Layer A/B/C 数据，对比基线 +4. **得出结论**：在研究 Issue 中记录实验结果和根因确认 +5. **修复原 Issue**：确认根因后，在原 Issue 分支上实施修复 +6. **关闭研究 Issue**：根因确认，修复完成，关闭研究 Issue + +### 关键原则 +- 一次研究 Issue 可以对应多个原 Issue（同一根因导致的多个症状） +- 研究 Issue 也遵循正常的 PR + CI 流程（但可以包含调试代码、日志等） +- 不确定的改动宁可开研究 Issue，也不要直接关原 Issue ## agent_poller 命令速查 @@ -317,9 +359,61 @@ QE-Agent 开 Issue (qe-feedback / bug / ci-failure) - [ ] **CI**：`agent_poller.py --action pr-status` 确认 CI 通过 - [ ] **合并**：`agent_poller.py --action merge-pr` 合并 PR - [ ] **验证**：用真实输入文档实际运行 pipeline，确认功能生效（非 dry-run） -- [ ] **关闭**：验证通过后 `--action close-issue` +- [ ] **关闭**：验证通过后 `--action close-issue`（关闭 comment 必须符合下方"Issue 关闭规范"） - [ ] **复盘**：`agent_poller.py --action lifecycle` 确认全流程完成 +## Issue 关闭规范 + +**关闭 Issue 时的 comment 必须包含以下四个要素，缺一不可：** + +``` +## 问题 +<一句话描述 Issue 的症状> + +## 根因 +<明确指出导致问题的根本原因，不是表面现象> + +## 修复 +<这个改动如何消除根因？为什么这个方案是正确的？> + +## 验证 +<具体的验证步骤和结果，不是空泛的"已通过"> +``` + +**禁止的关闭 comment：** +- "PR merged, 验证通过" — 没有说明根因和验证方式 +- "自行验证通过，变更已合入 main" — 没有说明验证了什么 +- 任何缺少上述四个要素的关闭 comment + +**示例（正确）：** +``` +## 问题 +_measure_coverage 将 0/0 维度 rate 算作 0%，拉低 overall 均值。 + +## 根因 +`0 / max(0, 1) = 0%`，diagram 维度无内容时 rate 为 0% 并参与均分。 + +## 修复 +引入 _safe_rate()：total=0 时 rate=1.0。overall 均分排除 total=0 的维度。 + +## 验证 +- pytest: 102 passed, 13 skipped +- test_layer_b_coverage: PASSED, overall 57.4%→86.1% +- 命令行确认: Section 100% + Table 72.2% → Overall 86.1% +``` + +## 禁止模式 + +以下行为模式被明确禁止。发现自己在做以下任何一件事，立即停止： + +| 禁止模式 | 为什么禁止 | 正确做法 | +|----------|-----------|----------| +| 单行改动 → 关 Issue → 重开 → 再改 的循环 | 说明根因没找到，在试错 | 开研究 Issue | +| 不跑 pipeline 就关质量级 Issue | 无法证明修复有效 | 跑 pipeline + e2e，或 Issue 保持 open | +| 关闭 comment 不写根因 | 无法判断修复是否正确 | 按 Issue 关闭规范写 | +| 对同一 Issue 连续提交 3 个以上 PR | 说明方向不对 | 暂停，开研究 Issue | +| pytest 绿了就关 Issue | pytest 只保证无回归，不保证功能正确 | 代码级可关，质量级必须 pipeline | + ## Session 收尾 **当 session 即将结束时（用户要求结束、或完成当前轮询周期后准备退出），执行以下收尾动作：** -- 2.52.0