Agent-Skills.md

Agent Skills: pr-reviewer

|

UncategorizedID: goldeneggg/dotfiles/pr-reviewer

Repository

goldeneggg/dotfiles
goldeneggg
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/goldeneggg/dotfiles/tree/HEAD/ai-linux/.claude/skills/pr-reviewer

Skill Files

Browse the full folder contents for pr-reviewer.

Download Skill

Loading file tree…

ai-linux/.claude/skills/pr-reviewer/SKILL.md

Skill Metadata

Name
pr-reviewer
Description
|

pr-reviewer

Git/GitHubを用いたアプリケーション開発における包括的なコードレビューを実施し、コード品質、セキュリティ、ベストプラクティスに焦点を当てます。

注意: このSkillを使用する際のユーザーとのやり取りはすべて日本語で行います。

Degrees of Freedom

  • 引数の解析: Low freedom — 以下の「引数の解析」セクションのパターンに厳密に従う。パターンに合致しない場合は必ずユーザーに確認する
  • レビュー観点の重み付け: Medium freedom — コード品質・セキュリティ・規約準拠・ベストプラクティスの4観点は必須。ただし、変更内容に応じて重点を置く観点をエージェントが判断してよい（例: 認証周りの変更ならセキュリティを重点的に）
  • 外部情報の収集: High freedom — MCPツールやWebSearchの使用判断はエージェントに委ねる。不明な技術・ライブラリに遭遇した場合は積極的に調査してよい
  • フィードバックの粒度: Medium freedom — 重要度レベル（Critical/High/Medium/Low）の判定基準は固定。ただし各指摘の説明の詳しさは問題の複雑さに応じて調整してよい
  • レポート出力の公開性: Low freedom — 「レポート出力原則（第三者可読性）」セクションに厳密に従う。レビュー結果は PR コメント等に転記されうる対外公開ドキュメントとして扱い、レビュー対象リポジトリ外・gitignore 対象・ローカル固有パスへの言及を一切含めない

引数の解析

$ARGUMENTS を以下のパターンでパースします：

| パターン | 例 | モード | |---------|-----|--------| | https://github.com/{owner}/{repo}/pull/{num} | https://github.com/goldeneggg/dotfiles/pull/123 | GitHub PRレビュー（URL） | | {owner/repo} {PR番号} | goldeneggg/dotfiles 123 | GitHub PRレビュー | | {owner/repo} {PR番号} --outline {概要} | goldeneggg/dotfiles 123 --outline 認証機能の追加 | GitHub PRレビュー（概要付き） | | {ブランチ名} | feature/new-api | ローカルブランチレビュー（base: main） | | {ブランチ名} --base {ベースブランチ} | feature/new-api --base develop | ローカルブランチレビュー（base指定） | | 引数なし | （空） | ユーザーにレビュー対象を確認 |

URL解析ルール: https://github.com/{owner}/{repo}/pull/{num} 形式のURLから owner/repo と PR番号を抽出します。URLに --outline 等のオプションを後続させることも可能です。

パースに失敗した場合: 引数がどのパターンにも合致しない場合は、ユーザーに正しい形式を提示して再入力を求めます。

スコープ

対象:

  • コード変更のレビュー（品質・セキュリティ・規約準拠・ベストプラクティス）
  • 問題点と改善点のフィードバック提供
  • PR承認可否の判断

対象外:

  • コードの修正・編集の実行
  • PRのマージ・クローズ操作
  • コミットの作成・修正
  • CIの実行・確認

目的

git管理されたリポジトリに対して徹底的なコードレビューを実施し、潜在的な問題の特定、改善提案、コーディング規約とベストプラクティスへの準拠を確認します。

レビュープロセス

1. 引数の解析とコード変更の取得

まず「引数の解析」セクションに従い $ARGUMENTS をパースし、レビューモードを決定します。

GitHub PRレビューの場合：

以下の2コマンドを並列実行してdiffとPR説明を同時に取得します：

# 並列実行1: diff取得
gh pr diff {pr_num} --repo {repo}

# 並列実行2: PR説明取得
gh pr view {pr_num} --repo {repo} --json title,body --jq '.title + "\n\n" + .body'

ローカルブランチレビューの場合：

git diff {base_branch}..{target_branch}
  • {base_branch}: --base で指定されたブランチ、未指定なら "main"

