review-elixir

Elixir コードレビュー

引数

• --parallel：エージェントがサブエージェントに対応している場合は、技術領域ごとに専門のサブエージェントを 1 つずつ割り当てます（それ以外の場合は、同じ出力で順次レビューします）
• パス：対象ディレクトリ（デフォルト：現在の作業ディレクトリ）

必須ゲート

出力に Issues を記載する前に、順番に完了してください（対象範囲が空でも構いませんが、指摘を捏造してはいけません）。

1. スコープゲート： レビュー対象の .ex／.exs／.heex パスが明示的に一覧化されています（Step 1 またはユーザー指定のパスから）。合格条件： 一覧を出力するか、「対象範囲に Elixir ファイルはありません」と出力します。その場合は Issues を記載せずに終了します。
2. リンターゲート（スタイル）： この Mix プロジェクトに対して Step 2 のコマンドを実行し、スキップしたツールがあれば 1 行で記載します（例：.credo.exs がない）。合格条件： プロジェクトのフォーマッター／リンターが合格と判定した箇所について、スタイルの問題を指摘しません。
3. プロトコルゲート： Step 6 より前に review-verification-protocol を読み込みます。合格条件： 少なくとも 1 つの指摘について、チェックリストに照らして確認します（該当項目を Review Summary または最初の Critical／Major の注記に記載します）。
4. エビデンスゲート（Critical／Major）： Critical または Major の項目ごとに、FILE:LINE のファイルを周辺の文脈全体も含めて再度読みます（差分の該当箇所だけでは不十分です）。合格条件： Issue の説明が、その位置で確認できるコードと一致しています。

Step 1：変更されたファイルを特定する

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

Step 2：リンター／フォーマッターの状態を確認する

重要：スタイル上の問題を指摘する前に、必ずプロジェクトのリンターを実行してください。

# 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

ルール：

• 特定のルールについてリンターが合格と判定した場合、その問題を手動で指摘してはいけません
• スタイルルールについては、リンターの設定を優先します
• リンターで検出できない問題（セマンティックな問題、アーキテクチャ上の問題など）のみ指摘します

Step 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$'

Step 4：検証プロトコルを読み込む

review-verification-protocol スキルを読み込み、レビュー中はチェックリストを意識してください。

Step 5：スキルを読み込む

該当するスキルを以下から読み込みます（SKILL.md を読み、そのルールを適用してください）。

必ず読み込む：

• elixir-code-review

検出結果に応じて読み込む：

条件	スキル
Phoenix が検出された	phoenix-code-review
LiveView が検出された	liveview-code-review
パフォーマンス重視のレビューが指定された	elixir-performance-review
セキュリティ重視のレビューが指定された	elixir-security-review
テストファイルが変更された	exunit-code-review

Step 6：レビュー

エージェントがサブエージェントに対応していて、かつ --parallel が設定されている場合は、技術領域ごとにサブエージェントを 1 つずつ並行して割り当てます。それ以外の場合は順次実行します。どちらの場合も出力は同一です。

順次実行（デフォルト）：

1. 該当するスキルを読み込む
2. まず Elixir の品質に関する問題をレビューする
3. Phoenix のパターンをレビューする（検出された場合）
4. LiveView のパターンをレビューする（検出された場合）
5. 検出された技術領域をレビューする
6. 指摘を統合する

並行実行（サブエージェントを利用でき、--parallel が設定されている場合）：

1. すべての技術を先に検出する
2. 技術領域ごとにサブエージェントを 1 つずつ割り当てる
3. 各サブエージェントがスキルを読み込み、担当領域をレビューする
4. すべてのサブエージェントの完了を待つ
5. 指摘を統合する

問題を指摘する前に

1. プロジェクトの規約を確認する（例：AGENTS.md または CLAUDE.md に記載された意図的なパターン）
2. 指摘箇所周辺のコードコメントを確認する（「intentional」、「optimization」、「NOTE:」など）
3. コードパスを追跡する（カバレッジ不足を指摘する前に確認する）
4. フレームワーク固有の慣習を考慮する — 一般的には問題に見えるものでも、Elixir／Phoenix では適切な場合があります

ステップ 7：指摘事項の検証

指摘事項を最終確定する前に、必須ゲートの項目 2～4 を満たしてください。問題を報告する前に、以下を実施してください。

1. 実際のコードを読み直す（差分の前後だけで済ませない）
2. 「未使用」とする場合：すべての参照を検索しましたか？
3. 「不足」とする場合：フレームワークや親側での処理を確認しましたか？
4. 構文上の問題の場合：現行バージョンのドキュメントで確認しましたか？
5. 実際の問題ではなく、スタイル上の好みにすぎない指摘は削除する

ステップ 8：レビューの収束

1 回のレビューでの完全性

すべてのカテゴリ（スタイル、ロジック、型、テスト、セキュリティ、パフォーマンス）にわたるすべての問題を、1 回のレビューで報告しなければなりません。 後のラウンドに問題を持ち越さないでください。

指摘事項を提出する前に、以下を自問してください。

• 「推奨した修正がすべて適用された場合、修正後のコードに新たな問題が見つかりますか？」
• 「修正時に、新しいコード（テスト、型、モジュール）を追加するよう求めており、そのコード自体にもレビューが必要になりますか？」

どちらかが「はい」の場合、作者が一度にすべて対応できるよう、予想される後続の問題も今回のレビューに含めてください。

スコープのルール

• 差分内のコードと、それに直接関連する既存コードのみをレビューする
• 差分以前には存在しなかった新機能、テストインフラ、アーキテクチャの変更を要求しない
• テストカバレッジが不足している場合は、1 件の軽微な問題として「X、Y、Z に対するテストカバレッジが不足しています」と指摘する。モックライブラリ、動作の切り出し、依存性注入のパターンなど、大幅な新規コードを導入する実装の詳細は指定しない
• 型仕様、ドキュメント、命名の問題は、公開 API の契約に影響しない限り軽微な問題とする
• 新しい依存関係（Mox、テストライブラリ、リンタープラグインなど）の追加を要求しない

修正の複雑さの予算

既存コードへの修正は、規模にかかわらず、実際の重大度に応じて指摘してください。

ただし、差分以前には存在しなかった新規コードの追加要求は、情報提供として分類しなければなりません。

• 新しい依存関係（Mox、リンタープラグインなど）の追加
• 新しいモジュール、ファイル、テストスイートの新設
• 新たな振る舞い、プロトコル、抽象化の切り出し

これらは、今後の作業として作者が検討するための改善提案であり、レビューをブロックするものではありません。

イテレーションの方針

修正適用後の再レビューの場合：

• 以前に指摘した問題が正しく修正されたかどうかだけを確認する
• 以前の指摘と無関係な新たな指摘を追加しない
• 修正されていない軽微な問題や、あれば望ましい程度の問題は受け入れ、再度指摘しない
• 再レビューの目的は新たな問題の発見ではなく、修正の検証です

出力形式

## 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 を明確に分ける
• 実際の重大度に応じて分類する
• 修正後に検証を実行する
• すべての問題を 1 回のレビューで報告し、後のイテレーションに持ち越さない
• 再レビューでは以前の修正のみを検証し、新たな問題を探さない
• 新規コード（新しいモジュール、依存関係、テストスイート）の追加要求は、ブロッキングではなく情報提供とする
• 判定では軽微な問題と情報提供項目を無視し、重大および主要な問題のみが承認を妨げる