review-elixir

Elixir 代码审查

参数

• --parallel：如果 Agent 支持子 Agent，则按技术领域分别派发一个专用子 Agent（否则按顺序审查，输出相同）
• 路径：目标目录（默认为当前工作目录）

硬性门槛

在输出中编写 问题 前，必须按顺序完成以下步骤（审查范围为空也可以；不得捏造发现）。

1. 范围门槛： 明确列出待审查的 .ex/.exs/.heex 路径（来自步骤 1 或用户指定的路径）。通过条件： 打印路径列表，或打印“范围内没有 Elixir 文件”——然后停止，不输出问题。
2. Linter 门槛（风格）： 已针对这个 Mix 项目运行步骤 2 中的命令；跳过的工具用一行说明（例如，没有 .credo.exs）。通过条件： 不得报告项目格式化程序或 linter 已通过的代码行上的风格问题。
3. 协议门槛： 在步骤 6 前加载 review-verification-protocol。通过条件： 至少有一项报告的问题已根据该清单核查（在审查摘要或第一条严重/主要问题说明中指出具体条目）。
4. 证据门槛（严重/主要）： 对每项严重或主要问题，重新阅读 FILE:LINE 处的文件内容（包括完整上下文，不仅是 diff 代码块）。通过条件： 问题描述与该位置可观察到的代码相符。

步骤 1：识别变更文件

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

步骤 2：验证 Linter/格式化程序状态

重要： 标记任何风格问题前，必须先运行项目的 linter。

# Check formatting
mix format --check-formatted

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

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

规则：

• 如果 linter 通过了某条具体规则，不得手动标记该问题
• linter 配置是风格规则的权威依据
• 仅标记 linter 无法检测的问题（语义问题、架构问题）

步骤 3：检测技术领域

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

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

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

# Check for test files
git diff --name-only $(git merge-base HEAD main)..HEAD | grep -E '_test\.exs$'

步骤 4：加载验证协议

加载 review-verification-protocol 技能，并在整个审查过程中牢记其清单。

步骤 5：加载技能

加载下列适用技能（阅读其 SKILL.md 并遵循其中的规则）。

始终加载：

• elixir-code-review

根据检测结果有条件地加载：

条件	技能
检测到 Phoenix	phoenix-code-review
检测到 LiveView	liveview-code-review
请求重点关注性能	elixir-performance-review
请求重点关注安全性	elixir-security-review
测试文件有变更	exunit-code-review

步骤 6：审查

如果 Agent 支持子 Agent（且设置了 --parallel），则并行派发一个子 Agent 负责一个技术领域；否则按顺序审查。两种方式的输出相同。

顺序审查（默认）：

1. 加载适用技能
2. 优先审查 Elixir 质量问题
3. 审查 Phoenix 模式（如果检测到）
4. 审查 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：验证发现

在最终确定问题前，先满足 硬性门槛 第 2–4 项。报告任何问题前：

1. 重新阅读实际代码（不只是差异上下文）
2. 对于“未使用”的说法——你是否搜索了所有引用？
3. 对于“缺失”的说法——你是否检查了框架／父级处理逻辑？
4. 对于语法问题——你是否对照当前版本的文档进行了验证？
5. 删除任何属于风格偏好、而非实际问题的发现

步骤 8：评审收敛

单轮完整性

你 MUST 在单轮评审中报告所有类别（风格、逻辑、类型、测试、安全、性能）中的所有问题。不要把问题留到后续轮次。

提交发现前，先问自己：

• “如果应用了我建议的所有修复，我会在修复后的代码中发现新问题吗？”
• “我是否要求编写新的代码（测试、类型、模块），而这些代码本身也需要评审？”

如果任一答案为是：现在就在本轮评审中纳入预计会出现的后续问题，以便作者一次性处理所有问题。

范围规则

• 仅评审差异中的代码及其直接相关的现有代码
• 不要要求新增差异前不存在的功能、测试基础设施或架构变更
• 如果缺少测试覆盖，将其作为一条 Minor 问题提出（“缺少对 X、Y、Z 的测试覆盖”）——不要指定模拟库、行为提取或依赖注入模式等会引入大量新代码的实现细节
• 类型规范、文档和命名问题属于 Minor，除非它们影响公共 API 契约
• 不要要求添加新依赖（例如 Mox、测试库、linter 插件）

修复复杂度预算

无论修复规模多大，都应按其实际严重程度指出对现有代码的修复要求。

但是，对于差异前不存在的全新代码的要求必须归类为 Informational：

• 添加新依赖（例如 Mox、linter 插件）
• 创建全新模块、文件或测试套件
• 提取新的行为、协议或抽象

这些是供作者在未来工作中考虑的改进建议，不是评审阻塞项。

迭代策略

如果这是修复后的重新评审：

• 仅验证之前指出的问题是否已正确解决
• 不要提出与之前问题无关的新发现
• 接受尚未修复的 Minor／Nice-to-Have 问题，不要再次提出
• 重新评审的目标是验证，而非发现

输出格式

## Review Summary

[1-2 sentence overview of findings]

## Issues

### Critical (Blocking)

1. [FILE:LINE] ISSUE_TITLE
   - Issue: Description of what's wrong
   - Why: Why this matters (bug, type safety, security)
   - Fix: Specific recommended 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] Pattern description (preserve this)

## Verdict

Ready: Yes | No | With fixes 1-N (Critical/Major only; Minor items are acceptable)
Rationale: [1-2 sentences]

修复后验证

应用修复后，执行与步骤 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
• 按实际严重程度分类
• 修复后运行验证
• 在单轮评审中报告所有问题——不要把发现留到后续迭代
• 重新评审仅验证先前的修复——不进行新的发现
• 对全新代码（新模块、依赖、测试套件）的要求属于 Informational，不构成阻塞
• Verdict 不考虑 Minor 和 Informational 项——只有 Critical 和 Major 会阻止批准