はじめに
以前、Claude CodeのSkillを使って、プロジェクトごとのレビュー観点を蓄積しながらコードレビューを行う仕組みを作りました。
前回の記事では、プロジェクトごとに1つのレビュー観点ファイルを用意し、/review 実行時にその内容を読み込んでレビューしていました。
また、新しく受けたレビュー指摘は一般化したうえで、同じ観点ファイルへ追加していました。
この仕組みによって、一度受けた指摘を次回以降のレビューへ活用できるようになりました。
一方で、運用を続ける中で、
- 観点ファイルが大きくなる
- 関係のない観点まで毎回読み込む
- 新しい指摘を直接追加するとルールが増え続ける
- 過去のセッションにも再利用できそうな知見が残る
といった課題が出てきました。
今回は、このレビューSkillをその後どのように改善したのかをまとめます。
💁 前回の記事はこちら
前回の構成と課題
前回は、プロジェクトごとに1つのMarkdownファイルを用意していました。
~/.claude/review-checklists/
├── project-a.md
├── project-b.md
├── project-c.md
└── _template.md
Skill本体は別に用意し、/review 実行時に対象プロジェクトの観点ファイル全体を読み込んでいました。
~/.claude/
└── skills/
└── review/
└── SKILL.md
運用を続けるにつれて、1つのファイルにフロントエンド、バックエンド、API、DB、テスト、セキュリティなどの観点が増えていきました。
その結果、フロントエンドだけを修正した場合でも、関係のない観点まで毎回読む状態になり、実行時間やトークン消費が気になるようになりました。
そこで、現在は「観点の分割」と「コマンドの役割分担」を行っています。
現在の構成
レビュー観点ファイルをカテゴリごとに分割
現在は、1ファイルにまとめるのではなくカテゴリごとに分割しています。
~/.claude/review-checklists/sample-project/
├── _index.md
├── 0-common.md
├── 1-frontend.md
├── 2-backend.md
├── 3-api.md
├── 4-database.md
├── 5-test.md
├── 6-performance.md
├── 7-maintainability.md
├── 8-security.md
├── note.md
└── retro.md
それぞれの役割は以下です。
| ファイル | 役割 |
|---|---|
_index.md |
変更内容に応じて読むカテゴリを判断する索引 |
0-common.md |
毎回確認する共通ルール |
1-frontend.md 〜 8-security.md
|
カテゴリごとのレビュー観点 |
note.md |
新しく受けた指摘の一時保存 |
retro.md |
過去セッションから拾った候補の一時保存 |
/review では最初に _index.md を確認し、必要なカテゴリだけを読みます。
例えばフロントエンドの変更であれば、
_index.md
0-common.md
1-frontend.md
5-test.md
のように対象を絞ります。
note.md と retro.md は通常のレビュー時には読みません。
コマンドも4つに分けた
現在は、用途ごとに4つのコマンドへ分けています。
| コマンド | 役割 | 主な書き込み先 |
|---|---|---|
/review <対象> |
プロジェクト固有の観点を使ったコードレビュー | 原則なし |
/review-note <指摘内容> |
新しく受けたレビュー指摘を保存 | note.md |
/review-retro |
過去のセッション履歴を横断して棚卸し | retro.md |
/review-apply |
note.md・retro.md の候補を精査して反映 |
各カテゴリファイル |
以前は /review にレビューと観点追加の役割を持たせていましたが、現在は「レビュー」「蓄積」「棚卸し」「反映」を分けています。
/review
/review はコードレビュー本体です。
_index.md を確認し、変更内容に応じたカテゴリファイルのみを読みます。
基本的には読み取り専用とし、レビューのたびに観点ファイルを直接更新しないようにしています。
これによって、観点が増えても毎回すべてを読み込む必要がなくなりました。
/review-note
/review-note は、新しく受けた指摘をその場で記録するためのコマンドです。
例えば、
/review-note 定数化と同時に既存値を変更する場合は、変更理由が分かるようにする
のように使います。
内容はすぐに正式なレビュー観点へ追加せず、まず note.md に保存します。
こうすることで、
- 今回だけの指摘か
- 他の実装でも使えるか
- 既存ルールと重複していないか
を後から確認できます。
/review-retro
/review-retro は、Claude Codeの過去のセッション履歴を横断して確認し、レビュー観点として再利用できそうな内容を棚卸しするためのコマンドです。
現在のセッションだけではなく、過去のセッションやサブエージェントの記録も対象にします。
毎回すべての履歴を確認するのではなく、retro.md に残している前回の棚卸し記録をもとに、前回以降に更新されたセッションを中心に確認します。
対象には、例えば以下のような内容があります。
- テスト失敗を受けてClaude Codeが修正した内容
- レビュー結果を受けて自律的に修正した内容
- サブエージェントが見つけた問題
- 汎用のコードレビュー機能で見つかった指摘
- 複数セッションで繰り返し発生している修正
抽出した内容は retro.md に候補として保存します。
複数のセッションを確認するため比較的重い処理なので、pre-commitには組み込まず、必要なタイミングで手動実行しています。
note.md と retro.md の違い
この2つはどちらも正式なレビュー観点へ追加する前の一時保存先ですが、情報源が違います。
| ファイル | 情報源 |
|---|---|
note.md |
今その場で受けた新しいレビュー指摘 |
retro.md |
過去のセッションを横断して棚卸しした結果 |
note.md は明示的に受けた指摘、retro.md は作業履歴から後から拾った候補、という使い分けです。
/review-apply
note.md と retro.md に保存した候補は、そのまま正式なレビュー観点にはしません。
/review-apply で、
- 既存ルールと重複していないか
- 一時的な指摘ではないか
- 他の実装でも使えるか
- どのカテゴリへ入れるべきか
を確認したうえで、必要なものだけ各カテゴリファイルへ反映します。
note.md / retro.md
↓
/review-apply
↓
精査
↓
カテゴリファイルへ反映
反映済みの候補も削除せず、反映済みであることが分かる形で残しています。
改善前後
大きく変わった点をまとめると以下です。
| 項目 | 以前 | 現在 |
|---|---|---|
| 観点ファイル | プロジェクトごとに1ファイル | カテゴリごとに分割 |
| レビュー時の読み込み | ファイル全体 | 必要なカテゴリのみ |
| 新しい指摘 | 観点へ直接追加 |
note.md に一時保存 |
| 過去セッションの確認 | なし |
/review-retro で棚卸し |
| 観点への反映 | 直接編集 |
/review-apply で精査後に反映 |
| コマンド |
/review 中心 |
4つに役割分担 |
構成は以前より複雑になりましたが、「レビューすること」と「レビュー観点を育てること」を分けられるようになりました。
まとめ
前回は、
過去のレビュー指摘をSkillに蓄積し、次回以降のレビューで再利用する
ことを中心にしていました。
その後、実際に運用する中で、
- 必要な観点だけを読み込む
- 新しい指摘をすぐ正式ルールにしない
- 過去のセッションからも知見を拾う
- 候補を精査してから反映する
という形へ変更しました。
レビュー観点を増やすことだけでなく、
何をいつ読ませるか、どこから情報を拾うか、どう整理して反映するか
も重要だと感じています。
AIを使った仕組みも、一度作って終わりではなく、実際の運用を通して少しずつ改善していく必要がありそうです。
今後も、レビュー精度と実行時間・トークン消費のバランスを見ながら調整していきたいと思います。
🔥 成長と挑戦を楽しむ仲間を募集中！
スピードリンクジャパンでは、一緒に技術を楽しめる仲間を探しています！
会社の雰囲気や働く環境などをまとめていますので、ご興味のある方はぜひサイトに遊びに来てください！
👉 リクルートサイトを見る"