AIで「動いた」を人に説明できますか？〜社内共有会で見えた理解負債の正体〜

こんにちは。ACS事業部の越川です。

先日、社内で「AIによるIaC生成」の現状共有会がありました。あるメンバーが、AIエージェントを使って要件からTerraformコードを自動生成する仕組みを作り、その進捗を共有する会です。

10名以上が参加し、活発な議論が生まれました。しかし、開始直後から参加者の間に混乱が広がりました。

「どのファイルを人が作って、どれをAIが作ったのか知りたい」 「ユーザーとしてのスタート地点がどこなのか知りたい」

こうした声が次々と上がったのです。

AIで「動いた」は、説明できたことにならない

発表者はVS Codeで生成されたファイルを見せながら説明していましたが、参加者には全体像が伝わりませんでした。結果として、別のメンバーがその場でフロー図を即興で作成し、発表者に「こういうことですか？」と確認しながら整理する展開になりました。

共有会のつもりが、即席のモブレビュー会になったのです。

なぜこうなったのか。発表者はAIと1対1で試行錯誤して「動くもの」を作っていました。自分とAIの間では成立していたプロセスが、第三者に説明しようとした瞬間に破綻したのです。

これは発表者個人の問題ではありません。AI駆動開発で「動いた」ことと「説明できる」ことの間には、想像以上のギャップがあるという構造的な問題です。

浮き彫りになった3つの課題

この共有会を通じて、3つの課題が見えてきました。

1. 人とAIの役割分担が言語化されていない

「どのファイルを人が作り、どれをAIが作ったのか」— これが最初に出た質問でした。AI駆動開発では、人間とAIが交互に作業を進めます。しかし、その境界が明示されていないと、第三者は成果物を見ても何が起きたのか理解できません。

2. コンテキストの限界にぶつかる

今回の仕組みでは、AIエージェントがTerraformモジュールの仕様書をダウンロードして読み込みますが、モジュールの数や1つあたりの仕様書のサイズが大きくなると、コンテキストウィンドウが溢れてしまうという問題が報告されました。

AIには一度に処理できる情報量の上限があります。この制約を意識せずに「全部渡す」アプローチを取ると、破綻します。

3. 全体のフローが設計されていない

参加者から「オーケストレーターが必要」「全体のフローが先に確立されていないと難しい」という声が上がりました。個々のエージェント（設計エージェント、コーディングエージェント）は動いていても、それらをどう連携させるかの設計がないと、全体として機能しません。

参加者の知見が課題を解いていく

興味深かったのは、共有会の後半で参加者の知見が次々と集まり、解決の方向性が見えてきたことです。

タスクをアトミック（最小）な単位に分割する — 全部を一度にAIに渡すのではなく、モジュール単位で分割して並列に処理させる
必要な時にロードする — 仕様書を全てコンテキストに入れるのではなく、必要になった時点で参照する仕組みにする
まずREADME.mdをAIに作らせる — プロジェクトの全体像を言語化することで、自分が理解していない部分が可視化される
システム要件から逆算する — モジュール（部品）から積み上げるのではなく、作りたいものを先に定義して必要なモジュールを絞る

発表者1人では解けなかった課題が、10人以上の知見で整理されていく。これはAIとの1対1では得られない価値です。

「説明できない」は理解負債のサイン

以前の記事で「理解負債」という概念を紹介しました。AIが生成したコードの仕組みを開発者が理解できない状態のことです。

techblog.ap-com.co.jp

今回の共有会で起きたことは、まさに理解負債が表面化した瞬間でした。AIと協働して「動くもの」を作れた。しかし、なぜ動くのか、どこが人の判断でどこがAIの判断なのかを説明できなかった。

これは、以前の記事で書いた「説明できないものは載せない」というルールの裏返しです。説明できないままチームに共有すると、フィードバックも改善もできません。

AIで動いたら、まず説明してみよう

今回の経験から、AI駆動開発で何かが「動いた」とき、次にやるべきことが見えてきました。

README.mdをAIに書かせる。 プロジェクトの目的、構成、人とAIの役割分担を言語化する。書かせた内容を自分で説明できるか確認する
チームに説明してみる。 説明できない部分が理解負債。そこがわかるだけでも価値がある
フロー図を描く。 人がやること、AIがやること、その間のインプット/アウトプットを可視化する

発表者はこの共有会を「できるだけ早く開きたかった」と言っていました。AIとの試行錯誤を重ねる中で、1人では解決できない壁にぶつかっていたのだと思います。AIとの対話でコンテキストが溢れるように、人間側の集中力や判断力にも限界があります。だからこそ、完璧に準備してからではなく、鮮度の高いうちにチームに共有する判断をしたのです。

そして実際、チームの知見で課題は整理されていきました。「動いたけど説明できない」という状態に気づけたこと自体が、この共有会の最大の成果です。AIとの1対1で完結させず、人の目に晒すことで初めて見える課題があるのです。