ブランチレビュートラッカー

ブランチレビュートラッカー は何をしますか？

複数ラウンドにわたって修正されるブランチのレビューです。各ラウンドでブランチを再レビューし、1つのページを更新します。そのページは、ステータスと、証拠、原因となったコミット、確認すべき場所を示す詳細ポップアップを備えた番号付きの問題リストです。

このページは claude.ai のアーティファクトであり、レビューの記録です。閲覧者にとっては読み取り専用です。レビューと修正が進むにつれて、Claude のみがステータスを変更します。新しいセッションは、会話やローカルファイルからではなく、ページの小さな context.json から再開されます。

トラッカーは3つのファイルを保持します。

• index.html: ページ、assets/tracker.html のコピー。
• issues.json: すべての問題とセッションログ。
• context.json: 再開用のメモ、次のセッションのため問題のインデックス、それを開始するプロンプト、およびページが表示する唯一の部分であるユーザーを待っているものの短いリスト。

1. レビュー対象を尋ねる

最初に候補を収集し、次にすべてを1回の AskUserQuestion 呼び出しで尋ねます。PR番号やURLなど、呼び出し時に回答が既に提供された質問はスキップします。

git for-each-ref --sort=-committerdate --count=6 --format='%(refname:short)' refs/heads
git symbolic-ref --short refs/remotes/origin/HEAD      # デフォルトのベース
git log --format=%s <base>..<target> | grep -oE '[A-Z]+-[0-9]+' | sort -u
gh pr list --head <target> --json number,url,title     # または: glab mr list --source-branch <target>

質問	選択肢
ターゲットブランチ	PRが指定された場合はPRのヘッドブランチ。それ以外の場合は、ベース以外で最近更新された3つのローカルブランチ
ベースブランチ	リモートのデフォルトブランチ（推奨）、次いで他の長期ブランチ（存在する場合）
チケット	ブランチ名とそのコミット件名から見つかったID。チケットなし

ユーザーは常に別の値を入力できます。チケットに関する質問は、ブランチが判明した後に行うか、最も可能性の高いターゲットから選択肢を導出します。

2. 環境を確認する

プリフライトスクリプトを実行し、そのテーブルをユーザーに表示します。

<このスキル>/scripts/preflight --target <ブランチ> [--base <ベース>] [--ticket <ID>]

これにより、リポジトリ、両方の参照、ユーザーのチェックアウト、ローカルブランチがPRヘッドと一致するかどうか、ホスト上のPR、git worktree を妨げる可能性のあるチェックアウトフィルター、およびレビューで使用されるCLIがチェックされます。終了コード2はブロッカー、1は警告のみを意味します。プロジェクトのビルドツールはチェックしません。これらはプロジェクトのヘルパースキルに属します。

スクリプトは両方のブランチをフェッチします。ベースは origin（最新の状態）から取得し、ターゲットはクローン（作成者がプッシュした可能性がある場所）から取得します。スクリプトが出力する参照に対してレビューを実行します。ローカルブランチがPRヘッドと異なるという警告が出た場合は、PRヘッドをレビューします。チェックアウトせずに git show <sha>:<path> で読み取ります。

次に、スクリプトでは確認できないこのセッションのツールを確認し、テーブルに追加します。

必要なもの	ツール	ない場合
レビュー	code-review スキル、または Agent ツール	ブロッカー
ページ	Artifact ツール	ファイルをスクラッチパッドに保持し、各ラウンド後にユーザーにそのパスを提供する。その旨を伝える
チケットのコンテキスト、およびチケットの投稿	Atlassian ツール（getJiraIssue、createJiraIssue）	チケットなしでレビューする。その旨を伝える
PRのコメントとチェック	gh または glab（認証済み）	ブランチのみをレビューする。その旨を伝える

次に、以下の「ヘルパースキル」の説明に従ってプロジェクトのヘルパースキルを探し、見つかった場合はその名前とともに、見つからなかった場合はレビューで不足するものとともに、ヘルパーごとに1行をテーブルに追加します。

