Claude CodeのPlanモードを駆使し、楽に品質を担保してみた

こんにちは、ウィルゲート開発室の武田です！

これは私がClaude Codeを使って仕様書駆動開発をしていたときのことです。仕様書を書いて、設計書を書いて、レビューして修正して...気がつくと既に半日が過ぎていて、ふと手を止めました。

「私、いつまでドキュメント書いてんの？」

もちろん、仕様書駆動開発にはメリットがあります。要件の整理、設計の明確化。これによってClaude Codeが仕様を満たす確実なコードを出力することができます。

しかし、怠惰な私は「もう少し楽できるんじゃないの？」という思いが頭をよぎります。特に1人月程度の機能開発では、「ドキュメント作成→レビュー→修正→関連ドキュメント修正」のループを重く感じてしまうのは、皆さんも経験されたことがあるのではないでしょうか。

そこで今回は、「Claude Codeを使いつつも、品質を保ちながら、少しだけ楽をする」方法を紹介します。

この記事の対象になる人
この記事の結論
仕様書駆動開発とその課題
解決策：Planモードを活用して軽くすり合わせる
Planモードとは
- 基本的な流れ
Planモードでのすり合わせのコツ
Planモードを使うときの注意点
- 3往復以上やりとりしない
- サンクコストを無視する勇気
品質を担保する仕組みを用意する
今回の方法の適用範囲と注意点
- 規模の大きい開発にはおすすめしない
- auto-compactの発生を絶対に避ける
実際にやってみて
まとめ

この記事の対象になる人

Claude Codeで仕様書駆動開発をしているが、毎回やるのが疲れると感じている人
ソフトウェア設計の原則をある程度理解しており、Claude Codeのコードに改善の余地を感じている人
1〜2人月程度の小規模機能開発でより効率的な方法を探している人

この記事の結論

小規模な開発には仕様書駆動開発ではなく、Planモードを使うと良い
Planモードを使うなら、3往復程度の議論で実装に移り、サンクコストに囚われず気軽に再実装することが大事
品質はCLAUDE.md、Test/Linter、実装後の人間による改善で担保する

仕様書駆動開発とその課題

私が以前行っていた開発プロセスは、仕様書駆動開発と呼ばれるものです。これはAWSが開発したエディタ「Kiro」で採用されている開発手法で、AIと人間で綿密に打ち合わせし仕様書を事前に作成した後にコーディングを開始するアプローチです。

要件定義書の作成
設計書の作成
実装計画書の作成
各ドキュメントを作成のたびにレビューと修正
実装開始

仕様書駆動開発では、各ドキュメント作成後に人間のレビューを挟みます。これによって方向性のブレは少なくなるものの、実装してみると設計を変更したくなることがままあります。しかし、そうなると修正が連鎖してしまうことがあるのです。設計を変更すると実装計画も見直しが必要になって、時には要件定義まで遡ることもあります。また、各レビューもドキュメントの情報量が多いため、指摘事項も多くなりがちで、疲弊してしまうことがありました。

解決策：Planモードを活用して軽くすり合わせる

そこで私が採用したのが、Anthropicが推奨する「Explore → Plan → Code → Commit」のフローを基本としつつ、Planモードを積極的に活用する方法です。

Planモードとは

Planモードは、Claude Codeが実装前に関連コードを探索し、得たコンテキストを元に計画を立案し、ユーザーの承認を得てから実装に移る機能です。

詳しい使い方はAnthropicの公式ドキュメントをご参照ください。 https://docs.anthropic.com/en/docs/claude-code/common-workflows#how-to-use-plan-mode

基本的な流れ

Explore（探索）: 既存コードの理解（Planモード）
Plan（計画）: 仕様や設計をすり合わせる（Planモード）
Code（実装）: Claude Codeに実装させる
Commit（コミット）: testやlinter等通過後、人間の手で微修正してコミットする

重要なのは、従来の緻密なドキュメントを作成するのではなく、Planモードで軽いすり合わせに重点を置くことです。

Planモードでのすり合わせのコツ

Planモードを使うときは、主に以下の観点ですり合わせを行います。

