なぜAI開発は失敗するのか。Claude Code実践で分かったプロンプトよりデータ構造設計が人間の主業務になる理由

AIにコードを書かせると、最初は魔法のように動く。

機能追加を重ねた瞬間、システム全体が音を立てて崩壊する。

プロンプトをこねくり回しても無駄だ。

原因はAIの理解力ではなく、データ構造とプロジェクト構造の欠落にある。

人間がやるべきは、AIへの指示の最適化ではない。

AIに渡す「構造の地図」を作ることだ。

ニュースの概要

海外のAI開発コミュニティで、AI主導開発の破綻を防ぐための根本的なアプローチが次々と報告されている。

AIに「この機能を作って」と自然言語で丸投げするのは完全に間違いだ。

システムが壊れる条件は明確に特定されている。

それは、データ構造が大きく変わる変更のときだ。

AIは目の前のロジックを完璧に書く。

キャンセル料の計算APIを修正させれば、複雑な段階制の計算も正しく実装する。

しかし、その変更が予約一覧画面や売上集計バッチにどう波及するかを知る術がない。

結果として、APIは正しいのに画面表示がおかしい、という不整合を起こして破綻する。

返品処理の実装でも同じことが起きる。

既存の請求書テーブルにマイナスの値を入れるよう指示しても、AIが新しいクレジットノート用のテーブルを新設してしまうことがある。

返品処理自体は動くが、未払残高の計算や消込処理がすべて壊れる。

AIは与えられた文脈の中でしか最適解を出せない。

これを防ぐための3つのアプローチが確立されつつある。

1つ目は、人間がデータ構造だけを決定し、AIに中間仕様書を生成させる手法だ。

「キャンセル料を段階制にする」という曖昧な指示は使わない。

「reservationsテーブルにcancellation_feeカラム（整数型）を追加する」というデータ構造の変更を厳密に定義する。

その定義を基に、AIに「どのAPIがどのデータを読み書きするか」を網羅した仕様書を作らせる。

この中間層を挟むだけで、AIの出力のブレはゼロになる。

2つ目は、エージェントによる仕様の単一情報源（SSOT）の維持だ。

複数のAIエージェントが連携して動く環境では、参照する仕様が少しでもズレると致命傷になる。

古い仕様を参照してテストコードを生成し、無限ループに陥る事故が多発している。

これを防ぐため、仕様書とソースコードの差分を常に監視し、自動同期する専用の管理エージェントを配置する。

3つ目は、既存プロジェクトの構造を自動抽出するツールの活用だ。

AIは賢いが、目の前のプロジェクトについては何も知らない。

ディレクトリ構成、データベースのスキーマ、APIのルーティング、コンポーネントの依存関係。

これらを構造化されたマークダウンとして抽出し、AIにコンテキストとして与える。

専用のCLIツールを使って、コマンド一発でプロジェクトの地図を生成し、AIに読み込ませる手法が標準になりつつある。

※この記事は、Claude Codeで1人SaaS開発しているしんたろーが、海外AI最新情報を開発者目線で解説する「AI活用Tips」です。

開発者目線の解説

AIにコードを書かせる体験は、最初は本当に感動する。

しかし、その感動は長くは続かない。

プロジェクトが大きくなり、ファイル数が50を超え、コンポーネントが複雑に絡み合い始めたあたりで、AIは突然トンチンカンな修正を始める。

Next.jsのプロジェクトなのに、Express前提のルーティングを提案してくる。

すでにプロジェクト内に便利な共通関数が存在するのに、それを完全に無視する。

全く同じ処理を別のファイルに一から書き出す。

原因は非常にシンプルだ。

AIはプロジェクトの全体像を見ていない。

目の前のファイルと、プロンプトで与えられたわずかな文脈だけで判断を下している。

人間なら「このテーブルにカラムを追加したら、あの画面の表示にも影響するな」と直感的に気づく。

AIにはその直感がない。

システム全体への波及効果を予測できないため、平気でコードを壊す。

ここで効いてくるのが、データ構造の明示だ。

データ構造は、システムの骨格そのものだ。

骨格さえ決まっていれば、どこに筋肉をつけ、どう動かすかは論理的に導き出せる。

人間がやるべきは「どう動かすか」を自然言語で指示することではない。

「どんな骨格にするか」を厳密に定義することだ。

