Code Review

コードレビュー

PRやコード変更を体系的にレビューするための汎用スキルです。 言語非依存の共通レビュー基準と、言語/フレームワーク固有のベストプラクティスを組み合わせて使用します。

ディレクトリ構成

code-review/
├── SKILL.md (このファイル)
└── references/
    ├── typescript-best-practices.md       # TypeScript固有のチェック
    ├── authorization-review-general.md    # 認可レビュー観点（一般編）
    ├── authorization-review-postgres-rls.md  # 認可レビュー観点（PostgreSQL RLS編）
    ├── github-pr-review-actions.md        # GitHub PRレビューアクション
    ├── ci-optimized-workflow.md           # CI環境でのコスト最適化ワークフロー
    ├── incremental-review.md             # インクリメンタルレビューの詳細
    ├── skill-review.md                    # Claude Codeスキル（SKILL.md）レビュー基準
    ├── skill-overview.md                  # スキル概要（公式ドキュメント）
    └── skill-best-practices.md            # スキルベストプラクティス（公式ドキュメント）

ランタイムファイル

CI実行時に自動生成されるファイル。リポジトリにはコミットしない。

外部スキル連携

React / Next.js のベストプラクティスは、Vercel提供の vercel-react-best-practices スキルを使用する。

• リポジトリ: https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices
• インストール: npx -y skills add vercel-labs/agent-skills --skill vercel-react-best-practices --agent claude-code --yes
• カバー範囲: 非同期ウォーターフォール排除、バンドルサイズ最適化、サーバー側パフォーマンス、クライアント側データ取得、再レンダリング最適化、レンダリングパフォーマンス、高度なパターン、JavaScriptパフォーマンス（8カテゴリ、40以上のルール）

コスト最適化（CI環境）

GitHub Actions等のCI環境で実行する場合、トリアージフェーズを軽量モデル（Haiku）に委任することでコストを大幅に削減できる。 詳細は references/ci-optimized-workflow.md を参照。

トリアージ結果の活用

CI環境で事前トリアージが実行されている場合、作業ディレクトリに .pr-triage.json が存在する。 このファイルが存在する場合、以下の最適化を適用する：

1. ステップ1をスキップ — トリアージ結果の summary を使用する 2. リファレンスの選択的読み込み — required_references に含まれるものだけを読む 3. 表層チェックの省略 — surface_issues に含まれるMinor/Suggestion問題は既にチェック済みとして、Critical/Major分析に集中する 4. 差分の効率的な確認 — files のカテゴリ分類を活用し、重要度の高いファイルから優先的にレビューする

// .pr-triage.json の構造
{
  "pr_number": 123,
  "summary": "認証ミドルウェアの追加とユーザーAPI新規作成",
  "files": {
    "added": ["src/middleware/auth.ts", "src/api/users.ts"],
    "modified": ["src/routes/index.ts"],
    "deleted": []
  },
  "languages": ["typescript"],
  "frameworks": ["express"],
  "change_categories": {
    "has_auth_changes": true,
    "has_db_changes": false,
    "has_rls_changes": false,
    "has_api_changes": true,
    "has_test_changes": false,
    "has_config_changes": false,
    "has_skill_changes": false
  },
  "required_references": [
    "typescript-best-practices.md",
    "authorization-review-general.md"
  ],
  "surface_issues": [
    {
      "severity": "Minor",
      "file": "src/api/users.ts",
      "line": 15,
      "issue": "`any`型が使用されている",
      "suggestion": "具体的な型に変更する"
    }
  ],
  "diff_summary": "認証ミドルウェアを新規追加。JWTトークン検証を実装。ユーザーCRUD APIを新規作成。テストは未追加。",
  "estimated_complexity": "medium",
  "focus_areas": ["セキュリティ: JWT検証の実装", "認可: ユーザーAPIのアクセス制御"]
}

`.pr-triage.json` が存在しない場合は、従来通りステップ1から全ステップを実行する（後方互換性あり）。

インクリメンタルレビュー（PR更新時の差分最適化）

PR更新（synchronizeイベント）時に、前回のレビュー状態を活用してトークン消費を削減する。 詳細は references/incremental-review.md を参照。

`.pr-review-state.json` が存在しない場合（初回レビュー）は、インクリメンタル最適化は適用されず、フルトリアージを実行する。不正な形式の場合も警告を出力してフルトリアージを実行する。

レビューワークフロー

以下のチェックリストをコピーして進行状況を追跡します：

レビュー進捗：
- [ ] ステップ1: 変更概要の把握
- [ ] ステップ2: 共通品質チェック
- [ ] ステップ3: 言語/フレームワーク固有チェック
- [ ] ステップ4: approve/reject判定
- [ ] ステップ5: レビュー結果の出力

ステップ1: 変更概要の把握

`.pr-triage.json` が存在する場合: このファイルを読み込み、summary、files、change_categories、diff_summary を使用する。以下の手動確認はスキップしてステップ2へ進む。

変更内容を理解する。

1. 変更ファイル一覧を確認 - 変更の範囲とスコープを把握 2. コード差分を確認 - 追加・変更・削除された内容を把握 3. 変更の意図を理解 - PR説明やコミットメッセージから目的を確認

確認すべきポイント：

• 変更は単一の目的にフォーカスしているか
• スコープが適切か（1つのPRで多すぎる変更をしていないか）
• 関連する変更が漏れなく含まれているか

ステップ2: 共通品質チェック

`.pr-triage.json` が存在する場合: surface_issues に含まれるMinor/Suggestionの問題は既にチェック済み。ここではCritical/Majorレベル（セキュリティ、ロジック・正確性、パフォーマンスの重大問題）の検出に集中する。表層的な問題（命名規則、デストラクチャリング等）は再チェック不要。

言語に依存しない汎用的なチェックを実施する。

2-1. セキュリティ

認可（Authorization）の詳細レビュー：認可に関わる変更がある場合は、references/authorization-review-general.md を参照して詳細なチェックを行う。PostgreSQL RLSを使用している場合は、追加で references/authorization-review-postgres-rls.md も参照する。

2-2. ロジック・正確性

2-3. 設計・保守性

2-4. パフォーマンス

2-5. テスト

ステップ3: 言語/フレームワーク固有チェック

`.pr-triage.json` が存在する場合: required_references に記載されたリファレンスのみを読み込む。リストにないリファレンスは読み込まない（トークン節約）。

変更ファイルの言語/フレームワークに応じて、対応するリファレンスファイルを参照する。

参照可能なリファレンス：

参照ルール：

• TypeScriptの変更 → 内部リファレンスを読み込む
• React / Next.js の変更 → vercel-react-best-practices スキルを併用する（インストール済みの場合）
• 認可に関わる変更（認証/権限チェック、データアクセス制御等） → 認可リファレンス（一般編）を参照
• PostgreSQL RLSを使用している場合 → 認可リファレンス（RLS編）も追加で参照
• GitHub Actions等のCI環境でPRレビューを実行する場合 → GitHub PRレビューアクションを参照（コメント投稿・評価方法）
• SKILL.mdファイルが含まれる変更 → スキルレビューリファレンスを参照し、スキル品質チェックを追加実施する
• 複数の言語/FWにまたがる変更の場合は、すべての該当リファレンスを参照する
• リファレンスが存在しない言語の場合は、ステップ2の共通チェックのみで判断する

ステップ4: approve/reject判定

すべてのチェック結果に基づき、以下の基準でapprove/rejectを判定する。

問題の重要度と減点

判定基準

満点は10点とし、以下の基準で判定する。

判定フローチャート

Critical問題あり？ → Yes → Reject（REQUEST_CHANGES）
       ↓ No
Major問題が3件以上？ → Yes → Reject（REQUEST_CHANGES）
       ↓ No
スコア5点未満？ → Yes → Reject（REQUEST_CHANGES）
       ↓ No
Major問題が1-2件？ → Yes → Conditional Approve
       ↓ No
スコア8点以上？ → Yes → Approve
       ↓ No
Conditional Approve

ステップ5: レビュー結果の出力

`.pr-triage.json` が存在する場合: トリアージフェーズの surface_issues をレビュー結果の「検出された問題」テーブルにマージする（重複を除外）。スコアリングにはトリアージの指摘も含める。

以下のフォーマットでレビュー結果を出力する。

GitHub上でのレビュー投稿：GitHub Actions等のCI環境でPRレビューを実行している場合のみ、references/github-pr-review-actions.md を参照して、ghコマンドやインラインコメントを使用してレビュー結果をGitHub上に投稿する。ローカル環境での実行時は、結果を標準出力に表示するのみとする。

