はじめに
関連記事（AI活用シリーズ）
※以下はいずれも筆者個人のQiita記事です。所属組織の公式見解・発信ではありません。
AI支援ツールを使ったマルチチーム開発で、PRレビューの度に同じ指摘を繰り返していることに気づいた。
2拠点体制でLaravel→React移行を進めている現場の話。全員が同じAI統合開発環境（AWSが公開している Kiro）を使っているのに、なぜかチーム間でコード品質にバラつきが出る。ルール定義ファイル（steeringやinstructions）に規約を書いてあるのに、だ。
この記事では、ルールが「存在するけど効いていない」問題の原因特定と、fileMatch設定と具体的な閾値で即日解決した実践を共有する。
環境
- React 18 + TypeScript
- バックエンド: Express（TypeScript）
- AI支援: Kiro（AWSが公開しているAI統合開発環境。steering / skill / instructions でAIに読ませるルールを定義できる）
- チーム構成: 2拠点体制
起きていた問題
あるPRをレビューしたとき、以下が全部まとめて出てきた。
❌ 共通のデータ取得フックを使うべきところで状態管理ストアを新規追加
❌ レガシーAPIラッパー（旧APIを集約した巨大ファイル）にメソッド追加（機能別分離せず）
❌ IT仕様書が独自パスに配置
❌ Repository が 683行（Read/Write 未分割）
❌ workflow yml にブランチの一時変更が混入
全部ルール定義ファイルに書いてある規約。書いてあるのに守られてない。正直、3回目くらいでこれは仕組みの問題だと確信した。
原因: inclusion: manual の罠
# こうなっていた
---
inclusion: manual
---
# React データ取得・状態管理の方針
...
manual は開発者がチャットで明示的に #ルール名 と指定しないとAIのコンテキストに入らない。
AIは「今のコンテキストに入っている情報」だけで判断する。ルールが入っていなければ、直近のコード（＝古いパターン）を参照して生成する。結果として一方のチームのAIは、もう一方が整備したルールの存在を知らないまま古いパターンを踏襲し続けていた。
レビューで何度指摘しても、次のPRでまた同じことが起きる理由がこれだった。
対策: 4つの変更で即日解消
対策1: ルールを fileMatch に変更
---
inclusion: fileMatch
fileMatchPattern: 'react/src/**/*.{ts,tsx}'
---
react/src/ 配下のファイルを触った瞬間にルールが自動で読み込まれる。忘れようがない。これが最も効果が大きかった。
対策2: 曖昧な文言を具体的な閾値に
「大きくなったら分割を検討」→ AIには通じない。こう書き直した:
## Repository 粒度ガイドライン
| 行数 | 対応 |
|------|------|
| 500行以下 | 分割不要 |
| 500〜800行 | PR本文にTODO記載。後続で分割 |
| 800行超 | 同一PR内で分割必須 |
数値があるとAIは判断に迷わない。人間も同様。
対策3: 禁止事項の明文化
## 禁止事項
- レガシーAPIラッパーへの新規メソッド追加 → 機能別のAPIクラスを新規作成する
- `.github/workflows/` 配下の変更 → React移行PRでは原則不可
- 状態管理ストアの新規追加 → 共通のデータ取得フックを使用する
「推奨しません」ではなく「禁止」と書く。AIは曖昧さに弱い。明確にNGと書くと、生成段階で避けてくれる。
対策4: 模範PRの明示
## 模範PR（構造の参考にすること）
- PR-A: 画面移植 — セルフレビュー収束・ADR・人間対応事項リスト
- PR-B: 参照系API画面 — API設計・discriminated union
AIは「どこを参照するか」を指定してあげると、そちらのパターンを踏襲する。指定しないと直近のコミット（古いパターン）が参照先になる。
結果
対策投入の翌日に来たPR:
✅ 共通のデータ取得フックを使用
✅ APIクラスは機能別ファイルとして独立
✅ IT仕様書は所定のディレクトリに配置
✅ workflow yml の変更なし
同じ開発者が出したPRなのに、品質が揃った。ルールが自動で読み込まれるようになっただけで、AIの生成結果が変わる。
技術的なポイントまとめ
inclusion（読み込み条件）の使い分け
| inclusion | 用途 | 例 |
|---|---|---|
manual |
開発者が意図的に呼ぶもの（スキルのトリガー等） | デプロイ手順 |
fileMatch |
特定パスのファイルを触ったら常に効かせたいルール | コーディング規約、構成ルール |
always |
全セッションで常に効かせたいルール | 用語集、禁止事項 |
React移行のコーディングルールのように「そのファイルを触るなら絶対知っておくべき」ものは fileMatch 一択。
ルールの書き方で効果が変わる
# ❌ 効かない書き方
Repository が大きくなりすぎないよう注意してください。
# ✅ 効く書き方
Repository は500行以下を維持する。800行を超えた場合は同一PR内でRead/Writeに分割すること。
AIへの指示も人間への指示も同じで、具体性がないと行動に繋がらない。
学んだこと
- ルールの「存在」と「適用」は別物。
manualとfileMatchの差は、ドキュメントを書くかSlackやWikiで周知するかの差くらいインパクトがある - AIが生成するコードの品質は、コンテキストに何が入っているかで9割決まる
- レビューで3回同じことを言ったら、それはルールの設計不備。機械に守らせるべき
おわりに
「AIに任せる」時代のコード品質管理は、コードそのものよりも「AIが参照するルール」の設計が本質だと実感した。
次はこのルール設計自体をCIで自動チェックする仕組み（新しいファイルが追加されたときに既存ルールとの整合性を検証する等）を作りたい。
本ブログに掲載している内容は、私個人の見解であり、所属する組織の立場や戦略、意見を代表するものではありません。