DIVX テックブログ

catch-img

Claude Codeのスキルでコードレビューはどう変わる?あり/なしを比較

AIにコードレビューを頼んでみたら、「それっぽい指摘はたくさん出るけど、本当に困っているところは拾ってくれない…」と感じたことはありませんか?

特に、小さなプロトタイプなどでは、人にレビューを頼む前に、まずAIで一通り確認しておきたい場面も多いと思います。

結論から言うと、Claude Codeのカスタムスキルに「このプロジェクトだけの事情」を書いておいたら、AIレビューの誤った指摘がなくなり、プロジェクトに合った指摘が出るようになりました。

なぜなら、汎用のAIレビューはコードしか見ておらず、「なぜそう書いたのか」「何をしてはいけないのか」を知らないからです。

実際に私も、ブラウザで動く小さなプロトタイプアプリで、プロジェクト専用のレビュー用スキルを作りました。そして、同じ変更をスキルあり/なしでレビューさせて比べてみたところ、はっきりした違いが出ました。

本記事では、スキルの作り方とレビュー用スキルに書くべきこと、そして比較結果を、良かった点も悪かった点も正直にお伝えします。

こんな方に読んでほしい

  • Claude Codeを使っているけど、スキル(SKILL.md)はまだ作ったことがない人
  • AIにコードレビューを頼んでいるけど、指摘がしっくりこない人
  • 人にレビューを頼む前に、AIで一通り確認しておきたい人

この記事を読むと、自分のプロジェクト用のレビュースキルを、今日から書き始められるようになります。

Claude Codeのスキルでコードレビューはどう変わる?あり/なしを比較

Claude Codeのスキルとは? プロジェクト専用の「手順書」をAIに渡す仕組み

まずは、スキルについてざっくり押さえておきましょう。

Claude Codeのスキルは、特定の作業の手順やルールを書いたMarkdownファイルです。リポジトリの .claude/skills/<スキル名>/SKILL.md に置いておくと、Claude Codeが必要なときに読み込んで、その手順どおりに作業してくれます。

作り方は、次の3ステップだけです。

  1. リポジトリに .claude/skills/my-review/ フォルダを作る
  2. その中に SKILL.md を作り、先頭に名前と説明、続けて手順やルールを書く
  3. Claude Code で「レビューして」と頼む(または /my-review で呼び出す)

SKILL.md の先頭は、たとえばこんな感じです。

---
name: my-review
description: このリポジトリの変更をコードレビューする。「レビューして」と頼まれたとき、またはコミット前に使う。
---

ポイントは description です。ここに「どんなときに使うか」を書いておくと、「レビューして」と頼むだけで自動でスキルが使われます。

CLAUDE.md との違いは、読み込まれるタイミングです。CLAUDE.md は毎回読み込まれる「常識」、スキルは名前と説明だけを覚えておき、本文は必要なときに読む「作業マニュアル」というイメージです。

レビューの観点は、レビューのときにしか使いません。普段の会話で毎回読み込ませる必要はないので、スキルに分けておくのがちょうどいいんです。

さらに、リポジトリにコミットしておけば、チームのメンバーも同じスキルを使えます。

プロジェクト専用レビュースキルに書いたこと

スキルの中身をそのままお見せすることはできませんが、どんな種類のことを書いたかを紹介します。大きく分けると、次の4つです。

レビュースキルに書いたこと

  • 過去に実際にハマった場所
  • このプロジェクトで守っている方針
  • コードを読んでも分からない事情
  • 確認の手順と、報告のしかた

ポイントは、どれも「一般的なレビュー観点」ではなく、このプロジェクトだけの話だということです。

過去に実際にハマった場所

まず書いたのは、自分が過去につまずいた場所です。

たとえば、このアプリにはビルドも型チェックもないので、JavaScriptで指定したIDがHTMLに無くても、実際に動かすまで気づけません。 また、処理の開始・停止まわりでは、ボタンの表示と内部の状態が食い違う不具合に何度も悩まされました。

こうした「前にここで壊れた」という情報を書いておくと、AIに毎回そこを確認してもらえるので、見落としを防ぐ保険になります。

このプロジェクトで守っている方針

AIは親切なので、「npmでライブラリを入れましょう」「ビルドツールを導入しましょう」と提案してくることがあります。

でも、このプロジェクトは「ビルドなしで、ファイルを置くだけで動く」ことを大事にしています。そこで、守りたい方針と、その理由を書いておきました。

コードを読んでも分からない事情

個人的に、一番スキルに書いてよかったのがこれです。

  • 画面の言葉を、なぜその表現にしているのか(仕様上の理由)
  • 過去に、意図して削除した文言や機能
  • 画面の中で揃えておきたい用語

たとえば、ある文言が消えていたとしても、「わざと消した」のか「うっかり消えた」のかは、コードだけでは区別できません。

