# Deep Review

> 設計整合性、セキュリティ、RDD準拠を深掘りチェックする。basic-review後の二次レビュー、sprint→mainマージ前の品質確認で使う。

- Skill: `mae616/deep-review` (Agent Skill)
- Install (CLI): `npx get-skill add mae616/deep-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mae616/deep-review/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mae616 (https://skillmd.com/u/mae616)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/mae616/deep-review

---


# [レビュー] Deep Review

## 入力: $ARGUMENTS
- PR番号（例: `#123` または `123`）
- 省略時: 現在のブランチの差分をmainと比較

---

## 🎯 目的
- **設計品質・セキュリティ・RDD整合**を深くレビューする
- 既存スキルの観点を活用した多角的チェック
- mainマージ前の最終品質ゲート

---

## 実行形態（文脈遮断・必須）

- **実装と同じ文脈でこのレビューを実行しない**（`basic-review` と同じ原則。実装者は自分の設計判断を「意図どおり」としか採点できない）
- 実装ループから呼ばれた場合は、**`code-reviewer` サブエージェント**（`.claude/agents/code-reviewer.md`）に `モード: deep` と PR番号/ブランチ名**だけ**を渡して実行する（文脈遮断≠情報遮断: レビュアーは差分・rdd.md・設計書・SSOTを自分で読む）
- **観点パネル（エージェントチーム）**: 変更が大きい場合（目安: 複数観点にまたがる/10ファイル超）は、観点ごと（セキュリティ/アーキテクチャ/設計品質/表現・描画系…下記「対象範囲」から該当分）に**並列の code-reviewer サブエージェント**へ分担させ、結果を統合する。統合時は重複指摘をまとめ、観点間で矛盾する指摘は両論併記して人間に委ねる
- 人間が実装文脈のないセッションで直接 `/deep-review` を起動した場合は、そのまま実行してよい
- **自律ループの収束判定は Critical / Warning 件数のみ**で行う。所感・総評は人間向けの出力であり、収束判定に影響させない

---

## モード自動判定

対象ファイルのパスで自動判定:
- `doc/**/*.md` → **設計書モード**
- それ以外 → **コードモード**（従来動作）

---

## 対象範囲

### コードモード

| 観点 | 参照スキル | チェック内容 |
|------|-----------|-------------|
| **セキュリティ** | `/security-expert` | OWASP基本、入力検証、認可、秘密情報 |
| **アーキテクチャ** | `/architecture-expert` | 境界、依存方向、責務分離 |
| **設計品質** | `/developer-specialist` | SOLID原則、重複回避、適切な抽象度 |
| **RDD整合** | - | doc/input/rdd.md との整合性 |
| **複雑さ** | - | 認知負荷、循環複雑度、ネスト深度 |
| **アクセシビリティ** | `/accessibility-engineer` | UI変更時のみ |
| **フロントエンド** | `/react`, `/svelte` 等 | 該当技術スタック時のみ |

### 設計書モード

| 観点 | チェック内容 |
|------|-------------|
| **SSOT整合** | rdd.md / architecture.md との整合性 |
| **Mermaid図** | 構文検証、描画可能性、図と説明の整合 |
| **ADR-lite妥当性** | 決定/理由/代替案/トレードオフの記載 |
| **網羅性** | 変更箇所が設計書に反映されているか |
| **構造品質** | 見出し階層、必須セクション、リンク |
| **用語統一** | プロジェクト内での用語の一貫性 |

### Docコメント転記（コード変更時）

PRにコード変更が含まれる場合、設計書の内容をDocコメントに転記:

1. **対応関係の特定**
   - 変更ファイル → 対応する設計書モジュール

2. **転記内容**
   - 責務・設計意図・制約・トレードオフ

3. **転記フォーマット**
   ```typescript
   /**
    * {関数/クラス名}
    *
    * @description {設計書からの責務・意図}
    * @constraint {設計上の制約があれば}
    * @see {設計書へのパス}
    */
   ```

4. **レビュー指摘として提案**
   - Docコメントが設計書と乖離している → Warning
   - Docコメントが無い → Suggestion（転記内容を提示）

---

## 実行手順

### 1. コンテキスト収集

**RDD読み込み:**
```bash
# プロジェクトの制約・技術スタックを確認
cat doc/input/rdd.md
```

**差分取得:**
```bash
# PR番号指定時
gh pr diff {PR_NUMBER}

# 省略時
git diff main...HEAD
```

**変更ファイル一覧:**
```bash
git diff --name-only main...HEAD
```

### 2. 関連スキル特定

変更内容に応じて適用するスキル観点を決定：

| 変更種別 | 適用スキル |
|----------|-----------|
| API/認証 | security-expert |
| DB/データ層 | architecture-expert |
| ビジネスロジック | developer-specialist |
| UIコンポーネント | react/svelte + accessibility-engineer |
| 設定/インフラ | security-expert |

### 3. 多観点レビュー

