Claude Code プロンプト設計｜Goal・Context・Done when 4要素の書き方

本記事は「Claude Code を数回触ったけれど、結果がブレる気がする」という方のための、プロンプト設計の基礎です。CC-13 で紹介した 3 要素（何をしたい・どこを見て・どう終わる）をさらに 1 段階くわしくし、Goal / Context / Constraints / Done when の 4 要素で安定させる考え方を整理します。最後にコピペで使えるテンプレートも 3 つ用意しました。

🌱 なぜプロンプト設計が必要なのか

ひとことで：プロンプトは AI への「指示書」だからです。曖昧な指示は曖昧な結果を生みます。

Claude Code は強力なエージェントですが、AI である以上「与えられた情報の範囲で最善を尽くす」のが基本動作です。同じタスクでも、プロンプトに含まれる情報量と精度で、出力の質は大きく変わります。

CC-13（最初の使い方）で覚えた 3 要素（何を／どこを見て／どう終わる）は、プロンプトの最低ラインです。本記事ではそれを 4 要素に拡張し、業務でも崩れないレベルまで引き上げます。

ポイントは「呪文を唱えれば良い結果が出る」ではなく、「書くべきことを抜け漏れなく書けば、ブレが減る」という地味な事実です。テンプレートを 3 つ覚えるだけでも、毎日のプロンプトが一段引き締まります。

🧩 4 要素：Goal / Context / Constraints / Done when

ひとことで：目的・文脈・制約・完了条件の 4 つを書くと、ブレが大幅に減ります。

CC-13 の 3 要素（何をしたい・どこを見て・どう終わる）を、さらに 1 段階分解した 4 要素が以下です。

要素	何を書く	例
Goal（目的）	達成したいゴールを 1 文で	「ログインが失敗するバグを直す」
Context（文脈）	どこを見ればいいか・前提条件	「src/auth/ を読んで、エラーログは ◯◯」
Constraints（制約）	やってはいけないこと	「既存テストを壊さない／legacy/ は触らない」
Done when（完了条件）	どうなったら完了か	「npm test が全件パスする」

3 要素から増えたのは Constraints（制約）です。これが地味に効きます。「やっていいこと」だけでなく「やってはいけないこと」を明示しておくと、想定外の暴走をかなり防げます。

順序にこだわらなくていい

「Goal → Context → Constraints → Done when の順でないとダメ？」と気にする必要はありません。4 つすべてが含まれていることのほうが、順序より大事です。1 文に収まりきらないときは箇条書きで書いて構いません。

⚖️ 悪いプロンプトと良いプロンプトの比較

ひとことで：曖昧な依頼はブレた結果に、4 要素入りの依頼は安定した結果につながります。

抽象論で終わらせないために、3 組の Before / After を見ていきます。曖昧版で起こりがちな問題と、それを 4 要素で潰した版を並べます。

例 1：バグ修正

❌ 悪い例

バグを直して。

何のバグか・どこを見ればいいか・どこで動作確認するかの情報がゼロです。Claude も全プロジェクトを総当たりで調査するか、見当違いの場所を直し始める可能性があります。

✅ 良い例

ログイン後にセッションが切れるバグを直したい。
src/auth/ を読んで、まず再現する失敗テストを書いてから修正してね。
既存テストは壊さないこと。
完了条件は npm test が全件パスすること。

Goal（バグ修正）／Context（src/auth/ 配下）／Constraints（既存テスト維持・先に失敗テスト）／Done when（npm test パス）の 4 要素が揃っています。

例 2：リファクタリング

❌ 悪い例

utils.js を綺麗にして。

「綺麗」の定義が完全に Claude 任せです。動作を変えてもいいのか・どのスタイルで揃えるのか・どこまでやるのかが全部不明です。

✅ 良い例

utils.js を ES2024 機能で整理してリファクタリングしたい。
動作は変えないで、既存テストは全部パスを維持すること。
変更前後の差分を表示してから書き換えてね。
完了条件は、既存の jest テストが全件パスし、行数が減っていること。

