レビュー観点のSkillsによる管理

前のセクションで、AIレビューがプルリクエストにコメントを投稿する状態は作れました。ただ、いま動いているレビューはClaudeの一般常識に依存しているため、そのままでは実運用に耐えません。まずAIレビューが持つ性質を整理し、その上でSkillsという仕組みで観点を明文化する運用に切り替えていきます。

1. AIレビューの注意点

前節で動いたAIレビューには、以下のような性質があります。運用に乗せる前に、性質を理解しておかないと「思ったより使えない」という印象で終わってしまいます。

1.1 レビュー品質のばらつき

同じプロンプト・同じ変更差分でも、AIが「何をチェックするか」は毎回同じにはなりません。指摘の粒度・拾える観点が実行のたびに変わるため、レビュー結果を再現しにくく、品質にもばらつきが出ます。加えて、モデルのバージョンアップや時期による振る舞い変化にも影響を受けるため、「先週まで拾えていた指摘が、今日は拾えていない」ということも起こります。

さらに、前回のレビューで指摘された内容を対応したのに、次回のレビューでは前回出なかった別の指摘が新しく返ってくる、ということも珍しくありません。1回のレビューで拾える観点が有限で、しかも毎回同じ観点セットが選ばれるわけではないため、対応 → 再レビュー → 新しい指摘 → 対応、と繰り返してもレビューが収束しない状態に陥りがちです。

1.2 組織やプロジェクトの規約に合わない

観点を絞らずレビューさせると、AIは一般的なベストプラクティスに沿った指摘を返します。自チームの命名規則、非推奨としている書き方、過去のインシデントから得た学習など、プロジェクト固有の規約は反映されません。結果、「チーム内ではOKなのに毎回指摘される」「本当に見てほしい観点は素通りされる」というズレが発生します。

例えば「外部公開する認証機能には多要素認証を必須とする」という組織ルールがあっても、AI はそこまでは知らないため、一般的なパスワード認証の実装として問題がなければ素通りします。逆に、社内で非推奨にしている書き方でも一般的には推奨とされていれば、AI からは「良い書き方」として扱われてしまうこともあります。

1.3 細かすぎる指摘

AIは目についた改善案をすべて列挙する傾向があります。細かすぎる指摘や、実装コストに合わないマイクロ最適化まで返ってくると、レビュアーがAIコメントに疲弊し、結果として「AIコメントは読まない」という運用に陥ります。

例えば、数ミリ秒しか変わらないループの書き換え提案、コメントの句読点の付け方、既に別で対応する予定になっているリファクタリング提案などが混ざってくると、本当に対応が必要な指摘が埋もれてしまいます。

2. Skillsの利用

上記3つは、いずれもAIに渡す観点を明文化・固定化することで抑え込めます。Claude Code Action の場合、これを実現するのが Skills という仕組みです。

2.1 Skillsとは

Skillsは、Claudeが参照するタスク別のガイドライン集です。リポジトリの .claude/skills/<skill名>/SKILL.md として配置しておくと、Claudeはプロンプトから該当するSkillを読み込み、その内容に沿って動作します。例えば coding-standards Skill を書けば、AIレビュー時に必ずその規約・優先度・出力フォーマットに従わせられます。

Skillsはリポジトリ内のファイルとして管理されるため、Git上でレビュー・履歴管理・変更追跡できるチーム資産になります。チームの知見が変わればSkillを更新するだけで、AIレビューの精度もそれに追従します。

2.2 前節の注意点をどう解決するか

Skillsを使うことで、前節で挙げた3つの注意点をまとめて抑えられます。まず「レビュー品質のばらつき」は、Skillに「必ず見る観点」と優先度を明文化しておくことで、実行のたびに同じ基準で指摘が入るようになります。「組織やプロジェクトの規約に合わない」については、Skillに自チームのコーディング規約・NG事項・過去のインシデントから得た学習を書き込むことで、一般的なベストプラクティスではなく自チームの規約に沿ったレビューに寄せられます。そして「細かすぎる指摘」も、Skillに重要度別の出しどころとノイズにならない出力方針を書いておけば、レビュアーが本当に見るべき指摘に絞り込めます。