ブロッカーがあれば停止し、不足しているものを伝えます。警告の場合は、レビューでカバーされない内容を伝え、続行します。

チケットが読み取れる場合は、そのサマリーとステータスを取得します。IDの後にステータスを括弧書きで記述します: PROJ-123 (進行中)。

3. 最初のラウンド

1. レビュー。 <target> に対して <base> を基準に code-review を呼び出すか、PR番号に対して呼び出します。レビュアーに、他のコミットは git show <rev>:<path> で読み取り、ユーザーのディレクトリ内で決してチェックアウトしないように指示します。

2. プローズをレビュー します（「プローズレビュー」の説明に従って）。code-review はコードの欠陥を探すものであり、プローズはカバーしません。

3. すべての所見を検証 します（「所見の検証」の説明に従って）。問題はこのステップの後にのみページに追加されます。このステップを通過しなかった所見は、リストに追加される前に破棄されるか、リストに追加された後は理由とともに dismissed（却下）に設定されます。

4. すべての問題を分類します。

   • 原因となったコミット: git log -S'<記号>' <base>..<target>、または git blame -s <target> -- <path>。
   • ベースにも同じ問題があるかどうか: git show <base>:<path>。ベースに既に存在する問題には "commitRole": "Pre-existing on" と "commit": "<base>" が設定されます。これはブランチのリグレッションではありませんが、ブランチが問題を悪化させる場合（例えば、より多くのデータを公開するなど）には、マージをブロックする可能性があります。
   • レビューされたコミットにおけるすべての場所の file:line。

5. トラッカーを書き込みます （セッションのスクラッチパッド内、ブランチ名のフォルダー名（/ は - に置き換え）に）。

   • index.html: assets/tracker.html のコピー。__TITLE__ はページ名に置き換えられます。ページ名は、ブランチのトピックを2〜4語で表し、その後に「レビュー」を付けたもの（例：APIキー認証レビュー）。
   • issues.json と context.json（「データファイル」の説明に従って）。

6. 両方のファイルを検証 します。バリデーターはスキーマ、すべての場所がレビューされたコミットに存在すること、および context.json のインデックスが問題と一致することをチェックします。

   python3 -I <このスキル>/scripts/validate-issues.py <dir>/issues.json --repo <リポジトリ>
   

7. 公開します。Artifact ツールの公開アクションを使用し、file_path を <dir>/index.html に、files を {"issues.json": "<dir>/issues.json", "context.json": "<dir>/context.json"} に、icon を "checklist" に、description を1文で設定します。返された URL を両方のファイル（"artifact"）に書き込み、再公開し、リンクをユーザーに提供します。

4. 以降のラウンド

ユーザーがブランチが更新されたと言った場合、または再レビューを要求した場合にラウンドを実行します。

1. ブランチが移動したことを確認します。 PRヘッドまたはターゲット参照を reviewed と比較し、git reflog -3 --date=iso <target> を確認します。プッシュは遅れて到着する可能性があり、ユーザーのローカルブランチはPRに遅れる可能性があります。何も移動していない場合は、その旨を伝えて停止します。
2. ベースをフェッチ します（git fetch origin <base>）。ベースが移動した場合は、それを記録し、git range-diff <old-base>..<old-tip> <new-base>..<new-tip> でブランチを比較します。
3. 変更内容を確認します:
   • git range-diff <base>..<reviewed> <base>..<target> は、どのコミットが書き換えられたか、追加されたか、削除されたかを示します。
   • git diff <reviewed> <target> は正味の変更を示します。
   • PRの新しいコメント、レビュー、チェック（gh pr view <n> --json comments,reviews、gh api repos/<owner>/<repo>/pulls/<n>/comments、gh pr checks <n>）。
