Elixir 代码审查

参数

• --parallel：若 agent 支持子 agent，则为每个技术领域分发一个专用子 agent（否则审查将顺序执行，输出结果完全相同）
• 路径：目标目录（默认为当前工作目录）

硬性校验门（Hard gates）

在输出中撰写 Issues 前，必须按顺序完成以下全部校验（允许作用域为空；禁止虚构发现）。

1. 作用域校验门：你已明确列出本次审查所涵盖的 .ex/.exs/.heex 文件路径（来自步骤 1 或用户指定路径）。通过条件：打印出该文件列表，或输出 “No Elixir files in scope” —— 此时立即终止，不报告任何 Issues。
2. 检查器校验门（风格）：步骤 2 中的命令已在此 Mix 项目中运行；跳过的工具需在一行内注明（例如：未找到 .credo.exs）。通过条件：不得对项目格式化器/检查器已在该行通过的风格问题进行报告。
3. 协议校验门：review-verification-protocol 必须在步骤 6 之前加载。通过条件：至少有一项报告的发现已对照该清单完成核验（需在 Review Summary 或首个 Critical/Major 条目中明确指出对应条目编号）。
4. 证据校验门（Critical/Major）：对每一项 Critical 或 Major 问题，你需重新阅读 FILE:LINE 处的原始文件（含完整上下文，而非仅 diff 片段）。通过条件：Issue 描述必须与该位置实际可观察到的代码一致。

步骤 1：识别变更文件

git diff --name-only $(git merge-base HEAD main)..HEAD | grep -E '.ex$|.exs$|.heex$'

步骤 2：验证检查器/格式化器状态

CRITICAL：在标记任何风格问题前，必须先运行项目检查器。

# 检查格式化
mix format --check-formatted

# 若存在则检查 Credo
if [ -f ".credo.exs" ] || grep -q ":credo" mix.exs 2>/dev/null; then
    mix credo --strict
fi

# 若已配置则检查 Dialyzer
if grep -q ":dialyxir" mix.exs 2>/dev/null; then
    mix dialyzer --format short
fi

规则：

• 若某条规则已通过检查器校验，则禁止手动标记该问题
• 检查器配置对风格规则具有最终解释权
• 仅标记检查器无法检测的问题（语义问题、架构问题等）

步骤 3：识别技术栈

# 检测 Phoenix
grep -r "use Phoenix|Phoenix.Router|Phoenix.Controller" --include="*.ex" -l | head -3

# 检测 LiveView
grep -r "use Phoenix.LiveView|Phoenix.LiveComponent|~H" --include="*.ex" -l | head -3

# 检测 Oban
grep -r "use Oban.Worker|Oban.insert" --include="*.ex" -l | head -3

# 检查测试文件变更
git diff --name-only $(git merge-base HEAD main)..HEAD | grep -E '_test.exs$'

步骤 4：加载验证协议

加载 review-verification-protocol 技能，并在整个审查过程中持续参考其检查清单。

步骤 5：加载技能（Skills）

根据适用性加载下方各项技能（需通读其 SKILL.md 并应用其中规则）。

始终加载：

• elixir-code-review

按检测结果条件加载：

步骤 6：执行审查

若 agent 支持子 agent（且设置了 --parallel），则并行分发一个子 agent 至每个技术领域；否则按顺序执行。两种方式生成的输出完全一致。

顺序执行（默认）：

1. 加载适用技能
2. 优先审查 Elixir 质量问题
3. 若检测到 Phoenix，则审查 Phoenix 模式
4. 若检测到 LiveView，则审查 LiveView 模式
5. 审查所有已识别的技术领域
6. 汇总全部发现

并行执行（当子 agent 可用且设置了 --parallel）：

1. 预先识别全部技术栈
2. 为每个技术领域分发一个子 agent
3. 各子 agent 加载对应技能并审查其专属领域
4. 等待所有子 agent 完成
5. 汇总全部发现

标记问题前须执行

1. 核查项目约定（如 AGENTS.md 或 CLAUDE.md）中是否记载了有意为之的模式
2. 核查问题附近代码注释，寻找 “intentional”、“optimization” 或 “NOTE:” 等标识
3. 追溯代码执行路径，再判断是否存在覆盖缺失
4. 考虑框架惯用法——表面上看似错误的写法，在 Elixir/Phoenix 场景下可能完全合理