「動作は変えない」という制約がプロのリファクタリングを Claude に促し、「行数が減っている」が定量的な完了条件として効きます。

例 3：テスト追加

❌ 悪い例

テスト書いて。

どのファイルに・どのスタイルで・何のケースを書くべきかが何も決まっていません。

✅ 良い例

NotificationsService.ts のテストを追加したい。
既存の *.test.ts と同じスタイル（jest + describe/it）に合わせてね。
エッジケースは empty / null / network error の 3 つを必ず含めて。
テスト実行して全件パスを確認したら完了。

「既存スタイルに合わせる」を Constraints に入れることで、コードベースの一貫性が崩れません。

🎛️ 4 要素を使い分ける

ひとことで：要素ごとに「書き方のコツ」があります。一気に全部覚えなくて大丈夫です。

ここからは 4 要素それぞれの書き方のコツを、具体例つきで整理します。

Goal：目的を 1 文で書く

Goal は 動詞で始める 1 文 が基本です。「〜したい」「〜を直す」「〜を作る」のように、何が達成されれば終わりかを明確にします。

• ❌ 「コードを良くしたい」（曖昧）
• ✅ 「OrderService のレスポンス時間を 500ms 以下に短縮したい」（測れる）

「測れる動詞」を意識すると、Done when と自然に繋がります。

Context：文脈を Claude が必要なだけ渡す

Context には次のような情報を入れます。

• ファイルパス：@src/auth/login.ts のように @ 記法で明示するとフォーカスが当たる
• エラーログ：再現時のスタックトレースは丸ごと貼って良い
• 関連する仕様書：URL や該当箇所の見出し
• 再現手順：「ログイン → 5 分放置 → リロードでセッション切れ」など

過剰に渡すとコンテキストが膨らむので、Claude が判断するために最小限必要な情報を選ぶのがコツです。

Constraints：「やってはいけないこと」を書く

Constraints は本記事でいちばん効果的な要素です。次のようなフレーズが定番です。

• 「既存テストは壊さないで」
• 「動作は変えないで（リファクタリングのとき）」
• 「legacy/ フォルダは触らないで」
• 「新しい依存ライブラリは追加しないで」
• 「pnpm 環境で動かしてね（パッケージマネージャの指定）」

「やっていいこと」を網羅するより、「やっちゃダメ」を 1〜3 個書く方が圧倒的に効きます。

Done when：完了の判定基準

Done when には次のような機械的に判定できる条件を書くのが理想です。

• 「npm test が全件パスする」
• 「npm run build が成功する」
• 「期待出力 [1, 2, 3] と一致する」
• 「変更前後の差分が 50 行以内である」

「いい感じになる」「きれいになる」のような主観的な判定はやめて、Claude が自分で判定できる条件にしましょう。

🪜 段階的に依頼する

ひとことで：いきなり「全部実装して」と頼まず、調査 → 計画 → 実装 → 検証に分けると速くなります。

意外に思われるかもしれませんが、1 回のプロンプトで全部頼むより、4 段階に分けて頼むほうが結果的に速いことが多いです。各段階で人間が方針を確認できるため、後戻りが減るからです。

段階 1：探索

src/auth/ 配下を読んで、ログイン処理の責任分担を表で整理して。
ファイルは編集しないでね。

Claude にコードを読ませて構造把握を共有してもらいます。読むだけにすることで安全です。

段階 2：計画

セッション切れバグの修正計画を 3 案書いて、それぞれの影響範囲を比較して。
コードは編集しないで、Markdown で計画書を出して。

複数案を提示してもらい、人間が方針を選びます。Claude Code にはプランモードもあり、そちらを使うとさらに安全です。

段階 3：実装

案 2 で実装してね。
src/auth/session.ts と関連テストだけ編集対象。
変更前後の差分を見せてから書き換えて。

選んだ案だけを実装させます。スコープを「ファイル単位で」絞るのがコツです。

段階 4：検証

npm test を実行して、全件パスするか確認して。
失敗があれば原因を 1 文で要約して、修正案を提示してね。