具体的には、データベースのテーブル定義、カラムの型、リレーションシップ、制約条件を明確にする。

そして、そのデータ構造を起点にして、AIに仕様書を書かせる。

「顧客名を表示する」という曖昧な表現は絶対に許さない。

「usersテーブルのnameカラムを参照する」と具体的に書かせる。

条件分岐も「ステータスが完了なら」ではなく「statusカラムが2なら」と定義する。

暗黙の了解や、文脈依存の解釈をすべて排除する。

例外ケースの見落としを防ぐため、「ステータスが2以外の場合は何もしない」といった否定形も必ず明記させる。

このアプローチは、新規機能の開発では非常に強力だ。

しかし、既存の巨大なコードベースにAIを導入する場合はどうするか。

すでに何百ものファイルがあり、複雑な依存関係が絡み合っている。

これを手作業で仕様書に落とし込むのは、苦行以外の何物でもない。

ここで登場するのが、プロジェクト構造の自動抽出ツールだ。

ソースコード全体を解析し、どのファイルが何をエクスポートしているかをリストアップする。

どのモジュールが頻繁にインポートされているかも可視化する。

データベースのスキーマも自動で読み取り、テーブル一覧と主要なカラムを抽出する。

これらをコンパクトなマークダウン形式にまとめ、AIのコンテキストファイルとして保存する。

AIに「コードを全部読んで理解しろ」と言うのではない。

「この地図を見ろ。全体像はここにある」と指示するのだ。

プロジェクトの技術スタックから、環境変数のリスト、利用可能なスクリプトまで網羅する。

しんたろー：
Claude Codeに複雑なリファクタリング頼むと、たまに盛大に既存ロジック消し飛ばすんだよね。
結局、人間がDBスキーマの変更差分をガチガチに固めてから渡すのが一番早い。
ツールに頼りきりになると、いざ壊れた時の復旧で徹夜する羽目になる。

仕様のズレがAI開発を殺す

さらに厄介なのが、仕様のズレだ。

AIエージェントを複数連携させて自律的に開発を進める試みが広がっている。

コードを書くエージェント、テストを書くエージェント、レビューするエージェント。

これらが別々の仕様を参照し始めた瞬間、プロジェクトは一瞬で崩壊する。

テストエージェントは古い仕様に基づいてテストを書き、失敗を報告する。

コードエージェントは新しい仕様に基づいてコードを修正し、テストを通そうとする。

お互いが異なる真実を信じているため、永遠に終わらないデバッグループが完成する。

これを防ぐには、仕様の単一情報源、いわゆるSSOTを絶対的なものとして管理する仕組みが必要だ。

仕様書が更新されたら、必ずソースコードやテストコードに同期する。

差分を検出し、揺れを一切許さない。

AIの自律性を高めるには、ガチガチの監視と制約が必要になる。

自由を与えすぎると、AIは勝手に新しいテーブルを作り、勝手に新しいビジネスルールをでっち上げるからだ。

1つのスキルに1つの責務を持たせる。

Wikiから仕様を取得する機能、差分を検出する機能、Wikiを更新する機能、Gitと同期する機能。

これらを細かく分割し、それぞれのエージェントに割り当てる。

真実の場所を維持するための地道な仕組みづくりが、AI開発の成否を分ける。

実務への影響

役割が完全に変わる。

「コードを書く人」から「データ構造を設計し、コンテキストを管理する人」へのシフトだ。

これまで、開発者の主業務はロジックを考え、コードに落とし込むことだった。

これからは違う。

ロジックはAIが高速かつ正確に書く。

人間は、AIが迷わずにロジックを書けるための「環境構築」に時間を費やすことになる。

具体的なアクションは明確だ。

まず、プロジェクトの全体構造をAIに理解させるためのコンテキストファイルを用意する。

Claude Codeなら「CLAUDE.md」、Cursorなら「.cursorrules」だ。

ここに、技術スタック、ディレクトリ構成、コーディング規約を記述する。

手書きは面倒なので、自動生成ツールを使う。

コマンド一発でプロジェクトの依存関係やエクスポートのカタログを出力し、ファイルに保存する。

ルーティングやDBスキーマが変わるたびに、このコマンドを実行して地図を最新に保つ。