步骤 7：验证发现项

在最终确定 Issues 前，必须满足 硬性校验门 中第 2–4 项。在报告任一问题前，请确认：

1. 重读实际代码（而不仅是 diff 上下文）
2. 针对“未使用（unused）”类主张——是否已搜索全部引用？
3. 针对“缺失（missing）”类主张——是否已检查框架/父级处理逻辑？
4. 针对语法类问题——是否已对照当前版本文档验证？
5. 移除所有仅为风格偏好、而非实质问题的发现项

步骤 8：审查收敛性

单次审查完整性

你必须在**单次审查中**报告所有类别（风格、逻辑、类型、测试、安全、性能）下的全部问题。禁止将问题保留至后续轮次。

提交发现前，请自问：

• “若作者采纳我全部建议修复，我在修复后的代码中是否会发现**新问题**？”
• “我是否要求新增代码（如测试、类型定义、模块）？这些新增内容本身是否也需要审查？”

若任一问题答案为“是”：请**立即在本次审查中包含这些预判的下游问题**，以便作者一次性解决全部事项。

作用域规则

• 仅审查 diff 中的代码及与其直接相关的既有代码
• 禁止要求新增功能、测试基础设施或 diff 前不存在的架构变更
• 若测试覆盖率缺失，仅以一项 Minor 问题形式标记（例如：“Missing test coverage for X, Y, Z”）——禁止指定实现细节（如 mock 库选型、behaviour 提取、依赖注入模式等，因其将引入大量新代码）
• typespecs、文档和命名问题均为 Minor 级别，除非其影响公共 API 合约
• 禁止要求新增依赖（如 Mox、测试库、检查器插件）

修复复杂度预算

对既有代码的修复，应按其真实严重性标注等级，不受代码修改量影响。

但对 diff 前完全不存在的净新增代码 的请求，必须归类为 Informational：

• 新增依赖（如 Mox、检查器插件）
• 新建模块、文件或测试套件
• 提取新的 behaviour、protocol 或抽象层

此类属于供作者未来考虑的改进建议，而非审查阻塞项。

迭代策略

若本次为修复后的复审（re-review）：

• 仅验证此前标记的问题是否已正确修复
• 禁止引入与上一轮审查无关的新发现
• 接受未修复的 Minor/Nice-to-Have 问题——无需重复标记
• 复审的目标是 **VERIFICATION（验证）**，而非 **discovery（发现）**

输出格式

## Review Summary

[1–2 句对整体发现的概述]

## Issues

### Critical (Blocking)

1. [FILE:LINE] ISSUE_TITLE
   - Issue: 问题描述（具体错在哪里）
   - Why: 为何重要（缺陷、类型安全性、安全风险等）
   - Fix: 具体推荐修复方案

### Major (Should Fix)

2. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Minor (Nice to Have)

N. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Informational (For Awareness)

N. [FILE:LINE] SUGGESTION_TITLE
   - Suggestion: ...
   - Rationale: ...

## Good Patterns

- [FILE:LINE] 模式描述（请保留此项）

## Verdict

Ready: Yes | No | With fixes 1-N （仅限 Critical/Major；Minor 项可接受）
Rationale: [1–2 句说明]

修复后验证

修复应用后，需运行与步骤 2 相同的检查，随后运行测试：

mix format --check-formatted

if [ -f ".credo.exs" ] || grep -q ":credo" mix.exs 2>/dev/null; then
    mix credo --strict
fi

if grep -q ":dialyxir" mix.exs 2>/dev/null; then
    mix dialyzer --format short
fi

mix test

所有调用的检查项均须通过，方可批准。

规则

• 必须在审查前加载技能（不可事后加载）
• 每个问题须按顺序编号（1、2、3…）
• 每个问题须包含 FILE:LINE 定位
• Issue / Why / Fix 三部分须清晰分隔
• 按实际严重性分类（Critical/Major/Minor/Informational）
• 修复后必须执行验证
• 所有问题须在单次审查中报告——禁止保留至后续轮次
• 复审仅验证此前问题是否修复——禁止新发现
• 对净新增代码（新模块、新依赖、新测试套件）的请求属 Informational 级别，非阻塞项
• Verdict 判定仅依据 Critical 和 Major 项——Minor 与 Informational 不影响批准