>

修正済み問題のフォローアップ：.pr-triage.json に resolved_issues が含まれる場合（インクリメンタルレビュー時）、元のインラインコメントにリプライして修正を報告する。レビュー完了後、投稿したコメントIDを .pr-review-state.json に記録する。

## Code Review: [判定結果]

### 変更概要
- **スコープ**: [変更の概要を1-2文で]
- **変更ファイル数**: [N]ファイル
- **主な言語/FW**: [検出された言語/FW]

### スコア: X/10

### 検出された問題

| # | 重要度 | ファイル | 問題 | 推奨される対応 |
|---|--------|---------|------|---------------|
| 1 | [Critical/Major/Minor/Suggestion] | [ファイルパス:行番号] | [問題の説明] | [対応方法] |

### 良い点
- [コードの良い点を具体的に記載]

### 判定
- **結果**: [Approve / Conditional Approve / Reject]
- **理由**: [判定理由の要約]

### 次のステップ
- [修正が必要な場合の具体的なアクション]

重要な注意事項

• レビューはコードの品質向上が目的であり、批判ではない。建設的なフィードバックを心がける
• 問題の指摘には必ず具体的な改善案を添える
• 変更の意図を尊重し、スタイルの好みではなく客観的な基準で判断する
• 自動検出が困難なドメイン知識やビジネスロジックの判断は、人間のレビュアーに委ねる
• Suggestionは強制ではなく、採用するかどうかは著者の判断に任せる

認可（Authorization）コードレビュー観点（一般編）

クライアント - サーバー構成での「認可」の実装をレビューするための、再現性の高いチェックリスト。

---

1. このガイドのスコープ

• 対象：Web/モバイル等の クライアント と サーバー（API/BFF） で構成される一般的なアプリ
• 目的：IDOR（他人のデータ参照/更新）、権限昇格、情報漏えい、CSRF/キャッシュ漏れ等の典型事故をレビュー段階で検出する
• 非対象：DB側でのRLSの詳細（→別ファイル「RLS編」で扱う）

---

2. コア原則（レビューでブレないための共通言語）

1. クライアントは信用しない 認可の最終判断は必ずサーバーで行う（クライアントはUXのための出し分けのみ）。 2. ユーザー文脈（userId/tenantId/role）はサーバーで確定する body/query/ヘッダ等のユーザー入力に依存してはいけない。 3. 入口（API）で必ず認可し、データ取得/更新の直前でも再確認する “入口でチェックしたから後はOK” の設計は漏れやすい。 4. 認可ロジックは分散させず、共通化・宣言化する ばらばらな if (isAdmin) が増えると漏れが起きる。 5. デフォルト拒否（Default Deny） “許可条件を満たすときだけ通す” を基本にする。

---

3. 用語の整理（レビュー時の誤解を防ぐ）

• 認証（Authentication）：あなたは誰か（ログイン、セッション検証）
• 認可（Authorization）：あなたはそれをして良いか（操作/参照の可否）
• 認可境界：サーバー（およびDB等のバックエンド）

クライアントのUI制御は境界ではない。

---

4. 入口（API/Server Action/Route）レビュー観点

すべての「外部から呼べる入口」（HTTP、RPC、Server Action 等）が対象。

✅ チェックリスト（入口共通）

• [ ] 認証が必須の入口で、必ずセッション/トークン検証をしている
• [ ] 認証の結果（userId、tenantId、scopes/roles）が サーバー側で確定している
• [ ] リクエストの userId / role / isAdmin を 信用していない
• [ ] 入力バリデーション（スキーマ検証）があり、型だけに依存していない
• [ ] エラー時に 適切なステータス（401/403/404）で返している（後述）
• [ ] “公開API” と “内部API（管理者/バッチ用）” が 同じ入口/同じ権限で混ざっていない

✅ チェックリスト（権限判定）

• [ ] 認可判定が 共通関数/ミドルレイヤに集約されている

例：requireAuth() / requireRole() / requirePermission() / authorize(action, resource)

• [ ] 認可判定が リソース単位で行われている（単なるロール判定だけで終わっていない）
• [ ] “参照可能” と “更新可能” が混同されていない（閲覧できても更新できない等）
• [ ] マルチテナントの場合、tenantId 境界が必ずチェックされている
• [ ] 認可判定に必要なデータ（所有者、メンバーシップ等）の取得が正しい
• [ ] “クライアントが送ったownerId” を根拠にしていない
• [ ] “DBにある真実” から判断している

---

5. データアクセス層レビュー観点（IDOR・漏えい対策の要）

認可が弱いとき、最後に壊れるのはここ。

✅ チェックリスト（取得・更新クエリ）

• [ ] スコープ/テナント/所有者の条件が必ず付く
• 例：WHERE tenant_id = ctx.tenantId AND ...
• [ ] “IDだけで取得” がある場合、必ず境界条件が追加されている
• NG例：getById(id) が tenant/owner を見ていない
• [ ] 更新・削除は 対象行が許可範囲か を保証する
• 例：UPDATE ... WHERE id = $id AND tenant_id = $tenantId
• [ ] “一覧取得” は フィルタ漏れしやすいので特に注意
• 例：管理者/一般ユーザーで条件が分岐する場合の漏れ
• [ ] 返却フィールドが権限に応じて適切（Field-level authorization）
• 例：email, billing, internalNotes 等を全員に返していない

✅ チェックリスト（共通化）

• [ ] “安全なクエリの型” を共通化できている
• 例：scopedToTenant(ctx).projects.findMany(...)
• [ ] 直書きクエリが散在していない（レビュー漏れを起こす）

---

6. クライアント側（UI/UXの認可）レビュー観点

セキュリティ境界ではないが、事故の予兆を見つける重要ポイント。

✅ チェックリスト（Client）

• [ ] UIの出し分けはしているが、サーバー側の認可に依存している

（UIで隠してもサーバーが許可しない）

• [ ] クライアントで isAdmin 等を ローカルストレージ/URL/任意入力から作っていない
• [ ] “権限情報” はサーバーが確定したデータから来ている（/me 等）
• [ ] 401/403 の扱いが適切
• 401：ログイン誘導
• 403：権限不足表示（必要なら 404 相当の扱い）
• [ ] ユーザー固有データが 共有キャッシュで混ざらない（特にSSR/キャッシュ層）

---

7. セキュリティ周辺（認可とセットで事故りやすい）

✅ CSRF（Cookieベースのセッションを使う場合は要注意）

• [ ] 状態変更（POST/PUT/PATCH/DELETE）でCSRF対策がある

例：Origin/Referer検証、CSRFトークン、SameSite運用の前提が明文化

✅ CORS / Credentials

• [ ] Access-Control-Allow-Origin: * と credentials: true の組み合わせをしていない
• [ ] 許可オリジンが明示され、環境ごとに正しく分離されている

✅ キャッシュ

• [ ] ユーザー固有レスポンスはキャッシュされない、またはユーザーごとに分離される

例：Vary: Cookie/Authorization、キャッシュキーに user を含める、no-store

• [ ] “認可結果” 自体を共有キャッシュしていない

✅ 監査ログ

• [ ] 重要操作（権限変更、支払い、公開/非公開など）に監査ログがある
• [ ] ログに機密情報（トークン、パスワード、個人情報の過剰）が入っていない

---

8. エラーハンドリング方針（403 vs 404）

レビューで揺れやすいので、チーム方針を決める。

• 401：未認証（ログインしていない/セッション無効）
• 403：認証済みだが権限なし（存在を明示してよい）
• 404：存在秘匿したいリソース（“見つからない” と返す）

✅ チェックリスト

• [ ] リソース種別ごとに 403/404 の方針が明文化されている
• [ ] 実装が方針に沿って一貫している（入口ごとにブレていない）

---

9. よくあるアンチパターン（見つけたら指摘）

• [ ] クライアント由来の userId を信用してクエリする（典型IDOR）
• [ ] “role=admin” をクライアント入力で受け取り、サーバーが信じる
• [ ] エンドポイント追加時に requireAuth/authorize を呼び忘れる
• [ ] 一部のAPIだけ “内部用” と言って認可を省略する（後で外部から叩かれる）
• [ ] 権限不足でも詳細なエラーメッセージで存在や内部情報が漏れる

---

10. 最低限のテスト要件（PRのDoD）

