最近は Claude Code の Plan モードをよく使っています。昨年12月ごろは前回の記事で紹介した自作の仕様駆動開発フレームワークを使っていましたが、ビルトインのPlanモードが改善され精度が高くなっており、こちらの方が軽量で必要十分だというケースが増えてきました。
ただ、仕様駆動開発の問題点として「コードレビューからマークダウンレビューになり、長文の中から抜け漏れを探すのが難しい」ことは変わらず課題です。実装させてみても、結局認識齟齬が発生してやり直すのは時間がもったいないです。
そこで試行錯誤していたのですが、Plan をステートマシン図として可視化する方法で少ないターン数で仕様の曖昧な部分が明確になりやすくなりました。せっかくなので Claude Code プラグインとして整備したので紹介します。
plan-tools プラグイン
このプラグインは現状 2 つのスラッシュコマンドを提供しています。
/plan-tools:state-machine/plan-tools:pbcopy
インストール
/plugin marketplace add MH4GF/shared-config
/plugin install plan-tools@mh4gf-marketplace/plan-tools:state-machine
現在のPlanからステートマシン図を生成し、Planファイルに加筆してくれます。以下のような図が追加されます。
## State Machine
```
┌─────────┐ submit ┌───────────┐ approve ┌──────────┐
│ Draft │ ────────────► │ Review │ ─────────────► │ Approved │
└─────────┘ └───────────┘ └──────────┘
│ │
│ cancel │ reject
▼ ▼
┌─────────┐ ┌───────────┐
│ Deleted │ │ Draft │
└─────────┘ └───────────┘
```図を描く過程で不明点があれば、Claude が AskUserQuestion ツールを使って質問してきます。「このタイミングでエラーになった場合はどう処理しますか？」といった具合です。これを再帰的に繰り返すことで、Plan の段階で仕様が明確になっていきます。
ビルトインのPlanモードで問題になるのが、このようなエッジケースの抜け漏れが多いことでした。ステートマシンとして図示するためにはエッジケースを全て処理しなければならないので、問題に気づきやすいです。
また、図に起こすことで人間にとっての理解容易性が上がるのも気に入っているポイントです。状態遷移図を見る方が全体像を把握しやすいのはわかりやすいメリットですし、自分の場合最近は新規のコードベースを触ることが多く、前提知識が薄くなりがちです。そのため知識不足が原因で意図しない実装結果を招くことがありました。例えばある非同期処理のトリガーはcron的な定期実行だと思っていたが、実際はユーザーによるUI上のボタン押下だけだった、みたいな勘違いです。ステートマシン図に起こしてトリガーを明示してもらうことで勘違いを防ぎやすい効果が自分はありました。
/plan-tools:pbcopy
こちらのコマンドは記事の主題ではないですが、Plan ファイルの内容もしくはファイルパスをクリップボードにコピーするコマンドです。 これが意外と便利で、以下のような使い道があります。
- Cursor の
composer-1や Devin に実装を依頼する際のコンテキストとして渡す - GitHub Issue にペーストしてチームに Plan 結果を共有する
- コピーしたパスを別のClaude Codeセッションで読み込んでもらい、Planファイルを更新してもらう
特にcomposer-1は圧倒的に実装速度が速いので、Claude Code で Plan を練った後、実装は任せるというワークフローで重宝しています。
自分の設定
ユーザースコープの CLAUDE.md で、以下のように設定しています。
ExitPlanModeの直前に/plan-tools:state-machineを実行- Plan を accept したタイミングで
/plan-tools:pbcopyを実行
こうしておくと、手動でコマンドを実行しなくても、常にレビュー用の図が生成され、Plan が共有可能な状態になります。
まだできていないこと
ステートマシン図によって計画の認識齟齬は減らせましたが、 現状のPlanモードの運用では詰められていない部分がいくつかあります。
QAの計画
現状のPlanモードは詳細な実装計画を立ててくれますが、挙動を保証するテストや動作確認方法は計画してくれないことが多く、追加で指示する必要があります。CLAUDE.mdでTDDのアプローチを指示したりしていますが、期待する計画が一発で得られたことがありません。うまい方法を探して試行錯誤しています。 経験上コーディングエージェントは一つの指示で複数の責務を持たせると全て中途半端になるので、テスト計画は別のコンテキストに分ける方がいいんでしょうね。サブエージェントを考えるのが良いのかな…
抽象度の高い戦略の計画
Planモードは実装タスクの計画に特化しているので、PRDやプロダクトブループリントなどのような複雑で抽象度の高い計画には適していません。これらも仕様駆動開発の「実装前に全ての仕様を決め切るのがそもそも難しい」という問題が残っています。
それを解決するために、前回記事での自作の仕様駆動開発フレームワークでは仕様ではなく論点を中心に据え、それぞれサブIssueに分解し解決していくアプローチをとっていました。しかし汎用的なドキュメントテンプレートにしており、抽象度の高い戦略で使いやすいとは言えませんでした。 戦略や現在の課題を1枚のマークダウンドキュメントにまとめていつでもLLMに相談できる状態を作ると意思決定のスピードが高まるため、継続的に更新する良い仕組みを作れると良さそうです。これもうまい方法を探したいですね。
前回記事での自作の仕様駆動開発フレームワークは2025年11月に作って記事にしましたがそれも2ヶ月で使わなくなったため、今回記事のアプローチもすぐに陳腐化するのだろうなとも思います。個人的には動きが速くて楽しい時代だなと感じます。