oto1720/isomorphism-review

Isomorphism Review Skill

AIコーディングで見落とされやすいパターン逸脱を、「プリンシプル オブ プログラミング」の7設計原則に照らして検出する。

なぜこのレビューが必要か

AIは個々の実装の局所最適に長けているが、コードベース全体のパターンを無意識に壊すことがある。 差分（diff）レビューでは「何が変わったか」しか見えず、「他の箇所がどう書いているか」が見えない。 このスキルは変更コードと類似の既存実装を並べて比較することで、diffでは気づけない逸脱を検出する。

チェックする7つの設計原則

1. 同型原理（形にこだわる）

同じ役割・構造・意味を持つコードは、コードベース全体で同じ「形」で書かれるべき。

| チェック項目 | 検出例 | |------------|--------| | 数値・単位の統一 | モジュール内でms/sec混在、px/rem混在 | | 高階関数の引数数 | コールバックの引数パターンが他と違う | | 関数使用順序 | 初期化→処理→後処理の順序が他と異なる | | 実装スタイル | 他はResultを使うがここだけtry/catch | | 命名パターン | 他はfetchUserだがここだけgetUser | | 戻り値型 | 他はFuture<Result<T>>だがここだけT? |

2. 対称原理（対称性を保つ）

set/get、start/stop、open/closeなど、対になる処理は対称的に実装されるべき。

| チェック項目 | 検出例 | |------------|--------| | 命名の対称性 | setXXXがあるのにgetXXXがない | | 条件と反条件 | if側は処理しているがelse側が欠けている | | 開始と終了 | initがあるのにdisposeがない | | 対称的な構造 | 上りの処理があるのに下りの処理が非対称 |

3. 階層原理（抽象レベルを揃える）

同じ層のクラス・関数は同じ抽象レベルで実装されるべき。

| チェック項目 | 検出例 | |------------|--------| | レイヤー責任 | Repositoryに表示ロジックが混入している | | 抽象レベル | 高レベルAPIと低レベル詳細が同じ関数内に混在 | | 依存方向 | 上位レイヤーが下位の具体実装に依存している |

4. 線形原理（処理フローを直線的に）

処理の流れは追いやすい直線に近い形であるべき。複雑な分岐や特殊ケースが主処理に混入していないか。

| チェック項目 | 検出例 | |------------|--------| | 分岐の複雑さ | ネストが他より深い、ガード節が使われていない | | 特殊ケースの混入 | 例外的処理が主フローに混在している | | 早期リターン | 他は早期リターンで書いているがここは深いネスト |

5. 単純原理（シンプルを保つ）

コードは単純かつ小規模に保つべき。複雑なテクニックの不必要な使用を検出する。

| チェック項目 | 検出例 | |------------|--------| | 過剰な抽象化 | 1回しか使わない抽象クラス・インターフェース | | 複雑なテクニック | 他の実装より難解なアルゴリズムを使っている | | 関数の大きさ | 他の同種の関数より著しく長い |

6. 明証原理（意図を明確に）

コードは誰が読んでも同じ意味に解釈できる明瞭さを持つべき。

| チェック項目 | 検出例 | |------------|--------| | 変数名・関数名 | 他のコードより意図が読み取りにくい命名 | | マジックナンバー | 他は定数化しているがここだけリテラル | | コメントの有無 | 複雑なロジックに説明がなく、他には説明がある |

7. 安全原理（防御的に設計する）

ありえないと思われる条件でも、安全側で処理を実装するべき。

| チェック項目 | 検出例 | |------------|--------| | nullチェック | 他はnull安全だがここはチェックが漏れている | | デフォルト処理 | switch/matchのdefault句が他にはあるがここにはない | | 境界値処理 | 他のメソッドは境界チェックしているがここにはない |

---

実行フロー

Step 1: 変更コードの特定

# 引数がある場合: 指定ファイルを対象にする
# 引数がない場合: git変更を取得
git diff HEAD --name-only 2>/dev/null
git diff --staged --name-only 2>/dev/null