• [ ] 代表的なロール/権限で “できる/できない” のテストがある
• [ ] 否定テスト（他人のIDでアクセスして拒否される）がある
• [ ] マルチテナントの場合、tenant跨ぎのアクセス拒否テストがある
• [ ] 401/403/404 の期待値テストがある（存在秘匿の方針を含む）

---

11. レビュー質問テンプレ（迷ったらこれを問う）

• その userId/tenantId/role はどこで確定した？（入力じゃない？）
• この操作は「誰が」「どの条件で」許可される？コードで表現できている？
• リソースIDだけで操作できない？（境界条件は？）
• 返却データに “見せてはいけないフィールド” は混ざってない？
• キャッシュや並列リクエストで、他ユーザーに漏れる経路はない？

認可（Authorization）コードレビュー観点（PostgreSQL RLS編）

一般編に 追加で 適用する、PostgreSQL Row Level Security（RLS）利用時のレビュー観点。

---

1. このガイドの位置づけ

• このファイルは「一般編」を置き換えない

→ 一般編 + RLS編 の二段でレビューする

• 目的：RLS の“効いていない/漏れる/バイパスされる”事故（特にコネクションプールや特権ロール起因）を防ぐ

---

2. RLS採用時のコア原則

1. RLSは最後の防衛線（whereの書き忘れ事故を止める） ただし入口（サーバー）での認可を省略する理由にはしない。 2. DBに渡す “ユーザー文脈” はサーバーが確定し、トランザクションローカルで注入する 3. RLSをバイパスできるDBロール/経路を最小化し、隔離する

---

3. 入口〜DBアクセスの“標準手順”があるか

RLS採用で最重要。実装が分散すると破綻する。

✅ チェックリスト（標準手順）

• [ ] すべてのDBアクセスが 共通ラッパー（RLSコンテキスト注入） を経由する
• [ ] ラッパーが 必ずトランザクションを開始する
• [ ] トランザクション内で set_config(..., true)（=ローカル設定）で文脈注入している
• [ ] 文脈注入の後にクエリを実行している（順序保証）
• [ ] 直接 db.query() している箇所が原則禁止（Lint/レビューでブロック）

目標：レビュー時に「このクエリはRLSコンテキスト下で実行される」と一目で分かる構造。

---

4. コネクションプール/設定漏れ（RLS最大の落とし穴）

✅ チェックリスト（漏れ防止）

• [ ] set_config の第三引数が true（トランザクションローカル） になっている
• false（セッション全体に残る）は原則NG（プールで別リクエストに漏れる）
• [ ] トランザクション外で set_config していない
• [ ] 例外時にトランザクションが必ず終了（rollback）し、接続がプールに戻る
• [ ] RLSコンテキスト注入を忘れた場合に“検知できる仕組み”がある
• 例：RLSポリシーが current_setting 未設定時は拒否（Default Deny）

---

5. DBロール設計（RLSが効かない事故を防ぐ）

RLSはロール/権限の設定で簡単に無効化される。

✅ チェックリスト（アプリ接続ロール）

• [ ] アプリ接続ロールが superuser ではない
• [ ] アプリ接続ロールに BYPASSRLS が付与されていない
• [ ] アプリ接続ロールが “テーブルオーナー” になっていない、または方針が明文化されている
• オーナー運用の場合：FORCE ROW LEVEL SECURITY の採用有無が明確

✅ チェックリスト（特権経路の隔離）

• [ ] 管理者/バッチでRLSを超える必要がある場合、専用ロール/専用接続/専用モジュールで隔離
• [ ] “通常API” が特権ロールを使っていない（RLSが無意味になる）
• [ ] 特権経路は監査ログ/追加テスト/追加レビュー対象になっている

---

6. RLSポリシー設計（過不足・穴・更新漏れ）

✅ チェックリスト（ポリシー網羅）

• [ ] 対象テーブルでRLSが 有効化されている
• [ ] SELECT / INSERT / UPDATE / DELETE の必要操作に対してポリシーが揃っている
• “読めるが更新が穴” “insertだけ穴” が起きやすい
• [ ] Default Deny（未一致なら拒否）になっている
• [ ] マルチテナントの場合、tenant_id 条件が常に入る設計になっている
• [ ] WITH CHECK（INSERT/UPDATE時の整合）を忘れていない
• 例：tenant_id を別テナントに差し替えられない

✅ チェックリスト（ポリシー条件の安全性）

• [ ] RLSが参照する “ユーザー文脈” が サーバー確定値に基づく
• current_setting('app.user_id') 等
• [ ] “role/adminフラグ” のような特権判定を アプリが任意に注入できる値に依存していない
• 推奨：DB内の membership/roles テーブルを参照して EXISTS で判断
• [ ] ポリシーが過度に複雑でない（複雑ならテスト/ドキュメントがセット）

---

7. SECURITY DEFINER / View / Function（RLS迂回の温床）

RLS採用でも、ここで抜け道ができる。

✅ チェックリスト

• [ ] SECURITY DEFINER 関数が存在する場合、利用目的と権限境界が明文化されている
• [ ] SECURITY DEFINER は search_path 固定等の安全策がある（SQL注入/オブジェクトすり替え対策）
• [ ] View 経由でRLSが期待通り効くかを確認している
• “ビューは安全” と決めつけない（実際の挙動は定義や権限で変わる）
• [ ] 特権関数/ビューを通常コードパスから呼べないように隔離している

---

8. ORM/クエリビルダとRLSの整合

✅ チェックリスト

• [ ] トランザクション境界がORMの抽象化で崩れていない
• “ラッパーでBEGINしたつもりが別コネクションでクエリが走る” を防ぐ
• [ ] 1リクエスト内の複数クエリが 同一トランザクション/同一接続 で実行されることが保証されている
• [ ] バルク処理/バッチがRLS前提なら、同じラッパーを使っている

---

9. テスト要件（RLS利用時は統合テストが必須）

✅ 最低限のDoD

• [ ] アプリ接続ロールで、ユーザーAがユーザーBの行を 読めない/更新できない 統合テスト
• [ ] tenant跨ぎの拒否テスト（マルチテナントの場合）
• [ ] RLS文脈未注入（app.user_id 未設定）時に 拒否される テスト
• [ ] 特権経路（管理者/バッチ）がある場合：通常経路から到達できないテスト

---

10. RLS編レビュー質問テンプレ

• このDBアクセスは必ず withRlsContext()（等）を通っている？
• set_config(..., true) がトランザクション内で呼ばれている？
• アプリ接続ロールで本当にRLSは効いている？（bypass/owner/superuserではない？）
• SELECTだけでなくUPDATE/INSERT/DELETEでも同様に守れている？
• SECURITY DEFINER / View が抜け道になっていない？

---

11. よくあるRLSアンチパターン

• [ ] set_config(..., false) でセッション設定を残し、プールでユーザーが混ざる
• [ ] 一部のコードパスがRLSラッパーを通らずに直クエリ
• [ ] アプリが特権ロールで接続しており、RLSが実質無効
• [ ] SELECTは守ったが、UPDATE/INSERTの WITH CHECK がなく差し替え可能
• [ ] SECURITY DEFINER 関数で意図せずRLSを迂回

---

CI環境でのコスト最適化ワークフロー

Opus単体で全ステップを実行する構成から、Haiku（トリアージ）+ Opus（深層レビュー）の2ジョブ構成に変更することで、トークン使用量を大幅に削減する。

目次

1. 最適化の概要 2. GitHub Actionsワークフロー設定例 3. Haiku使用時の注意点 4. 段階的な導入

---

1. 最適化の概要

従来構成（Opus単体）

[Opus] PR情報取得 → ファイル分類 → リファレンス全読み → 全チェック → 判定 → 投稿
       ~40ターン、リファレンス全読み込み

最適化構成（Haiku + Opus）

[Haiku] PR情報取得 → ファイル分類 → 表層チェック → .pr-triage.json出力
        ~10ターン

[Opus]  トリアージ読み込み → 必要なリファレンスのみ読み → Critical/Major集中 → 判定 → 投稿
        ~20ターン、リファレンス選択的読み込み

インクリメンタル構成（Haiku + Opus、PR更新時）

[Cache] 前回の .pr-review-state.json を復元

[Haiku] PR差分取得 → 前回との差分比較 → 変更ファイルのみ表層チェック → .pr-triage.json（incremental）出力
        ~5-8ターン（未変更ファイルのチェックをスキップ）

[Opus]  トリアージ読み込み → resolved_issuesへのコメントリプライ → 変更箇所のCritical/Major集中 → 判定 → 投稿
        ~15-20ターン

