はじめに

こんにちは！アジャイル事業部の伊藤です。

AI駆動開発では、「AIによるアウトプットをどう評価し、品質を担保するか」という運用面が課題となることが多いと思います。
そこで今回は、AIツールの挙動を定義できる「Agent Skills」を活用し、コードレビューの「型」を仕組み化することで、チーム全体のコード品質の標準化を図った事例をご紹介します。

この記事で得られること

  • 「Agent Skills」を活用したコードレビューの仕組み化：レビューの「型」を作りコード品質の標準化を図る具体例
  • 精度とコストを両立するフォルダ構成：AIの注意力を散漫にさせず、トークン消費も抑える「2層構造」の設計ノウハウ
  • 人間とAIが共生する運用フロー：AIに任せきりにせず、人間が最終判断を担う「Human-in-the-loop」の実践的なサイクル

1. スキルとは

「スキル（Agent Skills）」とは、AIコーディングツール向けの再利用可能な指示セットのことです。

  • オープン標準に基づいており、特定のツールに依存しません。
  • SKILL.md に指示を記述するだけで、AIの振る舞いを定義できます。
都度プロンプト スキル（Agent Skills）
再利用性 毎回の手入力やコピペが必要 プロンプトに応じて呼ぶべきスキルをAIが判断し発動する
品質の安定 書き方によって結果がバラつく 常に同じ指示が適用される
チーム共有 個人のノウハウに留まりがち リポジトリで管理・共有できる

2. 背景：レビューの「よくある指摘」を自動化したい

若手中心のチームで開発を進める中、AIによる高速なコード生成は大きな武器でしたが、一方で生成されたコードの品質チェックに相応の工数がかかっていました。可読性や保守性の判断を経験の浅いメンバーが行うのはハードルが高く、結果として人間による修正やレビューの負担が増えていたためです。

そこで、人間が繰り返し行っているレビューの基準を「Agent Skills」として定義し、AIにチェックさせる運用を導入しました。これにより、AIに単にコードを書かせるだけでなく、チームの基準に沿ったチェックまでをセットで自動化することを目指しました。

3. どう作ったか

前提

コーディングエージェントはCursorを使用しています。
「1. スキルとは」で述べた通り、オープン標準に基づいているため他のツールでも使用できますが、出力はツールによって変わる可能性があります。

ファイル構成

詳細な原則を個別に切り出した階層構造（2層構造）を採用しています。

.cursor/skills/code-review/
├── SKILL.md              # スキル本体（プロンプト）
├── README.md             # 利用者向け説明
└── references/           # 参照用フォルダ
    ├── tradeoffs.md      # 原則間の判断基準
    └── principles/       # 各原則の詳細（Good/Bad例付き）
        ├── dry.md                    # DRY原則
        ├── single-responsibility.md  # 単一責任
        ├── kiss.md                   # シンプルに保つ
        ├── yagni.md                  # 不要なものは作らない
        ├── separation-of-concerns.md # 関心の分離
        ├── early-return.md           # 早期リターン
        ├── immutability.md           # 不変性
        ├── explicit.md               # 明示的であること
        └── loose-coupling.md         # 疎結合

references/ の設計意図

この構成の肝は、詳細な原則を references/ フォルダに切り出した点にあります。これには大きく2つの理由があります。一つは、SKILL.md の肥大化を防ぎ、AIの注意力を散漫にさせないため。もう一つは、トークン消費量の節約です。すべての原則を常に読み込ませるのではなく、必要に応じて参照させる構成にすることで、コスト効率と精度の両立を図っています。

原則間の「トレードオフ」への対処

tradeoffs.md に原則衝突時の判断基準を明記しています。例えば「DRY（共通化）」と「疎結合」は、衝突することがあります。共通化を優先しすぎるとモジュール間の結合が強まり、一つの修正が広範囲に影響するリスクが生まれます。こうした「原則同士が衝突した際の優先順位」を明文化しておくことで、AIによるレビュー結果のブレを最小限に抑えています。

SKILL.md の設計

SKILL.md は、単なる「命令文」の集まりではありません。エージェントが特定のタスクを実行する際の「判断基準」と「動作フロー」を標準化するファイルです。
今回の設計では、特に以下の3点に注力しました。

1. 「可読性」の具体的な定義とターゲット設定

「読みやすいコード」という言葉は抽象的です。そこで、「プログラミング経験1〜2年のジュニア開発者が、実装を読まずに呼び出し側だけで使い方を理解できるか」という具体的な合格ラインを設定しました。 これにより、AIは「自分（AI）が読めるか」ではなく「人間（ジュニア層）が迷わないか」という一歩踏み込んだ視点でレビューを行うようになります。