📝 Claude Code 以外のツールでの位置づけ
同じ「AIに恒常的な指示を渡す」目的の仕組みは、他の主要AIコーディング支援ツールにも用意されています。GitHub Copilot では Custom instructions、OpenAI Codex CLI では AGENTS.md が該当します。記述の粒度や複数指針の切り分け方は異なりますが、「観点を明文化してAIに渡す」思想は共通なので、Skillに書いた内容は他ツール向けの指示にも転用できます。

3. coding-standards Skillの作成

Claude Code Actionは、リポジトリの .claude/skills/ 配下に置いたSkillファイルを自動で読み込みます。コーディング規約をここに書くと、Actionがプロンプトと合わせてこの内容もClaudeに渡してくれる仕組みです。詳細は Claude Code Skills(Anthropic公式ドキュメント) に記載があります。

Skillの追加そのものはレビュー対象ではないため、main ブランチに直接追加してpushします。まずローカルを main ブランチに戻して、リモートの最新を取り込みます。

git switch main
git pull origin main

Visual Studio Codeのエクスプローラーで ai-review-handson フォルダを右クリックし、「新しいフォルダー」から .claude/skills/coding-standards を作成し、その中に SKILL.md を作成します。

ai-review-handson
├── app.py
├── .claude/
│   └── skills/
│       └── coding-standards/
│           └── SKILL.md  ← このファイルを作成
└── .github/
    └── workflows/
        └── ai-review.yml

作成したファイルに以下の内容を記述して保存します。なお、以下の Skill は Skills の動作確認用に非常にシンプルにしたサンプルで、実運用に耐えられる内容ではありません。実プロジェクトでは、実際の運用ルール・過去のインシデント・チーム固有の知見を踏まえて内容を書き足してください。

# 開発規約

本ドキュメントは、本プロジェクトの開発とレビューの両方で参照する規約です。

## 命名

- 関数名は動詞から始める
- 変数名は名詞・名詞句にする
- クラス名は PascalCase で書く

## エラー処理

- エラーは呼び出し元まで wrap して返す
- レスポンスの JSON 形式は統一する
- HTTP ステータスは意味に合わせて選ぶ

## テスト

- 変更に対応するテストを追加する
- テストは仕様ベースで書く(実装をなぞらない)

## セキュリティ

- シークレット・トークンはコードに埋め込まない
- 入力バリデーションが必要な箇所で抜けを作らない
- ログに個人情報を出さない

## ドキュメント

- 公開関数には docstring を付ける
- TODO コメントには担当者を明記する

## 指摘の優先度

すべての指摘には以下のいずれかの優先度を付ける。優先度を付けない指摘は投稿しない。

- **must**: マージ前に必ず直す(バグ、セキュリティ、規約違反)
- **should**: 可能なら直す(可読性、命名の改善)
- **nice-to-have**: 覚えておく程度(提案レベルの改善案)

## ノイズを避けるための指針

- 自明な指摘はしない(Prettier や eslint で機械的に直せる範囲)
- 既存コードのスタイルに従う(PR の変更範囲外を「ついでに」直させない)
- 同じ観点の指摘は1つに集約する(同じ内容を複数箇所で繰り返さない)
- 意見が分かれるトピックは指摘しない(設計判断は人間のレビュー領域)

## 指摘のフォーマット

- 該当行に紐づけて投稿する(PR コメントではなく inline review comment)
- 「なぜそう変えるべきか」の理由を1文添える
- 修正案がある場合は、コードブロックで具体的に示す
- 優先度は指摘の冒頭に `[must]` `[should]` `[nice-to-have]` で明示する

なお、このSkillには「あなたはコードレビュアーです」のような役割の指示は含めていません。役割・ペルソナはSkill側ではなく、呼び出し側(本章では ai-review.yml の prompt)で渡すのが一般的です。Skillはタスクの中身(規約・観点・出力方針)を持ち、呼び出し側は「誰として、何をするか」を渡す、という役割分担にしておくと、同じSkillを別の呼び出しコンテキスト(例: ローカルのClaude Codeでの手動レビュー)から再利用しやすくなります。

各セクションの狙いを整理します。

