Vibe Codingの「定義書を書け」は正しかった。でも今はClaude Codeが肩代わりしてくれる

半年前、自分は定義書を手で書いていた

Claude Codeを本格的に使い始めた頃、「AIにコードを書かせる前にドキュメントを用意しろ」という記事に出会いました。@kloss_xyz氏の "why you suck at vibe coding" です。

要約すると、AIコーディングが失敗するのはAIのせいではなく指示に構造がないからで、6つの定義書（PRD、画面遷移、技術スタック、フロントエンド指針、バックエンド構造、実装計画）と3つの記憶ファイル（CLAUDE.md、progress.txt、lessons.md）を先に用意せよ、という内容でした。

これは正しかったです。実際にやってみると、AIの出力品質が明らかに変わりました。

ただ、今は状況が変わっています。

当時やっていたこと

自分はClaude Codeの運用知見を60以上のTipsとしてまとめているのですが、初期は以下のような運用をしていました。

CLAUDE.mdの階層設計

~/.claude/CLAUDE.md          ← ユーザーレベル（全プロジェクト共通）
~/project/CLAUDE.md           ← プロジェクトレベル
~/project/src/CLAUDE.md       ← ディレクトリレベル

ユーザーレベルには「TypeScriptのanyは禁止」「コミット前にテスト必須」みたいなグローバルルール。プロジェクトレベルには技術スタックやDB構成。ディレクトリレベルにはそのモジュール固有の注意点。

これは元記事の「CLAUDE.md」「TECH_STACK.md」「BACKEND_STRUCTURE.md」を、CLAUDE.mdの階層構造に統合したものです。ファイルを分けるより、Claude Codeが自動で読み込む仕組みに乗せた方が確実でした。

progress.txtの手動管理

セッションが切れるたびに「どこまで終わったか」を手で書いていました。

# 進捗
- [x] APIエンドポイント実装
- [x] フロントエンド初期化
- [ ] タスク一覧コンポーネント ← 今ここ

毎回これを書いて、次のセッション冒頭に「これ読んで続きやって」と渡す。正直、面倒でした。

lessons.mdへのエラー記録

# 教訓
- Tailwind v4はPostCSS設定がv3と変わった（ドキュメントに騙されない）
- FastAPIのOptionalフィールドはNoneが返る（レスポンスモデル注意）

これも手動。でもないと同じミスを繰り返すので、仕方なく書いていました。

今は何が変わったのか

Claude Codeのアップデートで、この手動運用の大部分が不要になりました。

/plan モードが定義書を代替する

> /plan タスク管理アプリを作りたい

/planを使うと、Claude Codeが自分から要件を聞いてきます。

• 「認証は必要ですか？」
• 「DBは何を使いますか？」
• 「モバイル対応は必要ですか？」

元記事で「AIに自分のアイデアを徹底的に尋問させろ」と書かれていたことを、/planが自動でやってくれます。質問に答えていくだけで、実装計画が出来上がる。PRD.mdやAPP_FLOW.mdを手で書く必要がなくなりました。

セッションresumeがprogress.txtを代替する

以前はセッションが切れるたびに進捗を手書きしていましたが、今はresumeで前回のコンテキストを復元できます。

claude --resume

「どこまで終わったか」をAIが覚えている状態から再開できるので、progress.txtの手動管理はほぼ不要になりました。

CLAUDE.mdは今でも必須

ただし、CLAUDE.mdだけは今でも手動で書く価値があります。理由は、/planやresumeが扱うのは「今のセッションの文脈」であって、「プロジェクト全体のルール」ではないからです。

# CLAUDE.md
- TypeScriptのanyは禁止。unknown + type guardを使う
- コンポーネントは1ファイル100行以内
- APIレスポンスは必ずZodでバリデーション
- console.logはデバッグ後に必ず削除

これはプロジェクトに参加する人間の新メンバーに渡すコーディング規約と同じです。AIも「新メンバー」だと思えば、ルールブックを用意するのは当然ですよね。

結局、何が残ったのか

以前	今	理由
PRD.md〜IMPLEMENTATION_PLAN.md（6つ）	/planモード	対話で自動生成される
progress.txt	--resume	セッション復元で不要に
lessons.md	CLAUDE.mdに統合	プロジェクトルールと一緒に管理する方が楽
CLAUDE.md	CLAUDE.md（手動）	これだけは機能で代替できない

9ファイル → 実質1ファイル（CLAUDE.md）＋ツール機能で完結するようになりました。

「構造化してから書かせる」は変わらない

ツールが進化しても、根底の思想は同じです。

• ❌ 「〇〇作って」と雰囲気で投げる
• ✅ 要件を明確にしてから書かせる

違うのは、その「明確にする作業」を人間が手動でやるか、/planでAIと対話しながらやるか、という手段だけです。

元記事の「ドキュメント・ファースト」は完全に正しかったし、今でもその思想は生きています。ただ、ドキュメントの作り方が「手書き」から「AIとの対話」に変わった。

これがこの半年で自分が体験した変化です。

まとめ

1. Vibe Codingの失敗は指示の構造不足（元記事の主張は今でも正しい）
2. 定義書6つ＋記憶ファイル3つの思想は有効だが、手動で全部書く時代は終わった
3. /planモードとresume機能が定義書と進捗管理を代替してくれる
4. CLAUDE.mdだけは自分で書く。これはプロジェクトのルールブックであり、ツール機能では代替できない
5. 重要なのは「構造化してから書かせる」という思想そのもの

CLAUDE.mdの設計パターンについては claude-code-tips に60以上のTipsとしてまとめています。

参考

• @kloss_xyz "why you suck at vibe coding" — 元記事

---

📘 関連Book
この記事の内容をさらに深掘りしたい方へ、Zennで有料Bookを公開しています。

実践Claude Code — コンテキストエンジニアリングで開発が変わる
CLAUDE.mdの設計思想から実践パターン、チーム開発、セキュリティまで全19章・12万字超の実践書です。