review-scoring

リソース

scripts/
  validate-review.sh
  validate-fix.sh
references/
  scoring-examples.md

レビュー採点プロトコル

このスキルでは、Work-Review-Fix-Check（WRFC）ループで使用する正確な採点基準とレビュー形式を定義します。コード品質を一貫性のある定量的な方法で評価し、レビュー結果を決定論的に検証できるようにします。

採点基準（1〜10 段階）

各レビューでは、コードを 10 個の観点から評価します。各観点に 1〜10 点のスコアを付けます。

• 1〜3：重大な欠陥、根本的な問題
• 4〜5：深刻な問題、許容基準を下回る
• 6〜7：許容範囲だが、目立った問題がある
• 8〜9：軽微な問題はあるが、品質が高い
• 10：卓越しており、本番環境で使用できる品質

10 個の観点

1. 正確性（重み：20%）

コードは意図どおりに動作しますか？

採点基準：

• 10：ロジックに欠陥がなく、すべてのエッジケースに対応し、null/undefined チェックがあり、オフバイワンエラーがない
• 7〜9：軽微なエッジケースへの対応漏れがあり、防御的なチェックを追加できる場合がある
• 4〜6：一般的な処理経路にロジックエラーがあり、null チェックが不足している、条件分岐が誤っている
• 1〜3：根本的なロジックエラーがあり、一般的な入力でクラッシュする、中核機能が壊れている

よくある問題：

• null/undefined チェックの不足
• ループや配列におけるオフバイワンエラー
• 誤ったブール論理
• 非同期コードでの競合状態
• 未処理の Promise 拒否

2. 完全性（重み：15%）

すべてが完全に実装されていますか？

採点基準：

• 10：機能が完全に実装され、TODO やプレースホルダー、コメントアウトされたコードがない
• 7〜9：将来の拡張向けの軽微な TODO コメントがある（中核機能ではない）
• 4〜6：中核機能がスタブのまま、プレースホルダー実装がある、重要な処理経路が欠けている
• 1〜3：ほとんどがプレースホルダーで、実装が不完全、主要な機能が欠けている

よくある問題：

• 本番コード内の TODO コメント
• ハードコードされた値を返すプレースホルダー関数
• エラー状態の未実装
• フォーム検証の不完全な実装
• 実際の API 呼び出しの代わりにモックデータを使用

3. セキュリティ（重み：15%）

脆弱性が防止されていますか？

採点基準：

• 10：入力が検証され、認証が確認され、秘密情報が漏えいせず、インジェクションを防止し、CORS が設定されている
• 7〜9：軽微なセキュリティ強化の余地がある（レート制限、追加のログ記録など）
• 4〜6：入力検証が不足している、一部の処理経路で認証チェックが回避されている、コード内に秘密情報がある
• 1〜3：重大な脆弱性がある（SQL インジェクション、XSS、認証情報の漏えい、認証なし）

よくある問題：

• 秘密情報のハードコード、または git へのコミット
• 認証チェックの不足
• 文字列連結による SQL インジェクション
• innerHTML または dangerouslySetInnerHTML による XSS
• 本番環境での CORS の * 設定
• CSRF 対策の不足
• クライアント側コード内の機密データ

4. パフォーマンス（重み：10%）

効率的ですか？

採点基準：

• 10：N+1 クエリがなく、適切なインデックスがあり、必要に応じてキャッシュを使用し、再レンダリングが最適化されている
• 7〜9：軽微な最適化の余地がある（メモ化、遅延読み込みなど）
• 4〜6：N+1 クエリが発生している、インデックスが不足している、不要な再レンダリングがある
• 1〜3：深刻なパフォーマンス問題がある（ブロッキング処理、メモリリーク、無限ループ）

よくある問題：

• N+1 データベースクエリ
• データベースインデックスの不足
• 不要な React の再レンダリング（useMemo/useCallback の不足）
• バンドルサイズが大きい（コード分割の不足）
• イベントループをブロックする同期処理
• メモリリーク（イベントリスナーがクリーンアップされない）

