AI コーディングエージェントのチーム展開に向けた段階的な環境整備の実践例

こんにちは、AWS ソリューションアーキテクトの秦です
現在、AI コーディングエージェントの活用が広がり、コーディングの生産性は大きく向上しています。
筆者がとある開発部門で、AI コーディングエージェントの導入を支援するプロジェクトに参加したところ、個人利用の段階では成果が出ていたものの、複数チームへの展開を始めたところでいくつかの課題に直面しました。
本記事では、そのチーム展開の際に直面した課題に対して私たちが実際に行ったアプローチと、そこから得られた学びを共有します。

なお、本記事は、特定のプロジェクトでの経験談であり、すべての組織にそのまま当てはまるとは考えていませんが、これから AI 駆動開発をチームに広げようとしている開発リーダーやアーキテクトの方の参考になれば幸いです。

チーム展開で直面した課題

まず、要点を整理すると、AI コーディングエージェントのチーム展開を始めるうえで見えてきた課題は次の 4 つに集約されました。

• 出力品質が個人のプロンプトの書き方に依存し、ばらつく
• 組織で決めた開発プロセス（分析 → 設計 → 実装 → テストなど）のステップに従わないケースがある
• うまく使えているメンバーの工夫が他のメンバーに共有されない
• レビューやセキュリティ検証が仕組みとして組み込まれていない

原因を追うと、いずれもエージェントが「チームのやり方」を知らないまま動いていることに行き着きました。
そのため、ルール・プロセス・品質基準をファイルとして整備してエージェントに読ませ、検証で得た学びをルールに還元する取り組みを段階的に進めました。
実装には Kiro を使いましたが、同種の機能があれば他のツールでも構成は再現できると考えています。

なお、ルールを書けばエージェントが必ず従うわけではなく、コンテキストが長いとルールが埋もれる、指示が矛盾すると挙動が不安定になる、といった課題が残ります。
ルール化できる範囲を仕組みで担保する、というのが今回のポイントです。

検討のステップ

検討時には、重要な前提があります。一度に完成させることはできないということです。全ルール・全プロセス・全ナレッジを最初から適用しようとすると、書く側も使う側も破綻します。
そこで、整備の進め方を以下のように考えてみました。
あくまで一例として捉えていただければと思います。また、各ステップを整備すると次の問題が見えてくるという構造になっています。

ステップ 1: ルールの明文化

展開初期は、各メンバーがプロンプトで毎回規約を指示しており、書き忘れた項目はエージェントが自己流で埋めるということも多いかと思います。
そこで、毎回伝えていたルールを Steering のファイルに固定し、全セッションに読み込ませ、既存のコーディング規約から違反頻度の高い項目を抜粋し、技術スタック、禁止事項、完了の定義を加えた形を作ります。

完了の定義は重要で、基準を渡さないと、エージェントはコンパイルが通った時点で「完了しました」と報告し、テストを省略することがあります。
「ビルド成功、単体テスト全パス、Lint エラーゼロ」のように判定可能な形で書くようにすると指示が明確になります。
一方、ビルドコマンドの手順だけを並べただけでは、エージェントが基準を理解せずコマンドを実行するだけになる場合があるため、「何を実行するか」と「何をもって完了とするか」は両方定義しておくと安心です。

ステップ 2: 知識の分割と役割の分離

ルールが育つとコンテキストの肥大化が問題になります。ルールを足したのに守られないルールが増えるというケースがあるため、常時読ませるファイルは禁止・必須ルールだけに絞り、詳細なパターン解説やコード例は必要なときだけ読み込まれる Skills に移します。

もう一つは実装とレビューの分離です。同じエージェントに両方させると「問題なし」で返ってくることが多く、レビュー専用のサブエージェントを分けました。
ただし、ルールに書いてあっても AI レビューが見逃すことがあり、確実に検出したい項目はレビュー側のチェックリストにも重ねて載せています。
委譲はメインエージェントからの一方向のみとし、差し戻しは例えば同一タスク 2 回まで、超えたら人間に渡す運用にします。

ステップ 3: ワークフローの構造化と棚卸し

タスク単位は安定しても、設計を飛ばして実装が始まる、テスト省略のまま完了になるというケースがあり、メインエージェントを「自分では実装しないオーケストレーター」とし、指示書にフェーズ順序と完了条件を明記して、満たさなければ次に進めない構成にしました。
セッションをまたぐ引き継ぎには、合否フラグ付きのフィーチャーリストと進捗ログをファイルで残し、開始時に読ませます。

棚卸しに使った 4 象限

この時点で、整備が場当たり的にならないように全体像の棚卸しするために、タイミング軸（事前/事後）× 読者軸（人間/AI）の 4 象限で成果物を分類してみました。

