review-agent

name	review-agent
description	`.agent/agents/reviewer.md` を入口に、PR差分やローカル差分を日本語でレビューするスキル。ユーザーが「レビュー」「PR確認」「差分確認」「コードレビュー」「reviewer」「レビュー指摘に対応」などを依頼したときに使う。GitHubレビュー指摘の対応（分類・方針提示・Worker委譲・resolved化）も扱う。

Review Agent

.agent/agents/reviewer.md を主担当として、バグ・回帰・セキュリティ・キャッシュ整合性・SSOT 違反を優先してレビューする。 PR 作成や説明文の確認では .github/codex-pr-rules.md も参照する。

参照順

1. AGENTS.md
2. .agent/agents/reviewer.md
3. .github/codex-pr-rules.md
4. 関連する ExecPlan
5. 関連する assets/docs/
6. 変更ファイルと git diff

実行ルール

1. レビューは日本語で行う。
2. 指摘を先に書き、重大度順に並べる。
3. 各指摘にはファイルと行番号を添える（特定できない場合は省略し、ルール10に従って検証不能として報告する）。
4. 問題がない場合は、問題なしと明確に述べ、残るテストギャップを短く添える。
5. 好みのリファクタではなく、バグ・回帰・セキュリティ・運用リスクを優先する。
6. DocumentParser 変更時は、影響フェーズの明示があるか確認する。
7. DB 更新処理では、db() ヘルパーと実行直前エスケープを確認する。
8. スーパーグローバル、直接 $modx 参照、生SQL、compact() の混入を確認する。
9. キャッシュに関係する変更では、無効化条件と再生成条件を確認する。
10. 指摘対象のファイル・行・シンボルが差分またはワークスペースに存在しない場合、推測で指摘を作らず「検証不能」として事実のみ報告する。
11. GitHub への返信・コメントと review thread の resolved 化は、修正と push の完了後に「GitHub上へ返信・コメントし、review thread を resolved 化しますか？ はい・いいえ」で確認し、はい の場合のみ実行する。
12. /resolve-review を経由せず直接修正・push した場合も、push 完了後に必ずスレッドの resolved 化をユーザーに確認してから実行する（スキップ禁止）。

コマンド

/review-diff

1. git diff と変更ファイルを確認する。
2. 変更領域に応じて関連 docs を読む。
3. .agent/agents/reviewer.md の観点でレビューする。
4. 指摘を重大度順にまとめる。
5. テスト不足と残リスクをまとめる。

/review-pr

1. PR の目的、差分、関連 Issue、CI 結果を確認する。
2. .github/codex-pr-rules.md に照らしてタイトル、説明、ラベル方針を確認する。
3. .agent/agents/reviewer.md の観点でレビューする。
4. 指摘を重大度順にまとめる。

/resolve-review <PR番号>

GitHub PR のレビューコメントを取得し、各指摘を評価・対応・解決する。 実装・コミット・push を伴う場合は Worker エージェントに委譲し、review-agent 自身は方針整理、確認、GitHub 上の返信・resolved 化のみ担当する。

ステップ 1: 指摘の収集と評価

まず GraphQL で未解決スレッド一覧を取得する（REST /comments には isResolved がないため、resolved 済みスレッドを分類対象から除外するために必要）:

# PR のレビュースレッドを全件取得し、未解決（isResolved == false）のものだけを対象にする
# GitHub GraphQL API は reviewThreads にフィルタ引数がないため全件取得後に選別する
# pageInfo.hasNextPage が true の場合は after: "<endCursor>" を追加して再実行する
gh api graphql -f query='
{
  repository(owner: "<owner>", name: "<repo>") {
    pullRequest(number: <PR番号>) {
      reviewThreads(first: 100) {
        pageInfo { hasNextPage endCursor }
        nodes {
          id
          isResolved
          comments(first: 1) {
            nodes { databaseId body }
          }
        }
      }
    }
  }
}'
# isResolved == false のスレッドのみを分類・解決対象にする
# 取得した databaseId は REST /comments のスレッド先頭コメント（in_reply_to_id が null）の id と一致する
# 返信コメント（in_reply_to_id がある）は in_reply_to_id を先頭コメントの id と照合してスレッドを特定する

次に、インラインレビューコメントとレビュー本文を取得する:

# インラインレビューコメント（差分行への指摘、スレッド単位で管理される）
gh api --paginate "/repos/<owner>/<repo>/pulls/<PR番号>/comments"

# レビュー本文（スレッドを持たないため resolved 化不可。対応要否を評価し、対応する場合はステップ2の方針一覧に含める）
gh api --paginate "/repos/<owner>/<repo>/pulls/<PR番号>/reviews"

取得した /reviews の結果は、state が DISMISSED のものを除外する。APPROVED は state のみで除外せず、本文がある場合は評価対象に含める（本文が空の APPROVED は除外してよい）。CHANGES_REQUESTED・COMMENTED は従来どおり対象とし、同一レビュアーが複数回投稿している場合は全件を評価対象とする。

/resolve-review を再実行する場合は、PR の既存コメント一覧（gh pr view <PR番号> --comments）を確認し、同じ review_id で既に返答済みの review body はこの段階で評価対象から外す（ステップ2の方針一覧に重複項目を残さないため）。

インラインコメントの各スレッドおよび /reviews の各レビュー本文をそれぞれ1単位として以下の基準で分類する（スレッド内の複数コメントは一括で判断する）:

判定	基準
対応する	バグ・セキュリティ・動作不正・明確な設計誤り
対応を検討	可読性・保守性に影響するが実装シンプルなもの
対応しない	好みのスタイル・過剰なエッジケース対応・シンプルさを損なう変更

「対応しない」と判断する典型例:

• 命名の好みや文体の指摘（機能・意味に影響しない）
• 実運用で発生しない理論上のエッジケース対応要求
• コードを複雑にしてまで型を厳密化する要求
• 既存パターンと統一するだけのリファクタ要求（設計改善でない場合）
• テストカバレッジのためだけに実装を変える要求

ステップ 2: 対応方針の提示（実施前に確認）

ユーザーに対応方針の一覧を提示し、確認を取ってから実装を進める。出力形式は ## 出力形式 を参照。

ステップ 3: 修正の実装

対応するスレッドの修正を実装する（Worker エージェントに委譲）。 Worker への委譲時は「修正内容、検証手順、検証結果の記録」を成果物として求める。

• 変更はシンプルさを最優先とする
• 対応しないスレッドは理由を明確に持つ

ステップ 4: 検証

コミット前に変更内容を確認する。

• 修正が指摘の意図を満たしているか確認
• 関連する動作や既存ロジックへの影響がないか確認

ステップ 5: Worker によるコミットと push

コミットと push は Worker に委譲し、次の手順で実行させる。

git add -p  # または対象ファイルを指定
# type は変更内容に応じて選択（fix / refactor / docs / chore など）
# scope は省略可能
git commit -m "<type>: レビュー指摘に対応"
git push

Worker による修正結果を確認した後、コミットと push が必要な場合は、まずユーザーに次の1問だけ確認する。

コミットして push しますか？ はい・いいえ

はい の場合のみ、Worker にコミットと push を行わせる。いいえ の場合はローカル修正と検証結果だけを報告し、GitHub への書き込みは行わない。

ステップ 6: GitHub上でのコメント解決

ステップ5の完了後、まずユーザーに次の1問だけ確認する。

GitHub上へ返信・コメントし、review thread を resolved 化しますか？ はい・いいえ

はい の場合のみ、このステップを実行する。いいえ の場合は GitHub への書き込みを行わず、ローカル修正と push の完了だけを報告して終了する。

対応したスレッドを resolved にする（コードへの書き込みではなく GitHub 上のスレッド状態変更のため review-agent が直接実行する）。ステップ1で取得した thread の id を使う:

# 対応済みスレッドを resolve（id はステップ1で取得した thread の id）
gh api graphql -f query='
  mutation {
    resolveReviewThread(input: {threadId: "<thread_id>"}) {
      thread { isResolved }
    }
  }
'

対応しないスレッドは、スレッドへの返信として理由を残した上で resolved にする（再実行時の重複を防ぐため）:

# 各スレッドに返信（comment_id はステップ1で取得した先頭コメントの databaseId）
gh api /repos/<owner>/<repo>/pulls/<PR番号>/comments/<comment_id>/replies \
  -f body="見送り理由の説明"
# 返信後に resolved 化（対応済みスレッドと同様）

/reviews 取得のレビュー本文に対する対応完了・見送り理由は PR コメントとして残す。本文には対象 review の id（GitHub が発行する一意な数値 ID）を含め、再実行時にステップ1で除外できるようにする:

gh pr comment <PR番号> --body "@レビュアー名（review_id: 123456789）: 対応内容または見送り理由"

ステップ 7: 完了報告

対応済み・見送りの一覧をユーザーに報告する。

出力形式

差分レビュー（/review-diff / /review-pr）:

セクション見出し（Findings / Open Questions / Tests）はツール間で共通の固定ラベルとして英語のまま使用する。指摘内容・確認事項・テスト説明は日本語で記載する。

指摘がある場合:

**Findings**
- [High] path/to/file.php:123: 指摘内容。影響と修正方針。
- [Medium] path/to/file.php:45: 指摘内容。影響と修正方針。

**Open Questions**
- 確認事項

**Tests**
- 実行済み、または未実行の理由

指摘がない場合:

重大な問題は見つかりませんでした。

**Tests**
- 実行済み、または未実行の理由

/resolve-review の出力:

方針確認フェーズ（ステップ2）:

レビュー対応方針:

- 対応する
  - スレッド xxxx（先頭コメント概要）→ [修正方針]
  - /reviews本文 @レビュアー名（review_id: XXXX）→ [修正方針]

- 対応を検討（ユーザー判断を仰ぐ）
  - スレッド xxxx（先頭コメント概要）→ [対応した場合の影響と見送りのリスク]
  - /reviews本文 @レビュアー名（review_id: XXXX）→ [対応した場合の影響と見送りのリスク]

- 対応しない（理由付き）
  - スレッド xxxx（先頭コメント概要）→ 見送り理由
  - /reviews本文 @レビュアー名（review_id: XXXX）→ 見送り理由

完了報告（ステップ7）:

対応完了:
- スレッド xxxx（先頭コメント概要）→ 対応内容
- /reviews本文 @レビュアー名（review_id: XXXX）→ 対応内容
見送り:
- スレッド xxxx（先頭コメント概要）→ 見送り理由
- /reviews本文 @レビュアー名（review_id: XXXX）→ 見送り理由