こういう「プロジェクトの事情」は、書かない限り、AIは知りようがないんです。

確認の手順と、報告のしかた

コードを読むだけでは、画面の崩れや文言の違和感は分かりません。そこでスキルには、画面に関わる変更があったら、Playwright(MCP)で実際に表示して確認する手順も書きました。

ここで工夫したのは、次の3点です。

  • file:// では一部のブラウザ機能が動かないので、最初からローカルサーバーで開くよう指示する
  • 文言の確認は、画像ではなくテキストで取れるスナップショットを使う(軽くて正確)
  • 毎回出る無害なログを「無視してよい」と書いておき、誤った指摘を防ぐ

特に3つ目は地味ですが大事です。書いておかないと、そのログを「エラーです」と報告されるおそれがあります。

さらに、次のようなことも決めておきました。

  • 実際のデバイスを使う操作など、自動で試せないことは「試していない」と報告する
  • 報告の形式をそろえる
  • レビューのときはコードを修正しない(レビューと修正を分ける)

【検証】Claude Codeのスキルあり/なしで、同じ変更をレビューさせてみた

正直に言うと、思っていたのとちょっと違う結果も出ました。

比較の条件

  • 対象:コミット前の同じ変更(HTML 1ファイルと JS 2ファイル)
  • 同じモデル(Claude Opus 5.5)のサブエージェント2つに、同時にレビューを依頼
  • スキルなし:「コミットされていない変更をレビューして」とだけ指示(スキルは使わせない)
  • スキルあり:「SKILL.md の手順どおりにレビューして」と指示。あわせて、Playwright での画面確認も行うよう指示し、ツールの読み込み方を伝えた

比較結果

スキルなし

スキルあり

指摘の数

12件

7件+「問題なしと確認した点」8項目

誤った指摘

1件(しかも重要度:高)

0件

ブラウザでの確認

なし

あり(Playwrightで実測)

所要時間

約52秒

約87秒

トークン

約7.4万

約8.2万

※今回は1回ずつの比較なので、あくまで「傾向の一例」として見てください。

数字だけ見ると、スキルなしのほうが指摘が多いですよね。中身を見ていくと、共通点と違いがはっきり分かれていました。まずは共通点から見ていきます。

共通:大事なバグの多くは、どちらも拾えた

動作に関わる大事なバグの多くは、どちらのレビューも同じように指摘していました。

たとえば、先ほど書いた「何度も悩まされた」開始・停止まわりでは、「停止してすぐ開始すると、前の処理が新しい処理を壊す」という不具合が新たに見つかりました。これは、どちらのレビューも指摘していて、修正案も同じでした。

つまり、スキルがなくても、コードを読めば分かるバグはちゃんと見つかります。 違いが出たのは、その周りの部分でした。

違い①:スキルなしは、一番上の指摘が間違っていた

スキルなしのレビューは、一番最初に、重要度「高」として、次のように指摘してきました。

.gitignore に HTML と JS の3ファイルが入っていて、無視対象になっている

ところが、実際の .gitignore に書いてあるのは、Playwrightの出力フォルダ(.playwright-mcp/)の指定だけ。git check-ignore で確かめても、この3ファイルは無視対象ではありませんでした。

一番目立つところで間違えられると、ほかの指摘も信じられなくなり、結局すべての指摘を自分で確認し直すことになります。これ、地味にこたえるんですよね…

一方、スキルありのレビューは同じ .gitignore を見て、「.claude/settings.local.json(個人用の権限設定)が .gitignore に入っていないので、コミット前に判断してください」という正しい指摘をしていました。

違い②:プロジェクトの事情を知っているかで、判断が変わった

今回の変更では、以前画面にあった「別サービスへの案内文」を削除していました。

  • スキルなし:「この案内文が削除されていますが、意図した変更ですか?」と迷う
  • スキルあり:意図した削除として扱い、問題として挙げなかった

スキルに、削除した文言についてのルールを書いておいたので、消したこと自体は問題なしとして扱えたわけです。

さらに、スキルありだけが拾った指摘もありました。

スキルありだけが拾った指摘

  • 画面の中で、同じ機能が2通りの名前で呼ばれている
  • 「結果をリセットしたい場合はページをリロードしてください」という案内が、今回追加した「クリア」ボタンと合っていない
  • 画面に書かれた「APIのバージョン」は、正確には使っているモデルの名前

どれも、スキルに画面の言葉についての事情を書いたからこそ出てきた指摘です。スキルなしのレビューも注意書きの変更には触れていましたが、言葉の揺れや、案内文と動作のずれには触れていませんでした。

違い③:「推測」ではなく「実測」で指摘してくれた

