【AIエージェント時代のチーム開発⑦】スキルファイルだけでは足りない。AIのブレを仕組みで吸収する

はじめに

AIエージェントをチーム開発で使うとき、よく出てくる対策があります。

それが、スキルファイルやプロジェクトルールの整備です。

たとえば、以下のようなものです。

• AGENTS.md
• CLAUDE.md
• Kiroのsteering file
• Copilotのcustom instructions
• プロジェクト独自のAI利用ルール

これらは有効です。
AIにプロジェクトの前提を伝えるためには、非常に重要です。

しかし、これだけでチーム開発のコードを統一しようとするのは危険だと思っています。

スキルファイルは必要です。
ただし、それは強制ではなく、誘導に近いものです。

スキルファイルは「お願い」に近い

スキルファイルには、たとえば次のようなことを書きます。

- Controllerは薄く保つ
- Serviceに業務ロジックを書く
- DTOの命名は XxxRequest / XxxResponse にする
- 共通コンポーネントは勝手に変更しない
- テストを必ず追加する

これは有効です。

AIがプロジェクトの方針を理解しやすくなります。
毎回同じ説明をしなくてもよくなります。
チーム全体でAIへの前提を揃えやすくなります。

しかし、AIが必ず守るとは限りません。

AIはコンパイラではありません。
ルールを書いたら必ず従う、というものではありません。

コンテキスト量、直近の指示、読ませたファイル、モデルの挙動、作業内容によって、ルールから外れることがあります。

そのため、スキルファイルだけに頼るのは危険です。

ルールが長すぎると効きづらい

スキルファイルを充実させようとすると、どんどん長くなりがちです。

• 命名規則
• ディレクトリ構成
• 例外処理
• ログ出力
• テスト方針
• 禁止事項
• レビュー観点
• UIルール
• APIルール

これらを全部書きたくなります。

しかし、長すぎるルールはAIにとっても扱いにくくなります。
すべてを毎回完全に守ることは期待しにくいです。

そのため、文章で書くルールと、機械的に縛るルールを分ける必要があります。

文章で書くべきもの

スキルファイルに向いているのは、判断基準や設計思想です。

たとえば、以下のようなものです。

• このプロジェクトで大事にしている設計方針
• 責務分担の考え方
• 既存コードを優先する方針
• リファクタを混ぜない方針
• 迷ったときの判断基準
• AIに作業前に確認してほしいこと

つまり、人間でも機械でも完全には判定しにくいが、方向性として重要なものです。

こういうものは、文章でAIに伝える価値があります。

機械で縛るべきもの

一方で、機械的に確認できるものは、文章ではなくツールで縛るべきです。

たとえば、以下です。

• formatter
• lint
• 型チェック
• 単体テスト
• 結合テスト
• CI
• 依存方向チェック
• 禁止importチェック
• カバレッジ確認
• ビルド確認

これらは、AIに「守ってください」とお願いするより、CIで落とした方が確実です。

AIがどれだけ「修正完了しました」と言っても、テストが落ちていればマージできない。
lintに違反していればマージできない。
禁止された依存方向があればマージできない。

この状態を作ることが重要です。

ひな形・テンプレートで形を固定する

コードの形を揃えたい場合、文章で説明するだけでは不十分です。

その場合は、ひな形やテンプレートを用意する方が効果的です。

たとえば、フロントエンドなら以下のようなものです。

• ページコンポーネントのひな形
• 検索フォームのひな形
• API呼び出しhooksのひな形
• テストファイルのひな形

バックエンドなら以下です。

• Controllerのひな形
• Serviceのひな形
• Repositoryのひな形
• Request / Response DTOのひな形
• テストコードのひな形

AIに「この方針で書いて」と伝えるより、最初から形を渡した方が揃いやすいです。

AIには、そのひな形をもとに必要部分を埋めてもらう。
これにより、AIの自由度を適切に制限できます。

AIのブレをなくすのではなく、吸収する

AIの出力を完全に固定することは難しいと思います。

また、必ずしも固定すべきでもありません。

AIは新しい解決策を出してくれることがあります。
既存の実装より良い提案をしてくれることもあります。

そのブレ自体は、AIの強みでもあります。

重要なのは、ブレを完全になくすことではありません。
ブレてもチーム開発が壊れないようにすることです。

そのためには、以下のような仕組みが必要です。

• スキルファイルで方向づける
• 代表実装を用意する
• ひな形で形を固定する
• lint / test / CIで逸脱を落とす
• PRを小さくする
• 差分レビューを行う

この組み合わせが現実的です。

まとめ

スキルファイルは有効です。
しかし、それだけでAIの出力を統一しようとするのは危険です。

スキルファイルは、AIへの強制ではなく、誘導に近いものです。

本当に揃えたいものは、文章だけではなく、機械的に確認できる仕組みに落とし込む必要があります。

• formatter
• lint
• 型チェック
• テスト
• CI
• ひな形
• テンプレート
• PRテンプレート

AIに同じコードを書かせることよりも、AIが多少ブレても同じ品質に収束する仕組みを作ることが重要です。

次回は、AI時代にベテランエンジニアの役割がどう変わるのかを考えます。

今後

以降の連載予定になります。

• 第1回：同じAIを使っているのに、なぜコードがバラバラになるのか
• 第2回：AIが書いた「動くコード」が、チーム開発では危ない理由
• 第3回：AIに任せたらコンフリクトだらけになった話
• 第4回：AIに「このファイル以外触らないで」と言うのは正しいのか
• 第5回：AI時代のPRは、なぜ重くなりやすいのか
• 第6回：AIには細かく指示しない方がいい、はチーム開発でも通用するのか
• 第7回：ステアリングファイルだけでは足りない。AIのブレを仕組みで吸収する
• 第8回：AI時代のベテランは、コードを書く人から仕組みを作る人へ