4. すべての修正を評価します。 変更が対処する各問題について、修正を読み、fix にその内容とコードの現在の動作を記録します。読み取りで確認できた場合のみ fixed に設定し、verified にどの程度検証されたかを記述します。
5. 修正によって引き起こされる問題を探します。 修正は問題を除去するのではなく、移動させることがよくあります。古いコードが偶然処理していた入力を確認します。
   • 欠落、空、または null の値。例えば、クライアントが設定しないプロパティが、以前は無害なリテラルを生成していたが、現在は「制限なし」を意味する場合。
   • 値がフォールバックするデフォルト。
   • 変更が触れることなく到達するコードパス。例えば、呼び出し元、他のエンドポイント、古いクライアント、エクスポートのインポート側など。
   • 変更が意図していないリクエストに対して変更が変更する動作。 各問題を新しい問題として追加し、両方の問題に対してそれを引き起こした修正を記録します。正味の変更に対して「プローズレビュー」を実行します。
6. 修正されていないすべての問題 を新しいコードに対して再評価し、コードが変更された修正済みの問題も再度確認します。
7. テストを実行する のは、以下の「テストによる再現」で許可されている場合のみです。
8. トラッカーを更新します（「トラッカーを最新に保つ」の説明に従って）。
   • reviewed を新しいチップに設定します。
   • commits を新しいハッシュに書き換えます。書き換えられたコミットは新しいハッシュを取得し、削除されたものはマップから削除され、新しいものは追加されます。
   • 変更された問題の status、commit、commitRole、note、fix、detail を変更します。
   • git grep -n を使用して、新しいチップにおける各場所の行を再検出します。算術演算で行をシフトしないでください。
   • 次の空き番号で新しい問題を追加します。番号を振り直さないでください。
9. 検証してから、同じURLに再公開します。
10. ユーザーに報告します: 今回のラウンドで修正された内容、まだ未解決の内容、新しい内容を、ファイル:行と実行された内容とともに伝えます。ページリンクで終了します。

所見の検証

問題がページに追加される前に、レビューされたコミットで自分でコードを読みます。

1. シナリオをエンドツーエンドでトレースします。 入力が入る場所から損害が発生する場所までを追跡し、各ステップを file:line で名前付けます。コードがたどらないステップを必要とする所見は、そのステップを理由として却下されます。
2. 前提条件を確認します。 トリガーとなる状態がどのように発生するかを尋ねます。
   • 誰がどのAPIを通じて入力を作成できるか、そしてバリデーターまたはデフォルトがそれを阻止するかどうか。
   • 無制限の有効期間や、何も指定されていない場合に割り当てられる役割など、設定されたデフォルトがシナリオに到達できなくするか、またはそれを通常のケースにするかどうか。
   • 既存のデータにそれが含まれる可能性があるかどうか。リポジトリ外のデータのみが回答できる場合は、プロジェクトのデータチェックヘルパーを使用します。ない場合は、ユーザーに確認方法を尋ねます。回答を verified とログに記録します。
3. 「意図された」ものと「許容可能な」ものを区別します。 動作が意図的であることを示すランブック、テスト、またはコードコメントは、それを無害にするものではありません。後方互換性を個別に確認します。既存のクライアントとデプロイされたバージョン、既存のデータ、および新しい機能を決して使用しなかったベンダーやユーザー。既存のワークフローの意図的な破壊は問題であり、ユーザーがそれを受け入れない限りブロッカーです。
4. どのように検証されたかを述べます。 verified に書き込みます。「コントローラーレベルのテストで再現されました。サービス層はスタブ化されていました」、「コードを読んだ結果。実行されていません」、「データチェック: 一致するレコードはありません」。証拠が証明するものと、証明しないものを報告します。データが示さない因果関係や比較の判定を主張しないでください。
5. 記録を残して却下します。 却下は status: "dismissed" と、誰がいつなぜ決定したかを示す dismissal を設定します。Claude が却下した場合は、その旨と、誰も承認していないことを述べます。ページはそれを表示します。
6. 異議が唱えられた場合に再開します。 ユーザーが却下または判定に疑問を呈した場合は、それを弁護するのではなく、コードから再確認します。間違っていた場合は、問題を再開し、却下を削除し、以前の判定が何を間違えたかを note に明確に述べます。