outlineパラメータ（--outline）：

  • 指定あり → 変更内容を理解するための主要なコンテキストとして使用
  • PRレビューで未指定 → 上記で取得したPRの説明を使用
  • ブランチレビューで未指定 → diff自体からコンテキストを推測

2. 変更内容の理解

  • まず、outline/コンテキストを読みます：

    • PRレビューの場合: {outline} が提供されていればそれを使用、なければPRの説明を使用
    • ブランチレビューの場合: {outline} が提供されていればそれを使用、なければdiffから推測

  • 次に、diff出力を分析して、どのコードが変更・追加・削除されたかを理解

  • コンテキストと実際のコード変更の両方に基づいて、変更の範囲と目的を特定

  • 言語固有の規約についてはプロジェクトドキュメント（CLAUDE.md）のコンテキストを考慮

3. レビューの実施

以下の観点で変更を検証します：

コード品質：

  • 変更が新しいバグや問題を導入していないか確認
  • 適切なエラーハンドリングパターンをチェック
  • コードの可読性と保守性を評価
  • 命名規則とコード構成を検証

コーディング規約：

  • CLAUDE.mdのプロジェクト固有のコーディング規約への準拠を確認
  • 適切なコードフォーマットと構造を検証
  • インポート順序をチェック（stdlib → external → internal）
  • テストカバレッジとテストパターンを検証

セキュリティ：

  • 潜在的なセキュリティ脆弱性を特定
  • ハードコードされた秘密情報や認証情報をチェック
  • 適切な入力バリデーションを検証
  • セキュリティクリティカルな操作での暗号ライブラリの適切な使用を確認

ベストプラクティス：

  • 言語固有のベストプラクティスへの準拠を評価
  • 適切な並行処理パターンをチェック（該当する場合）
  • 適切なエラーハンドリングとロギングを検証
  • リソース管理とクリーンアップを検証

追加の考慮事項：

  • 必要に応じてMCPツール（fetch、context7）を使用して外部ソースから最新の公式仕様とベストプラクティスを収集
  • プロジェクト固有のガイドラインはCLAUDE.mdを参照（言語・フレームワーク固有の規約が定義されている場合）

4. フィードバックの提供

フィードバックは以下の構造で日本語で提供します：

問題点（優先度別）:

  • 内容: 具体的な問題の説明
  • 期待される内容や動作との差異: 現状と期待される動作のギャップ
  • 根拠となる文献: 参考文献（該当する場合）
  • 該当箇所: diff 内のファイルパス（path/to/file.ext:42 形式）

改善点（優先度別）:

  • 内容: 改善提案
  • 具体的な改善方法: 具体的な改善アプローチ
  • 該当箇所: diff 内のファイルパス

その他の報告事項（もしあれば）:

  • 追加の観察事項や推奨事項

重要: 各指摘で参照するパスは、必ず後述「レポート出力原則」に従いレビュー対象 diff に含まれるパスのみとする。レビュー実行環境のローカルファイル・タスク管理用ドキュメント・gitignore 対象パスへは一切言及しない。

レポート出力原則（第三者可読性）

前提: このレビュー結果は PR コメント・Issue・Slack・メール等に転記される可能性のある「対外公開ドキュメント」として扱う。レビュー対象リポジトリの第三者（PR 作成者・他のレビュアー）が読んでも、参照されているファイル・概念がすべて当該リポジトリ内で完結することが必要。

参照可能なファイル

  • ✅ レビュー対象 diff に含まれるファイルパス（例: src/foo.ts:42）
  • ✅ レビュー対象リポジトリで git 管理されている公開ファイル（例: README.md, package.json, CLAUDE.md）
  • ✅ 公開 URL（公式ドキュメント、RFC、CVE 等）

参照禁止のファイル

  • ❌ gitignore 対象のローカルファイル（例: .env, tmp/, logs/, ローカルキャッシュ）
  • ❌ レビュー対象リポジトリ外のローカルパス（例: ~/notes/, /Users/xxx/, /tmp/）
  • ❌ レビュー実行環境固有のタスク管理ドキュメント（例: docs/tasks/, todos/, task-starter プロジェクト配下のパス）が当該リポジトリで管理外、もしくは「レビュー対象 diff の外側」にある場合
  • ❌ サブエージェント（task-reader 等）が返した内部サマリの引用元パス
  • ❌ レビュー担当者のホームディレクトリやマシン固有の絶対パス

