はじめに

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時代のベテランは、コードを書く人から仕組みを作る人へ