k2works/developing-review

開発成果物レビュー

開発フェーズの成果物（プロダクションコード、テストコード、PR、リファクタリング結果など）を複数の XP エージェントで並列レビューし、多角的なフィードバックを統合する。

レビューの価値

コードレビューは単なるバグ発見の手段ではない。設計の妥当性、テストの十分性、将来の変更容易性、ドキュメントとの整合性、そして実際のユーザーにとっての価値を同時に検証することで、「変更を楽に安全にできて役に立つソフトウェア」を維持する。

レビューエージェント

| エージェント | 視点 | 着眼点 | |:---|:---|:---| | xp-programmer | コード品質 | SOLID 原則、DRY、命名、可読性、TDD サイクルの遵守、シンプルな設計 | | xp-tester | テスト品質 | テストカバレッジ、境界値、エッジケース、テストの信頼性、テストピラミッドのバランス | | xp-architect | 設計整合性 | アーキテクチャとの整合、依存関係の方向、変更容易性、技術的負債の蓄積 | | xp-technical-writer | ドキュメント品質 | API ドキュメント、コメントの適切さ、README の更新必要性、機能の理解しやすさ | | xp-user-representative | 利用者視点 | 実装された機能がユーザーの期待に合っているか、業務フローとの整合、使い勝手 |

レビュー対象の判定

ユーザーのリクエストに応じてレビュー範囲を決定する。

| リクエスト | レビュー範囲 | |:---|:---| | 「PR をレビュー」 | git diff で変更差分を取得 | | 「このファイルをレビュー」 | 指定ファイルの全体 | | 「最近の変更をレビュー」 | git log + git diff で直近の変更を取得 | | 「実装をレビュー」 | 指定された機能に関連するファイル群 |

レビューワークフロー

1. レビュー対象の収集

レビュー対象のコードを特定し、変更内容を把握する。

• PR の場合: git diff でベースブランチとの差分を取得
• ファイル指定の場合: 指定ファイルと関連ファイルを読み取る
• 関連するテストファイル、設計ドキュメントも収集する

2. エージェントの並列起動

Agent ツールを使い、5 つのエージェントを 同一メッセージで並列起動 する。各エージェントには以下を指示する。

あなたは {エージェント名} です。
.claude/agents/{エージェント名}.md の定義に従ってレビューしてください。

## レビュー対象
{変更差分 / ファイル内容}

## 関連コンテキスト
{関連する設計ドキュメント、テストファイル、ユーザーストーリー}

## レビュー観点
{エージェント固有の着眼点}

## 出力形式
以下の形式でフィードバックを返してください：

### 評価サマリー
（1-2 文で全体評価）

### 良い点
- （具体的に）

### 改善提案
- 【重要度: 高/中/低】（ファイル:行番号）（具体的な改善提案と理由）

### 懸念事項
- （潜在的なバグ、セキュリティリスク、パフォーマンス問題など）

### スコープ外の発見
- （レビュー対象外だが報告すべき問題）

Agent ツールが利用できない場合のフォールバック

Agent ツールが利用できない環境では、5 つの視点を逐次的にシミュレートする。各エージェントの定義ファイル（.claude/agents/{エージェント名}.md）を読み、その視点でレビューを順次実施する。出力形式は同一のテンプレートに従う。

3. フィードバックの統合

全エージェントのフィードバックを受け取った後、以下の形式で統合レポートを作成する。

## コードレビュー結果

### レビュー対象
- {ファイル名 / PR 番号}

### 総合評価
（全エージェントの評価を統合した 2-3 文の評価）

### 改善提案（重要度順）

#### 高（マージ前に対応すべき）
| # | 提案 | 箇所 | 指摘元 | 理由 |
|---|------|------|--------|------|

#### 中（対応推奨）
| # | 提案 | 箇所 | 指摘元 | 理由 |
|---|------|------|--------|------|

#### 低（改善の余地あり）
| # | 提案 | 箇所 | 指摘元 | 理由 |
|---|------|------|--------|------|

### 矛盾事項

複数エージェントの指摘が相反する場合、ここに記載する。

| # | 視点 A | 視点 B | 論点 | 推奨判断 |
|---|--------|--------|------|----------|

### エージェント別フィードバック詳細

<details>
<summary>xp-programmer（高: N / 中: N / 低: N）</summary>
（フィードバック全文）
</details>

<details>
<summary>xp-tester（高: N / 中: N / 低: N）</summary>
（フィードバック全文）
</details>

<details>
<summary>xp-architect（高: N / 中: N / 低: N）</summary>
（フィードバック全文）
</details>

<details>
<summary>xp-technical-writer（高: N / 中: N / 低: N）</summary>
（フィードバック全文）
</details>

<details>
<summary>xp-user-representative（高: N / 中: N / 低: N）</summary>
（フィードバック全文）
</details>

4. 改善アクションの提案

重要度「高」の指摘は具体的な修正コードを提案する。修正を適用するかはユーザーの判断に委ねる。

5. レビュー結果の保存

統合レポートを docs/review/{対象名}_review_{YYYYMMDD}.md に保存する。過去のレビュー結果と比較できるようにし、改善のトレーサビリティを確保する。

レビュー完了条件

以下をすべて満たした場合にレビュー完了とする。

• 全エージェントのフィードバックが収集済み
• 統合レポートが作成済み
• 重要度「高」の指摘について対応方針（修正する / 許容する / 保留する）が決定済み
• レビュー結果がドキュメントとして保存済み

注意事項

• レビューは「変更を楽に安全にできる」コードを維持するための協調的な活動
• TDD サイクルの遵守状況（テストが先に書かれているか）もレビュー観点に含める
• セキュリティに関する指摘は重要度「高」として扱う

関連スキル

• orchestrating-development — 開発フェーズの全体ワークフロー
• developing-backend — バックエンド TDD 開発
• developing-frontend — フロントエンド TDD 開発
• git-commit — レビュー結果の保存後のコミット