はじめに
ども！毎日毎日Claude Codeとお話して日課となっている龍ちゃんです。直近ではClaude Codeに関するお話を執筆していこうと思います。
最初は「これは革命的だ！」と思って飛び込んだClaude Codeでしたが、実際に使い込んでいくと、思った以上に奥が深くて、適当にプロンプトを投げているだけでは思うような成果が出ないことがわかってきました。
今回は、私が実際にClaude Codeを使い倒してきた中で見つけた、「Vibe Coding」から卒業するための実践的なTipsをまとめてみました。同じような課題を感じている方の参考になれば幸いです。
今回紹介する問題点・課題を解消するために検証した内容をまとめています。こちらも併せて読んでもらえると楽しいかもしれません。
- Claude Code革命！3フェーズ開発で効率的な開発：計画→実装→検証術
- AI協働で仕様書アレルギー克服！開発時間を1週間→2日に短縮する実践法
- Claude Code仕様書ベースでハマる6つの落とし穴！失敗回避の備忘録
- AIと爆速開発！Next.js×Nest.js型定義同期の自動生成パイプライン構築術
Vibe Codingの落とし穴
雑なプロンプトでは成果が出ない現実
「とりあえずやってみる」テンション感で始めがちなClaude Codeですが、これが最初の落とし穴でした。数行のプロンプトで開発に十分な意図が伝わっていないんですよね。
例えば、「４輪駆動で走る車を作って」と言っているようなもので、具体的な仕様や制約が伝わっていない状況になってしまいます。これでは、Claude Codeも困ってしまいますよね。
ドキュメント化が成功の鍵
解決策として見えてきたのが、Claude Codingの前にドキュメント化しておくことの重要性です。
具体的には、以下のような準備が必要になります：
既存のコードがある場合
- /initはとりあえず打つ！
- 既存コードを読み取らせてドキュメントを作っておく
- Azureなどの構成などもある場合はドキュメント化しておく
コーディングの前にタスク専用の設計書を作成する
- 設計書→Codingの流れを徹底する
- まずは設計書を作成して内容が人間の意図しているものと一致しているか確認しておく
- Claude Codeはコードを書きたがるから、設計書のみに中止させる
Vibe Debugがつらすぎる問題
よくあるデバッグ地獄
Vibe Codingしていて、動かないことがそれなりにあります。エラー内容を入力して修正してもらうこともできますが、治らない場合は大胆な戦略をとることがあるんです。
例えば：
- フロントの改修をしているのに、バックエンドのコードを直そうとする
- 新規ファイルを作成してバージョンアップしたりする
- Bicepファイルを編集するときに、いったんリソースグループを削除してしまう
効果的なデバッグ戦略
エラー→Vibe Codingがつらくなる場合は、該当箇所のコードを読み込んで、人間の観点＋エラーメッセージ＋調査指示で取り組むことで精度が上がることがわかりました。
セッション管理の重要性
メモリ制限を理解する
ドキュメント化していない知識は伝わっていないと思ったほうが良いです。Claude Codeはセッション型でメモリに記憶を保持していないので、セッションを閉じると記憶が失われると思ったほうが良いですね。
そのため、定期的なドキュメント管理とプロジェクトのコア部分の情報をドキュメント化して読み込ませておくことが重要になります。
適切なタスクサイズ
１セッション１タスクぐらいの分量で収まるように進めることを意識しています。ドキュメント→タスクを完了させる動きをさせておくのがコツです。
セッションを閉じるとタスクの進捗が確認することができないので、セッションを閉じるときはタスクが完了したタイミングであることを意識しておきます。
巨大なタスクでなく、2~3hで完了させる程度でタスクのサイズを分割して進めるのが良いですね。タスクが大きすぎると、Claude Code側がフェーズを分割したりするので、フェーズ進行中はセッションを切らないようにしています。
実践的なTips集
不要ファイル・デバッグコンソールの管理
Vibe Debugの結果、不要なコードや不要なファイルが生成されていることがあります。これは、最終的にコミットやPRに含まないことが大切です。
最後に「参照していないコードを削除しておいてください。不要なファイルは削除してください」と指示することで、きれいな状態を保てます。
ディレクトリ単位で不要になったファイルは削除しておくことも重要です（過去のプロジェクトなどのファイルがある場合は削除しておきましょう）。
フロントとバックの型定義の不整合対策
バックエンドとフロントエンドでAPIの型が不整合が発生していたことがありました。
対応策：
- フロントのコードを作成する前にバックエンドのソースを読ませる
- バックエンドのAPIへアクセスする部分は自動生成させてそれを使用するように変更する（検討中）
CLAUDE.mdの活用と注意点
特にセッションが長くなった場合はCLAUDE.mdを無視しがちになります。AIは昔のコンテキストほど優先度が下がるというのはよくある話ですね。
対応策：
- セッションが長くなった場合はいったん切る
- セッションの開始時には必ずCLAUDE.mdを読み込まれるので、セッション内で編集するファイルの領域を決定する
- バック→フロントの連続ではなく、バック作成→OpenAPI Spec→フロントという連携をする
ただし、セッション開始時からCLAUDE.mdを無視することもあります。そういった場合は、追加のプロンプトで指示を与えることが効果的です。
具体的には：
- いったん処理を止めて、追加のプロンプトで再指示
- 「無視されているCLAUDE.mdを再度読み込んでください」といった明示的な指示
- 重要なルールを#コマンドで再度強調する
これらの方法で、CLAUDE.mdの内容を確実に反映させることができます。
ファイルスコープの明確化
編集するファイルと触らないファイルを決定することが重要です。例えば：
- ビルド後のファイルを直接変更しようとした
- フロントの改修中にバックエンドのコードを変更しようとした
このような問題を避けるために、事前にスコープを明確にしておきます。
プログラミングファイルによる違い
Bicepファイルは難しい
Bicepファイルの依存関係周りの設定が難しいことがわかりました。
回避策：
- 依存関係やリソースが完成した後で連携する処理はShell ScriptでAzure CLI経由で処理を行う
- Bicepの処理はリソースの作成のみに注力させておく
GitHub Actionsも要注意
GitHub Actionsについても課題があります：
- 提供されているActionsを読み込んで使うことが難しい
- 割と大胆なActionsを書いてくる（Azure CLIとかGitHub CLIを使うような）
回避策： GitHub Actionsはプログラム言語レベルで多岐にわたらないため、Vibe Codingではなく、人力コーディングで行ったほうが良いという結論になりました。
まとめ
今回は、Claude Code使用時の「Vibe Coding」から脱却するための実践的なTipsをまとめてみました。
重要なポイントをまとめると：
- 事前のドキュメント化と設計書作成を徹底する
- セッション管理とタスクサイズの適正化
- ファイル種別による特性を理解して使い分ける
- 型の不整合やスコープの明確化に注意する
Claude Codeは非常に強力なツールですが、適切な使い方を身につけることで、その真価を発揮できるようになります。皆さんも、ぜひこれらのTipsを参考に、より効率的な開発フローを構築してみてください！
LinterとFormatterの設定など、基本的な開発環境の整備も忘れずに。ここは人間と一緒ですからね。
Claude Codeでの開発、一緒に極めていきましょう！