[Cache] .pr-review-state.json を保存（コメントID含む）

期待されるコスト削減効果

Haikuの料金はOpusの約1/50（入力）〜1/100（出力）のため、Haikuフェーズの追加コストは無視できるレベル。

インクリメンタルモード時の追加削減（PR更新時）：

---

2. GitHub Actionsワークフロー設定例

完全な設定例（Vertex AI経由）

name: Automated PR Review (Optimized)

on:
  pull_request:
    types: [opened, synchronize, reopened]
    paths-ignore:
      - '.claude/skills/**'
      - '*.md'
      - 'LICENSE'

permissions:
  contents: read
  pull-requests: write
  issues: write
  id-token: write  # Vertex AI Workload Identity Federation用

concurrency:
  group: pr-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  # ==========================================================
  # Phase 1: トリアージ（Haiku - 軽量・高速・低コスト）
  # ==========================================================
  triage:
    if: github.actor != 'dependabot[bot]'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Restore previous review state
        id: restore-state
        uses: actions/cache/restore@v4
        with:
          path: .pr-review-state.json
          key: pr-review-state-${{ github.event.pull_request.number }}-dummy
          restore-keys: |
            pr-review-state-${{ github.event.pull_request.number }}-

      - name: Authenticate to Google Cloud
        id: auth
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
          service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}

      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Install skills
        run: npx -y skills add xtone/ai_development_tools --skill pr-triage --agent claude-code --yes

      - name: Run Triage with Haiku
        uses: anthropics/claude-code-action@v1
        env:
          ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
          CLOUD_ML_REGION: global
        with:
          github_token: ${{ steps.app-token.outputs.token }}
          use_vertex: "true"
          prompt: |
            PR #${{ github.event.pull_request.number }} のトリアージを実行してください。
            `.pr-review-state.json` が存在する場合はインクリメンタルモードで実行してください。
            /pr-triage
          claude_args: |
            --model claude-haiku-4-5@20251001
            --max-turns 10
            --allowedTools "Skill,Read,Glob,Grep,Bash(gh:*),Write"

      - name: Upload triage results
        uses: actions/upload-artifact@v4
        with:
          name: pr-triage
          path: |
            .pr-triage.json
            .pr-review-state.json
          retention-days: 1

  # ==========================================================
  # Phase 2: 深層レビュー（Opus - 高精度・Critical/Major集中）
  # ==========================================================
  review:
    needs: triage
    if: github.actor != 'dependabot[bot]'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Download triage results
        uses: actions/download-artifact@v4
        with:
          name: pr-triage
          path: .

      - name: Restore previous review state
        uses: actions/cache/restore@v4
        with:
          path: .pr-review-state.json
          key: pr-review-state-${{ github.event.pull_request.number }}-dummy
          restore-keys: |
            pr-review-state-${{ github.event.pull_request.number }}-

      - name: Authenticate to Google Cloud
        id: auth
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
          service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}

      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Install vercel-react-best-practices skill
        run: npx -y skills add vercel-labs/agent-skills --skill vercel-react-best-practices --agent claude-code --yes

      - name: Run Claude Code PR Review via Vertex AI
        uses: anthropics/claude-code-action@v1
        env:
          ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
          CLOUD_ML_REGION: global

          CLAUDE_CODE_ENABLE_TELEMETRY: "1"
          OTEL_METRICS_EXPORTER: "otlp"
          OTEL_LOGS_EXPORTER: "otlp"
          OTEL_EXPORTER_OTLP_PROTOCOL: "http/protobuf"
          OTEL_EXPORTER_OTLP_ENDPOINT: ${{ secrets.GRAFANA_OTLP_ENDPOINT }}
          OTEL_EXPORTER_OTLP_HEADERS: "Authorization=Basic ${{ secrets.GRAFANA_OTLP_TOKEN }}"
          OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE: "cumulative"
          OTEL_METRIC_EXPORT_INTERVAL: "30000"
          OTEL_LOGS_EXPORT_INTERVAL: "5000"
          OTEL_RESOURCE_ATTRIBUTES: "github.repository=${{ github.repository }},github.repository_owner=${{ github.repository_owner }},github.actor=${{ github.actor }},github.event_name=${{ github.event_name }},deployment.environment=production"
        with:
          github_token: ${{ steps.app-token.outputs.token }}
          use_vertex: "true"
          show_full_output: "true"
          prompt: |
            PR #${{ github.event.pull_request.number }} をコードレビューしてください。

            重要: まず `.pr-triage.json` ファイルを読み込んでください。トリアージフェーズの分析結果が含まれています。
            このファイルの内容に基づき、必要なリファレンスのみを読み込み、Critical/Majorレベルの問題に集中してレビューを行ってください。

            ## 修正済み問題へのフォローアップ（インクリメンタルレビュー時）

            `.pr-triage.json` の `resolved_issues` に要素がある場合、各問題の `comment_id` に対してリプライを投稿してください：

gh api repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/comments/{comment_id}/replies \ -f body="この問題は修正されました。"

            ## レビュー投稿

            レビュー完了後、必ず以下の2つのアクションをGitHub上で実行してください。
            1. 問題のあるコード行にインラインコメントを投稿する（mcp__github_inline_comment__create_inline_comment または gh api を使用）
            2. `gh pr review` コマンドでレビュー結果（approve/request-changes）を投稿する

            ## レビュー状態の保存

            レビュー完了後、投稿したインラインコメントのIDを記録した `.pr-review-state.json` を作成してください：

            1. `gh api repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/comments --jq '[.[] | select(.user.login == "github-actions[bot]" or .user.type == "Bot") | {comment_id: .id, file: .path, line: .line, issue: (.body | split("\n") | first), commit_id: .commit_id}]'` で投稿済みコメントを取得
            2. 以下の構造で `.pr-review-state.json` を出力する：

{ "pr_number": ${{ github.event.pull_request.number }}, "last_reviewed_commit": "<現在のHEADコミットSHA>", "last_reviewed_at": "<現在時刻（ISO 8601）>", "triage": { "surface_issues": [<.pr-triage.jsonのsurface_issuesをコピー（carried_over含む）>] }, "review_comments": [<上記で取得したコメント情報>] }

            テキスト出力のみで終了せず、必ずGitHub上にレビューを投稿してください。

            /code-review
          claude_args: |
            --model claude-opus-4-6@default
            --max-turns 25
            --allowedTools "Skill,Read,Glob,Grep,WebSearch,mcp__github_inline_comment__create_inline_comment,Bash(gh:*),Write"

      - name: Save review state to cache
        if: always()
        uses: actions/cache/save@v4
        with:
          path: .pr-review-state.json
          key: pr-review-state-${{ github.event.pull_request.number }}-${{ github.sha }}

---

3. Haiku使用時の注意点

Vertex AIでのHaikuモデルID

Vertex AI経由でHaikuを使用する場合、モデルIDは環境によって異なる場合がある。 使用可能なモデルIDを事前に確認すること：

# 利用可能なモデル一覧の確認（gcloud CLI）
gcloud ai models list --region=global --filter="displayName:claude"

一般的なVertex AIのモデルID：

• claude-haiku-4-5@20251001 (Claude 4.5 Haiku)
• claude-opus-4-6@default (Claude Opus 4.6)

トリアージ失敗時のフォールバック

トリアージジョブが失敗した場合、レビュージョブはスキップされる。 必要に応じて、トリアージなしでOpus単体レビューを行うフォールバックジョブを追加できる：

  review-fallback:
    needs: triage
    if: failure() && github.actor != 'dependabot[bot]'
    runs-on: ubuntu-latest
    steps:
      # トリアージなしでOpus単体レビュー（従来構成と同じ）
      # ...

---

4. 段階的な導入

Step 1: まず効果を測定

既存のワークフローと並行して最適化版を実行し、以下を比較する：

• トークン使用量（OTel メトリクス）
• レビュー品質（検出された問題の差分）
• 実行時間

Step 2: チューニング

実測結果に基づき以下を調整：

• Haikuの max-turns（デフォルト10、必要に応じて増減）
• Opusの max-turns（デフォルト25、トリアージ品質次第で削減可能）
• トリアージプロンプトの表層チェック項目

Step 3: 本番切り替え

品質に問題がなければ、最適化版に完全移行する。

GitHub PRレビューアクション

GitHub Actions等のCI環境でPRレビューを実行する際の、コメント投稿・評価方法のリファレンス。

---

1. このガイドのスコープ