2. 思考を強制する「3段階の自己検閲」

AIは時に、ルールを機械的に適用して「重箱の隅」を突つくような指摘をしてしまいます。これを防ぐため、回答を出力する前に以下のステップを踏むよう指示しています。

  • ① 設計意図の推測: 「なぜ作者はこの書き方を選んだのか？」をまず考えさせる。
  • ② 再検証: 意図を踏まえてもなお、原則を優先して指摘すべき問題か？を自問させる。
  • ③ 根拠の明示: 指摘する場合は、必ず特定の原則や規約と紐付ける。

このステップにより、「AIの独りよがりな指摘」を減らし、納得感のあるレビューを実現しました。

3. 「AI特有の癖」への先回り

AIが生成するコードには「過度に汎用化しすぎる」「エラーハンドリングが過剰/不足」といった特有の傾向があります。これらを「AIコードでよくある問題」として明文化し、チェックリストに含めることで、AI自身に自分の弱点を監視させています。

4. 使い方

プロンプト例

チャットで対象を指定するだけで、定義したスキルが自動的に適用されます。

・xxx.go をレビューして
・〜APIのコードRvをしてください
・aaa/bbb/ 配下をレビューして

出力の構造

人間が即座に修正要否を判断できるよう、AIは構造化された回答を返します。あえて「見送った指摘」をリストアップすることで、見送るべきかの最終判断を人間が行えるよう、判断の余地を残しているのがポイントです。

指摘事項
### 1. [重要] 問題の要約
- 箇所: `xxx/sss.ts:42`
- 設計意図: なぜこう書いたと推測されるか
- 問題: それでもなお問題である理由
- 根拠: どの原則・規約に基づくか
- 修正案:（具体的な改善コード）
見送った指摘
- 箇所: `xxx/sss.py:102`
- 一見すると問題: 〜違反に見える
- 見送った理由: 〜として意図的
総評（2-3文の全体評価）
・〜しており、責務分離と一貫性は取れている。
・一方で〜は、本番運用と仕様準拠の観点から修正を推奨する。

5. 運用フロー：AIと人間の共生（Human-in-the-loop）

本スキルの導入にあたり、単にAIに任せ切りにするのではなく、開発プロセスの中で「AIによるチェック」と「人間による最終判断」を組み込んだ運用を行い品質を担保しています。

1. 開発者によるセルフレビュー（PR作成前）

Pull Request（PR）を作成する前に、各担当者が自ら code-review スキルを実行します。

  • メリット: ケアレスミスや基本的な設計原則への抵触を、レビュワーに指摘される前に自分で修正できます。その分、レビュワーのレビュー工数も削減できます。
  • 基準: スキルが出力した指摘を参考に修正を行い、自信を持ってPRを出せる状態までブラッシュアップします。

2. レビュワーによるダブルチェック（PR提出後）

提出されたPRに対し、レビュワーも同様に code-review スキルを実行しつつ、人力でのレビューを並行して行います。

  • 役割分担: 構造的な問題や原則違反の「一次チェック」はAIに任せ、レビュワーは「複雑なビジネスロジックの正当性」や「将来的な保守性の担保」など、人間ならではの俯瞰的な視点での確認に注力します。

3. 「人間が最終判断を下す」という原則

最も重要なポイントは、AIはあくまで「強力な補助」であり、最終的な意思決定者は人間であるという点です。

  • 修正の要否: AIの指摘が常に正解とは限りません。あえて原則から外れる判断が必要な場合もあります。
  • 承認権限: 指摘を修正すべきか、あるいは「見送った指摘」として許容すべきかの最終判断は人間が行うことを徹底しています。

 6. 得た知見

実際の運用を通じて得られた知見です。

  • 「批判的に」や「自己評価を疑え」といった制約で精度を磨きながら、「作成 → 実行 → 改善」のサイクルを回し続けることが重要です。
  • スキルに限らずAIへの指示を明確化し、チームで共有することが、AI駆動開発の鍵になると実感しました。
  • 「毎回同じことを伝えている」なら、それはスキル化の絶好のタイミングです。

7. まとめ

SKILL.md 1ファイルから始められる「Agent Skills」は、業務の効率化、成果物の品質向上のための実用的な仕組みになります。

8. 今後の展望

AIの進化に伴い、「ベストな指示の書き方」も常に変化していきます。一度スキルを作って終わりにするのではなく、モデルのアップデートに合わせて内容を継続的にブラッシュアップしていくことが必要だと考えています。