セクション 記載内容 期待する効果
命名・エラー処理・テスト・セキュリティ・ドキュメント 各領域の規約を定義する AIレビューが自チームの規約に沿った指摘を返すようになる
指摘の優先度 must・should・nice-to-have の3段階を規定する レビュアーが重要度を1目で判断でき、対応の優先順位が付けやすくなる
ノイズを避けるための指針 自明な指摘の抑制・既存スタイルの尊重・重複回避を定義する AIコメントのノイズが減り、レビュアーが読み流さなくなる
指摘のフォーマット inline コメント・理由の明示・修正案の提示・優先度の明示を規定する AIコメントが読みやすく、開発者が対応するときの手がかりが揃う

4. Skillを反映したプルリクエストで動作確認

Skillファイルを main にコミット・pushし、その後のプルリクエストでAIレビューの精度がどう変わるかを確認します。

git add .claude/skills/coding-standards/SKILL.md
git commit -m "Add coding-standards skill"
git push origin main

main にSkillが反映されたら、もう一度意図的な問題を含むプルリクエストを出してAIレビューを確認します。前セクションのブランチには手を加えず、main から新しくブランチを切ります。

git switch -c intentional-issues-v2

Visual Studio Codeで app.py を以下の内容に書き換えます。

import os

API_KEY = "sk-1234567890abcdef"


def calculate_total(items: list[dict]) -> int:
    """商品リストの合計金額を計算する"""
    total = 0
    for item in items:
        total += item["price"] * item["quantity"]
    return total


def do_thing(data):
    return eval(data)

初期状態の app.py(calculate_total 関数のみ)に対して、前セクションと同じ意図的な問題を再度含めています。同じ問題を Skill 適用前と適用後で比較することで、AI レビューの粒度・優先度・出力フォーマットがどう変わるかを確認する狙いです。今回加えた変更は以下の3点です。

  • 未使用の import os の追加
  • API_KEY = "sk-1234567890abcdef" — シークレットのハードコード
  • def do_thing(data): return eval(data) — eval の使用、意味のない関数名、型ヒントの欠如

変更をコミットしてPushします。

git add app.py
git commit -m "Add eval and hardcoded key (v2 for review demo)"
git push -u origin intentional-issues-v2

intentional-issues-v2 から main へのプルリクエストを作成します。

プルリクエストを作成すると、ai-review.yml ワークフローが起動し、Claude Code Action が coding-standards Skill の規約を参照した状態でレビューを投稿します。

インラインコメント

APIキーのハードコードには [must] の優先度が付き、環境変数から読み込む形への Suggested change が提示されます。すでにpush済みのシークレットに対する対応(無効化・再発行)まで明記されています。

eval の指摘にも [must] が付き、代替関数(ast.literal_eval / json.loads)を示したうえで、規約の「関数名は動詞から始める」「公開関数には docstring を付ける」に紐付ける形で parse_literal への書き換え案がまとめて提示されます。

calculate_total の入力値検証には [should] が付き、キー欠落・負数・非数値などの想定外入力に対する扱いを決めるよう促されます。修正例のコードブロックも添えられています。

総評コメント

gh pr comment 経由でプルリクエスト全体への総評が投稿されます。must / should / その他 の3セクションで指摘がまとめられ、「セキュリティ上の重大な問題が2点あるため、現状ではマージ不可」という判定まで含まれています。

Skill 適用前と比べての変化

前セクション(Skill 適用前)の結果と比べて、次の変化が確認できます。

  • 指摘の冒頭に [must] [should] の優先度ラベルが付き、対応の優先順位を判断できるようになった
  • Skill に書いた規約への言及(「規約:関数名は動詞から始める/公開関数には docstring を付ける」など)が指摘の根拠として明示されるようになった
  • 総評コメントも must / should / その他 に構造化され、マージ可否の判定まで含む形になった

5. 改善サイクルの回し方

💡 ポイント
Skill は一度書いたら終わりではなく、AIレビューを回しながら育てていく資産です。指摘に混ざる「有用なもの」と「ノイズ」を見て、ノイズになる観点はSkillに「この場合は指摘しない」旨を追加し、見落としている観点はSkillに書き足していきます。この調整をプルリクエストのたびに繰り返すことで、レビューの質がSkillの質に集約されていきます。