1. 仕様を満たすロジックか - 要件を正しく満たしているか？ - エッジケースが考慮されているか？

2. モジュール化は適切か - クラスやメソッドの分け方は適切か？ - 配置場所や命名は妥当か？ - 関心の分離がされているか？

3. エラーハンドリングしているか - 例外処理は適切に組まれているか？

Planモードを使うときの注意点

3往復以上やりとりしない

Planモードでのすり合わせが3往復を超えそうになったら、その時点での最良の方針で一旦実装させることにしています。私の経験上、それ以上議論を重ねても、実装してみないと分からない部分が多いからです。むしろ、大枠をすり合わせて実装し、細かい部分は後から修正する方が効率的だと思っています。また、議論が長引くとコンテキストが膨らみすぎて、Claude Codeの精度が悪くなることもあります。

サンクコストを無視する勇気

前段で細かい部分は後から修正した方が良いと述べましたが、変更箇所が多すぎる場合は再実装させたほうが良いこともあります。仕様書駆動開発では、実装開始までに長い時間をかけているため、一度実装した内容をやり直させるのは心理的に重いものです。しかし、Planモードなら、すり合わせの時間はせいぜい5分程度しかかかりません。そのため、実装してみて「やっぱり違うな」と思ったら、それまでの実装を捨てて、すぐにPlanモードに戻って再度すり合わせを行い、再実装させましょう。また、再度すり合わせを行うときは、前の実装で課題をコンテキストに含めるのを忘れないようにしましょう。

品質を担保する仕組みを用意する

しかし、このままでは「軽いすり合わせだけだと、品質に不安が残るんじゃ？」という疑問が残ります。実際、このまま実施すると仕様書駆動開発よりも品質が悪かったり、仕様や要求を満たせていないコードを出力することがどうしても多くなります。そこで、以下の3つは最低限実施して品質を担保するようにしましょう。

1. CLAUDE.mdを書く

CLAUDE.mdに記載する要素

プロジェクトの概要
技術スタック
機能を示すユビキタス言語
プロジェクトの設計方針（サンプルとなるコードがあるなら示しておくと良い）
TestやLinterなどの品質管理ツールの実行方法

CLAUDE.md は短く保つようにしましょう。余計なコンテキストが増えるほど、LLMの性能が悪くなってしまいます。たとえば、技術スタックなら「Laravel vX.X」と記載しておくくらいで十分です。

2. Test・Linter・Formatterを必ず実行する

Claude Codeへのタスク指示時に「Test・Linter・Formatterがパスすること」を明示することで、各種品質管理ツールをパスするまで実装を繰り返させることができます。 Claude Codeに仕様やコーディング規約を守れているかを確認・判断させるのではなく、ツールを使って確認させるようにしましょう。

3. 実装後に人間がコードを改善する

実装後の細かい調整は人間が行います。

早期リターンの適用
変数のスコープを縮める
適切なコードコメントの追加
不要なコードの削除

などの小さな改善、いわゆる「リーダブルコード」や「Tidy First?」の第一部に書かれているような内容の修正を人間の手で行います。

今回の方法の適用範囲と注意点

ここまでPlanモードを使った方法を紹介してきましたが、この方法には適用できる範囲と注意点が存在します。

規模の大きい開発にはおすすめしない

全くのゼロからプロダクトを作る場合は、仕様書駆動開発をおすすめします。実装する量や複雑さが未知数であるため、しっかりとしたドキュメントを作成してから実装に入る方が無難です。また、複数チーム・複数月にまたがるような大規模開発でもこの方法は向いていません。理由は上と同じです。

auto-compactの発生を絶対に避ける

auto-compactが発生すると、それまでのコンテキストが圧縮され、Claude Codeが出力するコードの品質が大幅に低下します。 auto-compactされる前に必ず/clearして、新しいセッションを開始してください。もしauto-compactが頻発するようであれば、機能の粒度が荒すぎるサインです。タスクをもっと細かく分割する。もしくは、仕様書駆動開発に移行して、余計なコンテキストをドキュメントに退避させることを検討してください。