なぜClaude Codeで開発するほど設計の言語化が必要なのか。AIに丸投げせず自走させる秘訣

「いい感じに作って」

この一言で開発が終わる。魔法のような時代が来た。

現実は違う。

3回目の修正でバグが出る。

5回目でコードがスパゲッティになる。

10回目には、最初から自分で書いたほうが早い。

これがAIエージェント開発の残酷な真実だ。

AIを自走させるには、コードを書く力よりも「言語化する力」が求められる。

Claude Codeで1人開発を続ける中で見えてきた、AIを迷わせないための設計術を共有する。

バイブコーディングの理想と、ドキュメント・ファーストの現実

2025年の初頭、ある概念が提唱された。

バイブコーディングだ。

AIに細かい実装を任せ、自分は「何を作りたいか」というビジョンに集中するスタイル。

コードを一行一行書くのではなく、AIとの対話で開発を進める。

成功している層は、裏で「狂気的なまでの言語化」を行っている。

AIに丸投げするのではない。

AIに厳格な制約を叩き込んでいる。

多くの開発者が陥る罠がある。

「AIは賢いから、文脈を読んでくれるはずだ」という思い込みだ。

AIは文脈を「読む」のではなく、欠落した情報を「勝手に補完」する。

この補完が、プロジェクトを破壊する。

指示されていない機能を良かれと思って追加し、指定していないライブラリを勝手に導入する。

管理しきれない巨大なコードの塊ができあがる。

これを防ぐ唯一の方法が、ドキュメント・ファーストの開発だ。

コードを書く前に、ドキュメントを書く。

AIに「いい感じ」を任せるのをやめ、ドキュメントで「こういう感じ」を定義する。

ソースコードを書く代わりに、プロジェクトの「憲法」を作る作業だ。

これができていないバイブコーディングは、ただの「行き当たりばったりの丸投げ」だ。

しんたろー：
最初は「AI様、お願いします！」と丸投げしていた。
Claude Codeが勝手に知らないUIライブラリを入れ始めた時は冷や汗が出た。
そいつを剥がすのに丸一日溶かした。
AIは便利だが、手綱を握らないと平気で暴走する暴れ馬だ。

AIエージェントを自走させる「6つの定義書」と「3つの記憶」

Claude Codeのような自走型エージェントを使いこなすには、構造化された情報が必要だ。

具体的には、6つの定義書と3つの記憶ファイルをプロジェクト内に配置する。

これがあるだけで、AIの出力のブレは減る。

まず、定義書の核となるのがPRD.md（要件定義書）だ。

ここで最も重要なのは「作らないもの」の定義だ。

スコープ外を明記することで、AIの「良かれと思って」という暴走を物理的に封じる。

次にTECH_STACK.md（技術スタック定義）。

使用する言語やフレームワークのバージョンだけでなく、「これ以外のライブラリは絶対に追加するな」という禁止事項を太字で書く。

さらに、UI_GUIDELINE.md（デザイン規約）、BACKEND_STRUCTURE.md（バックエンド構造）、DB_SCHEMA.md（データベース設計）、そしてIMPLEMENTATION_PLAN.md（実装計画）を揃える。

これらはすべて、AIに対する「命令の解像度」を上げるためのツールだ。

AIは指示の質が、そのまま出力の質に直結する。

思考の解像度が低いまま指示を出せば、解像度の低いコードが返ってくる。

そして、セッションをまたいでAIの記憶を維持するためのファイルが重要になる。

CLAUDE.mdは、プロジェクト全体のハブとなる「憲法」だ。

プロジェクトの概要、各定義書へのリンク、そして過去にハマった「罠」を記載する。

AIは新しいセッションを開始するたびに、このファイルを最初に読み込む。

次にprogress.md（進捗管理）。

今どこまで終わっていて、次に何をすべきか。

AIにこのファイルを更新させることで、開発のコンテキストが途切れるのを防ぐ。

最後にlessons.md（教訓記録）。

エラーから学んだこと、特定のライブラリ特有の挙動などを記録する。

同じミスを二度繰り返さないための、自己改善ループを構築する。

しんたろー：
CLAUDE.mdに「罠」セクションを作るのはおすすめだ。
「このAPIはたまにタイムアウトするからリトライ処理を入れろ」と書いておくだけで、Claude Codeが先回りして対処してくれる。
自分の失敗をAIに共有して、二度と同じ轍を踏ませない。
これこそが、真のペアプログラミングだ。

コードを書く人から、ドキュメントで制約を設計するアーキテクトへ

AIエージェントの自走能力が向上するにつれ、エンジニアの役割は変化している。

これまでは「どう書くか」という実装力が価値の源泉だった。

これからは「何を、どのような制約下で作らせるか」という設計力が問われる。

開発者は「コーダー」から「アーキテクト」へとシフトする。

Claude Codeを使っていると、ターミナル上でエージェントがReActループを回しているのが見える。

ファイルを読み、思考し、コマンドを実行し、結果を確認する。

このループを、AIは人間よりも速く、かつ長時間、安定して回し続けることができる。

人間がこの「作業量」で勝負を挑むのは無謀だ。

集中すべきは、そのループが正しい方向に回っているかを監視し、適切な「ガードレール」を設置することだ。

具体的には、ハイブリッドな設計能力が求められる。