テストによる再現

ユーザーが要求した場合、またはリポジトリとユーザーの指示が許可する場合にのみ、ビルドとテストを実行します。プロジェクトのビルド方法とテスト方法、使用するツールチェーンと設定は、このスキルではなく、プロジェクトのビルド・アンド・テストヘルパーとその指示から取得します。

1. ユーザーのチェックアウトを決して使用しないでください。 テスト対象のコミットを別のディレクトリに配置します。
   • git worktree add --detach <スクラッチパッド>/<名前>-wt <sha>;
   • ワークツリーをブロックするものがある場合は、代わりにコミットをエクスポートし、ブロックするパスを除外します: git archive <sha> -- . ':(exclude)<ブロックされたパス>' | tar -x -C <dir>。例えば、git-crypt のsmudgeフィルターは、キーが利用できない場合に暗号化されたパスで失敗します。プリフライトスクリプトは、チェックアウトフィルターを持つパスを指定します。
2. プロジェクトの指示に従ってビルドして実行します。 プロジェクトがサポートしていないツールチェーンなど、ツールの障害はテスト結果ではありません。プロジェクトのヘルパーまたは指示に従って環境を修正し、再実行します。ヘルパーがない場合は、推測するのではなくユーザーに尋ね、プロジェクトノートのために学んだことを記録します。
3. 正しい動作をアサートするようにテストを記述します。 その後の失敗は問題を再現し、同じテストが修正の回帰テストになります。パスに沿って実際のクラスを駆動し、シナリオが必要とするものだけをスタブ化します。各スタブを実際のコードの動作を反映するようにし、verified でスタブ化された、または実行されなかったすべてのレイヤー（HTTP、セキュリティチェーン、データベースなど）を指定します。
4. 最も狭いセットを実行します: 新しいテストと、変更されたコードをカバーするテスト。
5. テストソースをトラッカーに保持します。 スクラッチパッドはセッション間で消去される可能性があります。テストを files 内の tests/<名前>.<拡張子> として、contentType: "text/plain" で公開し、問題内で名前を指定します。
6. クリーンアップします。 ワークツリーまたはエクスポート、およびユーザーのチェックアウトに残ったビルド出力（後続のビルドが拾うコンパイル済みテストクラスなど）を削除します。次に、git status と git worktree list でユーザーのチェックアウトが変更されていないことを確認します。

ヘルパースキル

レビューフローはすべてのプロジェクトで同じです。プロジェクトに関する知識は、それ独自のスキルにあります。それらが存在する場合は使用します。このスキルはプロジェクトのツールをハードコードしません。

セッションで利用可能なスキルのリストから、その説明によってそれらを見つけます。名前を推測しないでください。ステップで必要になったら、Skill ツールを使用してロードします。

ヘルパー	使用目的	ない場合
レビューチェックリスト	プロジェクトのリスク領域: セキュリティモデル、互換性の約束、API契約、移行	レビューは一般的な知識に依存します。見逃す可能性のある領域を伝えます
ビルドとテスト	1つのコミットを分離してビルドおよびテストする: コマンド、ツールチェーン、設定、既知のブロッカー	テストはユーザーに方法を尋ねた後にのみ実行されます。所見は「コードを読んだ結果」のままです
データチェック	リポジトリ外のデータから質問に安全に回答する	ユーザーに確認方法を尋ねます
プローズルール	コメント、ドキュメント文字列、変更ログ、コミットメッセージ、PRテキスト。例えば、一般的な…

[以下、翻訳のために省略]

プローズレビュー

このセクションは元のコンテンツで不完全でした。翻訳は対応する原文に基づいて完了します。

データファイル

このセクションは元のコンテンツで不完全でした。翻訳は対応する原文に基づいて完了します。

トラッカーを最新に保つ

このセクションは元のコンテンツで不完全でした。翻訳は対応する原文に基づいて完了します。