はじめに
みなさん、こんばんは。最近はClaude CodeでAIにコードを書かせる検証をしている龍ちゃんです。
先月はあまりブログを書けなくて、僕もビックリするぐらい三本しか書いていませんでした。今月は多少時間を取ってでもブログを書いていこうと思っています。
まずVibe Codingをやってみて感じた課題感に関してはこちらでまとめています。
AIが悪いのではなく、人間が悪い
色々検証して思ったことですが、だいたい人間の入力が悪いというか、人間のせいなんですよね。AIの仕組みでそれを解消しようという試みもありますが、業務でAIを使うなら、人間の入力が悪いと考えて、入力の方を改善していく方が、AIの精度向上を待つよりも効果的だと思います。人間の入力をいかに変えていくかということにフォーカスを当てて検証を進めています。つまり、Claude Codeが悪いんじゃなく、人間が悪いんです。
人間の入力をAIが理解しやすいように作っていくという前提を押さえてもらえればと思います。
従来手法の限界：ペアコーディング
最初の1〜2ヶ月間、Claude Codeを使い始めた頃は、Vibe Coding（ペアコーディング）という手法で開発していました。プロンプトとしては100から300文字ぐらいのシンプルなものを投げていました。
これだと小規模な改善や機能追加には非常に優秀でした。リファクタリングも効果的でした。しかし、大規模な開発（例えば、一つのページ全体を組むような）をしようとすると、意図したとおりのものを作ってくれないことがありました。AIが自由に解釈しすぎて、変なものを作ってくることもありました。
ペアコーディングの具体的な問題点
実際にペアコーディング手法で開発していて気づいた課題があります。雑なプロンプトを投げて作ったものだと、やっぱり意図したものが作られないということが頻繁にありました。また、ペアプログラミング的な使い方だと人間の手が入る分、作業が遅くなるという印象もありますね。
特に既存プロジェクトで、すでにコード規約やディレクトリ構成が決まっている状態なら、それを学習させてからエンドポイントを追加する作業は割と有効だと思います。しかし、300文字程度で自分が作りたいものを説明するのは文豪でも難しいでしょう。文章が苦手な人にとっては尚更です。
ここで思い出してほしいのが「人間が悪い」ということです。そういう意味では、「意図したものができない」と言っている人は、当然のことを言っているだけなのです。
このような背景があり、リファクタリングは得意分野だと言えます。既存コードのパフォーマンス問題を改善するといった単純な指示は分かりやすいです。しかし新機能開発となると話が違います。Claude Codeで自分の意図したとおりのものを作る手法についてお話ししようと思います。
ディレクトリ構成とファイル管理
ディレクトリ構成としては、計画・検証用のドキュメント部分と実装コード部分を分けています。
/
├── CLAUDE.md # プロジェクト全体のガイドライン
├── docs/ # 計画・設計フェーズ
│ ├── CLAUDE.md # 計画フェーズ専用ルール
│ ├── features/ # 新機能計画
│ ├── bugs/ # バグ調査・修正計画
│ └── research/ # 検証結果・知見
└── application/ # 実装フェーズ
├── backend/
│ └── CLAUDE.md # バックエンド実装ルール
└── frontend/
└── CLAUDE.md # フロントエンド実装ルール新手法：3フェーズ開発
最近実践している方法では、開発フェーズを「計画」「実装」「検証」の3つに分けています。
計画フェーズ
まず「計画」フェーズでは、やりたいことの仕様書をAIに説明し、文書化してもらいます。このフェーズではコードを一切書かせません（型定義などの簡単なものは除く）。
AIが返してきたドキュメントを確認し、自分の意図しているものかを確認します。これによってAIが自由に解釈する余地を減らします。
計画フェーズで効果を発揮するCLAUDE.mdや具体的な手法・効果については「AI協働で仕様書アレルギー克服！開発時間を1週間→2日に短縮する実践法」で紹介しています。
実装フェーズ
次に「実装」フェーズでは、作成した仕様書を読み込ませ、それに基づいて実装してもらいます。説明は全て計画フェーズで作った仕様書に含まれているので、それを入力として与えるだけです。
人間は監視役に徹し、AIが暴走した場合は適宜小さなプロンプトで修正します。
実装時に陥りそうな課題に関しては、「Claude Code仕様書ベースでハマる6つの落とし穴！失敗回避の備忘録」でも書いています。
検証フェーズ
最後の「検証」フェーズでは、仕様書の不備がどこにあったか、その結果どのような変更が加えられたかを分析します。これにより実装と仕様を照らし合わせ、根拠のない編集を防止できます。実装後は人間の手で確認作業を行います。
計画と実装を比較することで、レビューした仕様書の中で不足があった分などを特定することができます。
計画ドキュメントと実装の内容を確認して、計画と実装の差異がある点をまとめてください。ここで不測の指摘があるってことは、仕様書や計画が不足しているということになります。ここで学びができますね。
実際の開発効果：驚異的な時間短縮
この3フェーズ手法を実践してみて、開発期間は圧倒的に短縮されました。具体的な事例をご紹介しますと：
小規模システムの例
- バックエンドのエンドポイント2つ
- フロントエンドの画面1つ
- 開発時間：約30分で完了
作った画面は結構シンプルなシステムでしたが、エンドポイントの仕様としては単純なものでした。この規模なら、仕様書作成から実装まで含めて30分という短時間で完成します。
中規模システムでの限界 一方で、バックエンドのエンドポイントが4つで、フロントエンドの画面でそれら4つのエンドポイントをいい感じに使うような中規模なものを作ろうとすると、セッションが限界になったりということがありました。この辺はタスクを分割するべきだったなと考えています。
この手法の効果と学び、そして課題
現在はプライベートリポジトリで検証しているため、大規模プロジェクトへの導入経験はまだありませんが、中規模程度の開発であれば強力なツールになると思います。特にプロトタイピングでは大きな力を発揮しそうです。
バグ発生率と仕様漏れの実態
開発時の課題として、バグというよりも仕様漏れの方が圧倒的に多いです。仕様書を元に開発するので、仕様から漏れている内容が実装している最中やテストしている最中に気づいたりします。これは大体バグというより仕様漏れかなと思います。
ビルドが失敗するようなケースは結構あるんですが、PrettierやESLintなどのフォーマッターやリンターをちゃんと定義しておいて、その定義の下で処理してもらうようにするとある程度コードとしては綺麗になります。
ただし、ディレクトリ構成やプロジェクトのコード設計思想みたいなところを伝えていないと、fat controllerのように1ファイルに対して過剰にコードを書いてしまうみたいなことは割とありがちですね。
学習効果の発見
個人的に学びになった点としては、仕様書作成が苦手な私でも、AIが返してきた仕様書を見て「分かりやすい」と感じることがあります。学習的な側面でも価値があると思います。
完璧な仕様書があれば理想的ですが、そういうものは実際には存在せず、どこかに不備があるものです。だからこそ、機能ごとに段階的に仕様書を作っていくアプローチが有効だと思います。
また、検証フェーズで計画の不備を見つけるプロセスを踏むことでレビュー観点を育てることができます。レビューをする体験そのものが貴重です。
実践での注意点とコツ
ここにまとまり切っていない部分に関しては別途「Claude Code仕様書ベースでハマる6つの落とし穴！失敗回避の備忘録」でまとめています。
この手法が向いていない作業
実際に検証してみて、この3フェーズ手法でも上手くいかない作業があることが分かりました。
プロジェクト構造の大幅変更 プロジェクトのディレクトリ構成を変えるような作業は、Claude Codeだとパスの解決なども自動でやってくれるのですが、使っている・参照しているファイルを再帰的に検索してということになるので、実際時間がかかってしまうという印象があります。
簡単なリネーム作業 関数のリネームのような作業に関しては、人間の手作業の方が圧倒的に早いです。VS Codeのリファクタリング機能のようなサポート機能を使うのがいいんじゃないかなと思っています。
フロントエンドデザインの特殊性
フロントエンドのデザインに関しては、仕様書を書いて作るというのはあまり向いていないかなと思ってます。
理由としては：
- フロントエンドで最初に想定していた仕様が全てを満たすことって無い
- UIを文章で説明するのって結構な分量が必要
- 分量が増えるとAIが混乱する確率も上がる
- 実際に画面を見て「何か違うな」という瞬間が割とある
- 自分の書いている仕様と自分の頭の中にあるイメージが合ってることがあまりない
- コンテキストが膨大に増えていく
そのため、フロントエンドに関しては別のアプローチが必要だと考えており、別途検証を進めています。
Claude Codeの”忘れっぽさ”との付き合い方
実際に運用していて気づいたのですが、CLAUDE.mdにいくら設定を書いても、コンテキストを無視することが結構あります。特に長時間の作業や複雑なタスクになると、最初に設定した原則を忘れてしまうことがありますね。
そういう時の対処法として、私は以下のようなアプローチを取っています：
リアルタイム修正パターン 動作を確認しながら進めて、「あ、意図した挙動をしてないな」と感じた瞬間に処理を止めます。そして、プロンプトに守ってほしい原則を改めて追加して再度実行する、という感じですね。
事後確認パターン 処理が完了した後に、「あれ？原則守ってないですよね？」とClaude Codeに詰める作業も行っています。これによって、なぜその判断をしたのかを確認し、次回の改善につなげています。
この経験から学んだのは、AIも完璧ではないということです。「人間が悪い」と言いましたが、同時にAI側の限界も理解して、適切にガードレールを設ける必要がありますね。完璧な仕様書があれば理想的ですが、そういうものは実際には存在しないのと同じように、完璧なAIも存在しません。だからこそ、人間とAIの協働において、お互いの特性を理解することが重要だと感じています。
適用に向いているプロジェクト
逆に、この手法が効果的なのは：
- バックエンドのAPI開発：仕様が明確に定義しやすい
- データ処理ロジック：入力と出力が明確
- 既存プロジェクトへの機能追加：コード規約やディレクトリ構成が既に決まっている
- プロトタイピング：完璧性よりもスピードを重視
まとめ
私は新機能開発とバグレポートをこの二つの方法で分けて対応しています。計画段階で仕様書を挟むことで、意図したものを作れるようになります。
ただし、万能ではありません。プロジェクトの性質や作業内容によって、従来のペアコーディング手法や人間による手作業の方が効率的な場合もあります。適材適所で使い分けることが重要ですね。
皆さんも、ぜひこの3フェーズ開発手法を試してみて、自分のプロジェクトに合うかどうか検証してみてください！何か質問や改善点があれば、コメントでお聞かせください。
