review-llm-artifacts

LLM アーティファクトのレビュー

LLM コーディングエージェントが残す一般的なアーティファクト（過剰な抽象化、デッドコード、テストにおける DRY 違反、冗長なコメント、防御的な処理の過剰実装）を検出します。

ハードゲート（順番どおり）

各合格条件が客観的に満たされた場合にのみ先へ進みます（アーティファクトがあるにもかかわらず「レビュー完了」とするのを防ぎます）。

ゲート	合格条件
G1 — スコープ	ファイルリストが空でないか、Step 1 のメッセージだけを出力して終了していること。scope が all または changed に設定されていること。
G2 — 4 つのカテゴリ	テスト、デッドコード、抽象化、スタイルの各カテゴリがレビューされていること（サポートされている場合は 4 つのサブエージェントを並列実行するか、同じカテゴリを網羅する 4 つの順次パスを実行します）。いずれかのカテゴリが完了していない場合は停止してください。全カテゴリを完了したと示す JSON や要約を書いてはいけません。
G3 — 要約の前に JSON	Step 6 の Markdown より前に .beagle/llm-artifacts-review.json が存在し、有効な JSON であること。
G4 — 整合性	実行完了として扱う前に Step 7 のチェックに合格していること。

引数

フラグと省略可能なパスを $ARGUMENTS から解析します。

フラグ	効果
(デフォルト)	変更ファイルのスコープ — git merge-base HEAD main 以降に変更されたファイルのみ（PR 形式のスコープ）
--all	プロジェクト全体のスキャン — 対象パス以下の条件に一致するすべてのソースファイル
--parallel	サブエージェントがサポートされている場合、並列実行を強制します（対象ファイルが 4 件以上の場合はデフォルトで有効）
パス	スキャンするルートディレクトリ（デフォルト：現在の作業ディレクトリ）

Step 1: スコープの決定

A. 変更ファイルのみ（デフォルト）：

ベース参照を明示的に解決し、見つからない場合は明確にエラーにしてください。git merge-base の呼び出しを || true で囲んではいけません。これにより main／master の参照が見つからない場合にエラーが握りつぶされ、origin/main しかないリポジトリや master を使うリポジトリで「スキャンするファイルがありません」と報告されるためです。ベース参照が見つからない場合は、暗黙にフォールバックせず、代わりに --all を指定するようユーザーに案内してください。

BASE=$(for ref in main origin/main master origin/master; do
         git rev-parse --verify "$ref" >/dev/null 2>&1 && { echo "$ref"; break; }
       done)
if [ -z "$BASE" ]; then
  echo "error: no main/master ref found (checked main, origin/main, master, origin/master). Pass --all for a full-project scan." >&2
  exit 1
fi
MERGE_BASE=$(git merge-base HEAD "$BASE") || {
  echo "error: git merge-base HEAD $BASE failed." >&2
  exit 1
}
git diff --name-only "$MERGE_BASE..HEAD" | grep -E '\.(py|ts|tsx|js|jsx|go|rs|java|rb|swift|kt)$' || true

（grep の末尾にある || true は意図的なものです。ソースファイルが 0 件見つかるのは、ベース参照の解決に失敗した場合とは異なり、正当な空のスコープ結果です。）

B. プロジェクト全体（--all）：

TARGET（デフォルトは .）からソースファイルを一覧表示し、除外する依存関係／ビルド用ディレクトリをプルーニングして、find がその中に降りていかないようにします。! -path "*/foo/*" は出力をフィルタリングするだけで、find はディレクトリを探索し続けます（大規模な node_modules、target などでは、数分間の無駄な I/O が発生します）。代わりに -prune を使用してください。