5. 規約（重み：10%）

プロジェクトのパターンに従っていますか？

採点基準：

• 10：既存の命名規則、ファイル構成、インポート順序、コードスタイルに合致している
• 7〜9：軽微なスタイルの不統一がある（フォーマット、インポート順序）
• 4〜6：異なる命名規則を使用している、ファイルの配置場所が誤っている、パターンに一貫性がない
• 1〜3：プロジェクトの規約を完全に無視し、既存のパターンと矛盾するパターンを導入している

よくある問題：

• 命名の不統一（camelCase と snake_case の混在）
• ファイルの配置場所が誤っている（utils/ 内のコンポーネントなど）
• インポート順序の規約違反
• タブとスペースの混在
• コードベースの他の部分と異なるエラー処理パターン

6. テスト容易性（重み：10%）

テストが存在し、意味のある内容になっていますか？

採点基準：

• 10：包括的なテストがあり、エッジケースが網羅され、意味のあるアサーションがあり、カバレッジが高い
• 7-9：テストは存在するものの、一部のエッジケースが不足しているか、アサーションが弱い
• 4-6：最低限のテストしかなく、正常系のみで、エッジケースがない
• 1-3：テストがない、または動作を検証しないテストしかない

よくある問題：

• テストがまったくない
• 正常系のみを対象にしたテスト
• アサーションがないテスト（スモークテストのみ）
• エッジケースのカバレッジ不足
• 実装の詳細に依存した壊れやすいテスト

7. 可読性（重み：5%）

理解しやすいですか？

採点基準：

• 10：明確な命名、適切な抽象化、複雑なロジックの説明、自己説明的なコード
• 7-9：おおむね明確だが、意味が分かりにくい変数名や、説明のない複雑なロジックが少しある
• 4-6：命名が不適切で、複雑すぎ、必要な箇所にコメントがない
• 1-3：理解不能で、1文字の変数名が使われ、深くネストされ、説明がない

よくある問題：

• 1文字の変数名（ループカウンターを除く）
• 50行を超える関数
• 4階層を超えるネスト
• 意味不明な略語
• 説明コメントのない複雑なロジック

8. エラー処理（重み：5%）

エラーは適切に処理されていますか？

採点基準：

• 10：すべてのエラーが捕捉され、適切にログに記録され、ユーザー向けメッセージが明確で、サイレントな失敗がない
• 7-9：エラーは捕捉されているが、ログの改善が必要で、一般的なメッセージがいくつかある
• 4-6：try/catchブロックが不足し、サイレントな失敗があり、エラーメッセージが不適切
• 1-3：エラー処理がなく、エラーでクラッシュし、ユーザーへのフィードバックがない

よくある問題：

• 空のcatchブロック（サイレントな失敗）
• 一般的なエラーメッセージ（「問題が発生しました」）
• エラーがログに記録されない
• 処理されないPromiseの拒否
• ユーザー向けのエラー状態がない

9. 型安全性（重み：5%）

型は正確かつ包括的ですか？

採点基準：

• 10：型が正確で、anyがなく、ジェネリクスが適切に使われ、strictモードが有効になっている
• 7-9：おおむね型付けされているが、修正用のTODOコメントが付いたany型が少しある
• 4-6：any型が多く、検証のない型アサーションがあり、型付けが緩い
• 1-3：TypeScriptが無効になっている、いたるところでanyが使われている、型アサーションでエラーを隠している

よくある問題：

• anyの過剰な使用
• 実行時検証を伴わない型アサーション（as）
• 戻り値の型注釈がない
• ジェネリクスの制約が不適切
• strictモードの無効化

10. 統合性（重み：5%）

既存のコードと連携して動作しますか？

採点基準：

• 10：シームレスに統合され、既存の機能を壊さず、APIコントラクトに従っている
• 7-9：統合に関して小さな調整が必要
• 4-6：既存の機能を壊し、APIコントラクトに違反し、他の箇所に大規模な変更が必要
• 1-3：既存システムと互換性がなく、複数の機能を壊す

