AI コーディングエージェントが普及し、今では開発現場において欠かせない存在となってきました。従来のシステムアーキテクトやエンジニアは、自問自答しながら叩き上げた設計書やコードを手に、有識者にレビューを依頼し、開発を進め、慎重にテストを重ねた上でリリースすることが主な業務の流れでした。
今は AI と壁打ちしながらクイックに成果物を作り上げ、別の AI がそれをレビューし、人は最終確認をするというところまで来ています。もはや家電と同じく必需品として定着してきていることを実感すると同時に、私自身も日々積極的に活用しています。
とはいえ、AI コーディングによって果たして本当に開発費用が下がり、リリース周期が短縮でき、ビジネスが成功しやすく・スケールしやすくなったかについては、一度じっくり考えてみる必要があるかもしれません。
チーム開発という観点での AI コーディングと悩み
Vibe Coding という言葉を筆頭に、AI コーディングエージェントの発展は目まぐるしく進化してきました。システム開発のプロジェクトを遂行するためには、要望を聞き、要件を調整・整理し、設計し、周辺システムとの調整を行い、実装・テストをして、リリース・監視・運用をするという非常に多岐にわたる領域の業務が存在しますが、生成 AI はこのすべての領域において非常に有効な自動化ツールとして機能します。例えば、以下のような業務が該当します。
- 顧客やビジネス要望に対して実現性を検討し、編集可能なテキストベースの要件一覧として整理
- 整理した要件を元に、UML 設計資料を作成
- 設計資料を元に、開発タスクを起票・遂行
- 複数のエージェントによるレビュー
- 自動 E2E テストと実行レポート
- リリース判定、リリースノート作成
- 各種運用ツール、トラブル対応、不具合調査
一方で、以下のような観点で悩まされるチームも非常に多いのではないでしょうか。
- 「とりあえず動く」ものは素早く作れても、コードの中身やロジックの詳細が把握しきれない
- なぜ動くのか、なぜそのような仕様になっているかを説明できない
- コーディングエージェントの出した回答が、微妙に現場の事情を踏まえておらずピントがずれている
- オーバースペックで過剰な設計、過剰な実装によるコード量の増加、それらに伴うトークン消費量の増加
- 認知負荷増大によるブラックボックス化
コーディングエージェントに向き合う日々で、その場しのぎのタスク消化はできても、ビジネスやチーム規模にあった技術選定であったり、チームメンバー同士でのボトムアップや人材育成に関しては悩みを抱えることもあるかと思います。
この記事では、AI コーディングエージェントによる変化を受け入れつつも、そういった悩みを軽減し時代にあった形でのおすすめ構成を伝えていきます。
シンプルかつ予測可能な内部設計方針
AI コーディングエージェントは、ドメイン駆動やクリーンアーキテクチャなどの理論を体得しているベテランメンバーにとっては非常に強力な手段ですが、それが身に付いていないメンバーにとっては以前より学習が難しい環境になったと言えます。よって、ポイントのみを小さく抑え、シンプルでこれだけはぶれさせないという分かりやすい原則を言語化し、チームに浸透させる方法が有効です。具体的には、以下の内容について触れておき、スキル化することで統一的な構成管理を図る形になります。
- 外部から入ってくるデータは、基本的に信頼せず、境界にて検証する
- ユーザーリクエスト、API 応答、ファイル読み込み、LLM 応答
- 検証したデータをドメインデータモデルに変換し、ビジネスロジックへ投入
- 副作用のない純粋関数で構成され、処理失敗時の冪等なリトライが可能
- ローカルでのサーバー起動なしでもロジックのテストができるように
- 外部システムを呼び出し、結果を記録するレイヤーをロジックから分離
- データの保存、外部APIとの通信、ログ、ファイルI/Oなどの副作用が対象
- ロジックから分離し、状態を持たず、外部世界とつながる処理に徹する
- ドメインに関連するデータはしっかりモデリングを行い、ロジックと状態管理の分離を徹底する
とはいえ、これでもまだ言葉の抽象度が高く、より分かりやすく本質的なポイントを抑えるために、以下2つの考え方を基本とすることができます。
- Functional Core（ロジック層）
- ビジネスロジック、状態遷移、各種判断、アプリケーションコア機能の実装
- Imperative Shell（副作用）
- DB接続、外部API呼び出し、ログ出し、ファイルI/Oなど
このような構造はサーバーレスを含むクラウド分散型システムでは特に重要で、冪等性を担保し運用の安定性を確保するための重要な観点で、ネットワークエラーやリトライ状況でも重複送信等の問題に対応できる余地を与えます。ソフトウェア開発の基本原則は AI コーディングであるか否かにかかわらず有効ですので、基本に立ち返って振り返るという姿勢が必要になるかもしれません。
バックエンド（WebAPI）参考構成
従来のシステムのみならず、業務用 AI エージェントの開発など、複雑な機能であればあるほど、詳細設計が必要です。本格的な実装を開始する前に、メソッド名単位までのアウトラインをスケルトンで作成するステップを徹底することと、青枠（ Functional Core ）とオレンジ枠（ Imperative Shell ）の棲み分けを明確にすることがポイントになります。オレンジ枠に特定の業務ロジックを入れ込まず、どのロジックからも再利用できる形にしなければなりません。
データの受け渡しは Model クラスを実装するなどとモデリングとスキーマ管理を行うという前提で、場合によっては DAO レイヤーや非同期での連携を挟む構成も検討できます。いずれにしても、原則として、外部世界とつながる部分（ Imperative Shell ）をラッパーとして再利用できる形にしておくことで、メンテナビリティに優れ、AI コーディングでも推論や実装の正確性・生産性が大きく向上します。
フロントエンド参考構成
ざまざまなフレームワークとディレクトリ構成が存在するフロントエンド開発でも、同じ原則が適用できます。
どのようなフレームワークであっても、コンポーネント・カスタムロジック・状態管理・データモデル・外部API接続という要素が必須です。このような要素を機能単位として共通のインターフェースで実装する構成を徹底すれば、各機能の追加・保守が予測可能な形になり、バックエンドと同じくAI コーディングでも推論や実装の正確性・生産性が大きく向上します。
AI コーディングの「コスト」に対するアプローチ
AI コーディングエージェントは、ファイルを１つ直すたびに会話全体を送り直します。キャッシュ適用や最適化を鑑みても、直すファイルの数だけ要求が発生するため、そのままコストにつながります。AI コーディングエージェントが中身を確認・手を入れる回数（ターン数）を少なくする工夫をすることで、AI コーディングをかなり予測性の高く人間における認知負荷を低くキープすることが可能です。
前項の Functional Core と Imperative Shell の棲み分けは、チーム開発における AI コーディングエージェントにとって重要です。純粋なコアロジックはテストでの品質保証・検証の可視性に優れるため、AI コーディングエージェントは画面を実装してみなくても、自分の書いたコードを自分で確かめられます。
こちらの資料は、このようなルールに基づき、AI コーディングエージェントによるファイル修正の量を 13 倍削減した実験結果を示しており、少し工夫するだけでも大きい効果を実感できます。
過剰ではなく、分かりやすい成果物を作るための工夫
また、Pull Request・Issue・タスクの説明、ソースコード内のコメント、仕様ドキュメント作成等において、情報の粒度や量に悩まされることがあります。時には投稿テンプレートを適用したにも関わらず、省略できるはずの情報も含め、過剰な情報が含まれることによって、 AI にとっては過剰なコンテキスト、人間にとっては認知負荷によるミスリードにつながるケースがあります。
これを防ぐため「簡潔に書いて」または「分かりやすく書いて」というプロンプトを入れがちですが、このような場合でも仕組み化を図ることができます。その時々に本当に必要な情報、読み手に価値のある情報というのは、それほど多くの文字数を必要としません。よって、各項目に対して「20-30文字程度で」という定量的な説明を付け加え、読み手にとって足りなければ項目を増やす形での取り組みが有効です。
開発業務はソースコードを書くだけではないため、以下のようにプロンプトを工夫しチーム開発という環境に配慮するとより生産性向上を図ることができます。
[リーダビリティのルール]
- １つの文章には１つの考えを含む。
- 文章の長さは 20~30 を超えないようにする。
- 目的後と述語を金揃えた、完結な文章を書く。
- 条件と例外を１つの文章に含めず、分離する。
この仕組みの詳細についても、こちらの資料が参考になります。気になる方はチェックしてみてください。
おわりに
このような内部設計を整えるための工夫は、AI コーディングであってもなくても、本質的な部分は変わらず有効であることが実感できます。再現可能性を高め、外部世界とつながる部分はリトライを含めコントロールが効かせる領域として扱い、システムのあらゆるプロセスを安定的に検証・リトライ・運用できるようにすることです。
AI コーディングとチーム開発でお悩みの方は、ぜひ下記にてお問い合わせください。