pr-review-and-document

PR のレビューと記録

pr-review-toolkit を使用して包括的な PR レビューを実施し、構造化された結果を PR コメントとして投稿します。

使用するタイミング

以下の場合にこのスキルを使用します。

• 包括的な PR レビューを PR 上に記録する必要がある場合
• 機能ブランチの正式なレビューレコードが必要な場合
• チーム内で参照できるよう、レビュー結果を PR 上に直接表示する必要がある場合

ワークフロー

ステップ 1：PR 番号を取得する（キャッシュ対応）

PR_NUMBER=$("${CLAUDE_PLUGIN_ROOT}/scripts/get-pr-number.sh")

ブランチと PR 番号のキャッシュ（branch-map.json）を有効期間 1 時間で使用し、キャッシュにない場合は GitHub API にフォールバックします。

現在のブランチに PR が存在しない場合は、ユーザーに知らせて終了します。

ステップ 2：既存のレビューコメントを確認する（キャッシュ対応）

EXISTING_CONTENT=$(${CLAUDE_PLUGIN_ROOT}/scripts/cache-read-comment.sh "$PR_NUMBER")

利用可能な場合はローカルキャッシュを使用し、キャッシュにない場合は GitHub API にフォールバックします。

コンテンツが返された場合：

• `` ブロックからメタデータを抽出します
• 現在の review_round と課題のステータスを確認します
• .pr-review-cache/pr-${PR_NUMBER}.json を読み込み、.content_hash を EXPECTED_CONTENT_HASH として保存します
• 次のレビューを書き込む際、既存の [Gemini] と [Codex] の課題、および review_sources メタデータを保持します

ステップ 3：PR レビューを実施する

Skill ツールを使用して、opus モデルで pr-review-toolkit を起動します。

Skill: pr-review-toolkit:review-pr
Args: all
Model: opus

必須エージェント（常に実行）：

• code-reviewer - 一般的なコード品質と CLAUDE.md への準拠
• code-simplifier - コードを簡潔にする機会
• silent-failure-hunter - エラー処理とサイレントな失敗の検出
• type-design-analyzer - 型設計の品質分析
• pr-test-analyzer - テストカバレッジの分析
• comment-analyzer - コメントの正確性と保守性

重要： 包括的なカバレッジを確保するため、すべてのレビューで全エージェントの実行が必須です。

ステップ 4：レビューコメントを整形する

非表示のメタデータと折りたたみ可能なセクションを使って、レビューを PR コメントとして構成します。

文字数制限： 全体のコンテンツを約 40K 文字未満にしてください（GitHub の上限は 65,536 文字です）。

複数ソースとの互換性： 既存のレビューコメントがある場合、コメント全体をそのまま再生成しないでください。新しい Claude の結果を既存の構成に統合します。

