comprehensive-review

包括的なレビュー

概要

コードを完成と判断する前に、7つの基準に照らしてレビューします。

基本原則： セルフレビューを行うことで、問題がほかの人に届く前に発見できます。

必須要件： レビュー成果物は GitHub の Issue に投稿する必要があります。これはフックによって適用されます。

開始時に宣言： 「包括的なコードレビューを実施します。」

レビュー成果物の要件

これは任意ではありません。 PR を作成する前に、次のことを行ってください。

1. 7つすべての基準に照らしてレビューを完了する
2. すべての指摘事項を記録する
3. 以下の形式を厳守して、成果物を Issue のコメントに投稿する
4. すべての指摘事項に対応する（修正するか、追跡用 Issue を作成して対応を保留する）
5. 成果物を更新し、「未対応：0」と表示する

review-gate スキルと PreToolUse フックにより、この成果物がなければ PR の作成はブロックされます。

7つの基準

1. 見落とし

質問： 何を見落としているでしょうか？

確認項目	自問すること
エッジケース	境界ではどうなりますか？入力が空の場合は？最大値の場合は？
エラーパス	外部サービスに障害が発生したらどうなりますか？ネットワークの問題が起きたら？
並行処理	複数のユーザーやスレッドが同時に使用したら？競合状態は起きませんか？
状態	誤った順序で呼び出されたらどうなりますか？無効な状態になりませんか？
依存関係	依存関係の動作が変わったらどうなりますか？

// Blindspot example: What if items is empty?
function calculateAverage(items: number[]): number {
  return items.reduce((a, b) => a + b, 0) / items.length;
  // Blindspot: Division by zero when items is empty!
}

// Fixed
function calculateAverage(items: number[]): number {
  if (items.length === 0) {
    throw new Error('Cannot calculate average of empty array');
  }
  return items.reduce((a, b) => a + b, 0) / items.length;
}

2. 明確さ／一貫性

質問： ほかの人にも理解できますか？

確認項目	自問すること
名前	名前から、それぞれの処理や要素の内容が分かりますか？
構造	コードは論理的に整理されていますか？
複雑さ	もっと簡潔にできますか？
パターン	既存のパターンに沿っていますか？
意外性	読み手を驚かせる点はありませんか？

3. 保守性

質問： 安全に変更できますか？

確認項目	自問すること
結合度	ほかのコードと密接に結合していませんか？
凝集度	1つのことを適切に行っていますか？
重複	ロジックがほかの場所でも繰り返されていませんか？
テスト	テストで十分にカバーされていますか？
拡張性	新しい機能を簡単に追加できますか？

4. セキュリティリスク

質問： 悪用される可能性はありますか？

確認項目	自問すること
入力の検証	すべての入力を検証し、サニタイズしていますか？
認証	アクセスは適切に制御されていますか？
認可	権限を確認していますか？
データの露出	機密データは保護されていますか？
インジェクション	SQL、XSS、コマンドインジェクションが発生する可能性はありますか？
依存関係	依存関係は安全で、最新の状態ですか？

注意： セキュリティ上重要なファイル（auth、api、middleware など）を変更する場合は、より詳細な分析のために security-review スキルを使用してください。

5. パフォーマンスへの影響

質問： 規模が拡大しても対応できますか？

確認項目	自問すること
アルゴリズム	計算量は適切ですか？O(n) で可能なのに O(n²) になっていませんか？
データベース	N+1 クエリはありませんか？インデックスが不足していませんか？全テーブルスキャンが発生していませんか？
メモリ	メモリ上に大きなオブジェクトを保持していませんか？メモリリークはありませんか？
ネットワーク	不要なリクエストはありませんか？ペイロードが大きすぎませんか？
キャッシュ	結果をキャッシュする必要はありませんか？

6. ドキュメント

質問： ドキュメントは十分に整備されていますか？

確認項目	自問すること
公開 API	すべての公開関数にドキュメントがありますか？
パラメーター	パラメーターの型と目的は明確ですか？
戻り値	戻り値について説明されていますか？
エラー	発生するエラーについて説明されていますか？
例	複雑な使い方が例で示されていますか？
理由	自明でない判断について説明されていますか？

ドキュメントの基準については、inline-documentation スキルを参照してください。

7. 標準とスタイル

質問： プロジェクトの規約に沿っていますか？

確認項目	自問すること
命名	プロジェクトの命名規約に従っていますか？
フォーマット	プロジェクトのフォーマットに合っていますか？
パターン	確立されたパターンを使用していますか？
型	型が完全に指定されていますか（any を使用していませんか）？
言語	インクルーシブな言葉を使用していますか？
IPv6 優先	ネットワークコードでは、デフォルトで IPv6 を使用していますか？IPv4 は、文書化されたレガシー対応の場合に限られていますか？
リンティング	すべてのリンターに合格していますか？

style-guide-adherence、strict-typing、inclusive-language、ipv6-first の各スキルを参照してください。

レビュープロセス

ステップ 1：準備する

# Get list of changed files
git diff --name-only HEAD~1

# Get full diff
git diff HEAD~1

# Check for security-sensitive files
git diff --name-only HEAD~1 | grep -E '(auth|security|middleware|api|password|token|secret)'
# If matches found, security-review skill is MANDATORY

ステップ 2：各基準を確認する

7 つの基準それぞれについて、次の手順を実施します。

1. 変更されたコードをすべて確認します
2. 見つかった問題を記録します
3. 重要度（Critical／Major／Minor）を判定します