• 対象：GitHub Actions等のCI環境でのClaude Code実行時のみ
• 目的：レビュー結果を適切な形式でGitHub上に投稿する
• 前提：gh CLI が利用可能であり、適切な権限（GITHUB_TOKEN等）が設定されていること
• 非対象：ローカル環境での実行（ローカルではレビュー結果を標準出力に表示するのみ）

CI環境の判定

以下の環境変数でCI環境かどうかを判定できる：

これらが設定されていない場合は、このリファレンスの内容（GitHub上への投稿）は実行しない。

---

2. PR情報の取得

レビュー開始前に、PRの全体像を把握する。

基本情報の取得

# PR基本情報の取得
gh pr view <PR番号> --json title,body,author,createdAt,headRefName,baseRefName,mergeable,reviewDecision

# 変更ファイル一覧の取得
gh pr diff <PR番号> --name-only

# コード差分の取得
gh pr diff <PR番号>

# 既存のレビューとコメントの確認
gh pr view <PR番号> --json reviews,comments

取得すべき情報

---

3. インラインコメントの投稿

具体的なファイル・行番号が特定できる問題は、インラインコメントで指摘する。

MCPツールを使用する場合

mcp__github_inline_comment__create_inline_comment

このツールが利用可能な場合は、ファイルパスと行番号を指定してインラインコメントを投稿できる。

gh APIを使用する場合

gh api repos/{owner}/{repo}/pulls/{pr_number}/comments \
  -f body="コメント内容" \
  -f commit_id="$(gh pr view <PR番号> --json headRefOid -q .headRefOid)" \
  -f path="ファイルパス" \
  -F line=行番号 \
  -f side="RIGHT"

インラインコメントのベストプラクティス

• 問題の重要度を明示: **Critical**:, **Major**:, **Minor**: などのプレフィックスを使用
• 具体的な修正案を提示: 問題だけでなく解決方法も記載
• コード例を含める: 可能であれば修正後のコードスニペットを提示

---

4. レビュー結果の投稿

レビュー完了後、結果をPRに投稿する。

投稿パターン

パターン1: Critical問題あり → REQUEST_CHANGES

マージ前に必ず修正が必要な問題がある場合。

gh pr review <PR番号> \
  --request-changes \
  --body "## ⚠️ 変更が必要です

以下のCritical問題が検出されました。修正してから再度レビューをリクエストしてください。

### Critical問題

- [問題の概要] - 詳細はインラインコメントを参照

**注**: 具体的な問題箇所と修正方法はファイルのインラインコメントで指摘しています。

修正後、このレビューを解決してください。"

パターン2: Major/Minor問題あり → 条件付きAPPROVE

重大ではないが改善すべき問題がある場合。

gh pr review <PR番号> \
  --approve \
  --body "## ✅ 条件付きでApprove

レビューを完了しました。重大な問題は見つかりませんでしたが、いくつかの改善点があります。

### 分析結果

#### 📦 Skill Quality: X/10
- 良い点: [概要]
- 改善点: [件数]件の指摘（インラインコメント参照）

### 改善項目

**注**: 具体的な改善箇所と推奨される対応は、各ファイルのインラインコメントで詳しく説明しています。

これらは次のイテレーションで対応することをお勧めします。"

パターン3: 問題なし → APPROVE

問題が検出されなかった場合。

gh pr review <PR番号> \
  --approve \
  --body "## ✅ Approved

レビューを完了しました。問題は見つかりませんでした。

### 分析結果

#### 📦 Skill Quality: 10/10
✅ フロントマターが正しく設定されています
✅ descriptionにトリガー条件が明記されています
✅ ディレクトリ構造が適切です
✅ 参照ファイルがすべて存在します

### Summary

マージして問題ありません。"

---

5. レビュー結果のフォーマット

標準フォーマット

## Code Review: [判定結果]

### 変更概要
- **スコープ**: [変更の概要を1-2文で]
- **変更ファイル数**: [N]ファイル
- **主な言語/FW**: [検出された言語/FW]

### スコア: X/10

### 検出された問題

| # | 重要度 | ファイル | 問題 | 推奨される対応 |
|---|--------|---------|------|---------------|
| 1 | [Critical/Major/Minor/Suggestion] | [ファイルパス:行番号] | [問題の説明] | [対応方法] |

### 良い点
- [コードの良い点を具体的に記載]

### 判定
- **結果**: [Approve / Conditional Approve / Reject]
- **理由**: [判定理由の要約]

### 次のステップ
- [修正が必要な場合の具体的なアクション]

---

6. GitHub Actionsでの実行時の注意事項

権限設定

GitHub Actionsで実行する場合、以下の権限が必要：

permissions:
  contents: read
  pull-requests: write
  issues: write

allowedTools の設定（重要）

claude-code-action の claude_args で --allowedTools を指定する場合、以下のツールをすべて含めること。不足するとスキルの実行やコード読み取りに失敗し、レビューが正常に行われない。

設定例：

--allowedTools "Skill,Read,Glob,Grep,WebSearch,Bash(gh:*)"

注意: allowedTools を指定しない場合は全ツールが利用可能。指定する場合は上記の必須ツールを漏れなく含めること。過去にこの設定不足により、17ターン消費してもレビューが投稿されない問題が発生した。

環境変数

gh CLIが正しく動作するために必要：

env:
  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

または、GitHub Appトークンを使用：

env:
  GH_TOKEN: ${{ steps.app-token.outputs.token }}

自動レビューの注意事項

• レビューはAIによる自動分析であり、最終的な判断は人間のレビュアーが行う必要がある
• スキルの実用性やドメイン知識が必要な判断は人間のレビューが必要
• 自動レビューの結果を過信せず、補助的なツールとして活用する

---

7. GitHub Actionsワークフローの設定例

コスト最適化版: Haiku + Opus の2ジョブ構成でトークンコストを50-60%削減できる設定例は ci-optimized-workflow.md を参照。

anthropics/claude-code-action を使用した、実運用で検証済みの設定例。

name: Automated PR Review

on:
  pull_request:
    types: [opened, synchronize, reopened]
    paths-ignore:
      - '.claude/skills/**'
      - '*.md'
      - 'LICENSE'

permissions:
  contents: read
  pull-requests: write
  issues: write

concurrency:
  group: pr-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  automated-review:
    if: github.actor != 'dependabot[bot]'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Install vercel-react-best-practices skill
        run: npx -y skills add vercel-labs/agent-skills --skill vercel-react-best-practices --agent claude-code --yes

      - name: Run Claude Code PR Review
        uses: anthropics/claude-code-action@v1
        with:
          github_token: ${{ steps.app-token.outputs.token }}
          prompt: |
            PR #${{ github.event.pull_request.number }} をコードレビューしてください。

            /code-review
          claude_args: |
            --max-turns 40
            --allowedTools "Skill,Read,Glob,Grep,WebSearch,Bash(gh:*)"

設定のポイント

Vertex AI経由の場合: use_vertex: "true" と ANTHROPIC_VERTEX_PROJECT_ID、CLOUD_ML_REGION の設定が追加で必要。認証には Workload Identity Federation を使用し、id-token: write 権限も追加する。

---

8. チェックリスト

レビュー投稿前

• [ ] PR情報を取得し、変更の意図を理解した
• [ ] 変更ファイルを確認し、差分を分析した
• [ ] 問題を重要度別に分類した
• [ ] インラインコメントで具体的な箇所を指摘した

レビュー投稿時

• [ ] 適切なレビューアクション（approve/request-changes/comment）を選択した
• [ ] レビュー本文に分析結果のサマリーを含めた
• [ ] インラインコメントへの参照を含めた
• [ ] 次のステップを明示した

インクリメンタルレビュー（PR更新時の差分最適化）

PR更新（synchronizeイベント）時に、前回のレビュー状態を活用してトークン消費を削減する。

.pr-review-state.json の構造

CI環境で actions/cache により実行間で永続化される。

注意: .pr-review-state.json が不正な形式（JSONパースエラー等）の場合は、警告を出力してフルトリアージを実行する。破損した状態ファイルに基づいてインクリメンタルモードを実行してはならない。

{
  "pr_number": 123,
  "last_reviewed_commit": "abc123def",
  "last_reviewed_at": "2026-03-06T10:00:00Z",
  "triage": {
    "surface_issues": [
      {
        "severity": "Minor",
        "file": "src/api/users.ts",
        "line": 15,
        "issue": "`any`型が使用されている",
        "suggestion": "具体的な型に変更する"
      }
    ]
  },
  "review_comments": [
    {
      "comment_id": 789,
      "file": "src/api/users.ts",
      "line": 15,
      "severity": "Minor",
      "issue": "`any`型が使用されている",
      "commit_id": "abc123def"
    }
  ]
}

