レビューと品質管理

はじめに

エージェントが生成するコードの量が増えるほど、レビューの方法も変わる必要がある。すべてを手動でレビューするのは非現実的だし、すべてを自動化に任せるのはリスクがある。

本モジュールでは、「人間はどこに集中すべきか」「何を自動化すべきか」を明確にし、効率的かつ安全な品質管理の方法を学ぶ。

Golden Principles: 意見のある機械的ルール

Golden Principles とは

チームで合意した「絶対に守るべきルール」を、機械的に検証可能な形で定義したもの。人間の好みや慣習ではなく、品質に直結するルールに絞る。

例: raica バックエンドの Golden Principles

# docs/conventions/golden-principles.md

## 1. Domain Purity
domain/ パッケージは外部ライブラリに依存しない。
検証: tests/architecture/domain_deps_test.go

## 2. Boundary Validation
外部入力は API 層で検証し、domain 型に変換する。
domain 層に生の string/int を渡さない。
検証: 型システム + custom linter

## 3. Error Context
エラーは必ず wrap し、何をしようとしたかのコンテキストを含める。
検証: custom linter (errwrap-check)

## 4. Auth on Patient Data
患者データにアクセスする API は必ず auth middleware を通す。
検証: tests/architecture/auth_coverage_test.go

## 5. Timeout on External Calls
外部 API 呼び出しと DB クエリには必ず timeout 付き context を使う。
検証: custom linter (timeout-check)

なぜ Golden Principles が重要か

レビューの判断基準が明確になる: 「これは Golden Principle に違反しているか？」
エージェントの自動修正が可能: 機械的に検出 → エラーメッセージに修正方法
チーム内の議論が減る: 合意済みのルールとして参照できる
スケールする: チームやコードベースが大きくなっても一貫性を保てる

品質スコアリング

ドメインごとの品質基準

すべてのコードに同じ品質基準を適用するのは非効率。ドメインのリスクレベルに応じて基準を変える。

高リスク（厳格な品質管理）:
  - 患者データの処理
  - 認証・認可ロジック
  - 請求計算
  - データマイグレーション

中リスク（標準的な品質管理）:
  - API ハンドラ
  - ビジネスロジック
  - データアクセス層

低リスク（軽い品質管理）:
  - 内部ツール
  - 開発用スクリプト
  - ドキュメント生成

品質チェックリスト

## 高リスクドメインのレビューチェックリスト

### 自動チェック（CI で実行）
- [ ] 全テストが通る
- [ ] lint エラーがない
- [ ] 構造テストが通る
- [ ] セキュリティスキャンが通る
- [ ] テストカバレッジ 80% 以上

### 人間のレビュー（必須）
- [ ] ビジネスロジックが仕様と一致しているか
- [ ] エッジケースが考慮されているか
- [ ] 患者データのアクセス制御が適切か
- [ ] パフォーマンスに問題がないか
- [ ] 既存機能への影響を確認したか

Continuous Garbage Collection

Tech Debt の蓄積を防ぐ

エージェントが生成するコードは、個々には正しくても、時間が経つと一貫性が失われていく。定期的なクリーンアップが必要。

Cleanup Agent の活用

定期的にエージェントにクリーンアップを依頼する:

# 週次のクリーンアップタスク

# 1. 未使用の import / 変数の削除
claude "src/ 内の未使用の import と変数を削除してください"

# 2. エラーメッセージの改善
claude "src/api/handlers/ 内のエラーメッセージを確認し、
修正方法のヒントが含まれていないものを改善してください"

# 3. ドキュメントの整合性チェック
claude "CLAUDE.md と docs/ の内容が実際のコードと一致しているか確認し、
不一致があれば修正してください"

Golden Principles に基づく定期チェック

# 月次の Golden Principles 監査
claude "docs/conventions/golden-principles.md に記載されたルールが
すべて機械的に検証されているか確認してください。
検証がないルールがあれば、テストまたは linter ルールを追加してください。"

パターンの統一

# 類似コードのパターン統一
claude "src/api/handlers/ 内のエラーレスポンスの書き方を確認してください。
pkg/response.Error() を使わずに直接書いているものがあれば、
統一してください。"

エージェント生成コードのレビュー方法

人間のレビューが価値を発揮する場面

1. Correctness（正しさ）

エージェントの出力: コンパイルが通り、テストも通る
人間の判断: 「だが、このビジネスロジックは仕様と異なる」

例:
- 保険の自己負担率の計算ロジックが制度と合っていない
- ページネーションの cursor が重複レコードを返す可能性がある
- 並行処理で race condition が発生する設計になっている

2. Architecture（設計）

エージェントの出力: 動くコードが生成された
人間の判断: 「だが、この設計では将来の変更が困難になる」

例:
- 今は 1 種類だが将来複数になる概念がハードコードされている
- パフォーマンスがスケールしない設計
- 他のモジュールとの整合性が取れていない

3. Security（セキュリティ）

エージェントの出力: 機能が正しく動作する
人間の判断: 「だが、セキュリティ上の懸念がある」

例:
- SQL インジェクションの可能性
- 認可チェックの漏れ
- 個人情報のログ出力

