意図・仕様・計画をつなぐ書類

前のレッスンでは、ボトルネックが構築から前後の工程へ移ったことを見ました。ここから3回のレッスンでは、その前後の工程を、Claude Codeと一緒に回すための具体的な形を作っていきます。最初の1回は、コードを書く前の工程です。

思いつきをそのままClaude Codeに投げると、最初の数往復はうまくいきます。ところが、あとから「なぜこの仕様にしたのか」を思い出せなくなったり、レビューする人が経緯を追えなくなったりすることがあります。原因は、考えた過程がどこにも残っていないことです。

意図(intent)：思いついた人の言葉で書く

最初に書くのは、思いついた人が自分の言葉で書く「意図」の書類です。何を求めているのか、なぜそれが必要なのか、どんな制約があるのかを、平易な言葉でまとめます。技術的な仕様には踏み込みません。

書いたら、リポジトリのintent/のようなフォルダにコミットします。1つのプロダクトの中で完結するなら、この程度のシンプルな置き場所で十分です。

いま考えている〔やりたいこと〕について、いくつか質問して、
意図の書類(困りごと・望む結果・関係者・制約)としてまとめる手伝いをしてください。
まだ固まっていない部分は、選択肢を示して聞いてください。

〔やりたいことを書く〕

Claudeに壁打ち相手になってもらい、範囲・関係者・制約について聞き返させると、自分の頭の中にあった前提を書き漏らさずに済みます。書けたら、思いついた本人が読み返し、誤解している部分を直してからコミットします。

仕様(spec)：意図をもとに、広げて固める

意図が固まったら、それをもとに要件と設計をまとめた「仕様」の書類を作ります。意図の承認をきっかけに、Claudeに1つの会話の中でブランド・セキュリティ・既存の設計との整合性を確認させながら仕様を組み立ててもらい、依頼した人はそれをレビューする側に回ります。ゼロから自分で書く必要はありません。

ここで効くのは、矛盾を仕様の段階で見つけておくことです。「このAPIは公開してよいか」「この項目は個人情報にあたらないか」といった判断は、コードができあがってからレビューで指摘するより、仕様書を作る時点で確認したほうが手戻りが小さくて済みます。

計画(plan)：Claude Codeのプランモードで作る

仕様が決まったら、実装の計画を作ります。ここでClaude Codeのプランモードが使えます。プランモードでは、Claudeはファイルを読んでプランを提案しますが、承認するまで編集は行いません。ターミナルではclaude --permission-mode planで開始でき、セッションの途中でもShift+Tabを押すたびに切り替わります。

$claude --permission-mode plan
⏸ plan mode on

Claudeが出したプランをその場で承認するのではなく、「この会話を一度も見ていない人が、プランだけを読んで実装できるか」を基準に、足りない部分を質問して埋めていきます。承認したプランはplan.mdとしてコミットし、あとから実装がそのプランからずれたときは、同じコミットで書類の側も更新します。

やってみよう

演習1：意図の書類を1つ書いてみる

いま抱えている「作りたいもの」について、困りごと・望む結果・関係者・制約の4項目で、意図の書類を書いてみましょう。誰かに読ませて、意図が正しく伝わるか確かめてください。

演習2：仕様と計画のどちらで止まっているか

過去に手戻りが起きた仕事を1つ思い出してください。原因は「意図が曖昧だった」「仕様の時点で矛盾に気づけなかった」「計画が実装できるほど具体的でなかった」のどれに近いでしょうか。

今日のまとめ

3行で振り返ります。

• 意図(intent)は思いついた人が自分の言葉で書き、仕様(spec)は意図をもとに要件と設計へ広げ、計画(plan)はプランモードで実装できる粒度まで固める
• 各書類をコミットして残すと、あとから「なぜこの形にしたか」を追える監査証跡になる
• プランモードは、コードが生成される前にレビューする仕組みを技術的に強制する

次のレッスンでは、計画をもとにコードを書く「作る段」で、CLAUDE.md・スキル・フックという3つの層をどう使い分けるかを見ていきます。人間が最終的に判断する範囲については、人間が判断することでも扱っています。