しんたろー：
ThreadPostのディレクトリ構成、気づいたらめちゃくちゃ複雑になっててAIが迷子になりがち。
自動でコンテキストファイル生成する仕組み、気になってる。
プロンプトに毎回「このファイル見て」って書くのがダルすぎて、そろそろ何とかしたい。

次に、機能追加や仕様変更のワークフローを変える。

いきなりAIに「この機能を追加して」とプロンプトを投げるのは今日からやめる。

まず、データベースのスキーマやデータ構造の変更を人間が考える。

「この機能を実現するには、どのテーブルにどんなカラムが必要か」を定義する。

そのデータ構造の差分をAIに渡し、「この変更に伴う影響範囲と、必要なAPIの仕様をリストアップして」と指示する。

AIが生成した仕様書を人間がレビューする。

「既存のこの処理と矛盾しないか」「この画面への影響が漏れていないか」を確認する。

仕様書が完璧になったら、それを絶対的なコンテキストとして設定し、初めてコード生成を指示する。

この手間を挟むことで、手戻りは激減する。

複数のプロンプトを投げて試行錯誤する時間は無駄だ。

必要なのは、決定論的な入力だ。

揺るぎないデータ構造と、明確なプロジェクトの地図。

これさえあれば、AIは文句も言わずに完璧なコードを吐き出し続ける。

ただし、代償もある。

データ構造の設計ミスは、システム全体の致命傷に直結する。

AIは与えられたデータ構造が正しいと信じ切って、すべてのロジックを構築する。

後から「やっぱりこのカラムの型、違ってたわ」と気づいたときの修正コストは計り知れない。

人間には、システム全体を見通す高度な抽象化能力と、データモデリングのスキルがこれまで以上に求められる。

コーディングのハードルは下がった。

だが、設計のハードルは跳ね上がった。

仕様のズレを許容しない厳格な運用体制も必要になる。

ドキュメントの更新をサボれば、AIは即座に古い情報を信じて暴走を始める。

ドキュメントの維持は、もはや「後でやる作業」ではない。

コードを書く前に行う「必須の前提作業」だ。

FAQ

Q1: Vibe CodingでAIが既存のコードを壊してしまうのを防ぐには？

AIはシステム全体への波及効果を予測できないため、複雑な変更ではコードを壊しがちだ。

防ぐには、まず人間が「データ構造（DBスキーマなど）」の変更を明確に定義する。

それに基づいてAIに「どのAPIがどのデータを読み書きするか」を網羅した仕様書（中間層）を生成させる。

その仕様書をコンテキストとして与えてからコード生成を行うことで、破綻を極限まで減らすことができる。

AIへの指示はロジックではなく構造から始める。

Q2: 既存の大きなプロジェクトにClaude CodeやCursorを導入する際、最初にすべきことは？

プロジェクトの全体構造をAIに理解させるためのコンテキストファイルを作成することだ。

専用のCLIツールを使えば、ディレクトリ構成、DBスキーマ、APIルート、主要な依存関係などを自動解析して構造化されたマークダウンを出力してくれる。

手作業の負担なくAIの回答精度とプロジェクト理解度を上げることができる。

AIにソースコードを全部読ませるのではなく、コンパクトな地図を渡すのが正解だ。

Q3: 複数のAIエージェントや開発者が関わる場合、仕様のズレをどう管理すればいい？

仕様書（Wikiやマークダウン）を「単一の真実の情報源（SSOT）」として厳格に管理する仕組みが必要だ。

ソースコード（Git）と仕様書の間に差分が生じないよう、差分検出や自動同期を行う仕組みを導入する。

専用の管理エージェントやCI/CDパイプラインを活用し、AIが常に最新かつ唯一の仕様を参照できる状態を維持する。

仕様の揺れはAIの判断の揺れに直結する。

しんたろー：
AIのコンテキスト管理、まじで沼。
情報を渡しすぎるとトークン上限に引っかかって回答がポンコツになるし、少なすぎると幻覚を見始める。
プロジェクトの規模に合わせて渡す情報を動的に絞り込む仕組みが今後どうなるか、気になってる。

まとめ

AI開発の成否は、プロンプトの巧拙ではなく、データ構造の定義とコンテキストの管理で決まる。

人間は設計に集中し、AIに迷いのない地図を渡す。

👉 ThreadPostでSNS運用を自動化する