#### 3.1 セキュリティ観点
```
- [ ] 入力検証は適切か（サニタイズ、型チェック）
- [ ] 認可チェックは漏れていないか
- [ ] 秘密情報がハードコードされていないか
- [ ] SQLインジェクション/XSS/CSRFの脆弱性はないか
- [ ] エラーメッセージで内部情報を漏らしていないか
```

#### 3.2 アーキテクチャ観点
```
- [ ] 依存の方向は正しいか（内→外への依存のみ）
- [ ] 責務が適切に分離されているか
- [ ] 既存の境界を壊していないか
- [ ] 新しい概念の導入は妥当か
```

#### 3.3 設計品質観点
```
- [ ] 重複コードを作っていないか（既存の再利用）
- [ ] 単一責任原則を守っているか
- [ ] テスト可能な設計か
- [ ] 過剰な抽象化をしていないか
```

#### 3.4 表現・描画系観点（UI/アニメーション変更時）
```
- [ ] 世界観整合: 境界・容器・レイヤーの辻褄が合っているか（見た目の嘘がないか）
- [ ] 未翻訳の要素: ジャンルの定番UI/定番文言がそのまま残っていないか（`project-design-language` のメタファーで言い直せているか）
- [ ] フレーム内の重い処理: 全画面blur・合成等が要素数に比例していないか（層単位でまとめられないか）
- [ ] 決定性・テスト可能性: 状態を持つ必要が本当にあるか
- [ ] SSOT迂回: 色/文言/効果値の直書きがないか
```

#### 3.5 RDD整合観点
```
- [ ] 技術スタックの指定に従っているか
- [ ] 非機能要件を満たしているか
- [ ] 目標/非目標の範囲内か
- [ ] 制約事項を守っているか
```

#### 3.6 複雑さ観点
```
- [ ] 関数/メソッドが長すぎないか（目安: 50行以下）
- [ ] ネストが深すぎないか（目安: 3段以下）
- [ ] 条件分岐が複雑すぎないか
- [ ] 認知負荷が高くないか（一度に理解すべき概念数）
```

### 4. 結果出力

```markdown
## 🔍 Deep Review 結果

### 対象
- PR: #{PR_NUMBER} または ブランチ: {branch_name}
- 適用観点: セキュリティ, アーキテクチャ, 設計品質

### 🔴 Critical（マージ前に必須修正）
| 観点 | ファイル | 内容 | 推奨対応 |
|------|----------|------|----------|
| セキュリティ | src/api.ts:45 | SQLインジェクション脆弱性 | プレースホルダを使用 |

### 🟠 Warning（強く推奨）
| 観点 | ファイル | 内容 | 推奨対応 |
|------|----------|------|----------|
| 設計 | src/service.ts | 200行超の巨大関数 | 責務分割を検討 |
| RDD | src/auth.ts | JWT使用（RDDはSession指定） | 要確認/ADR |

### 🟡 Suggestion（検討推奨）
| 観点 | ファイル | 内容 | 推奨対応 |
|------|----------|------|----------|
| 複雑さ | src/calc.ts:30 | ネスト4段 | 早期リターンで簡素化 |

### 🟢 Good Practice（良い点）
- src/user.ts: 適切な入力検証
- src/repo.ts: 依存方向が正しい

### RDD整合チェック
- **技術スタック**: ✅ 準拠
- **非機能要件**: ✅ 準拠
- **制約事項**: ⚠️ 要確認（JWT vs Session）

### サマリ
| レベル | 件数 |
|--------|------|
| Critical | 1 |
| Warning | 2 |
| Suggestion | 1 |
| Good | 2 |

### 推奨アクション
1. Critical を修正してから再レビュー依頼
2. Warning は修正を強く推奨
3. RDD違反がある場合はADR-liteで変更要求

---

### 💬 所感

**設計の印象:**
{全体的な設計アプローチへの所感}

**特に良かった点:**
- {具体的に優れていた設計判断}
- {例: 責務分離が明確で拡張しやすい構造}
- {例: エッジケースの考慮が丁寧}

**成長ポイント:**
{今後さらに良くなるためのヒント（批判ではなく提案として）}

**総評:**
{前向きなまとめ。例: 「セキュリティ意識が高く、RDDに沿った堅実な実装です。Warningの点を改善すれば、長期運用でも安心できるコードになりますね！」}
```

---

## 出力先

**PR番号指定時（⚠️ 確認あり）:**
```bash
gh pr comment {PR_NUMBER} --body "{レビュー結果}"
```

**省略時:**
- 標準出力にレビュー結果を表示

---

## 判断基準

### Critical（マージブロック）
- セキュリティ脆弱性
- データ損失の可能性
- RDDの明確な違反（承認なし）

### Warning（強く推奨）
- 設計原則の違反
- 保守性の大幅な低下
- パフォーマンス問題

### Suggestion（任意）
- より良い書き方の提案
- 軽微な改善点

---

## 自己評価
- **成功自信度**: (1-10)
- **一言理由**: {短く理由を記載}

