メインコンテンツへスキップ
AMPL/ dev
開発系講座一覧

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

思いつきをコードに変える前に、意図(intent)・仕様(spec)・計画(plan)という3つの書類をバージョン管理につなぐ。各段階が前の書類を読み込んで始まる仕組みを作る

このレッスンで

終わる頃には、次ができるようになります

  • 意図・仕様・計画という3つの書類が、それぞれ何を記録するものかを説明できる
  • 各書類をコミットして残すことで、あとから経緯を追える監査証跡になる理由を説明できる
  • プランモードを使って、編集前にプランをレビューする流れを実践できる

前のレッスンでは、ボトルネックが構築から前後の工程へ移ったことを見ました。ここから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を押すたびに切り替わります。

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

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


やってみよう

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

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

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

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


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

参考

Claude Code公式: プランモードで編集前にレビューする
claude --permission-mode planの使い方と、Shift+Tabでの切り替え、承認までファイルを編集しない仕組みの一次情報
code.claude.com/docs · code.claude.com

このレッスンは役に立ちましたか?