すべての作業をAIに任せるのは、コスト的にもリスク的にも賢明ではない。

例えば、本番環境へのデプロイやデータベースのマイグレーションなど、リカバリ不能な操作は人間が介入する。

一方で、ユニットテストの作成やボイラープレートの実装、ドキュメントの更新などは、AIに100%任せる。

この「どこまでを任せ、どこで介入するか」の線引きが、プロジェクトの成否を分ける。

また、コスト管理もエンジニアの仕事になる。

AIエージェントの1セッションは、入力と出力の合計で数十万から150万トークンに達する。

1回のタスクで数百円から数千円のコストがかかる計算だ。

何でもかんでもAIに丸投げするのは、札束を燃やしてコードを書いているのと同じだ。

単純な文字列置換やファイルの移動なら、自分でスクリプトを書いたほうが早いし安い。

推論が必要な高度なタスクだけをAIに振る、というリソース配分のセンスが問われている。

しんたろー：
最近は、コードを一行も書かずにドキュメントだけを1時間書くこともある。
完璧なドキュメントがあれば、Claude Codeは30分で数日分の実装を終わらせてくれる。
思考の汗をドキュメントで流し、実装の汗はAIに流してもらう。
これが現代のスマートな開発スタイルだ。

AI時代の生存戦略：エンジニアの市場価値はどこにあるのか

AIがコードを書けるようになった世界で、エンジニアの市場価値は「要件の適合性を判断する力」と「全体構造を維持する力」にある。

AIはテストを通す天才だ。

しかし、そのテストが本来のビジネス要件を満たしているかどうかまでは判断できない。

エージェントは、テストを通すために実装を書き換えるのと同じくらい簡単に、テストケース側を緩めることがある。

「動いているから正解」という罠に陥らないための、人間の厳しい目が必要だ。

また、プロジェクトが大規模になるほど、一貫性の維持が難しくなる。

AIは局所的な最適化には強いが、数万行に及ぶコード全体の整合性を保つのはまだ苦手だ。

ここで、前述したドキュメント・ファーストの設計が効いてくる。

ドキュメントを「プロジェクトの北極星」として機能させ、AIが常にそこを参照するように仕向ける。

この構造を作り、維持できるエンジニアこそが、AI時代に生き残るプロフェッショナルだ。

さらに、ローカルエージェントの優位性についても理解しておく必要がある。

Claude Codeのようなローカルで動くツールは、機密コードや社内環境変数を安全に扱える。

クラウドにすべてを投げるのではなく、自分の手元でエージェントを飼い慣らす。

この「セキュアな自走環境」を構築できるスキルも、企業にとっては大きな魅力になる。

これからの開発は、ますます「バイブ（直感）」と「ロジック（言語化）」の融合になる。

直感でアイデアを出し、それを厳密なドキュメントに落とし込み、AIに高速で形にさせる。

このサイクルを回せるようになれば、1人でSaaSを開発することも、大規模なプロジェクトを少人数で回すことも可能になる。

AIは僕たちの仕事を奪う敵ではない。

僕たちの思考を拡張し、具現化を加速させる、最強のブースターだ。

Claude Code開発におけるFAQ

Q1: Claude Codeに「いい感じに作って」と頼むと、なぜ破綻するのですか？

AIは文脈を補完するために、独自の解釈で機能を追加したり、不要なライブラリを導入したりするためです。これを防ぐには、PRD.md（要件定義書）で「作らないもの」を明記し、TECH_STACK.mdで技術スタックを固定する必要があります。AIは指示されたことには忠実ですが、指示されていないことを勝手に最適化しようとする性質があるため、制約条件の明文化が不可欠です。

Q2: 完全自動化を目指すべきですか？

完全自動化は「ベストエフォートな目標」です。特に本番環境へのデプロイやDBマイグレーションなど、リカバリ不能な操作をAIに任せるのはリスクが高すぎます。実務では「実装層はエージェントに任せて介入ゼロを目指し、要件定義とマージ前のレビューは人間が確実に行う」という階層化された設計が、生産性と安全性のバランスを保つ最適解となります。

Q3: コストを抑えるにはどうすればいいですか？

ルーティン作業はNode.jsスクリプトなどで自動化し、LLMは自然言語理解や高度な推論が必要な場面に限定して使うのがコツです。何でもエージェントに頼むと、1セッションで数千円のコストがかかることもあります。また、CLAUDE.mdやprogress.mdでコンテキストを整理しておくことで、AIが迷って無駄な試行錯誤（トークン消費）をするのを防ぐことができます。

まとめ：AIを「自走」させるのは、あなたの「言葉」だ

AIエージェントによる開発は、単なるコード生成の自動化ではない。

それは、ドキュメントによる制約定義と、人間による意思決定の最適化へとフェーズが移行している。

実装を丸投げするのではなく、構造化されたドキュメントを介して「コンテキストを注入」する。

これこそが、自走型開発を成功させるための必須条件だ。

僕も毎日Claude Codeと向き合っているが、結局のところ、AIが書くコードの質は、僕が書くドキュメントの質を超えない。

AIを魔法の杖にするか、ただの金食い虫にするかは、あなたの「言語化能力」にかかっている。

さあ、エディタを開いて、コードを書く前にまずPRD.mdから書き始めてみよう。

それが、最強の開発チームへの第一歩だ。