よくある問題：

• 公開APIへの破壊的変更
• 既存の認証フローとの互換性がない
• 他の機能を壊す（リグレッション）
• 共有ユーティリティを使わない（車輪の再発明）
• 既存の状態管理との競合

総合スコアの計算

総合スコアは、10項目の加重平均です。

Overall = (Correctness x 0.20) + 
          (Completeness x 0.15) + 
          (Security x 0.15) + 
          (Performance x 0.10) + 
          (Conventions x 0.10) + 
          (Testability x 0.10) + 
          (Readability x 0.05) + 
          (Error Handling x 0.05) + 
          (Type Safety x 0.05) + 
          (Integration x 0.05)

例：

Correctness: 9
Completeness: 8
Security: 10
Performance: 7
Conventions: 9
Testability: 6
Readability: 8
Error Handling: 7
Type Safety: 9
Integration: 9

Overall = (9x0.20) + (8x0.15) + (10x0.15) + (7x0.10) + (9x0.10) + 
          (6x0.10) + (8x0.05) + (7x0.05) + (9x0.05) + (9x0.05)
        = 1.8 + 1.2 + 1.5 + 0.7 + 0.9 + 0.6 + 0.4 + 0.35 + 0.45 + 0.45
        = 8.35/10

合格／不合格のしきい値

総合スコアによって判定が決まります。

スコア範囲	判定	必要な対応
>= 9.5	合格	リリース可能 — 本番環境への準備完了
8.0-9.49	条件付き合格	軽微な問題 — 修正して再確認（8.0を含み、全面的な再レビューは不要）
6.0-7.9	不合格	重大な問題 — 修正後、全面的な再レビューが必要
6.0未満	不合格	大幅な手直しが必要 — 修正後、全面的な再レビューが必要

重要な項目のルール：いずれかの項目のスコアが4未満の場合、計算されたスコアにかかわらず、総合判定は自動的に不合格になります。

必須のレビュ​​ー出力形式

すべてのレビューでは、必ず以下の構成をそのまま出力してください。検証スクリプトはこれらのセクションをチェックします。

## Review Summary
- **Overall Score**: X.X/10
- **Verdict**: PASS | CONDITIONAL PASS | FAIL
- **Files Reviewed**: [list of files]

## Dimension Scores
| Dimension | Score | Notes |
|-----------|-------|-------|
| Correctness | X/10 | [specific findings] |
| Completeness | X/10 | [specific findings] |
| Security | X/10 | [specific findings] |
| Performance | X/10 | [specific findings] |
| Conventions | X/10 | [specific findings] |
| Testability | X/10 | [specific findings] |
| Readability | X/10 | [specific findings] |
| Error Handling | X/10 | [specific findings] |
| Type Safety | X/10 | [specific findings] |
| Integration | X/10 | [specific findings] |

## Issues Found

### Critical (must fix)
- [FILE:LINE] Description of issue. Fix: [specific fix]
- [FILE:LINE] Description of issue. Fix: [specific fix]

### Major (should fix)
- [FILE:LINE] Description of issue. Fix: [specific fix]
- [FILE:LINE] Description of issue. Fix: [specific fix]

### Minor (nice to fix)
- [FILE:LINE] Description of issue. Fix: [specific fix]
- [FILE:LINE] Description of issue. Fix: [specific fix]

## What Was Done Well
- [specific positive observation with file reference]
- [specific positive observation with file reference]

フォーマット要件

1. 総合スコア：数値でなければなりません（X.X/10 形式、小数点以下 1 桁）
2. 判定：PASS、CONDITIONAL PASS、FAIL のいずれかと完全に一致しなければなりません
3. 各項目のスコア：10 項目すべてを X/10 形式で記載し、注記には具体的な所見を含めてください（「問題ありません」のような一般的な表現は不可）
4. 問題の分類：すべての問題を Critical／Major／Minor のいずれかに分類してください
5. FILE:LINE 参照：すべての問題に、具体的なファイル名と行番号を記載してください
6. 修正案：すべての問題に、具体的な修正方針（変更内容、変更方法、コード例）を含めてください
7. 良かった点：「良かった点」を含め、少なくとも 1 つの肯定的な所見を記載してください

