「雰囲気開発」から抜け出す：Claude Codeを仕様駆動で使いこなす方法

AIにコードを書かせると生産性が上がる——そう感じた後に、「気づいたらどこを変えても別のバグが出る」状態になった経験はないだろうか。『実践Claude Code入門』（エンジニア選書）は、この問題に「Vibe Coding（雰囲気による開発）」という名前を与え、その脱出路を示している。

1. Vibe Codingとは何か

「この機能を追加して」「スタイルをもう少し整えて」——その場その場のプロンプトでAIに要求を伝え続けると何が起きるか。

AIはその時点のコンテキストで最適な出力を生成しようとする。しかし設計方針が共有されていなければ、AIは「前回と異なる設計」をそれぞれの要求に対して選び続ける。コードは機能するが、一貫したアーキテクチャを持たないパッチワーク状態になる。

修正するたびに別の場所が壊れる状態は、技術的負債ではなく設計の不在によるものだ、と本書は位置づける。

flowchart LR
    subgraph VIBE["❌ Vibe Coding（雰囲気開発）"]
        P1["その場のプロンプト"] --> AI1["AI が場当たり的に実装"]
        AI1 --> BUG["修正したら別の場所が壊れる"]
        BUG --> P1
    end
    subgraph SPEC["✅ 仕様駆動（Spec-Driven）"]
        SP["CLAUDE.md\n+ 仕様書"] --> AI2["AI が方針を守って実装"]
        AI2 --> QA["テスト・レビュー"]
        QA --> CM["コミット"]
    end
    style VIBE fill:#fce8e8,stroke:#e53935
    style SPEC fill:#e8f8e8,stroke:#4caf50

2. Claude Codeは「補完ツール」ではなく「合意を実行するエージェント」

従来のコード補完ツール（Copilot世代）は、開発者が書くコードの続きを予測するものだった。Claude Codeはそれとは異なる動きをする。

仕様ファイルを読み込み、コードベースを探索し、実装してテストを実行し、結果を確認して修正する——という一連の作業を自律的に行う。開発者がすべてのコードを書くのではなく、AIに何を達成させるかの「仕様」を定義する役割に変わる。

本書の言葉を借りれば、エンジニアの役割は「作業員」から「ディレクター」へ移行している。

3. CLAUDE.md がコンテキストの劣化を防ぐ

会話が長くなるほど、AIは以前に決めたルールを参照しにくくなる。「コンポーネントはすべて Server Component にする」「ESLint の特定のルールは無効にしない」といった決定が、後半のプロンプトで無視されることが起きる。

本書が推奨するのがリポジトリ直下に置く CLAUDE.md だ。ここにプロジェクトの構成、技術スタック、守るべき規約を記述しておくと、AIは毎回このファイルを参照した上で応答する。

記載すべき内容の例:

• ディレクトリ構成と各ディレクトリの役割
• 使用しているフレームワークとバージョン
• 実行を禁止するコマンド（git push の禁止など）
• コミットメッセージの形式

この仕組みは「記憶の補強」ではなく、AIとの「合意の文書化」として機能する。

4. エンジニアが担うべき「インテリ活動」

AIが得意な作業とそうでない作業を分けて考えることも、本書の重要なテーマだ。

AIに委ねやすい作業:

• コードの記述・修正
• 既存コードの解析とリファクタリング
• テストコードの生成
• ドキュメントの形式整備

人間が担い続けるべき作業:

• ビジネス要件の整理とドメイン知識の言語化
• アーキテクチャ上の意思決定と判断基準の設定
• 「何を作るか」の定義と優先順位づけ

AIの能力が上がるほど、後者の比重は増す。本書が「仕様書を書く」ことを繰り返すのは、仕様の曖昧さがそのままコードの混乱になるからだ。

5. この本が効く具体的な場面

「AIに機能追加を頼むたびに別の場所が壊れ、修正に追われる」「動くコードは出てくるのに、全体の設計を誰にも説明できない」——こうした詰まりに本書は効く。第4章で描かれる、AIでテトリス風アプリを作る開発者が「スコアを足して」「色を変えて」と場当たりに要求を重ねた末、どこを直してもバグが出る状態に陥る事例は、その典型だ。