検証も Claude に任せます。失敗時は原因の要約まで頼むと、人間の判断が早まります。

📝 タスク別プロンプトテンプレート 3 つ

ひとことで：コード理解・バグ修正・テスト追加の 3 つを、コピペで使える形にしました。

毎日の開発でよく出てくる 3 タスクを、4 要素入りのテンプレートにします。◯◯ の部分を埋めて使ってください。

コード理解テンプレート

[Goal] @◯◯（ファイル名）のロジックを説明したい。
[Context] とくに ◯◯ 関数の挙動と、それがどこから呼ばれているかを中心に。
[Constraints] ファイルは編集しないで、読み取りだけにしてね。
[Done when] Markdown 形式の説明と、呼び出し関係の図解（Mermaid 等）を出力。

新しいリポジトリやレガシーコードのキャッチアップにそのまま使えます。

バグ修正テンプレート

[Goal] バグ「◯◯」を修正したい。
[Context] 再現手順は ◯◯。エラーログは以下：
（ログを貼る）
[Constraints] 既存テストは壊さないこと。`legacy/` フォルダは触らない。
[Done when] まず失敗するテストを書いて、それが通るまで修正。npm test 全件パス。

「先に失敗するテストを書く」を入れることで、Claude が TDD（テスト駆動開発）的に動くようになり、修正の確証度が上がります。

テスト追加テンプレート

[Goal] ◯◯（ファイルパス）にテストを追加したい。
[Context] 既存の *.test.ts のスタイルに合わせる（jest + describe/it）。
[Constraints] モックは禁止。実装の挙動はそのまま動かして検証する。
[Done when] エッジケース（empty / null / 異常入力）3 つを含めて、npm test 全件パス。

「モック禁止」のような Constraints を強めに書くと、テストの質が上がります。プロジェクト方針に合わせて調整してください。

🔗 プロンプト設計と他機能の関係

ひとことで：プロンプトを「永続化」「コマンド化」「分担」する 3 つの拡張があります。

良いプロンプトが書けるようになると、次は「毎回書くのが面倒」という贅沢な悩みが出てきます。それぞれ Claude Code の別機能に繋がっています。

同じ指示を毎回打つ → CLAUDE.md に書いて永続化

「pnpm を使ってね」「テストは npm run test:unit で動く」のようなプロジェクト固有のルールは、CLAUDE.md に書いておけば毎セッション自動で読み込まれます。詳しくは CC-03 CLAUDE.md 完全ガイド。

何度も呼び出す → Skills（カスタムコマンド）化

「コードレビュー」「コミットメッセージ生成」のような繰り返し呼ぶプロンプトは、Skills として保存すれば /review のような短いコマンドで呼び出せます。詳しくは CC-06 スラッシュコマンド & スキル。

大量出力タスク → サブエージェントに委譲

「コード全体を読んでセキュリティ監査して」のようなメインのコンテキストを汚したくないタスクは、サブエージェントに任せるのが定石です。詳しくは CC-08 サブエージェント・並列作業。

チームで共有する → CLAUDE.md と Skills を Git で配布

CLAUDE.md も .claude/skills/ も Markdown ファイルなので、Git で共有できます。チーム全員が同じプロンプト資産を使える状態にすれば、レビュー基準やコーディング規約も自然に揃います。

📚 次に読む記事

プロンプト設計を覚えたら、次のステップは「安全に運用する」と「反復作業を仕組み化する」の 2 方向です。

• 許可ダイアログを賢く運用したい → パーミッションと安全設定ガイド（CC-05）
• 段階的依頼を実プロジェクトで試したい → 実践ワークフロー集（CC-04）
• プロのプロンプト集を覗きたい → プロのベストプラクティス完全集（CC-09）

CLAUDE.md にプロンプトを永続化するのは、テンプレートを「自分の語彙」に育てる第一歩です。気に入ったテンプレが見つかったら、まずプロジェクトの CLAUDE.md に書き写してみてください。