• 書き込む前にメタデータをスキーマ 1.1 に更新します。共通ヘルパーの使用を推奨します。

  METADATA_JSON=$(printf '%s\n' "$EXISTING_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-upgrade.sh --stdin --last-writer pr-review-and-document)
  

• メタデータ JSON（例：jq を使用）を編集した後、共通ヘルパーで非表示ブロックを置き換えます。

  # Set up a temp file for the modified metadata JSON.
  # (If this code block already declares its own trap, extend it instead of adding a second line.)
  METADATA_FILE=$(mktemp)
  trap 'rm -f "$METADATA_FILE"' EXIT
  
  # Write the edited metadata JSON to the temp file.
  printf '%s' "$METADATA_JSON" > "$METADATA_FILE"
  
  # Replace the metadata block in the comment.
  UPDATED_CONTENT=$(printf '%s\n' "$EXISTING_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-replace.sh --stdin --metadata-file "$METADATA_FILE")
  

• review_sources.gemini、review_sources.codex、[Gemini] の課題、および [Codex] の課題を保持します
• 新しい Claude のレビューによって変更されたことが確認できない限り、既存の課題ステータス（✅、⏭️、⚠️、🔴）を保持します
• タグのない課題は Claude の課題として扱います
• このレビューで新しい指摘が追加された場合にのみ、PR 全体の review_round を増やします。指摘のない更新では review_sources.claude.last_reviewed_* のみ更新します

メタデータブロックの形式

メタデータブロックは、識別用の特定のマーカーを含む HTML コメント構文を使用します。

• 開始：JSON の後の独立した行にある ``

重要： find-review-comment.sh スクリプトは `

🤖 PR レビュー

ブランチ： branch-name → base-branch ラウンド： N | 更新日： YYYY-MM-DD レビュアーソース： Claude

---

📊 概要

カテゴリー	合計	修正済み	未対応
🔴 重大	X	X	X
🟡 重要	X	X	X
💡 提案	X	X	X

ステータス： [✅ マージ可能 | ⚠️ 要対応 | 🔴 ブロッキングの課題あり]

---

🔴 重大な課題

1. [ステータス絵文字] 課題のタイトル

ファイル： path/to/file.ts:line

問題： 課題の説明。

修正： 解決方法または修正案。

[重大な課題ごとに繰り返します]

---

🟡 重要な課題

1. [ステータス絵文字] 課題のタイトル

ファイル： path/to/file.ts:line

問題： 説明。

修正： 解決方法。

[重要な課題ごとに繰り返します]

---

💡 提案

N 件の提案を表示（M 件対応済み）

#	提案	ステータス
1	説明	✅ / ⏭️

---

✨ 強み

• 肯定的な所見 1
• 肯定的な所見 2

---

📋 型設計の評価

型	カプセル化	表現力	有用性	強制力	総合
TypeName	X/10	X/10	X/10	X/10	X/10

---

🎯 アクションプラン

マージ前：

• アクション項目 1
• 完了した項目

マージ後（バックログ）：

• 今後の改善

---

_{pr-review-and-document スキルで生成 | ラウンド N | [編集履歴を表示](click edited)}

### Step 5: Write Review Comment (Cache-Aware)

Pipe the formatted content directly to `cache-write-comment.sh` via `--stdin`:

```bash
if [ -n "${EXPECTED_CONTENT_HASH:-}" ]; then
  printf '%s\n' "$REVIEW_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/cache-write-comment.sh --stdin "$PR_NUMBER" --expected-content-hash "$EXPECTED_CONTENT_HASH"
else
  printf '%s\n' "$REVIEW_CONTENT" | ${CLAUDE_PLUGIN_ROOT}/scripts/cache-write-comment.sh --stdin "$PR_NUMBER"
fi

このスクリプトは次の処理を行います：

• ローカルキャッシュを更新します（.pr-review-cache/pr-{N}.json）
• upsert-review-comment.sh --stdin を介して GitHub と同期します（stdin パイプを使用し、一時ファイルは使用しません）
• コメント URL を返します
• このスキルが読み取った後に別のツールがキャッシュを更新した場合は 4 で終了します。その場合は再読み込みし、変更を新しいコメントにマージして、1 回だけ再試行してください

ステップ 6：確認

返された URL を確認して、コメントが正常に投稿されたことを確認します。

ステータスインジケーター

一貫したステータスインジケーターを使用してください。

インジケーター	意味
✅	修正済み／解決済み
⏭️	保留／意図的にスキップ
⚠️	要注意
🔴	ブロッカー／重大

複数ラウンドのレビュー

既存のレビューを更新する場合：

1. このラウンドで新しい指摘が追加されたかどうかに基づいて、review_round とタイムスタンプを更新します。
   • 新しい指摘がある場合： review_round を増やし、updated_at、課題数、ステータスを更新します。
   • 空の更新（新しい指摘なし）： review_round は変更せず、review_sources.claude.last_reviewed_head と review_sources.claude.last_reviewed_at のみを更新します。既存の課題のステータスや件数は変更しないでください。
2. review_sources のメタデータと、Claude 以外の既存の課題セクションを保持します。
3. 同じコメントを維持します（GitHub が編集履歴を記録します）。

以前のレビュー内容は GitHub の「edited」ドロップダウンに保存され、完全な監査証跡を確認できます。

メタデータの移行

古い schema_version: "1.0" メタデータを読み込む場合は、書き込む前にメモリ上でアップグレードします。

1.0 のフィールド	1.1 のフィールド
skill	未設定の場合は created_by、レガシーフィールドの skill、現在の last_writer
agents_run	review_sources.claude.agents_run と、互換性維持期間中のトップレベル agents_run
gemini_integrated_ids	review_sources.gemini.consumed_comment_ids
gemini_integration_date	review_sources.gemini.last_integrated_at

ダウングレードしないでください。新しい書き込みではコメントのメタデータスキーマ 1.1 を使用し、キャッシュのエンベロープは schema_version: "1.0" のままにします。

可能な場合は、この移行に ${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-upgrade.sh を使用してください。その後、${CLAUDE_PLUGIN_ROOT}/scripts/review-metadata-replace.sh を使用して、課題セクションに触れずに、返された JSON を `` ブロックにマージします。

統合に関する注意事項

pr-review-toolkit との併用

このスキルは pr-review-toolkit:review-pr コマンドをラップし、次の処理を行います。

1. 包括的な分析のために opus モデルを強制的に使用します
2. 必ず 6 つすべてのレビューエージェントを実行します（必須）
3. 出力を構造化された PR コメントとしてフォーマットします
4. PR に直接投稿します

文字数制限への対応

レビュー内容が約 40K 文字を超える場合：

1. <details> で折りたたむセクションを増やします
2. 詳細すぎる説明を要約します
3. 詳細なコード例を折りたたみ可能なセクションに移動します

PR がない場合

現在のブランチにオープンな PR がない場合：

• ユーザーに伝えます
• 先に PR を作成するよう提案します：gh pr create

検証チェックリスト

レビューコメントを投稿する前に、次を確認してください。

• PR 番号が正しく特定されている
• 6 つすべてのレビューエージェントが実行されている
• メタデータ JSON が有効である
• 課題数が内容と一致している
• ステータスインジケーターに一貫性がある
• 内容が 40K 文字未満である
• コメントが正常に投稿／更新されている