「外部不可視リソース」の扱い

レビュー対象リポジトリの外にある資料（ローカルメモ、別リポジトリのタスクドキュメント等）を推論材料として参照すること自体は問題ない。ただしレポート内では:

  1. 要件・仕様は本文を直接埋め込む — 「タスク要件: ユーザー認証 API を JWT ベースで実装する」のように要件文そのものを記載する。レビュアーは別資料を開かずに文脈を理解できる状態にする
  2. 番号・記号での間接参照を避ける — 「タスク要件 番号 3 によれば〜」「仕様書 §2 では〜」のような外部資料への番号参照は、第三者には何を指すか分からない。さらに後述の通り GitHub auto-link を招くリスクがある場合は致命的に誤誘導する
  3. 第三者が確認不能な情報は省く — レビュアーが追跡確認できない参照を残すと「言われた通りに見えない」状態を作り、レビューの信頼性が落ちる

GitHub auto-link を発火させない記法ルール

レポートが PR コメントや Issue 本文に転記された際、以下のパターンは GitHub によって自動リンク化され、全く無関係のIssue/PR/ユーザーへ誘導されてしまう。レポート本文では絶対に使わない:

| パターン | GitHub での解釈 | 代替表現 | |---|---|---| | #数字 (例: #3, #42) | 同リポジトリの Issue/PR #N へのリンク | 「受け入れ条件 3」「項目 3」のように # を外して書く | | GH-数字 | Issue/PR への代替リンク | 「項目 N」のように一般語で記載 | | org/repo#数字 | 他リポジトリの Issue/PR | 「外部要件 N」のように記載 | | @username | ユーザーへのメンション通知 | 「担当者」「実装者」のように役割名で記載。固有名は本当に必要な箇所のみ、かつ通知が発火しても問題ない場合に限る | | @org/team | チームへのメンション通知 | チーム名は通常文で記載（例: バックエンドチーム） | | GH-数字, フルコミットSHA(7文字以上) | コミットへのリンク | 該当の差分に対しては path/to/file.ext:42 形式で参照 |

特に # + 数字 は、AI が「要件番号」「タスク番号」を表現するために自然に書きがちなパターンであり、自動リンクに気付かないまま PR コメントへ貼られると無関係チケットへ誘導してしまう。受け入れ条件・タスク要件・チェックリストを参照する際は # を絶対に付けない。

報告前チェック

レポート生成完了時、出力に対して以下を点検する:

  • [ ] パス参照がすべて Phase 1 で取得した diff のファイルパスに対応しているか
  • [ ] todos/, logs/, tmp/, .env, ~/, /Users/, /home/ 等を含む参照がないか
  • [ ] サブエージェントの出力に含まれていたパス（task-reader の specs/references パス等）を引用していないか
  • [ ] 外部不可視ドキュメントの内容を直接埋め込み済みで、番号・記号での間接参照が残っていないか
  • [ ] #数字, GH-数字, org/repo#数字, @username, @org/team といった GitHub auto-link を発火させるパターンがレポート本文・テーブル・引用箇所に含まれていないか（含まれていれば必ず代替表現へ置換）

問題がある記載は削除または抽象化してから報告する。報告後の修正は混乱を招くため、チェックは報告前に必ず実施する。

5. レビュー合格基準

レビュー結果を以下の重要度レベルで分類し、PR承認の判断基準とします：

重要度レベル:

  • 🔴 Critical: セキュリティ脆弱性、データ損失リスク、本番環境への重大な影響

    • 対処: 即座に修正必須 - PRマージ前に必ず解決
    • 例: SQLインジェクション、認証バイパス、機密情報の漏洩

  • 🟠 High: バグの可能性、コーディング規約の重大な違反、パフォーマンス劣化

    • 対処: 修正を強く推奨 - PRマージ前の解決を推奨
    • 例: エラーハンドリング不足、メモリリーク、重要な命名規則違反

  • 🟡 Medium: 改善提案、リファクタリング推奨、マイナーな規約違反

    • 対処: 次回以降の改善候補 - PRマージ可能だが改善を検討
    • 例: 可読性の向上、テストカバレッジの追加、コメントの改善

  • 🟢 Low: コメント改善、命名の微調整、スタイルの統一

    • 対処: オプション - 時間があれば対処
    • 例: 変数名のタイポ、コメントの文言調整