レビューで指摘しないこと

"The code doesn't match human stylistic preferences, and that's okay."

以下は Golden Principles に含まれない限り、レビューで指摘すべきではない:

変数名の好み（明確であれば OK）
コードの書き順（ロジックが正しければ OK）
コメントの量（過不足がなければ OK）
空行の入れ方

これらをチームとして統一したいなら、linter ルールとして機械化する。人間のレビューで繰り返し指摘するのは、レビュアーとレビュイーの両方の時間の無駄だ。

Agent-to-Agent Review

コンセプト

エージェントが生成したコードを、別のエージェントにレビューさせる。

# Agent A が実装
claude "患者検索 API を実装して"

# Agent B がレビュー
claude "src/api/handlers/patient_search.go を以下の観点でレビューして:
1. Golden Principles (docs/conventions/golden-principles.md) への準拠
2. 既存パターンとの一貫性 (src/api/handlers/medication.go と比較)
3. エッジケースの考慮
4. エラーメッセージの品質"

活用場面

低リスクドメイン: Agent-to-Agent Review + CI で十分な場合がある
中リスクドメイン: Agent-to-Agent Review → 人間が最終確認
高リスクドメイン: Agent-to-Agent Review + 人間の詳細レビュー

注意点

Agent-to-Agent Review は補助的なもの。高リスクな変更では人間のレビューを省略しない
レビュー観点を明確に指定する。漫然と「レビューして」だけでは有効ではない
エージェントのレビューは「パターン準拠の確認」に最も価値がある

味（Taste）をツールに組み込む

「味」とは

チームが大切にする品質基準のうち、明文化しにくいもの。例えば:

「このレベルの抽象化は早すぎる」
「ここは将来の拡張を見越して interface にすべき」
「このエラーメッセージは運用時に役立たない」

味をツールに変換する

「味」を感じるたびに、それをルールとして定式化できないか考える:

味: 「エラーメッセージが雑だ」
  ↓ 定式化
ルール: 「エラーメッセージには (1) 何をしようとしたか、(2) 何が失敗したか、
        (3) 可能なら修正のヒント を含めること」
  ↓ 機械化
Linter: エラーメッセージの最小文字数チェック + コンテキスト変数の有無チェック

味: 「抽象化が早すぎる」
  ↓ 定式化
ルール: 「interface は 2 つ以上の実装が存在するか、テストでモックが必要な場合のみ定義する」
  ↓ 文書化
docs/conventions/when-to-use-interfaces.md に記載

すべてを機械化する必要はない

機械化のコストが高い「味」は、ドキュメントに記載する。重要なのは「暗黙の了解」のまま放置しないこと。

# docs/conventions/code-taste.md

## エラーハンドリング
- エラーメッセージは「原因特定 → 修正」のサイクルを支援する
- "invalid input" だけでは不十分。何が、なぜ invalid かを含める

## 抽象化のタイミング
- "Rule of Three": 同じパターンが 3 回出現したら抽象化を検討する
- それまでは具象のまま保つ（早すぎる抽象化は避ける）

## テストの粒度
- 公開 API をテストする。内部実装の詳細をテストしない
- テスト名は「何がどうなるか」を日本語で書く

Try This: レビュープロセスの改善

Exercise 1: Golden Principles の策定

チームで以下のワークショップを行う:

過去 1 ヶ月の PR レビューコメントを収集する
繰り返し指摘されているパターンを特定する
そのうち機械化できるものを Golden Principles として定義する
テストまたは linter ルールとして実装する

Exercise 2: レビューコメントの分類

直近 10 件の PR レビューコメントを以下に分類する:

カテゴリ	例	あるべき対応
自動化可能	「import の順序が違う」	linter で検出
パターン準拠	「既存の形式と異なる」	Agent Review で検出
設計判断	「この抽象化は早すぎる」	人間のレビュー
ビジネス正しさ	「この計算式は制度と異なる」	人間のレビュー

自動化可能なものが多ければ、フィードバックループに改善余地がある。

Exercise 3: Agent-to-Agent Review の試行

エージェントにコードを生成させる
別のセッションで、そのコードをレビューさせる
レビュー結果を人間の目で評価する
有用な指摘と的外れな指摘を分類し、レビュープロンプトを改善する

Exercise 4: 品質ドメインの分類

プロジェクトのモジュールを高・中・低リスクに分類する:

各モジュールのリスクレベルを判定する
リスクレベルに応じたレビュープロセスを定義する
高リスクモジュールの Golden Principles を優先的に整備する

まとめ

エージェント生成コードの品質管理原則:

Golden Principles: 機械的に検証可能な「絶対ルール」を定義する
リスクベースのレビュー: ドメインのリスクに応じてレビュー密度を変える
Continuous Garbage Collection: 定期的にクリーンアップして一貫性を保つ
人間は判断に集中: 正しさ、設計、セキュリティに人間のレビューを集中させる
味をツールに変換: 暗黙の品質基準を明文化し、可能なら機械化する
スタイルにこだわらない: 動作の正しさ > コードのスタイル

次のステップ

チームワークフロー - チームでの Agent-First 開発の実践
フィードバックループの構築 - 品質ゲートの設計