インクリメンタルトリアージの動作

.pr-review-state.json が存在する場合、トリアージジョブは以下の最適化を行う：

1. 変更差分の比較 — last_reviewed_commit 以降に変更されたファイルを特定する 2. Minor/Suggestionのスキップ — 前回から変更のないファイルに対する surface_issues はそのまま引き継ぎ、再チェックしない（"carried_over": true を付与） 3. 変更ファイルのみ再チェック — 変更があったファイルについてのみ、表層チェックを実行する 4. 解決済み問題の検出 — 前回の surface_issues のうち、該当行が修正されたものを resolved_issues として出力する

インクリメンタルモードの .pr-triage.json 追加フィールド

{
  "incremental": true,
  "base_commit": "abc123def",
  "changed_since_last_review": ["src/api/users.ts"],
  "unchanged_since_last_review": ["src/routes/index.ts"],
  "resolved_issues": [
    {
      "comment_id": 789,
      "file": "src/api/users.ts",
      "line": 15,
      "issue": "`any`型が使用されている",
      "resolution": "fixed"
    }
  ],
  "surface_issues": [
    {
      "severity": "Minor",
      "file": "src/routes/index.ts",
      "line": 42,
      "issue": "マジックナンバーの使用",
      "suggestion": "定数に抽出する",
      "carried_over": true
    }
  ]
}

修正済み問題へのコメントリプライ

レビュージョブは resolved_issues に含まれる問題について、元のインラインコメント（comment_id）にリプライする：

gh api repos/{owner}/{repo}/pulls/{pr}/comments/{comment_id}/replies \
  -f body="この問題は修正されました。"

`.pr-review-state.json` が存在しない場合（初回レビュー）は、インクリメンタル最適化は適用されず、フルトリアージを実行する。

Claude Code スキル ベストプラクティス（公式ドキュメント）

このドキュメントはClaude公式ドキュメントに基づくスキル作成のベストプラクティスです。

目次

• コア原則
• スキル構造
• 命名規則
• 効果的な説明の書き方
• 段階的開示パターン
• ワークフローとフィードバックループ
• コンテンツガイドライン
• 一般的なパターン
• 避けるべきアンチパターン
• 効果的なスキルのチェックリスト

---

コア原則

簡潔さが鍵

コンテキストウィンドウは共有リソース。スキル内のすべてのトークンに価値があるか検証する。

自問すべき質問:

• 「Claudeは本当にこの説明が必要ですか？」
• 「Claudeがこれを知っていると仮定できますか？」
• 「このパラグラフはそのトークンコストに見合う価値がありますか？」

良い例（約50トークン）:

import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

悪い例（約150トークン）: PDFが何であるかの説明、ライブラリの選択理由、インストール方法の説明など冗長な記述。

適切な自由度を設定する

---

スキル構造

YAMLフロントマター要件

---
name: your-skill-name      # 必須
description: ...           # 必須
---

`name`フィールド:

• 最大64文字
• 小文字、数字、ハイフンのみ
• XMLタグ禁止
• 予約語禁止: 「anthropic」「claude」

`description`フィールド:

• 空でない
• 最大1024文字
• XMLタグ禁止
• 何をするか + いつ使用するか の両方を含める

---

命名規則

推奨: 動名詞形（動詞 + -ing）

スキルが提供するアクティビティを明確に説明する：

• processing-pdfs
• analyzing-spreadsheets
• managing-databases
• testing-code
• writing-documentation

許容される代替案

• 名詞句: pdf-processing, spreadsheet-analysis
• アクション指向: process-pdfs, analyze-spreadsheets

避けるべき名前

• 曖昧: helper, utils, tools
• 過度に一般的: documents, data, files
• 予約語含む: anthropic-helper, claude-tools

---

効果的な説明の書き方

必須: 三人称で書く

説明はシステムプロンプトに挿入されるため、視点の不一致は発見の問題を引き起こす。

必須: 具体的で主要な用語を含める

効果的な例

PDF処理スキル:

description: PDFファイルからテキストと表を抽出し、フォームに入力し、ドキュメントをマージします。PDFファイル、フォーム、またはドキュメント抽出について言及している場合に使用してください。

Gitコミットヘルパースキル:

description: gitの差分を分析して、説明的なコミットメッセージを生成します。ユーザーがコミットメッセージの作成またはステージされた変更のレビューを支援するよう求めている場合に使用してください。

避けるべき曖昧な説明

description: ドキュメントに役立ちます      # 何の？いつ？
description: データを処理します           # どんなデータ？どう処理？
description: ファイルでいろいろなことをします  # 具体性がない

---

段階的開示パターン

SKILL.mdのガイドライン

• 500行以下に保つ
• 超える場合はコンテンツを別のファイルに分割
• 参照は1レベル深さまで

推奨ディレクトリ構造

skill-name/
├── SKILL.md              # メイン指示（トリガー時にロード）
├── FORMS.md              # フォーム入力ガイド（必要に応じてロード）
├── reference.md          # APIリファレンス（必要に応じてロード）
├── examples.md           # 使用例（必要に応じてロード）
└── scripts/
    ├── analyze_form.py   # ユーティリティスクリプト
    └── validate.py       # 検証スクリプト

パターン1: 参照付きの高レベルガイド

# PDF処理

## クイックスタート
[基本的なコード例]

## 高度な機能
**フォーム入力**: 完全なガイドについては[FORMS.md](FORMS.md)を参照
**APIリファレンス**: すべてのメソッドについては[REFERENCE.md](REFERENCE.md)を参照

パターン2: ドメイン固有の組織

bigquery-skill/
├── SKILL.md (概要とナビゲーション)
└── reference/
    ├── finance.md (収益、請求指標)
    ├── sales.md (機会、パイプライン)
    └── product.md (API使用、機能)

深いネストを避ける

悪い例（深すぎる）:

SKILL.md → advanced.md → details.md → sub-details.md

良い例（1レベル深い）:

SKILL.md → advanced.md
SKILL.md → reference.md
SKILL.md → examples.md

長い参照ファイルには目次を

100行以上の参照ファイルには上部に目次を含める：

# APIリファレンス

## 目次
- 認証とセットアップ
- コアメソッド（作成、読み取り、更新、削除）
- 高度な機能
- エラー処理パターン
- コード例

## 認証とセットアップ
...

---

ワークフローとフィードバックループ

複雑なタスクにはチェックリストを使用

## 研究統合ワークフロー

このチェックリストをコピーして進行状況を追跡します：

- [ ] ステップ1：すべてのソースドキュメントを読む
- [ ] ステップ2：主要なテーマを特定する
- [ ] ステップ3：クレームを相互参照する
- [ ] ステップ4：構造化された要約を作成する
- [ ] ステップ5：引用を確認する

フィードバックループを実装

一般的なパターン: バリデータを実行 → エラーを修正 → 繰り返す

1. コンテンツを作成する
2. チェックリストに対してレビューする
3. 問題が見つかった場合：
   - 各問題をメモする
   - コンテンツを修正する
   - チェックリストを再度レビューする
4. すべての要件が満たされたときのみ続行

---

コンテンツガイドライン

時間に敏感な情報を避ける

悪い例:

2025年8月前にこれを行っている場合は、古いAPIを使用してください。

良い例:

## 現在の方法
v2 APIエンドポイントを使用します

## 古いパターン
<details>
<summary>レガシーv1 API（2025-08で廃止）</summary>
...
</details>

一貫した用語を使用する

良い（一貫性）:

• 常に「APIエンドポイント」
• 常に「フィールド」
• 常に「抽出」

悪い（一貫性がない）:

• 「APIエンドポイント」「URL」「APIルート」「パス」を混ぜる
• 「フィールド」「ボックス」「要素」「コントロール」を混ぜる

---

一般的なパターン

テンプレートパターン

## レポート構造

常にこの正確なテンプレート構造を使用してください：

# [分析タイトル]

## エグゼクティブサマリー
[主要な調査結果の1段落の概要]

## 主要な調査結果
- 調査結果1
- 調査結果2

## 推奨事項
1. 具体的で実行可能な推奨事項

例パターン

入出力ペアを提供：

## コミットメッセージ形式

**例1：**
入力：JWTトークンを使用したユーザー認証を追加しました
出力：
feat(auth): JWT ベースの認証を実装する

条件付きワークフローパターン

## ドキュメント変更ワークフロー