$ARGUMENTS にファイルパスが指定された場合はそのファイルを対象にする。 変更ファイルを読み込み、変更箇所の前後の文脈も含めて把握する。

Step 2: パターン種別を特定

変更された各ファイルから、上記7原則のどの観点でチェックすべきかを判断する。 特に「同型原理」は最も逸脱が起きやすいため、必ず実施する。

Step 3: コードベースから類似実装を検索

各パターン種別に対して、コードベース内の「同じ役割を持つ既存実装」を検索する。

# エラーハンドリングパターン検索
grep -rn "catch\|Result\|Either" --include="*.dart" --include="*.ts" --include="*.go" . | head -40

# 命名パターン検索（例: fetch系のメソッド）
grep -rn "def fetch\|fun fetch\|fetch(" --include="*.py" --include="*.dart" . | head -30

# Repository/Serviceクラスの実装
grep -rn "class.*Repository\|class.*Service" --include="*.dart" --include="*.ts" . | head -20

# 非同期処理パターン
grep -rn "async\|await\|Future\|Promise" --include="*.dart" --include="*.ts" . | head -40

# エラーログ出力パターン
grep -rn "logger\.\|log\.\|print\|debugPrint" --include="*.dart" --include="*.ts" . | head -30

類似実装を3〜5件ピックアップして実際に読み込み、実装パターンを把握する。

Step 4: 比較とレポート生成

docs/reviews/isomorphism_{YYYYMMDD_HHMMSS}.md に出力する。

---

レポートフォーマット

# 設計原則チェックレポート（同型原理ほか）

**実行日時**: {date}
**対象**: {変更ファイル一覧}
**参照した設計原則**: プリンシプル オブ プログラミング（同型・対称・階層・線形・単純・明証・安全）

---

## サマリー

| 重要度 | 件数 |
|--------|------|
| 🔴 Critical（明確なパターン逸脱） | N |
| 🟠 Major（要確認の差異） | N |
| 🟡 Minor（軽微な不統一） | N |
| 🟢 OK（一貫性確認済み） | N |

---

## 検出された問題

### [I-1] {問題のタイトル} — {該当する原理名}

**重要度**: 🔴 / 🟠 / 🟡

**変更箇所**: `path/to/changed/file.dart:42`

**比較対象（既存の類似実装）**:
- `path/to/existing/file_a.dart:15`
- `path/to/existing/file_b.dart:88`

**変更コード**:
```lang
{実際のコードを引用}

既存の標準パターン:

{比較対象のコードを引用}

逸脱の内容: {何がどう違うか、具体的に}

推奨: {どう統一すべきか}

---

一貫性が確認できた箇所

[OK-1] {タイトル} — {原理名}

ファイル: path/to/file.dart {判断根拠}

---

参照した類似実装

| パターン種別 | 参照ファイル | |------------|------------| | エラーハンドリング | services/auth_service.dart:30 | | API呼び出し | repositories/user_repository.dart:55 |

---

アクションアイテム

• [ ] [I-1] {問題} — 既存パターンに合わせて修正推奨
• [ ] [I-2] {問題} — 意図的な変更なら理由をコメントに記載

---

Generated by Claude Code / isomorphism-review skill

---

## 判断上の注意

**意図的な変更 vs 見落とし**を区別する。以下の場合は指摘優先度を下げる:
- コメントで逸脱の理由が明示されている
- 新ライブラリ・新パターンへの移行途中と判断できる文脈がある
- 対象ファイルが明らかに別レイヤー・別ドメインで同型でなくて当然の場合

差分だけでなく変更ファイルの全体コンテキストを読み、変更の意図を理解してから比較すること。

## 出力完了メッセージ

設計原則チェック完了（同型原理ほか）

レポート: docs/reviews/isomorphism_{timestamp}.md

原則違反: N件（Critical: N / Major: N / Minor: N） 一貫性OK: N箇所 参照した類似実装: N件 主な逸脱原則: {同型/対称/階層/...}