問題の重大度に関するガイドライン

Critical：リリース前に必ず修正してください。例：

• セキュリティ脆弱性
• データ破損のバグ
• 認証の回避
• 一般的な入力でのクラッシュ
• 露出したシークレット

Major：リリース前に修正するべきです。例：

• パフォーマンスの問題（N+1 クエリ）
• 重要な処理経路におけるエラーハンドリングの欠如
• アクセシビリティ違反
• 型安全性の違反（過剰な any）
• 保守性に影響する規約違反

Minor：修正が望ましいものの、リリースを妨げるものではありません。例：

• 最適でない命名
• 複雑なロジックに対するコメントの不足
• 軽微なスタイルの不統一
• リファクタリングの機会
• 脆弱なテストアサーション

注：重大度は、システムのリスク状況によって異なる場合があります（例：高規模システムでは、パフォーマンスの問題が Critical となることがあります）。

修正エージェントの要件

修正エージェントが問題を含むレビューを受け取った場合：

必ず修正する項目

1. すべての Critical の問題 — 例外なし
2. すべての Major の問題 — 例外なし
3. Minor の問題 — オーケストレーターによって明示的に優先度を下げられている場合を除く

必ず記録する項目

修正を適用した後、修正エージェントは次の内容を作成しなければなりません：

## Fixes Applied

### Critical Issues Addressed
- [FILE:LINE] [Original issue] -> Fixed by: [what was changed]
- [FILE:LINE] [Original issue] -> Fixed by: [what was changed]

### Major Issues Addressed
- [FILE:LINE] [Original issue] -> Fixed by: [what was changed]

### Minor Issues Addressed
- [FILE:LINE] [Original issue] -> Fixed by: [what was changed]