1. 変更タイプを決定します：

   **新しいコンテンツを作成していますか？** → 「作成ワークフロー」に従う
   **既存のコンテンツを編集していますか？** → 「編集ワークフロー」に従う

---

避けるべきアンチパターン

Windowsスタイルのパス

• 良い: scripts/helper.py, reference/guide.md
• 避ける: scripts\helper.py, reference\guide.md

多くのオプションを提供しすぎる

悪い例:

pypdfまたはpdfplumberまたはPyMuPDFまたはpdf2imageまたは...を使用できます

良い例:

テキスト抽出にはpdfplumberを使用してください。
スキャンされたPDFでOCRが必要な場合は、代わりにpdf2imageを使用。

---

効果的なスキルのチェックリスト

コア品質

• [ ] 説明は具体的で主要な用語を含む
• [ ] 説明にはスキルが何をするか、いつ使用するかが含まれる
• [ ] SKILL.mdボディは500行以下
• [ ] 追加の詳細は別のファイルにある（必要な場合）
• [ ] 時間に敏感な情報がない
• [ ] 全体で一貫した用語
• [ ] 例は抽象的ではなく具体的
• [ ] ファイル参照は1レベル深い
• [ ] 段階的開示が適切に使用されている
• [ ] ワークフローに明確なステップがある

コードとスクリプト（該当する場合）

• [ ] スクリプトは問題を解決し、Claudeに任せない
• [ ] エラー処理は明示的で有用
• [ ] マジックナンバーがない（すべての値が正当化されている）
• [ ] 必要なパッケージが指示にリストされている
• [ ] スクリプトに明確なドキュメントがある
• [ ] Windowsスタイルのパスがない（すべてフォワードスラッシュ）
• [ ] 重要な操作の検証/確認ステップ
• [ ] 品質が重要なタスクにフィードバックループが含まれる

テスト

• [ ] 少なくとも3つの評価シナリオが作成されている
• [ ] 実際の使用シナリオでテストされている

Claude Code スキル概要（公式ドキュメント）

このドキュメントはClaude公式ドキュメントに基づくスキルの概要です。

目次

• スキルとは
• スキルの仕組み（段階的情報開示）
• スキルの構造
• 必須フィールドの要件
• セキュリティ考慮事項

---

スキルとは

Agent Skillsは、Claudeの機能を拡張するモジュール型の機能です。各Skillは、Claudeが関連する場合に自動的に使用する指示、メタデータ、およびオプションのリソース（スクリプト、テンプレート）をパッケージ化します。

主な利点:

• Claudeを専門化する: 領域固有のタスク用に機能をカスタマイズ
• 繰り返しを削減する: 1回作成して、自動的に使用
• 機能を組み合わせる: Skillsを組み合わせて複雑なワークフローを構築

---

スキルの仕組み（段階的情報開示）

Skillsには3つのタイプのコンテンツを含めることができ、それぞれ異なる時間に読み込まれます。

レベル1: メタデータ（常に読み込まれる）

SkillのYAMLフロントマターは検出情報を提供します：

---
name: pdf-processing
description: PDFファイルからテキストと表を抽出し、フォームに入力し、ドキュメントをマージします。PDFファイル、フォーム、またはドキュメント抽出について言及している場合に使用してください。
---

• スタートアップ時にシステムプロンプトに含まれる
• Skill当たり約100トークン
• 多くのSkillsをインストールしてもコンテキストペナルティなし

レベル2: 指示（トリガーされたときに読み込まれる）

SKILL.mdのメインボディには、手続き的な知識が含まれています：

• ワークフロー
• ベストプラクティス
• ガイダンス

• 5000トークン未満を推奨
• Skillの説明に一致するリクエスト時にのみ読み込まれる

レベル3: リソースとコード（必要に応じて読み込まれる）

追加の資料をバンドル可能：

pdf-skill/
├── SKILL.md (メイン指示)
├── FORMS.md (フォーム入力ガイド)
├── REFERENCE.md (APIリファレンス)
└── scripts/
    └── fill_form.py (ユーティリティスクリプト)

• 指示: 特殊なガイダンスを含む追加マークダウンファイル
• コード: Claudeがbashを介して実行する実行可能スクリプト
• リソース: データベーススキーマ、APIドキュメント、テンプレート等

重要: スクリプトを実行する場合、スクリプトコード自体はコンテキストに入らない（出力のみ）

トークンコスト一覧

---

スキルの構造

すべてのSkillには、YAMLフロントマターを含むSKILL.mdファイルが必要です：

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
[Clear, step-by-step guidance for Claude to follow]

## Examples
[Concrete examples of using this Skill]

---

必須フィールドの要件

name フィールド

description フィールド

---

Claude Codeでの配置

Claude CodeのカスタムSkillsはファイルシステムベース：

• 個人スキル: ~/.claude/skills/ - ユーザーのインストール先
• プロジェクトスキル: .claude/skills/ - プロジェクト固有

マーケットプレイス配布用の場合は、上記以外の場所（例: {domain}/skills/{skill-name}/）に配置し、ユーザーがインストールする形式にする。

---

セキュリティ考慮事項

Skillsは信頼できるソースからのみ使用することを強くお勧めします。

主なリスク:

• データ流出
• 不正なシステムアクセス
• その他のセキュリティリスク

注意事項:

• 徹底的に監査する（すべてのバンドルファイルを確認）
• 外部URLからデータを取得するSkillsは特に危険
• ツールの悪用の可能性を考慮
• 機密データへのアクセス権を持つSkillsに注意

---

制限事項

ランタイム環境の制約

• ネットワークアクセスなし: 外部API呼び出し不可
• ランタイムパッケージのインストールなし: 事前にインストールされたパッケージのみ
• 事前設定された依存関係のみ: コード実行ツールドキュメントで利用可能なパッケージを確認

クロスサーフェス可用性

カスタムSkillsはサーフェス間で同期されません：

• Claude.aiにアップロードされたSkillsはAPIに別途アップロードが必要
• Claude Code Skillsはファイルシステムベースで分離

Claude Code スキル（SKILL.md）レビュー基準

PRにSKILL.mdファイルが含まれる場合、通常のコードレビューに加えて本基準でスキル品質をチェックする。

目次

• フロントマター検証
• description品質チェック
• ディレクトリ構造チェック
• SKILL.mdボディ品質チェック
• 参照ファイルチェック
• 避けるべきパターン検出
• スコアリング基準
• 出力フォーマット

公式ドキュメント参照

スキルの仕組みやベストプラクティスの詳細は、以下を参照：

• スキル概要: skill-overview.md
• ベストプラクティス: skill-best-practices.md

---

フロントマター検証（Critical）

Critical判定:

• フロントマターが欠落 → Critical
• nameが不正な形式 → Critical
• descriptionが空 → Critical

---

description品質チェック（Major/Minor）

必須要素（Major）: 1. 何をするか: スキルの機能を具体的に説明 2. いつ使用するか: トリガー条件を明記

品質チェック（Minor）:

• 三人称で記述（「〜します」「〜を処理する」）
• 具体的なキーワードが含まれている
• 一人称・二人称は避ける（「お手伝いします」）
• 曖昧な表現は避ける（「ドキュメントに役立ちます」）

---

ディレクトリ構造チェック（Critical/Major）

マーケットプレイス配布用の正しい配置:

{domain}/skills/{skill-name}/
├── SKILL.md           # 必須
├── references/        # オプション
└── scripts/           # オプション

Critical: 誤った配置:

• ~/.claude/skills/ - ユーザーのインストール先（配布用ではない）
• .claude/skills/ - プロジェクト固有スキル用（配布用ではない）

注: プロジェクト固有スキルとして.claude/skills/に配置している場合は、その意図が明確であればCriticalとしない。

Major: 命名規則違反:

• CamelCaseやsnake_caseは不可
• kebab-caseを使用（動名詞形を推奨: processing-pdfs）

---

SKILL.mdボディ品質チェック（Minor）

---

参照ファイルチェック（Major/Minor）

---

避けるべきパターン検出

---

スコアリング基準

通常のコードレビューのスコアリング（SKILL.mdのステップ4）に、スキル固有の問題も加算する。

---

出力フォーマット

スキルレビュー結果は、通常のコードレビュー出力の「検出された問題」テーブルに統合する。 加えて、以下のスキル品質セクションを追加する：

### スキル品質: X/10

#### フロントマター
- [pass/fail] name: [評価コメント]
- [pass/fail] description: [評価コメント]

