レビュアー向けにマージリクエストに注釈を付ける
AIが作成した差分を読むレビュアーは、時間の大半を、作成者がすでに知っていた次の3つのことを再構築することに費やします:なぜこの変更が存在するのか、どのような動作が変わったのか、そして誰がこのコードを呼び出すのか。このスキルは、これら3つを、マージリクエストのレベルで、平易な言葉で書き留めます。ソースコードのコメントとしてではありません。
注釈は3つのレイヤーで構成され、それぞれに異なるルールがあります:
| レイヤー | カバレッジ | 伝える内容 |
|---|---|---|
| 概要 - 1つのMRレベルのコメント | 常時 | 変更全体のマップ |
| ファイル - 変更されたファイルごとに1つのコメント | 常時(自動生成ファイルを除く) | このファイルの変更が意味すること |
| インライン - 差分の行にアンカー | 真に非自明な箇所のみ、バジェットあり | この特定のコードがこのようになっている理由 |
ファイルカバレッジは無条件です:レビュアーが差分内の任意のファイルを開くと、その説明を見つけられなければなりません。何を説明する価値があり、何が自明であるかという判断は、ファイル内のメソッドや個々のハンクに適用され、ファイル全体がカバーされるかどうかには適用されません。
操作モード
| モード | タイミング | 動作 |
|---|---|---|
annotate | MRへの初回実行 | 完全な注釈セットを構築し、プレビュー表示後、承認後に投稿 |
sync | MRブランチへのプッシュ後毎回 | 既存の注釈を新しい差分と照合し、変更があったもののみを更新、削除、または追加 |
このスキルによる注釈がすでにMRに存在する場合(マーカーで検出、§7参照)、annotateではなくsyncを実行してください。annotateを再実行するとコメントが重複します。
1. 事前確認
何かを書き始める前に、以下を確認します:
- プラットフォームとMRの特定。
git remote -v→ gitlab.com/セルフホストGitLab、github.com、またはBitbucket。次に、現在のブランチのオープンMRを見つけます(glab mr view、gh pr view)。MRがまだ存在しない場合は、停止してその旨を伝えます。このスキルは既存のMRに注釈を付けるものであり、作成するものではありません。 - 差分範囲。 常に
git merge-base HEAD origin/<ターゲットブランチ>→<ベース>..HEADを使用します。ベアのターゲットブランチの先端に対して差分を取ってはいけません:ターゲットにマージされた無関係なコミットがこのMRの変更として表示されてしまいます。 - 言語。 プロジェクトのMRですでに使用されている言語で注釈を書きます(既存のMR/PRの説明やコメントを確認)。デフォルトは、ユーザーがあなたに話しかけている言語とします。
- 投稿の権限。 MRへの投稿はチーム全体から見え、レビュアーに通知されます。デフォルトはドライランプレビューを会話内で表示し、ユーザーが承認した後にのみ投稿します。ユーザーが事前に尋ねずに投稿するよう指示している場合のみ、プレビューをスキップします。
references/platform-gitlab.md、references/platform-github.md、または references/platform-bitbucket.md を読んで正確なコマンドを確認してください。コメントAPIは重要点(ファイルレベルのアンカー、解決可能性、更新セマンティクス)で異なります。
2. 変更インベントリの構築
2つのスクリプトは、このファイルの隣の scripts/ にあります。絶対パスで呼び出します。このスキル自身のディレクトリから構築します。実行中のワーキングディレクトリはユーザーのリポジトリであり、スキルではないため、ベアの scripts/... パスは失敗します。以下では、$SKILL はこのSKILL.mdを含むディレクトリを表します(例:ユーザーレベルのインストールでは ~/.claude/skills/annotate-merge-request、またはプラグインからロードされた場合はプラグインの skills/annotate-merge-request)。
python3 "$SKILL/scripts/diff_inventory.py" <base>..HEAD --json > /tmp/sdmr-inventory.json
変更されたファイルごとに、以下を提供します:変更種別(追加/変更/削除/リネーム)、requires_file_comment(自動生成/ベンダリングファイルの場合のみfalse)、file_fingerprint、およびそのファイルのハンク(新しい側の行番号付き。インラインコメントがアンカーする必要があるもの)、最も近い囲みシンボル、および自明性シグナル。スペックファイルとテストファイルについては、test_casesも出力します。これは、差分から読み取るのではなく、2つのリビジョン間のケースボディを比較して計算された、各ケースのステータス(unchanged / adapted / added / removed)を持つファイル内のすべてのケースです。これはあなたの読解のためのヒューリスティックマップであり、代替ではありません。説明しようとしているものについては、実際の差分を読んでください。
各ハンクの anchor は提案です(最初に追加された行)。added_lines は代わりにアンカーできるそのハンク内のすべての行をリストします。説明が実際に関係している行を選択してください。
ハード制約:インラインコメントは差分に表示される行にのみアンカーできます。 GitLabもGitHubも、ハンクから遠く離れた未変更のコードにコメントすることはできません。MRが触れていないコードについて言いたいことはすべて、ファイルコメントまたは概要コメントに記述し、インラインには決して記述しません。
3. レイヤー1 - 変更されたすべてのファイルをカバー
インベントリが requires_file_comment: true とマークしたすべてのファイルは、正確に1つのファイルレベルのコメントを取得します。例外なし、バジェットなし、それが「十分に興味深いか」という判断もありません。
唯一の例外は自動生成およびベンダリングされた出力 - ロックファイル、dist/、スナップショット、コード生成、ミニファイされたバンドル、vendor/です。インベントリはこれらにフラグを立てます。もしプロジェクトが生成するものを見逃した場合、それも除外し、どのパターンを追加すべきかをユーザーに伝えます。
変化するのは形状と長さであり、存在の有無ではありません:
- 実際のロジック変更があるファイルは、完全なテンプレート(
references/annotation-format.md)を取得します:役割、変更理由、変更前→変更後、呼び出し元。 - スペックファイルまたはテストファイルは、代わりにテストケースリストを取得します - 現在含まれているすべてのケースが、それぞれステータス(
unchanged/adapted/added/removed)と、変更されたものについては短い説明と共に表示されます。標準テンプレートはスペックには適していません:それらを呼び出すものはないため、エントリポイントセクションは構造上空になります。インベントリがあなたのためにステータスを計算します(ファイルごとのtest_cases)。adaptedケースはレビュアーが最も必要とするものであるため、最初に表示され、呼び出し形状が変わったのか、期待値が変わったのかを述べる必要があります。完全なルールはreferences/annotation-format.mdにあります。 - 機械的なファイルは、レビュアーが自信を持ってスキップできる1行を取得します:
インポートパスのみ - PricingServiceのリネームに従う。動作変更なし。 - 削除されたファイルは、なぜ削除され、何に置き換えられたかについての1行を取得します。これは多くの場合、MR内で最も有用な注釈の1つです。
これらをファイルレベルのコメントとしてアンカーします(GitHubでは subject_type=file、GitLabでは position_type=file)。行にはアンカーしません。ファイルヘッダーにアタッチされるため、コードと混ざり合わず、レビュアーが各ファイルを開くときに1つずつ目にします。インスタンスがファイルレベルのアンカーリングをサポートしていない場合は、ファイルの最初の変更行にフォールバックします。プラットフォームリファレンスが正確なフォールバックを提供します。
1行をうまく書くことが、ここでのスキル全体です。ボリュームはファイル数に比例するため、機械的なファイルが3段落で説明されているのは欠陥であり、丁寧さではありません。
4. レイヤー2 - 概要コメント
MRレベルでの1つのコメントであり、レビュー全体のエントリポイントです。references/annotation-format.md で指定されている通りに構造化されます:
- 意図 - このMRが解決する問題を、2、3文で平易な言葉で。差分を言い換えないこと。
- 変更前→変更後の動作 - 実行中のシステムの観測者が気づくであろうこと。新しいコンポーネントの場合は、「新しい」と言い、「変更前」をでっち上げない。
- エントリポイントグラフ - 読者が実際のエントリポイント(HTTPルート、CLIコマンド、イベントハンドラ、cron、エクスポートされたAPI)から変更されたコードに到達する方法。最大3レベルに制限。変更された領域ごとに1行、ファイルごとではない。
- 読む順序 - 最初に開くべきファイル、機械的なフォロースルーであるファイル。
- インラインコメントのインデックス - 各インライン注釈へのリンク。
概要には独自のボリューム制限があります(最大7つの読み順エントリ、最大5つの動作行、ファイルごとの列挙は禁止 - それはファイルコメントが行います)。これらは references/annotation-format.md にあります。尊重しないと、概要はファイルコメントが防ごうとしていたテキストの壁になります。
エントリポイントグラフの検証
決してコールグラフを推測しないでください。 でっち上げられた呼び出し元リストは、注釈がないよりも悪いです:自信を持って間違っており、レビュアーはそれを信頼します。主張する各エッジについて、実際の検索(リポジトリ全体で rg -n 'symbolName'、テストと設定を含む)で呼び出し元を見つけ、エントリポイントまたは3レベルのいずれかに到達するまで上方に追跡します。シンボルの呼び出し元を解決できない場合 - 動的ディスパッチ、DIコンテナ、リフレクション、文字列キーのレジストリ - もっともらしい連鎖を書くのではなく、エントリポイント未解決(<理由>) と書きます。
5. レイヤー3 - コードが非自明な箇所のみのインラインコメント
これは判断が伴う唯一のレイヤーです。references/significance-test.md からの有意性テストをすべてのメソッドとハンクに対して実行します。短いバージョン:
注釈を付けるタイミング:読者が「なぜこれがこのようになっているのか?」と合理的に尋ねる可能性がある場合 - 非自明な意図、差分に表示されない動作変更、ローカル外の結果、意図的なトレードオフ、異常なアルゴリズム、回避策、ファイル外部からの制約、または同じMR内の別の変更との相互作用。
スキップするタイミング:コードがこのコードベースの有能な読者にとって自明である場合:文字列をタイトルケースにする5〜10行のヘルパー、DEBOUNCE_MS = 300 定数、明白なnullチェック、機械的なテスト更新。ファイルコメントがすでにファイルをカバーしています。ここでインラインコメントを付けると、価値の低い繰り返しになります。
コードのサイズはテストではありません。その推論距離がテストです。カスタムエンコーディングスキーム内の6行のヘルパーはコメントを必要としますが、200行の生成スナップショットファイルは必要としません。
バジェット(デフォルト、ユーザーが明示的に引き上げる可能性があります):
- ファイルあたり最大3つのインラインコメント、MRあたり最大12。
- これらは上限であり、クォータではありません。ストーリーがファイルコメントで完全に語られているファイルはゼロのインラインコメントを取得し、それが正常なケースです。
- バジェットを超えることはシグナルであり、ライセンスではありません:1つのMR内で12を超える箇所が真に非自明である場合、MRが大きすぎるか、説明が1つのストーリーとして語られる概要に属します。そのことをユーザーに伝えてください。
各インライン注釈は、ファイルコメントと同じセクションを使用しますが、そのハンクにスコープされ、短く保ちます - 3〜6行、狭い差分ビュー内で読めるように。
6. MR内の相互参照
変更が同じMR内の別の変更と一緒にのみ意味をなす場合、それらをリンクします。相互参照は通常エントリポイントグラフに属しますが、意図(「<他のファイル>がXを渡すようになったため必要」)や変更前/後(「古いパスはまだ存在します。<他のコメント>を参照」)にも現れます。ファイルコメントがそれらにとって最も自然な場所です:このファイルの新しいコントラクトは [[ref:order-controller]] によって消費されます。
コメントのURLはコメントが投稿されるまで存在しません。そのため、相互リンクには2つのフェーズが必要です:
- 別の注釈へのリンクが属する場所にプレースホルダートークン(
[[ref:<スラッグ>]])を付けてすべてのコメントを投稿します。 - 作成されたコメントのID/URLを収集し、各本文を編集して、トークンを実際のリンクに置き換えます。
投稿前にスラッグを計画します。すべての [[ref:...]] トークンはフェーズ2で解決されなければならず、投稿されたコメントに残ったトークンは目に見える欠陥です。フェーズ2はオプションではありません。
7. 識別マーカーを付けて投稿
このスキルが作成するすべてのコメントは、レンダリングされたマークダウンでは見えないマーカー行で終わります:
<!-- sdmr:v1 kind=overview -->
<!-- sdmr:v1 kind=file slug=<slug> anchor=<file> ffp=<file-fingerprint> -->
<!-- sdmr:v1 kind=inline slug=<slug> anchor=<file>@<new-line> fp=<hunk-fingerprint> -->
ffp= にはインベントリからの file_fingerprint を、fp= にはハンクの fingerprint を使用します。マーカーは sync を可能にするものです:スキル自身のコメント、それぞれが何にアタッチされていたか、そしてそれが説明したコードのフィンガープリントを識別します。マーカーなしで注釈を投稿しないでください。人間のコメントを編集しないでください。
注釈は未解決のままにしておきます。 解決されたスレッドは折りたたまれてレンダリングされるため、レビュアーはすべての注釈を1つずつ展開する必要があります。これは、注釈が存在する目的そのものを隠してしまいます。それらを開いたまま投稿し、レビュアーが読む際に各自で解決できるようにします。そのクリックが彼ら自身の「読んだ」マーカーになります。
その選択の代償:プロジェクトがマージ前にすべてのスレッドの解決を要求する場合(GitLabのすべてのスレッドが解決されている必要があります、GitHubの会話の解決を必須にする)、マージボタンがブロック解除される前に注釈を解決する必要があります。ファイルごとにファイルコメントがあるため、これは現実的なクリック数になります。そのため、そのような設定を検出したらユーザーに伝え、最後に一括解決を提案します。両方のコマンドはプラットフォームリファレンスファイルにあります。
8. プッシュ後の同期
新しいコミットは、注釈を静かに無効にします:コメントが説明するコードが移動したり、意味が変わったり、消えたりする可能性があります。そして、新しいファイルにはまったくカバレッジがありません。MRブランチへの各プッシュ後に、sync モードでこのスキルを再実行します。
python3 "$SKILL/scripts/sync_state.py" --inventory /tmp/sdmr-inventory.json --comments /tmp/sdmr-comments.json
--comments は繰り返し可能で、プラットフォームの生のJSONをそのまま受け取ります。GitHubではこれは2つの呼び出し(レビューコメントとイシューコメント)であるため、両方のファイルを渡します。
既存の注釈をそれぞれ、ok(アンカーとフィンガープリントが変更なし - そのまま)、moved(同じコード、新しい行 - 再アンカー)、stale(説明したコードが変更された - 再読み取りして書き直し)、または orphaned(ファイルまたはハンクが削除された - 削除)に分類します。また、file coverage も報告します。これは、どの変更ファイルにまだファイルレベルのコメントがなく、どのファイルが免除されているか、そしてインラインコメントの候補となる uncovered ハンクです。
その後、フラグが立てられたもののみを修正し、常に概要コメントをその場で書き直し(MR全体を要約するため、任意のプッシュで無効になる可能性があります)、§6のフェーズ2を再実行して相互参照リンクがまだ有効なコメントを指すようにします。ファイルカバレッジの MISSING 行はオプションの作業ではありません。コメントのない新しいファイルこそ、このスキルが存在して防ぐギャップです。フォースプッシュの場合、プラットフォームごとの削除されたコメントの処理、および実際に変更されていないコメントのチャーンを回避する方法については、references/sync-after-push.md に従ってください。
ユーザーに、これを各プッシュ後に実行する必要があること、そして references/sync-after-push.md にオプションの pre-push フック設定が含まれていることを一度伝えてください。