読む前は「プロンプトの技術が足りない」と考えていた読者が、読後には「合意すべき仕様を言語化していなかった」と原因を捉え直せるようになる。問題の在り処が、プロンプトの巧拙から開発プロセスの設計へと移る。

6. 向いている人・向いていない人

向いているのは、AIが生成したコードの保守や品質維持に追われ、長期的な設計の一貫性に不安を抱える現役エンジニアだ。チームにAIツールを導入したいが、メンバーに何を任せ何を期待すべきか指針を探しているテックリードやマネージャーにも、判断の軸を与える。

一方で向いていないのは、Claude Codeのコマンドや基本操作だけを手早く知りたい人だ。本書は仕様駆動という思想の解説に比重があり、操作手順を求める読者には遠回りに感じられる。SkillやSub-agentsを組み合わせた高度なワークフローは開発プロセスの見直しを迫るため、既存の進め方を当面変えたくない段階では、導入のハードルが先に立つ。

7. どこから読むか

最初から通読してもよいが、AI開発で「うまくいかない実感」がある人は第4章から入ると引き込まれやすい。ここではVibe Codingが設計を崩していくメカニズムが事例で語られ、自分のチームの状況と重ねやすい。

仕様駆動の具体像をつかみたいなら、リポジトリに置く複数のドキュメント（要求定義・技術仕様・開発ガイドライン・用語集など）の構成案が実務にそのまま写せる。すでに大規模な既存コードにAIを入れる立場なら、後半の第6〜8章が主戦場で、レガシーコードの解析とドメイン知識の抽出が扱われる。関心のある入り口から読み始め、必要な章に厚みを置くのが効率的だ。

8. よくある誤解

本書をめぐって生じやすい誤解が二つある。一つは「強力なツールを導入すれば、それだけで生産性が上がる」という期待だ。本書が繰り返すのは逆で、成果を出すには何を作りたいかの言語化と、AIとの合意形成という工夫が要る。ツールは前提を整えた人にだけ力を発揮する。

もう一つは「仕様を固めれば毎回同じコードが出力される」という思い込みだ。LLMは非決定的で、仕様駆動を徹底しても出力は完全には一定しない。仕様は出力を狭める制約であって、決定論的な型ではない。AIは揺らぐもの——そのつもりで付き合うリズムをつかむしかない。

9. 読み終えた後の最初の一歩

読んだら、次の開発でひとつだけ試すとよい。まずは担当プロジェクトのリポジトリ直下に CLAUDE.md を一枚置き、ディレクトリ構成・使用技術・守るべき規約を数行書き出すことだ。いきなり複数のドキュメントを揃える必要はなく、一番曖昧な合意から文書化する。

次の段階として、チケット着手時にAIへすぐ実装させず、修正ファイル一覧と変更の根拠を「実装計画」として先に出させ、人間が承認してから着手するフローを一度回してみる。この二つを習慣にするだけで、場当たりな指示の連鎖から、合意を起点にした開発へと重心が移り始める。

筆者の体験から

チームでAIコーディング支援ツールを試験的に使い始めた時期があった。各自が思い思いにプロンプトを打つだけで進めていたところ、若手は勢いよく動くコードを出してきた。とはいえレビューで直してもらうと前回とは違う設計で返ってきて、指摘のたびに前提から説明し直す羽目になっていた。

この本を読んで以来、CLAUDE.mdをリポジトリ直下に置き、着手前に修正ファイル一覧と根拠を実装計画として出させ、承認してから着手させる流れをチケット運用に組み込んだ。要求定義から用語集まで揃えるフルセットの構成は数人規模のチームには重すぎると感じ、CLAUDE.mdと簡単な実装計画だけに絞っている。

以前、若手がAIに「フィルタをつけて」「ソートも」「エラー表示も親切に」とその場その場で要求を重ねる様子を見たことがある。似たフィルタ処理があちこちに別の書き方で増え、最終的にどこを直しても他がズレる状態になった。それ以降、着手前に変更ファイル一覧を出させるようにしている。

---

本記事のリンクには Amazon アソシエイト等の広告が含まれる場合があります。リンク経由の購入で運営者に紹介料が支払われることがあります。