#### ディレクトリ構造
- [pass/fail] 配置: [評価コメント]
- [pass/fail] 命名: [評価コメント]

#### SKILL.mdボディ
- [pass/fail] 行数: [X行]
- [pass/fail] 例の有無: [評価コメント]
- [pass/fail] ワークフロー: [評価コメント]

#### 参照ファイル
- [pass/fail] 存在確認: [評価コメント]
- [pass/fail] ネスト深度: [評価コメント]

TypeScript ベストプラクティス

コードレビュー時にTypeScriptコードを評価するためのチェックリストです。

出典: AWS 規範ガイダンス - TypeScript のベストプラクティス

目次

• 型安全性
• 列挙型の使用
• インターフェイス設計
• デストラクチャリング
• 命名規則
• 変数宣言
• アクセス修飾子
• ユーティリティ型
• 設計パターン
• リンター・フォーマッター

---

型安全性

any型の使用を避ける（Major）

any型はTypeScriptの型チェックを無効化するため、バグの温床となる。 オブジェクトと関数の型を明示的に指定する。

// ❌ any型の使用
function processData(data: any) {
    return data.value; // 型チェックが効かない
}

// ✅ 型を明示的に指定
type Result = "success" | "failure";

function verifyResult(result: Result) {
    if (result === "success") {
        console.log("Passed");
    } else {
        console.log("Failed");
    }
}

レビュー観点：

• [ ] any型が使用されていないか
• [ ] 関数の引数と戻り値に型が指定されているか
• [ ] ユニオン型やリテラル型で値の範囲を制限しているか

---

列挙型の使用

名前付き定数にはenumを使う（Minor）

関連する定数のグループにはenumを使用し、コードの可読性と保守性を高める。

// ❌ マジックナンバーや文字列リテラルの直接使用
if (event === 0) {
    console.log("Created");
}

// ✅ enumで意味のある名前を付ける
enum EventType {
    Create,
    Delete,
    Update,
}

class InfraEvent {
    constructor(event: EventType) {
        if (event === EventType.Create) {
            console.log(`Event Captured: ${event}`);
        }
    }
}

レビュー観点：

• [ ] 関連する定数群がenumまたはユニオン型でグループ化されているか
• [ ] マジックナンバーや意味不明な文字列リテラルが散在していないか

---

インターフェイス設計

インターフェイスで契約を定義する（Major）

クラスやオブジェクトの形状をインターフェイスで定義し、型の一貫性を強制する。

interface BucketProps {
    name: string;
    region: string;
    encryption: boolean;
}

class S3Bucket {
    constructor(props: BucketProps) {
        console.log(props.name);
    }
}

readonlyプロパティを活用する（Minor）

変更されるべきでないプロパティにはreadonlyを指定し、不変性を保証する。

interface Position {
    readonly latitude: number;
    readonly longitude: number;
}

インターフェイスの拡張でプロパティの重複を減らす（Minor）

共通プロパティを基底インターフェイスにまとめ、拡張で派生させる。

// ❌ プロパティの重複
interface EncryptedVolume {
    name: string;
    keyName: string;
}

interface UnencryptedVolume {
    name: string;
    tags: string[];
}

// ✅ 共通プロパティを基底に抽出
interface BaseVolume {
    name: string;
}

interface EncryptedVolume extends BaseVolume {
    keyName: string;
}

interface UnencryptedVolume extends BaseVolume {
    tags: string[];
}

空のインターフェイスを避ける（Major）

空のインターフェイスは型の契約を強制せず、型安全性の恩恵を受けられない。

// ❌ 空のインターフェイス - 任意のオブジェクトを受け入れてしまう
interface BucketProps {}

class S3Bucket implements BucketProps {
    constructor(props: BucketProps) {
        console.log(props);
    }
}

// 異なる構造のオブジェクトが両方とも受け入れられてしまう
const bucket1 = new S3Bucket({ name: "bucket", region: "us-east-1", encryption: false });
const bucket2 = new S3Bucket({ name: "bucket" });

レビュー観点：

• [ ] 空のインターフェイスが定義されていないか
• [ ] 共通プロパティが基底インターフェイスにまとめられているか
• [ ] 変更されないプロパティにreadonlyが付与されているか

---

デストラクチャリング

プロパティアクセスにデストラクチャリングを使う（Suggestion）

ES6のデストラクチャリングで冗長なプロパティアクセスを減らす。

const config = {
    name: "myApp",
    scope: "global",
};

// ❌ 冗長なプロパティアクセス
const appName = config.name;
const appScope = config.scope;

// ✅ デストラクチャリング
const { name, scope } = config;

レビュー観点：

• [ ] 同一オブジェクトから複数プロパティを取得する際にデストラクチャリングが使われているか

---

命名規則

標準の命名規則に従う（Minor）

// ✅ 命名規則に従った例
const userName = "john";
function getUserData() {}

const MAX_RETRY_ATTEMPTS = 3;
const API_BASE_URL = "https://api.example.com";

class DatabaseConnection {}
interface UserProfile {}

type ResponseStatus = "success" | "error";
enum HttpStatusCode {}

レビュー観点：

• [ ] 変数・関数がcamelCaseで命名されているか
• [ ] クラス・インターフェイス・型がPascalCaseで命名されているか
• [ ] グローバル定数がUPPER_CASEで命名されているか
• [ ] プロジェクト全体で命名規則が一貫しているか

---

変数宣言

varキーワードを使わない（Major）

varは関数スコープで動作し、意図しない変数の上書きを引き起こす。letとconstを使用する。

// ❌ varの使用
var count = 0;
if (true) {
    var count = 1; // 外側のcountを上書き
}
console.log(count); // 1（意図しない挙動）

// ✅ letの使用
let count = 0;
if (true) {
    let count = 1; // ブロックスコープ内のみ
}
console.log(count); // 0（期待通り）

レビュー観点：

• [ ] varが使用されていないか
• [ ] 再割り当てしない変数にはconstが使われているか
• [ ] 再割り当てが必要な場合のみletが使われているか

---

アクセス修飾子

適切なアクセス修飾子を使用する（Minor）

クラスメンバーの可視性を制御し、カプセル化を実現する。

レビュー観点：

• [ ] 内部実装のメンバーにprivateが付与されているか
• [ ] publicがデフォルトで良い場合、明示的に省略されているか（プロジェクト規約に従う）
• [ ] 継承を考慮してprotectedが適切に使われているか

---

ユーティリティ型

ユーティリティ型を活用する（Suggestion）

TypeScript組み込みのユーティリティ型で、既存の型を効率的に変換する。

Partial\<Type\>

すべてのプロパティをオプションにする。部分更新に有用。

interface Dog {
    name: string;
    age: number;
    breed: string;
    weight: number;
}

// すべてのプロパティがオプション
let partialDog: Partial<Dog> = {};

Required\<Type\>

すべてのプロパティを必須にする。Partialの逆。

interface Dog {
    name: string;
    age: number;
    breed: string;
    weight?: number;
}

// weightも必須になる
let dog: Required<Dog> = {
    name: "scruffy",
    age: 5,
    breed: "labrador",
    weight: 55,
};

その他の主要ユーティリティ型

レビュー観点：

• [ ] 手動で型を再定義する代わりにユーティリティ型が活用されているか
• [ ] 部分更新にはPartialが使われているか

---

設計パターン

ファクトリーパターンを活用する（Suggestion）

オブジェクト作成ロジックが複雑な場合、ファクトリーパターンに委任して責務を分離する。

// ❌ コンストラクト内で直接作成
class MyStack {
    constructor() {
        // 複雑な作成ロジックが散在
        const lambda1 = new Lambda(/* 多数のパラメータ */);
        const lambda2 = new Lambda(/* 多数のパラメータ */);
    }
}

// ✅ ファクトリーに委任
class LambdaFactory {
    static create(name: string, config: LambdaConfig): Lambda {
        // 作成ロジックを集約
        return new Lambda(/* ... */);
    }
}

レビュー観点：

• [ ] 類似オブジェクトの作成が複数箇所に散在していないか
• [ ] 複雑な初期化ロジックが適切に抽象化されているか

---

リンター・フォーマッター

ESLintとPrettierを導入する（Suggestion）

{
    "scripts": {
        "lint": "eslint --ext .js,.ts .",
        "format": "prettier --ignore-path .gitignore --write '**/*.+(js|ts|json)'"
    }
}

レビュー観点：

• [ ] ESLintの警告やエラーが未解決のまま残っていないか
• [ ] コードフォーマットがプロジェクトの規約に従っているか