PR承認判断基準:

  • ✅ 承認可能: Critical 0件 かつ High 2件以下
  • ⚠️ 条件付き承認: High 3-5件（重要度に応じて判断）
  • ❌ 要修正: Critical 1件以上 または High 6件以上

レビュー完了時の報告:

レビュー完了時は、以下の形式で総合判定を提示します：

## 📊 レビュー結果サマリー

- 🔴 Critical: X件
- 🟠 High: X件
- 🟡 Medium: X件
- 🟢 Low: X件

**総合判定**: [承認可能 / 条件付き承認 / 要修正]
**推奨アクション**: [具体的な次のステップ]

ガイドライン

  • 重要: ユーザーとのすべてのコミュニケーションは日本語で行う必要があります - 質問、フィードバック、説明、その他すべてのやり取り
  • 必要に応じてMCPツール（fetch、context7、WebFetch、WebSearch）を使用して外部ソースから最新の公式仕様とベストプラクティスを収集
  • 不明点は必ずユーザーに確認してから進める
  • レビュータスクは徹底的かつ粘り強く完了させる
  • 開発者がコード品質を向上させるのに役立つ実用的なフィードバックに焦点を当てる
  • レポート出力前に「報告前チェック」を必ず実施し、第三者可読性を担保する
  • GitHub auto-link を発火させない — #数字, @username などのパターンは PR コメントに転記された瞬間に無関係のIssue/PR/ユーザーへ誤誘導する。要件番号・項目番号を参照する際は # を付けず「項目 3」「受け入れ条件 3」のように一般語で表現する

エラーハンドリング

レビュー実行時に発生する可能性のあるエラーと対処方法：

引数の解析失敗

原因:

  • $ARGUMENTS がどのパターン（repo+PR番号/ブランチ名）にも合致しない
  • リポジトリ名が owner/name 形式でない
  • PR番号が数値でない

対処:

  • 解析できなかった引数の内容をユーザーに提示
  • 正しい形式の例を示して再入力を依頼:
    • GitHub PR: /pr-reviewer owner/repo 123
    • ローカルブランチ: /pr-reviewer feature/xxx
    • オプション付き: /pr-reviewer owner/repo 123 --outline 概要
  • 引数なしの場合はレビュー対象を質問

diff取得失敗

原因:

  • PR番号が存在しない
  • ブランチが見つからない
  • リポジトリへのアクセス権限がない

対処:

  • エラーメッセージをユーザーに提示
  • 正しいPR番号またはブランチ名の確認を依頼
  • リポジトリ名が owner/name 形式で正しいか確認

gh CLI認証エラー

原因:

  • GitHubトークンが未設定
  • トークンの有効期限が切れている
  • 必要なスコープ（repo, read:org等）が不足

対処:

  • gh auth status でログイン状態を確認するよう促す
  • gh auth login の実行を案内
  • 必要に応じて gh auth refresh -s repo でスコープを追加

空のdiff

原因:

  • 対象ブランチに変更が存在しない
  • ベースブランチとターゲットブランチが同一
  • すでにマージ済み

対処:

  • 「変更が検出されませんでした」と報告
  • ブランチ名やPR番号が正しいか確認を依頼
  • git log でコミット履歴の確認を提案

巨大なdiff（10,000行以上）

原因:

  • 大規模なリファクタリング
  • ライブラリのバージョンアップ（lock fileを含む）
  • 自動生成コードの大量追加

対処:

  • 「差分が非常に大きいため、全体レビューに時間がかかります」と通知
  • ファイル単位またはディレクトリ単位での段階的レビューを提案
  • 特に重要なファイルを指定してもらうよう依頼
  • lock fileや自動生成ファイルを除外したレビューを提案

ネットワークエラー

原因:

  • GitHub APIの一時的な障害
  • レート制限の超過
  • ネットワーク接続の問題

対処:

  • エラーの内容を確認し、ユーザーに報告
  • レート制限の場合は gh api rate_limit で状況確認を促す
  • 一時的な障害の場合は時間をおいて再試行を提案