code-review

Files (3)

• SKILL.md
• eagle-code-security.md · references/
• eagle-goal-context.md · references/

SKILL.md (first lines)

# 代码审查技能

完成实现后，按顺序执行以下阶段。本技能编排两路并行 Eagle 审查：Eagle 1 检查代码质量与安全，Eagle 2 验证目标与上下文完备性。

---

## Phase 0 — 收集上下文

先读取审查模板，再收集所有上下文。

### 读取模板

```
Read references/eagle-code-security.md
Read references/eagle-goal-context.md
```

> 大文件使用 offset/limit 参数分段读取，Read 输出带行号方便 Eagle 引用。

### 收集 GOAL

提取用户的原始需求。如果多次修正，以**最终确认版本**为准。

### 收集 CONSTRAINTS

整理技术栈约束、架构限制、性能要求、兼容性要求等。

### 获取 diff 基准引用

根据变更状态确定 `{DIFF_BASE}`：

| 场景 | `{DIFF_BASE}` |
|------|---------------|
| 代码未提交（staged 或 unstaged 变更） | `HEAD` |
| 已提交的单笔 commit | `HEAD~1` |
| Feature branch 多笔 commit | `git merge-base HEAD <target>`（target 从对话上下文提取，通常是 `main` 或 `origin/main`） |

### 获取变更文件列表

```bash
git diff --name-only {DIFF_BASE}
```

输出干净的变更路径列表（每行一个文件），可直接用于 git 命令的路径参数。

> 可额外参考 `git diff --stat {DIFF_BASE}` 中的增删行信息编写变更概要。

### 收集变更概要

基于变更文件列表和对话上下文，编写 3-5 句的人类可读变更概要，记录为 `{CHANGE_SUMMARY}`。描述变更目的和影响范围，不包含原始 diff。

例：
```
本次变更为认证模块新增 JWT refresh token 机制。新增了 refresh.ts 文件，修改了 auth.ts 中的 token 验证逻辑。后端新增 /auth/refresh 端点，前端登录流程同步更新以支持 token 自动刷新。
```

### 收集 BACKGROUND

从对话中提取：为什么需要这个变更？关联了哪些系统？是否有讨论过的替代方案？

---

## Phase 1 — 填充模板

对两个模板执行 {占位符} → 实际值的替换。填充完成后，模板即是可直接传给子 agent 的三段式 prompt。

**必须使用模板原文**：Eagle 的 prompt 只能由「读取模板文件全文 → 替换 {占位符}」构造，禁止重写、压缩、摘要或增删模板章节；模板中的 **SUMMARY:** / **CONTEXT:** / **ACCEPTANCE:** 及所有章节标题必须逐字保留。

### 占位符来源映射

| 占位符 | 来源 | 用于 |
|--------|------|------|
| `{GOAL}` | Phase 0 · 收集 GOAL | 两个 Eagle |
| `{CONSTRAINTS}` | Phase 0 · 收集 CONSTRAINTS | Eagle 2 |
| `{CHANGED_FILES}` | Phase 0 · 获取变更文件列表（路径列表） | 两个 Eagle |
| `{DIFF_BASE}` | Phase 0 · 获取 diff 基准引用 | 两个 Eagle |
| `{CHANGE_SUMMARY}` | Phase 0 · 收集变更概要 | 两个 Eagle |
| `{BACKGROUND}` | Phase 0 · 收集 BACKGROUND | 两个 Eagle |

---

## Phase 2 — 并行启动两路 Eagle

**同一轮次同时启动，不允许串行。**

### Eagle 1 — 代码质量与安全审查

启动 Eagle 1 子 agent，传入填充后的 `eagle-code-security` 模板作为 prompt。在后台并行运行，不等待结果。Eagle 1 半自主，可执行只读命令（git diff、Read、git blame）获取代码，不修改任何文件。

### Eagle 2 — 目标与上下文完备性审查

同一轮次，启动 Eagle 2 子 agent，传入填充后的 `eagle-goal-context` 模板作为 prompt。同样在后台并行运行。Eagle 2 半自主，可执行只读命令（git diff、Read、git log、git blame、gh pr list、gh issue list）搜索额外上下文。

---

## Phase 3 — 收集结果

等待两个 Eagle 完成后，记录各自 verdict。

### 结果分类

| 状态 | 含义 |
|------|------|
| PASS | 审查通过，无可报告问题 |
| FAIL | 发现至少一个 Must Fix 问题 |
| INCONCLUSIVE | Eagle 无法形成确定结论（上下文不足、歧义、超时等） |

### INCONCLUSIVE 重试逻辑

如果任一 Eagle 返回 INCONCLUSIVE，执行一次简化重试：

1. 构造简化版 prompt：只包含 `{CHANGE_SUMMARY}`, `{CHANGED_FILES}`, `{DIFF_BASE}` 和 `{GOAL}`，去掉其他上下文
2. 指示 Eagle 聚焦与目标相关的特定文件/函数，而非自由探索
3. 重新启动同一 Eagle，传入简化版 prompt，仍然后台并行运行
4. 如果重试后仍然 INCONCLUSIVE → 保持为 INCONCLUSIVE，**继续执行不阻塞**

### 注意事项

- 两个 Eagle 各自输出独立 verdict

From 418-teapot/ZooKeeper, MIT.

More from 418-teapot/ZooKeeper