### Issues Not Fixed
- [FILE:LINE] [Original issue] -> Reason: [why it wasn't fixed]

**Example**:
- [src/api/legacy.ts:45] Complex refactoring of legacy code -> Reason: Out of scope for this PR, tracked in ticket #1234

禁止事項

1. 変更せずに修正済みと主張しない：実際にコードを変更せずに、問題を修正済みとして扱ってはいけません
2. 部分的な修正をしない：問題を完全に修正するか、修正できない理由を記録してください
3. 黙ってスキップしない：問題をスキップする場合は、その理由とともに「未修正の問題」に記録してください
4. 新たな問題を生じさせない：修正によって新たなバグが発生しないようにしてください（再レビューで確認します）

再レビューの要件

修正が適用された後、再レビュアーは次のことを行わなければなりません：

検証手順

1. 以前に指摘された各問題を確認する

   • 修正が適用されたことを確認する
   • 修正によって問題が実際に解消されたことを確認する
   • 修正によって新たな問題が生じていないこと、また問題が別の箇所に移っただけではないことを確認する

2. すべての項目を再採点する

   • 以前のスコアをそのままコピーしないでください
   • 現状をゼロから評価します：（a）変更されたファイルを読む、（b）評価基準を適用する、（c）現状に基づいて採点する
   • スコアの変更を記録します（「セキュリティ：6 -> 9」）

3. 新たな問題を特定する

   • 再レビューで見つかった問題は、新たな指摘事項です
   • 修正によって直接引き起こされたものでない限り、リグレッションには数えません
   • 同じ評価基準を用いて、Critical／Major／Minor に分類してください

再レビューの出力形式

## Re-Review Summary
- **Overall Score**: X.X/10 (was Y.Y/10)
- **Verdict**: PASS | CONDITIONAL PASS | FAIL
- **Previous Issues**: X critical, Y major, Z minor
- **Issues Resolved**: X critical, Y major, Z minor
- **New Issues Found**: X critical, Y major, Z minor

## Dimension Score Changes
| Dimension | Previous | Current | Change |
|-----------|----------|---------|--------|
| Correctness | X/10 | X/10 | +/- X |
| [etc] | ... | ... | ... |

## Previous Issues - Resolution Status

### Critical Issues
- [RESOLVED] [FILE:LINE] [Original issue] -> RESOLVED
- [NOT FIXED] [FILE:LINE] [Original issue] -> NOT FIXED: [reason]

### Major Issues
- [RESOLVED] [FILE:LINE] [Original issue] -> RESOLVED

### Minor Issues
- [RESOLVED] [FILE:LINE] [Original issue] -> RESOLVED

## New Issues Found
[Use standard Critical/Major/Minor format]

WRFC ループのコンテキスト

このスキルは、Work-Review-Fix-Check ループの重要な構成要素です：

1. Work：エンジニアが機能を実装します
2. Review：レビュアーがこの採点基準を適用し、スコア付きのレビューを作成します
3. Fix：修正エージェントがすべての Critical／Major の問題に対処し、修正レポートを作成します
4. Check：再レビュアーが修正を検証し、再採点して、次のループが必要かどうかを判断します

オーケストレーターは、数値スコアと判定を用いて判断します：

• PASS（9.5 以上）：ループを終了し、完了としてマークします
• CONDITIONAL PASS（8.0～9.49）：簡易な修正と確認のサイクルをもう 1 回行います
• FAIL（8.0 未満）：レビュー、修正、確認のループをもう一度すべて実施します

避けるべき一般的な採点ミス

スコアの過大評価

誤り：重大な問題があるのに、8～9 のスコアを付ける 正しい対応：評価基準を文字どおり適用します。6～7 は「許容範囲だが、注目すべき問題がある」を意味します

重大度の不整合

誤り：セキュリティ脆弱性を「Major」とし、「Critical」にしない 正しい対応：重大度のガイドラインに従います。認証の回避は常に Critical です

FILE:LINE の参照漏れ

誤り：「エラー処理が不十分です」 正しい：「src/api/users.ts:42 - 空の catch ブロックがエラーを黙って握りつぶしています」

曖昧な修正提案

誤り：「型安全性の問題を修正してください」 正しい：「any を User 型に置き換え、zod スキーマで実行時検証を追加してください」

主観的な理由によるスコアの留保

誤り：「ドメインが複雑だから」や「完璧を避けるため」という理由で、10 点ではなく 9.5 点を付ける 正しい：問題が特定されなかった場合、スコアは 10 点です。スコアは客観的であり、特定された実行可能な問題のみに基づく必要があります。10/10 は常に達成可能であり、欠陥が見つからない場合は付与しなければなりません。ドメインの複雑さ、コードの新規性、哲学的な慎重さなど、主観的な理由でポイントを差し引いてはいけません。

肯定的な所見の無視

誤り：問題のみを列挙する 正しい：適切にできている点も記録する（優れたパターンを促進します）

判定の不一致

誤り：全体スコアが 7.2/10 なのに、判定が「PASS」 正しい：スコア 7.2 -> 判定 FAIL（条件付きのしきい値は 8.0、合格のしきい値は 9.5）

検証スクリプト

このスキルには、決定論的な検証スクリプトが含まれています。

• scripts/validate-review.sh：レビュー出力が形式要件に準拠しているかを確認します
• scripts/validate-fix.sh：修正エージェントの出力が、すべての重大／主要な問題に対応しているかを確認します

実装の詳細については、scripts/ ディレクトリを参照してください。

クイックリファレンス

ディメンションの重み

Correctness:      20%  (most important)
Completeness:     15%
Security:         15%
Performance:      10%
Conventions:      10%
Testability:      10%
Readability:       5%
Error Handling:    5%
Type Safety:       5%
Integration:       5%

判定のしきい値

9.5+ -> PASS
8.0-9.49 -> CONDITIONAL PASS
6.0-7.9 -> FAIL
<6.0 -> FAIL (major rework)

問題の重大度

Critical: Security, crashes, data corruption -> MUST FIX
Major: Performance, missing features, poor practices -> SHOULD FIX
Minor: Style, optimization opportunities -> NICE TO FIX