ステップ 3：セキュリティに関わる変更を確認する

セキュリティに関わるファイルが 1 つでも変更されている場合は、次の手順を実施します。

1. security-review スキルまたは security-reviewer サブエージェントを呼び出します
2. セキュリティレビューの結果を成果物に記載します
3. 成果物に「Security-Sensitive: YES」と記載します

ステップ 4：指摘事項を記録する

## Code Review Findings

### 1. Blindspots
- [ ] **Critical**: No handling for empty array in `calculateAverage()`
- [ ] **Minor**: Missing null check in `formatUser()`

### 2. Clarity/Consistency
- [ ] **Major**: Variable `x` should have descriptive name

### 3. Maintainability
- [x] No issues found

### 4. Security Risks
- [ ] **Critical**: SQL injection possible in `findUser()`

### 5. Performance Implications
- [ ] **Major**: N+1 query in `getOrdersWithUsers()`

### 6. Documentation
- [ ] **Minor**: Missing JSDoc on `processOrder()`

### 7. Standards and Style
- [x] Passes all checks

ステップ 5：すべての指摘事項に対処する

apply-all-findings スキルを使用して、すべての問題に対処します。

修正できない指摘事項については、次の手順を実施します。

1. deferred-finding スキルを使用して追跡用 Issue を作成します
2. 成果物に追跡用 Issue へのリンクを記載します
3. 「追跡用 Issue なしで保留」は許可されません

ステップ 6：成果物を Issue に投稿する（必須）

レビュー成果物を GitHub Issue にコメントとして投稿します。

ISSUE_NUMBER=123
gh issue comment $ISSUE_NUMBER --body "$(cat <<'EOF'

## Code Review Complete

| Property | Value |
|----------|-------|
| Worker | `[WORKER_ID]` |
| Issue | #123 |
| Scope | [MINOR|MAJOR] |
| Security-Sensitive | [YES|NO] |
| Reviewed | [ISO_TIMESTAMP] |

### Criteria Results

| # | Criterion | Status | Findings |
|---|-----------|--------|----------|
| 1 | Blindspots | [✅ PASS|✅ FIXED|⚠️ DEFERRED] | [N] |
| 2 | Clarity | [✅ PASS|✅ FIXED|⚠️ DEFERRED] | [N] |
| 3 | Maintainability | [✅ PASS|✅ FIXED|⚠️ DEFERRED] | [N] |
| 4 | Security | [✅ PASS|✅ FIXED|⚠️ DEFERRED|N/A] | [N] |
| 5 | Performance | [✅ PASS|✅ FIXED|⚠️ DEFERRED] | [N] |
| 6 | Documentation | [✅ PASS|✅ FIXED|⚠️ DEFERRED] | [N] |
| 7 | Style | [✅ PASS|✅ FIXED|⚠️ DEFERRED] | [N] |

### Findings Fixed in This PR

| # | Severity | Finding | Resolution |
|---|----------|---------|------------|
| 1 | [SEVERITY] | [DESCRIPTION] | [HOW_FIXED] |

### Findings Deferred (With Tracking Issues)

| # | Severity | Finding | Tracking Issue | Justification |
|---|----------|---------|----------------|---------------|
| 1 | [SEVERITY] | [DESCRIPTION] | #[ISSUE] | [WHY] |

### Summary

| Category | Count |
|----------|-------|
| Fixed in PR | [N] |
| Deferred (with tracking) | [N] |
| Unaddressed | 0 |

**Review Status:** ✅ COMPLETE

EOF
)"

重要：「Unaddressed」は 0 でなければなりません。「Review Status」は「COMPLETE」でなければなりません。

重要度レベル

重要度	説明	対応
Critical	セキュリティ上の問題、データ損失、クラッシュ	マージ前に修正が必要
Major	重大なバグ、パフォーマンスの問題	マージ前に修正が必要
Minor	スタイル、明瞭さ、小規模な改善	マージ前に修正することが望ましい

チェックリスト

コードレビューごとに、以下を完了してください。

• 見落とし：エッジケース、エラー、並行処理を確認
• 明瞭さ：名前、構造、複雑さを確認
• 保守性：結合度、凝集度、テストを評価
• セキュリティ：入力、認証、インジェクション、情報漏えいを確認（機密ファイルでは必須）
• パフォーマンス：アルゴリズム、クエリ、メモリを確認
• ドキュメント：公開 API を文書化
• スタイル：規約に準拠
• すべての指摘事項を記録
• すべての指摘事項に対処するか、追跡用 Issue を作成して保留
• レビュー成果物を Issue に投稿（指定の形式）
• 成果物に「Unaddressed: 0」と記載
• 成果物に「Review Status: COMPLETE」と記載

統合

このスキルは、次から呼び出されます。

• issue-driven-development - ステップ 9

このスキルは、次を使用します。

• review-scope - レビュー範囲を決定
• apply-all-findings - 問題に対処
• security-review - セキュリティに関わる変更に使用
• deferred-finding - 追跡用 Issue の作成に使用

このスキルは、次によって適用されます。

• review-gate - PR の前に成果物を検証
• PreToolUse hook - 成果物がない場合に PR をブロック

このスキルは、次を参照します。

• inline-documentation - ドキュメントの基準
• strict-typing - 型の要件
• style-guide-adherence - スタイルの要件
• inclusive-language - 言語の要件
• ipv6-first - ネットワークコードの要件（IPv6 を優先し、IPv4 はレガシーとして扱う）