スマホで表示したときにレイアウトが崩れる問題は、どちらのレビューも指摘しました。ただ、根拠がまったく違います。

  • スキルなし:CSSから判断して、横スクロールが発生すると指摘
  • スキルあり:Playwrightで幅375pxにして、「左カラムの幅が2pxになる」「横スクロールが発生する」と実際の数値で報告

さらに、スキルありは「実際のデバイスを使った操作と、外部APIの実際の呼び出しは試していない」と、確認していない範囲まで書いてくれました。

違い④:「問題なし」も報告してくれる

スキルありのレビューは、指摘だけでなく、スキルに書いた項目ごとに「確認して問題なし」も返してくれました(今回は8項目)。

指摘がゼロの項目も「ちゃんと見た」と分かるので、レビューを受ける側として安心感がまったく違います。

正直に言うと:スキルありが見落としたものもある

ここまでスキルありを推してきましたが、良いことばかりではありませんでした。

スキルなしのレビューだけが拾った、正しい指摘もあります。

スキルなしだけが拾った指摘

  • 処理の再開に失敗しても、例外を握りつぶしているので気づけない
  • 停止→再開すると、各行の時刻が 00:00 から数え直しになり、前の行と区別できない
  • 状態表示に aria-live がない(アクセシビリティ)

チェック項目を細かく書いた分、そこに集中して視野が狭くなったのだと思います。

ちなみに、時間は約1.7倍、トークンは約1.1倍に増えましたが、ブラウザでの確認が主な理由だと思います(ツールの呼び出しは3回→17回に増えていました)。正確さと引き換えなら、十分許容範囲だと感じました。

レビュースキルを書くときの4つのコツ

比較の結果をふまえて、レビュー用スキルを書くときのコツをまとめます。

スキルを書くときのコツ

  1. 一般論ではなく「このプロジェクトで実際に起きたこと・決めたこと」を書く
  2. 「なぜそうするのか」も一緒に書く
  3. 確認できないこと・無視してよいことを明記する
  4. チェック項目以外の気づきも拾わせる

1. 「このプロジェクトで起きたこと」を書く

「エラー処理を確認する」のような一般論は、スキルに書かなくてもAIはチェックしてくれます。

書くべきなのは、「この文言はわざと消した」「この言葉はこういう理由で使わない」のような、コードを読んでも分からない情報です。過去にハマった場所、チームで決めたルールなどを、そのまま書いてしまいましょう。

2. 「なぜ」も一緒に書く

「file:// では一部のブラウザ機能が動かないので、ローカルサーバーで開く」のように理由を書いておくと、AIが似たような状況でも応用して判断しやすくなります。

3. 「できないこと」「無視してよいこと」を書く

  • 自動で試せないことは、「試していない」と報告させる
  • 毎回出る無害なログは、「無視してよい」と書いておく

これだけで、誤った指摘と、確認したフリを防ぎやすくなります。

4. チェック項目以外の気づきも拾わせる

今回の比較で分かった弱点への対策です。スキルの最後に、たとえばこんな1行を足しておくと良さそうです。

上記のチェック項目以外にも気づいたことがあれば、「その他」として挙げる。

または、普段は専用スキルでレビューして、大きな変更のときだけ汎用レビューも併用する、という使い分けもアリだと思います。

まとめ:スキルは「AIへの引き継ぎ資料」。小さく書き始めよう

今回の内容をおさらいします。

  • Claude Codeのスキルは、.claude/skills/<名前>/SKILL.md に置く「作業マニュアル」
  • レビュー用スキルには、コードを読んでも分からないプロジェクトの事情を書くのが一番効く
  • 今回の比較では、スキルありのレビューは誤った指摘がなく、Playwrightでの実測や「確認していない範囲」まで報告してくれた
  • 一方で、チェック項目以外の観点を見落とすこともあるので、「その他」の欄を用意しておくのがおすすめ

書いてみて気づいたのですが、このSKILL.mdは、新しくプロジェクトに入った人向けの「レビュー観点メモ」としても、そのまま読めます。 AIのために書いたものが、人への引き継ぎ資料にもなるんです。

最初から完璧に書く必要はありません。「この前ハマったこと」を3行書くところから始めてみてください。

AIレビューの指摘にモヤモヤしている方は、ぜひ自分のプロジェクト用のスキルを作って、AIレビューを「うちのプロジェクトをよく知っているレビュアー」に育ててみてください!

DIVXでは、お客様の業務を理解したうえでの開発や、AIを取り入れたレビューの進め方についてもご相談を承っています。「自社のプロジェクトでも試してみたい」という方は、お気軽にお問い合わせください。

お気軽にご相談ください


ご不明な点はお気軽に
お問い合わせください

サービス資料や
お役立ち資料はこちら

DIVXブログ

テックブログ タグ一覧

人気記事ランキング

関連記事