初めに
前回のブログでは「Claude Code革命！3フェーズ開発で効率的な開発：計画→実装→検証術」について紹介しましたが、今回は実際にClaude Codeで仕様書ベース開発運用する際に「これは絶対に押さえておかないとハマる」というポイントについてお話しします。
実際に検証していて失敗したことや、気をつけないと時間を無駄にしてしまうポイントを中心にまとめました。
1. ドメイン知識の明示的なドキュメント化の重要性
この方法で検証していて失敗したこともあります。例えば、プロジェクトの基礎的な知識（ドメイン知識）は、明示的にドキュメント化しない限りAIは理解してくれません。
実際あった問題として、ネイティブアプリとWebアプリのバックエンドリンクの構成があります。ローカル環境ではSWCでエミュレートしていて、「/api」に自動でプロキシされる仕組みでしたが、AIはそれを知らずにバックエンドURLを直接埋め込もうとして、APIパスの参照エラーが多発しました。
これは「プロジェクトコア」のようなドキュメントを作成して共通知識を提供することで解決しました。AIは書かれていないことは認識できず、セッション内で与えていない情報は理解しません。
プロジェクトコアドキュメントの具体例
プロジェクトコアには、実際にデプロイする環境のプロキシの設計やプロジェクトの根幹に関わる部分をちゃんと定義しておくべきです。
今回私が作った環境では、Azure Static Web Appsをバックエンドリンクで構築していて、スラッシュAPIというのが自動でプレフィックスで飛んでいくという仕組みがあります。そのため、プレフィックス「/api」でアクセスするということを明記したり、プロジェクト構成みたいなのを書いておいて、そういった情報をAIに与えています。
当たり前のように思える環境設定や開発ルールも、AIにとっては「初めて聞く話」です。人間の開発者なら暗黙知として共有されている部分も、AIには明示的に教える必要があります。
2. AIがドキュメントを無視する問題への対処
計画フェーズでは「計画.md」などのファイルに指示を書いていますが、AIは時々ドキュメントを無視することがあります。人間と同じで、指示や定義を見ないこともあるんです。読んだうえで無視することもあるので、絶対守ってほしいことはドキュメント化し、プロンプトでも注意するのが重要です。
これは本当にイライラするポイントで、せっかく時間をかけて詳細な仕様書を作っても「それ、無視しちゃダメでしょ！」ということが頻繁に起こります。
無視されやすいパターンと対策
プロンプトに期待してない情報は割と無視しますね。そのパターン的なミスの傾向みたいなのがあったら、マークダウンファイルに情報反映させるというやり取りをよくやっています。
仕様書を書いてもらうフェーズと開発フェーズで、仕様書を書いている最中にコードの編集をしたりしていたんですよ。そこで、仕様要件フェーズと開発フェーズの三つに分けますという指示をつけて、計画フェーズではファイルの編集は加えないでくださいという指示を追加しています。開発フェーズは、作成した仕様のドキュメントを読んで、それに対してステップバイステップで開発を進めてくださいということを、マークダウンファイルで定義しています。
対策としては：
- 最重要な制約事項はドキュメントに書く
- さらにプロンプトでも再度強調する
- 「この部分だけは絶対に守ってください」という明示的な指示を含める
二重、三重の安全策を講じることが大切です。
3. 仕様書の適切な分量バランス
仕様書の分量については、長すぎるとAIが無視する確率が上がります。「無視しました」という返答が返ってくることもあり、それを見たときは正直ブチ切れました（笑）。
短ければ理想的ですが、短すぎると時間がかかるので、AIが無視する可能性も考慮しながら適切な分量を見極める必要があります。どの程度の分量が適切かはプロジェクト依存です。ドメイン知識が多ければ、その分仕様書に書く情報は少なくて済みます。
具体的な分量の目安
私の環境で言うと、エンドポイント2つと、それに対応する画面1つという感じだと、体感的に上手くいったという印象です。これは本当にプロジェクトによるというか、プロジェクトコアによる感じの内容というか、元のコンテキスト量が影響してきます。
この辺りは経験則になってしまいますが、AIが「長いから読みたくない」と判断するラインを見極めることが重要です。人間と同じで、あまりにも長い仕様書は最後まで読んでもらえません。
4. 新機能開発とバグレポートの使い分け
私は新機能開発とバグレポートをこの二つの方法で分けて対応しています。
- 新機能開発: 必ず3フェーズ（計画→実装→検証）を踏む
- 小さな変更: でもドキュメント→実装という段階を踏む
- 本当に小さな変更: 人間がやったほうが早い
人間がやったほうが早い変更の見極め
プロジェクト構成的な部分の変更ですね。コード規約みたいなところで、ちょっと上の階層にファイルを移し替えたりとか、ファイル構成で、ちょっとこっちに移行させるほうがいいよねみたいな話とか、ファイルの単純な移動は、VS Codeの補完機能が優秀なので、そういった作業とか、あとは関数名が気に入らないので、関数名のリネームするという作業ですよね。
人間が手を動かして作業して、セッションが継続しているのであれば、ちゃんと変更を加えましたよということをAI側に伝えてあげる必要はあります。そうじゃないと、人間が編集したファイルとAIが編集しようとしているファイルでコンフリクト起きてしまうので、再度ファイルを作ろうとするんですよ。なので、そういったところで調整を取っていく必要はあるかなと思います。
この使い分けが重要で、何でもかんでもAIに頼めばいいというものではありません。1行2行の修正をAIに説明するより、自分でやってしまったほうが早いケースも多々あります。
プロセスを踏んでも意図したものができない場合は、やはり人間のドキュメントが不十分だということです。AIは書かれていないことを自由に判断するので、ドキュメントの質を高める必要があります。
5. 中規模開発での威力と現在の限界
現在はプライベートリポジトリで検証しているため、大規模プロジェクトへの導入経験はまだありませんが、中規模程度の開発であれば強力なツールになると思います。特にプロトタイピングでは大きな力を発揮しそうです。
個人的に学びになった点としては、仕様書作成が苦手な私でも、AIが返してきた仕様書を見て「分かりやすい」と感じることがあります。学習的な側面でも価値があると思います。
完璧な仕様書があれば理想的ですが、そういうものは実際には存在せず、どこかに不備があるものです。だからこそ、機能ごとに段階的に仕様書を作っていくアプローチが有効だと思います。
6. よくある失敗パターンとその対策
型定義の不整合問題
本当によくあるのが、フロントエンドとバックエンドで型定義が共通化されてなくて、バックエンドにアクセスできない、APIアクセスは成功してるんだけども、画面に表示がされないということがありました。
対策としては、OpenAPI スペックを作らせて、そのOpenAPIスペックから型定義を作成する。そして、フロントエンドはその型定義を絶対に使用するようにする、という感じで回避しています。
デプロイ環境の差異による問題
デプロイ環境の差異みたいなところで問題が起きることもあります。今回Azure のバックエンドリンクで、スラッシュAPIのコンテンツを自動でプロキシしてくれるんですけど、そういったことを伝えてなくて、なんか別のエンドポイントベースURLみたいなのを付けて、そこにアクセスするようにしましょうみたいな提案をされました。
バックエンドが現状、localhost の3001番で動いてるので、ローカル3001番に直接アクセスするように変えちゃいましょう、みたいなことを言われることがあります。これはプロジェクトコアドキュメントでしっかりと環境構成を明記しておくことで回避できます。
まとめ
Claude Codeは確実に開発効率を向上させてくれるツールですが、これらのポイントを押さえておかないと、余計な時間を費やしてしまいます。特にドメイン知識の明示化と仕様書の分量バランスは、成功の鍵となる重要な要素です。
まぁ暴走するのは人間と一緒って感じですね。人間よりも暴走しがちですが、言いやすい相手ですよねｗ
皆さんも、ぜひこれらのポイントを参考にClaude Codeを活用してみてください！
