ClaudeによるコードレビューをAgent Skillsで育てる

2026-03-24 Report
#claude #review #agentskills
  1. 背景
  2. 以前の構成で課題だったこと
  3. 役割ごとにskillを分けた
  4. 自動レビューと対話モードが同じskillを読む
  5. tuningもskillだけを更新する
  6. 現在の構成の良いところ
  7. おわり

背景

前回の記事では、Claudeのレビューに対する開発者の反応を収集し、.github/copilot-instructions.md と CLAUDE.md を自動更新する仕組みを紹介した。

この仕組み自体は、いまは所属チームの複数プロダクトでかなり広く使っている。 指摘の妥当性やコンテキストの読み方という点で、既存の自動レビューとは手応えが違う。実際、リポジトリ次第では人間がほとんどレビューしておらず、Claudeとのやり取りを中心とした運用になっている。

その後、実際に運用している claude-review.yaml と claude-review-tuning.yaml は大きく変わった。 現在はpromptを直接育てるのではなく、Agent Skillsを中心に据える構成である。 自動レビューと、専用メンションによる対話が、同じ知識源を参照するようになっている。

主な変更点は以下の3つ。

前回の記事の末尾では、「direct_prompt と custom_instructions が prompt に統合されたら工夫が必要そう」と書いていたが、知識や判断基準をskillへ分離する形に進んだため、この懸念はかなり薄くなっている。

以前の構成で課題だったこと

前回の構成でも、レビュー品質を継続的に改善するという目的は達成できていた。 ただ、運用していくと次の点が気になってきた。

特に大きかったのは2つ目。 レビューコメントを付ける場面だけでなく、開発者が専用メンションでClaudeと会話しながら「この指摘の意図は何か」「そのまま修正してほしい」とやり取りする場面でも、同じ判断基準と同じプロジェクト知識を参照してほしかったためだ。

役割ごとにskillを分けた

現在の claude-review は、以下の2つのskillを読む前提になっている。

役割は明確に分けた。

code-review-guidelines には自動更新用のマーカーを置いた。

# Code Review Guidelines

<!-- claude-review-tuning -->

<!-- /claude-review-tuning -->

人間が手で書く長期的な方針はこのマーカーの外に置き、自動チューニングはマーカー内だけを書き換える。 これにより、「人間が決めた原則」と「最近のフィードバックから学んだ調整」を同じファイルに共存させやすくなった。

自動レビューと対話モードが同じskillを読む

現在の claude-review は、自動レビュー用と対話用の2系統を1つのreusable workflowにまとめている。

自動レビュー側では、promptの中でskillを読むように明示している。

prompt: |
  ...
  If the skills "code-review-guidelines" and "project-knowledge" are available, load them before starting the review.
claude_args: >-
  --allowedTools "...,Skill(code-review-guidelines),Skill(project-knowledge),..."

PR作成や更新時にはこちらが動作する。 トップレベルの要約コメントは必ず残し、具体的な問題はinline commentで返す。 一方で git add / git commit / git push は禁止しており、あくまでレビュアーとして振る舞わせている。

対話モードは、たとえば @claude のような専用メンションで起動する。

trigger_phrase: "@claude"
--append-system-prompt "Only modify or edit code when the user explicitly requests a fix, change, or implementation."

レビューの再確認や説明依頼であればcomment-onlyのまま応答し、明示的に修正を依頼されたときだけコード変更に入るように分けている。

つまり現在の claude-review は、

という1本の流れにまとまっている。

tuningもskillだけを更新する

claude-review-tuning の役割も変わった。 前回は .github/copilot-instructions.md や CLAUDE.md を更新していたが、現在はskillファイルだけを更新する。

流れは次の通り。

  1. collect.ts が前回のtuning PR以降にマージされたPRを収集する
  2. bot作成のPRは除外し、ClaudeとPR authorのコメントだけを時系列で並べる
  3. sync-skills.sh で .agents/skills の体裁を揃える
  4. Claudeがskillを更新するPRを作り、自動マージする

収集スクリプトが前回のtuning PR以降だけを見るようになっているため、毎回「最近の運用で実際に起きたこと」だけを材料にできる。 毎回のチューニングで、直近の運用変化をそのまま取り込める。

更新前には必ず sync-skills.sh を通す。 これにより、.agents/skills/<name>/SKILL.md を正規形に保ちつつ、.claude/skills 側からも参照できる状態を維持できる。

実際のtuning promptでは、skill間の責務分離をかなり強く縛っている。

Goal: tune two skills with strict separation of concerns.

Global constraints:
- Do NOT modify YAML frontmatter
- Each file must not exceed 150 lines
- Do not duplicate the same point across files
- If evidence is weak or one-off, do not add a new rule/fact

その上で、

と明示している。 これで、レビュー基準とリポジトリ固有知識を分けて保てるようになった。

ここで、promptやrepository contextを自動的に増やさないのは意図的である。 Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? では、リポジトリ向けのcontextは推論コストを20%以上増やすと報告されている。 その結果、タスク成功率をむしろ下げる傾向があるという。

自分たちの運用で見えていたこととも、この結論はよく一致している。以前はレビュー基準とプロジェクト知識をまとめて増やしていくと、重要ではない指摘や、チームとして意図している設計へのコメントが紛れ込みやすくなった。

だからこそ現在のtuningでは、何でもかんでも知識を足すのではなく、繰り返し役に立ったルールを code-review-guidelines へ寄せている。 リポジトリ固有で安定した事実は project-knowledge にまとめた。 前回のようにprompt本体を自動改善し続けるより、最小限だけをskillとして保つ方が安全だと考えている。

現在の構成の良いところ

まず、何を調整しているのかが前よりはっきり見える。 以前はレビュー方針の変更もリポジトリ知識の追加も、どちらも「指示文の更新」に見えていた。 現在はレビュー基準の調整なのか、プロジェクト知識の追加なのかを分けて読める。

また、自動レビューと対話モードが同じ知識を読むため、定期tuningが形骸化しにくくなった。 レビュー時に学んだことが、PR上の説明や修正依頼でもそのまま使われる。

チューニング差分の意味も読み取れるようになった。 .github/copilot-instructions.md のような長い指示文より、code-review-guidelines と project-knowledge という責務の見えるファイルの方が、何を調整したのかを把握しやすい。

運用ルールも前より言葉にしやすい。 自動レビューではまずコメント中心、対話モードでは必要なときだけ修正へ進む、という役割分担にしている。 細かい権限設計は自分たちの運用前提で割り切っている部分もあるが、少なくともどう振る舞ってほしいかは前より書き分けやすくなっている。

おわり

前回の記事では、「Claudeレビューをフィードバックで自己改善するループ」を作った話を書いた。 今回のフォローアップで書きたかったのは、レビューを継続改善するときにはpromptを育て続けるより、最小限のskillへ責務を分離した方が運用しやすい、という点である。

しばらく回してみても、この方向の方がレビューの継続改善を日常運用に乗せやすいと感じている。 一方で、どこまでを project-knowledge に書かせるか、どのくらいの頻度でtuningするか、といったバランスはまだ試行錯誤中だ。 今後もリポジトリごとの差を吸収しつつ、最小限のcontextでどこまでレビュー品質を維持できるかを引き続き見ていけたらと思う。