find "$TARGET" \
  \( -type d \( \
       -name node_modules -o -name .git -o -name vendor -o -name __pycache__ \
    -o -name .venv        -o -name venv -o -name dist   -o -name build \
    -o -name target       -o -name .next -o -name coverage -o -name .turbo \
  \) -prune \) -o \
  \( -type f \( \
       -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \
    -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.rb" \
    -o -name "*.swift" -o -name "*.kt" \
  \) -print \)

大規模なリポジトリ： --all では非常に多くのファイルが一覧表示される場合があります。ファイル数が 400 を超えた場合は警告し、範囲を絞るよう案内してください。TARGET としてサブディレクトリを指定するか、--all を外してデフォルトの変更ファイルスコープに戻すよう提案します。ユーザーが明示的にキャンセルしない限り、処理は続行してください。この警告は、PR の差分によってすでに範囲が限定されているデフォルトの変更ファイルスコープでは表示されません。

ファイルが見つからない場合は、次のメッセージを出力して終了します。

No files to scan. Check the path, branch, or pass --all for a full-project scan.

レポートの scope を設定します。--all の場合は "all"、デフォルトの変更ファイルスコープの場合は "changed" にします。

Step 2: 言語の検出

ファイルリストから一意なファイル拡張子を抽出します。

echo "$FILES" | sed 's/.*\.//' | sort -u

レポート用に拡張子を言語名に対応付けます。

• .py -> Python
• .ts, .tsx -> TypeScript
• .js, .jsx -> JavaScript
• .go -> Go
• .rs -> Rust
• .java -> Java
• .rb -> Ruby
• .swift -> Swift
• .kt -> Kotlin

Step 3: 4 つのカテゴリのレビュー

以下の 4 つのカテゴリすべてを網羅してください。エージェントがサブエージェントをサポートしており、対象ファイル数が 4 件以上（または --parallel が指定されている）場合は、カテゴリごとに 1 つのサブエージェントを割り当てて並列実行します。それ以外の場合は、同じ指摘事項をまとめられるよう、4 つのカテゴリを自分で順次レビューします。いずれの場合も、次の手順に従ってください。

1. llm-artifacts-detection スキルを読み込みます
2. 各カテゴリをレビューします（並列の場合はサブエージェントごとに 1 カテゴリ、順次の場合は一度に 1 カテゴリ）
3. 以下の構造化形式で指摘事項を収集します

カテゴリ 1：テスト

焦点： LLM による生成に起因するテストのアンチパターン

• DRY 原則への違反（セットアップコードの繰り返し、アサーションの重複）
• アプリケーションロジックではなく、テストライブラリ／フレームワークのコードをテストしている
• モックの境界が不適切（モックの使いすぎ、または不足）
• 実装の詳細を説明する、冗長すぎるテスト名
• 実装をそのままなぞるだけのテスト

カテゴリ 2：デッドコード

焦点： 未使用または古くなったコード

• 未使用のインポート、変数、関数、クラス
• 解決されるべき TODO／FIXME コメント
• 削除済み機能の後方互換性コード
• 削除されたコードに対する孤立したテストファイル
• コメントアウトされたコードブロック
• 常にオン／オフになっている機能フラグ

カテゴリ 3：抽象化

焦点： 過剰設計のパターン

• 不要な抽象化レイヤー（実装が1つしかないインターフェース）
• コピー＆ペーストによる乖離（類似コードが少しずつ異なる状態になっている）
• 過剰な設定（変更されることのない設定項目）
• 時期尚早な汎用化
• 単純なオブジェクト生成に対する Factory／Builder パターン
• 深い継承階層

カテゴリ 4：スタイル

焦点： 冗長または過剰に防御的なパターン

• 自明なコードを説明する冗長なコメント
• 過剰な防御的処理（null にならない値に対する null チェック）
• 不要な型ヒント（型が明らかな動的言語）
• 明示しすぎたエラーメッセージ
• 冗長なログ出力
• ドキュメントがあるのに、コード自体でも説明している

ステップ 4：検出結果を統合する

前提条件： G2 を満たしていること（4 つすべてのカテゴリレビューが正常に完了している）。

4 つすべてのカテゴリレビューが完了したら（サブエージェントによる並列実行、または順次実行）、次の手順を行います。

1. すべての検出結果を1つのリストにまとめます
2. 一意の ID を割り当てます（1、2、3...）
3. 表示用にカテゴリごとにグループ化します

書き込み前の照合（誤情報の生成防止）： JSON に書き込む検出結果はすべて、ブランチ名、ディレクトリ、自身の推論ではなく、カテゴリレビューの [FILE:LINE] ISSUE_TITLE 出力に基づいていなければなりません。ID を割り当てた後、統合した表 — id | category | file:line | description — を出力し、各行が特定のカテゴリレビューの結果に基づいていることを確認します。どのカテゴリレビューにも報告されていない検出結果を追加してはいけません。

ID の固定： ID は欠番や重複のない連続した 1..N とします。この 1..N の集合が固定 ID 集合となり、後続のスキル（verify-llm-artifacts、fix-llm-artifacts）はこれに1対1で対応します。summary.total は N と等しくなければならず、summary.by_category の件数の合計も N でなければなりません。JSON を書き込む前に、ID 集合を明示します。

ステップ 5：JSON レポートを書き込む

.beagle ディレクトリが存在しない場合は作成します。

mkdir -p .beagle

検出結果を .beagle/llm-artifacts-review.json に書き込みます。

{
  "version": "1.0.0",
  "created_at": "2024-01-15T10:30:00Z",
  "git_head": "abc1234",
  "scope": "all" | "changed",
  "target": ".",
  "files_scanned": 42,
  "languages": ["Python", "TypeScript", "Go"],
  "findings": [
    {
      "id": 1,
      "category": "tests" | "dead_code" | "abstraction" | "style",
      "type": "dry_violation" | "unused_import" | "over_abstraction" | "verbose_comment" | "...",
      "file": "src/utils/helper.py",
      "line": 42,
      "description": "Repeated setup code in 5 test functions",
      "suggestion": "Extract to a pytest fixture",
      "risk": "Low" | "Medium" | "High",
      "fix_safety": "Safe" | "Needs review",
      "fix_action": "refactor" | "delete" | "simplify" | "extract"
    }
  ],
  "summary": {
    "total": 15,
    "by_category": {
      "tests": 4,
      "dead_code": 5,
      "abstraction": 3,
      "style": 3
    },
    "by_risk": {
      "High": 2,
      "Medium": 8,
      "Low": 5
    },
    "by_fix_safety": {
      "Safe": 10,
      "Needs review": 5
    }
  }
}

ステップ 6：概要を表示する

前提条件： G3 を満たしていること（JSON がディスク上にあり、解析可能である）。

## LLM Artifacts Review

**Scope:** Changed files since merge-base with main | Entire project under `<path>` (when `--all`)
**Files scanned:** 42
**Languages:** Python, TypeScript, Go

### Findings by Category
...
### Summary Table
...
### Next Steps

- Run the [verify-llm-artifacts](../verify-llm-artifacts/SKILL.md) skill to confirm findings and drop false positives before fixing.
- Run the [fix-llm-artifacts](../fix-llm-artifacts/SKILL.md) skill after verification (or to preview safe-only fixes).
- Review the JSON report at `.beagle/llm-artifacts-review.json`

ステップ 7：検証（レポートの整合性）

完了する前に、レビューが正しく実行されたことを確認します。

1. JSON の妥当性： .beagle/llm-artifacts-review.json が存在し、解析可能であることを確認します
2. カテゴリの網羅性： 4 つすべてのカテゴリレビューがエラーなく完了していることを確認します（サブエージェントによる並列実行、または順次実行）
3. Git HEAD の記録： レポートの git_head フィールドが空でないことを確認します
4. 古さの確認： 以前のレポートがある場合は、保存された git_head と現在の HEAD を比較し、異なっていれば警告します
5. ID と件数の整合性： 検出結果の ID が連続した 1..N であり、summary.total == N で、summary.by_category の合計が N であることを確認します。不一致は検出結果の追加、欠落、重複を意味します。完了前に修正してください。

python3 -c "import json; json.load(open('.beagle/llm-artifacts-review.json'))" 2>/dev/null && echo "✓ Valid JSON" || echo "✗ Invalid JSON"

python3 - <<'PY'
import json
r = json.load(open('.beagle/llm-artifacts-review.json'))
ids = [x['id'] for x in r['findings']]
n = len(ids)
ok = ids == list(range(1, n + 1)) and r['summary']['total'] == n \
     and sum(r['summary']['by_category'].values()) == n
print("✓ ids 1..N and counts consistent" if ok else f"✗ id/count mismatch: ids={ids} total={r['summary']['total']}")
PY

STORED_HEAD=$(jq -r '.git_head' .beagle/llm-artifacts-review.json 2>/dev/null)
CURRENT_HEAD=$(git rev-parse --short HEAD)
if [ "$STORED_HEAD" != "$CURRENT_HEAD" ]; then
  echo "⚠️ Report was generated on $STORED_HEAD, current HEAD is $CURRENT_HEAD"
fi

検証に失敗した場合は、エラーを報告し、続行しないでください。

検出結果ごとの検証（JSON 構文ではなく、精度の検証）は別のスキルです。verify-llm-artifacts — 大量削除や、リスクの高い項目に対する --fix を実行する前に使用してください。

各検出結果の出力形式

[FILE:LINE] **ISSUE_TYPE** (Risk, Fix Safety)
- Description
- Suggestion: Specific fix recommendation

ルール

• ハードゲートの順序に従ってください。G3（Step 6 の前に JSON）を省略しないでください。
• **捏造防止：**すべての指摘は、カテゴリレビューの [FILE:LINE] 出力（Step 4 のエコー）にたどれる必要があります。ブランチ名、ディレクトリ、推論から指摘を捏造しないでください。review-verification-protocol スキル → 捏造防止（ゲート 0）を参照してください。
• まず必ず llm-artifacts-detection スキルを読み込んでください。
• 4 ファイル以上の場合は、（エージェントが対応していれば）4 つのカテゴリレビューに並列サブエージェントを使用してください。それ以外の場合は、順番に実行してください。
• すべての指摘に必ずファイルと行番号の参照を付けてください。
• リスクを正直に分類してください（過大評価も過小評価もしないでください）。
• 変更が機械的で、元に戻せる場合に限り、修正の安全性を「Safe」としてください。
• 必要に応じて .beagle ディレクトリを作成してください。
• 概要を表示する前に JSON レポートを作成してください。
• デフォルトの対象範囲は、main とのマージベース以降の変更ファイルです。プロジェクト全体をスキャンするには --all を渡してください。