分類してみると、ステップ 1〜2 で作ったものは C 象限（AI が事前に読むルール）に集中しがちで、A・B 象限は従来の開発プロセスの資産がそのまま残っている一方、D 象限（AI の出力を事後に機械検証する仕組み）は追加整備が必要な状況でした。
D はルールが守られたかを確認する整備になっていて、これが次の品質ゲートに取り組むきっかけになります。

また、A・B 象限の成果物は残り続けますが、人間がどの粒度で読むかは変わってきます。実際、テスト結果は AI が要約したものを人間が確認する形に移りつつあります。
変わらなかったのは、承認の責任がプロセスのどこにあるかであるため、この観点を整備の判断軸にしています。

ステップ 4: 品質ゲートの組み込み

ステップ 1 が基準の「宣言」だとすると、ステップ 4 はその「守り」です。この二つが対になって初めてエージェントの環境整備が機能します。そのために品質ゲートを検討します。品質ゲートは次の 2 点がポイントです。

• 合否判定可能な完了条件: 「ビルド成功」「静的解析の指摘ゼロ」など、機械的に Yes/No が決まる条件を事前に合意する
• 不合格なら進めない構造: 条件を満たさない限り次フェーズに進めない関門を仕組みとして置く

実装は、ビルド・カバレッジ・静的解析・AI レビューを一括実行するゲート用サブエージェントを定義し、タスク完了時にオーケストレーターから呼び出す形にして、不合格ならタスクは未完了に戻ります。
既存の CI で検証できる項目は同じコマンドをゲートからローカルで実行して再利用し、ブラウザ操作での E2E テストや AWS リソースの検証など、CI に乗っていない検証だけを Model Context Protocol (MCP) による外部ツール連携で追加しました。ゲートを新規に作るというより、既存の検証資産を関門として組み込み直す作業が中心になるかと思います。

また、ゲートに入れる項目は機械判定できるものに限定しました。要件の妥当性のような項目まで入れると、判定が安定せず外す可能性があります。
UX の良し悪しなど熟練者の判断に依存する項目は人間レビューに残し、ゲートは「機械で落とせる不合格を先に落とし、人間のレビューを設計判断に集中させる前処理」と位置づけました。
4 象限でいえば、D 象限を埋めた上で、B 象限の人間の承認は残す、という分担です。

また、整備の効果測定には「評価セット」を用意しました。チームで頻出するタスクの指示文（既存画面への項目追加、API エンドポイントの新設など）を数個固定したテスト問題集のようなもので、同じ指示を複数回実行し、品質ゲートをすべて通過した割合を成功率として記録します。
AI の出力は同じ指示でも毎回変わるため、1 回の試行では整備の効果を判断できないからです。ルール変更の前後でこの成功率を比較することで、「なんとなく良くなった」ではなく数値で改善を確認できるようにしました。

ステップ 5: 学習ループと組織展開

また、環境整備する上で得た学びとして、レビューで繰り返し指摘されるパターンを記録し、汎用的なものは Steering や Skills に「昇格」させるという営みも重要です。
この記録と昇格のトリガーには Hooks を使い、セッション終了時に、開発者が入力した修正指示を自動的に学習候補として記録し、後から Steering / Skills への昇格を判断する運用です。

同時に、モデルの進化に応じて効きの薄くなったルールを削る「棚卸し」も行います。ルールは積み上げるだけでなく、不要になった補助輪を外す運用も含みます。できれば数か月に一度の再評価が目安です。

まとめ

本記事では、AI コーディングエージェントをチームに展開する際に直面した課題と、それに対して私たちが行った環境整備をご紹介しました。

チーム展開で見えてきた課題は、出力品質のばらつき、開発プロセスの不徹底、工夫の属人化、検証の仕組みの不在の 4 つでした。
いずれもエージェントが「チームのやり方」を知らないまま動いていることが原因であり、ルール・プロセス・品質基準をファイルとして整備してエージェントに読ませ、得られた学びをルールに還元する、という取り組みを段階的に進めました。

整備は一度に完成させるのではなく、ルールの明文化から始めて、知識の分割と役割の分離、ワークフローの構造化、品質ゲートの組み込み、学習ループの構築へと、各ステップで見えてきた課題に応じて進めています。本文で挙げた各ステップの症状は、チームの整備がどこまで進んでいるかを見極める手がかりにもなるかと思います。

特定のプロジェクトでの経験談ではありますが、これから AI 駆動開発をチームに広げようとしている方の参考になれば幸いです。

著者のプロフィール

秦 将之 ソリューションアーキテクトとして、お客様の AWS 導入と活用のご支援を担当しています。開発プロセスの改善や自動化が好きで、最近は Kiro Crew を使った開発ワークフローを試しています。

堀 貴裕 アマゾンウェブサービスジャパン合同会社のソリューションアーキテクトです。普段は製造業やシステムインテグレーターのお客様のご支援を中心に活動しています。最近は Kiro を使ったお客様の業務変革支援に邁進中です。

参考

• Kiro Documentation: https://kiro.dev/docs/