code-review

コード分析・採点スキル

コードを読んで、品質を7軸で採点し、具体的な改善点をフィードバックする。

---

採点の前に確認すること

• 言語・フレームワーク — TypeScript / Python / React / Next.js など
• コードの文脈 — 何をするコードか（コンポーネント / API / ユーティリティなど）
• レビューの目的 — 全体品質 / セキュリティ重点 / 特定の懸念点など

文脈が不明な場合でも、コードから読み取れる範囲で採点を始める。

---

採点軸（100点満点）

1. スコープ遵守 ／ YAGNI（20点）

「必要なことだけをやっているか」

減点対象：

• 依頼されていない機能が追加されている
• 「将来使うかも」という理由で追加された処理
• 今の要件では呼ばれないコードパス
• 使われていない引数・オプション

良い状態： コードを読んだとき「なぜこれがあるのか」に一瞬でも疑問が生まれない

---

2. 抽象化の適切さ（15点）

「抽象化が早すぎないか、逆に繰り返しすぎていないか」

減点対象（早すぎる抽象化）：

• 1〜2箇所しか使わない関数・コンポーネントへの無理な切り出し
• ジェネリクスや設定オブジェクトで汎用化しているが、実際には1パターンしかない
• BaseXxx / AbstractXxx / IXxx など、継承前提の設計が必要ないケース
• 3行でできる処理をクラス化・モジュール化している

減点対象（繰り返しすぎ）：

• 明らかに同じロジックが3箇所以上コピーされている
• 定数になるべき値がハードコードで散らばっている

良い状態： 同じロジックが3回以上出てきたら抽象化を検討する。それ未満は繰り返しでOK。

---

3. コメントの品質（15点）

「コメントはWHYだけか、WHATを説明していないか」

減点対象：

• コードを読めばわかることをコメントで繰り返している

  // ユーザーを取得する
  const user = getUser(id);
  

• 関数名・変数名が説明していることをdocstringで再説明している
• 「何をしているか」を説明するコメントブロック
• タスク・PR・呼び出し元への参照（腐る）

  // issue #123 のために追加
  // LoginFlow から呼ばれる
  

加点対象（書いてよいコメント）：

• 隠れた制約・非自明な不変条件
• 特定バグの回避策（バグのURLがあればなお良い）
• 「なぜこうしていないか」の説明

良い状態： コメントを消してもコードが自己説明できる。コメントがあるならWHYだけ。

---

4. エラーハンドリングの適切さ（15点）

「起きえない失敗まで防御していないか、逆に境界が無防備でないか」

減点対象（過剰）：

• 内部関数の戻り値を再度nullチェックしている（フレームワーク保証があるのに）
• 型が保証している値に対してのtype narrowingを重ねる
• try/catchで握りつぶして握り潰した後に何もしない

  try { ... } catch (e) { /* 何もしない */ }
  

• フォールバックが「絶対に発火しない」のにデフォルト値を詰め込む

減点対象（不足）：

• ユーザー入力・外部APIレスポンス・環境変数を無検証で使っている
• ネットワークエラー・タイムアウトの考慮がない

良い状態： バリデーションはシステム境界（ユーザー入力・外部API）だけ。内部コードは型とフレームワークを信頼する。

---

5. セキュリティ（20点）

「OWASP Top 10 レベルの脆弱性がないか」

チェック項目：

• XSS — dangerouslySetInnerHTML の無防備な使用 / HTMLエスケープ漏れ
• SQLインジェクション — 文字列連結でクエリを組み立てていないか
• コマンドインジェクション — ユーザー入力を exec / eval / child_process に渡していないか
• 認証・認可の欠如 — エンドポイントにアクセス制御がないか
• 秘密情報の露出 — APIキー・トークンのハードコード / クライアントへの漏れ
• CSRF — 状態変更APIにCSRF対策があるか
• 依存関係 — 脆弱なバージョンの既知パッケージを使っていないか

重大な脆弱性は1件で大幅減点。指摘は必ずコードの該当箇所を示す。

---

6. 命名・可読性（10点）

「名前がコードの意図を伝えているか」

減点対象：

• 型情報を名前に含める（userString, itemList, isFlag）
• 略語・1文字変数（ループインデックス i / j は許容）
• 動詞のない関数名（userData() → fetchUserData() / buildUserPayload() など）
• true を返すのに isXxx でない / false を返すのに isXxx になっている
• data, info, manager, helper など意味のない名前

良い状態： コメントなしで関数・変数の目的が伝わる。

---

7. 後方互換ハック・デッドコード（5点）

「削除されたコードの痕跡が残っていないか」

減点対象：

• 使われなくなった変数を _ リネームで残している（_unused, _oldFn）
• 削除した型・関数を re-export だけして残している
• // TODO: 後で消す が残ったまま
• コメントアウトされたコードブロック
• 到達不能な return / break 以降のコード

良い状態： 使わないものは消す。消すのが怖い理由があるなら、それはコードではなくコミットメッセージに書く。

---

出力フォーマット

採点結果は以下の形式で出力する：

## コードレビュー結果

**総合スコア：XX / 100**

| 軸 | 点数 | 満点 |
|---|---|---|
| スコープ遵守 / YAGNI | XX | 20 |
| 抽象化の適切さ | XX | 15 |
| コメントの品質 | XX | 15 |
| エラーハンドリング | XX | 15 |
| セキュリティ | XX | 20 |
| 命名・可読性 | XX | 10 |
| 後方互換ハック・デッドコード | XX | 5 |

---

### 良い点
- 〇〇（具体的にどのコードが良いか）

### 改善が必要な点

#### [軸名]（-X点）
問題のコード：

該当コード

理由：〇〇だから。
修正案：〇〇にする。

---

### 総評
[3〜5文でコードの全体印象・最優先で直すべき点]

---

採点の原則

• 減点は必ずコードの該当箇所を引用する。 「コメントが多い」だけでは伝わらない。
• 「好みの問題」は指摘しない。 動作や保守性に影響しない書き方の差異はスコアに含めない。
• 良い点も必ず書く。 悪い点だけ並べるレビューは改善の方向性が見えない。
• 修正案はシンプルに。 問題を解消できる最小限のコードだけ示す。余分な改善を乗せない。
• セキュリティ問題は必ず最初に目立たせる。 スコアが高くても脆弱性があれば最優先で伝える。