Claude Codeに指示を出したのに「返ってきたコードが使えない」そういう経験をしたエンジニアの多くは、指示の「内容」ではなく「形式」に問題があります。
「もう少し読みやすくして」「このロジックを改善して」という指示は、AIへの「お願い」であってタスク記述ではありません。
AIはあなたのシステム構成の歴史も、触れてはいけないテーブルも知らないからです。
ここでは、Context・Task・Constraints・Success Criteriaの4要素で構成する「構造化指示」の書き方を解説します。
コピーして使えるテンプレートと、実際の変換例を通じて、指示を再設計するための判断軸を提示します。
Claude Codeの結果が使えない理由は「指示の形式」にある
「リファクタリングして」が失敗する構造的な理由
「この関数をきれいにして」「もっと読みやすくリファクタリングして」こうした指示は、表現が曖昧なのではなく、AIが判断するために必要な情報がゼロという点で構造的に欠陥があります。
Claude Codeはあなたのシステムについて何も知りません。
そのコードが書かれた経緯も、依存している外部サービスも、絶対に変更してはいけないデータベーステーブルも、すべて推測するしかありません。
Context(文脈)を書かないということは、目隠しをした職人に「とりあえずここを直して」と頼むようなものです。
推測が当たることもありますが、技術的には正しくても実務では使えない変更が返ってくることも頻繁にあります。
これは「AIの限界」ではなく、指示の設計ミスです。
構造化指示とは何か？4要素の定義
「構造化指示」とは、AIに渡すタスクを4つの要素に分けて記述した、判断情報つきの指示文です。
以下の4要素で構成します。
- Context（背景・文脈）：このコードは何をするものか。どのシステムに属し、何と連携しているか
- Task（作業内容）：具体的に何をするか。動詞から始まる1文で書く
- Constraints（制約）：変更してはいけないもの。触れてはいけない範囲
- Success Criteria（完了条件）：AIが自分で検証できる、測定可能な完了基準
4要素がそろった指示は、AIの「推測」を「確信」に変えます。
結果として、修正ラウンドの回数が減り、使えるコードが1回目に返ってくる確率が大幅に上がります。
プロンプトだけの書き方は、上記の「Task」と「Constraints」だけの断片だけを書いている状態とも言えます。
Context（文脈）｜AIの「推測」を「確信」に変える背景情報の書き方
4要素のなかで最も効果が大きいのがContextです。
同時に、最も省略されやすい要素でもあります。
Contextを省くと何が起きるか
次のケースを見てください。
「APIエンドポイントを高速化してリファクタリングして」という指示を出した場合、Claude Codeはルーティング構造を整理し、処理を分散させ、確かに「高速になりうる形」に書き直します。
しかし結果として、エンドポイントを参照していた5つの別モジュールが動作しなくなることがあります。
Claude Codeが間違えたのではありません。「ルーティング構造を変えてはいけない」というContextがなかったために、変更対象として認識されてしまったのです。
Contextに含める4つの情報
Contextの段落には、以下の4点を含めてください。
- このコードの役割：何をするファイル・モジュールか（例：Stripeウェブフックを受信して注文テーブルに書き込む決済処理モジュール）
- 接続先：依存している外部サービス、データベース、他モジュール（例：ordersテーブルはリードレプリカであり書き込みは不可）
- 経緯・複雑さの背景：なぜ今の形になっているか。レガシーな理由がある場合は明記（例：2021年に実装、当時の仕様に合わせた構造が残存）
- トラフィック・業務上の重要度：1日500件処理・本番稼働中など（AIが「大胆に変えても問題ない」と判断するのを防ぐ）
3文のContextが、3回の修正ラウンドをなくします。
Task・Constraints・Success Criteria｜残り3要素の設計方法
Taskは「動詞から始まる」1文で書く
Taskは作業内容の定義であり、目標の説明ではありません。
- NG：「読みやすくなるように改善してほしい」
- OK：「process_webhook関数（現在180行）を、各関数50行以内に分割する」
「〜になるように」という表現はAIに解釈を委ねます。
「〜する」という動詞起点の記述は、AIが迷わずに実行できるタスク定義になります。
Constraintsは「触れてはいけない範囲」を先に列挙する
AIコーディングで問題が起きる最大の原因は、制約の未指定です。
Constraintsは「やること」ではなく「やってはいけないこと」のリストとして書きます。
設計するときに考えるべき制約カテゴリは4つです。
- インターフェース制約：関数シグネチャ、APIの入出力仕様、DBスキーマ（他モジュールが依存しているため変更不可）
- 依存関係制約：ライブラリバージョン、互換性要件（例：Stripeライブラリのバージョンは現行を維持する）
- スコープ制約：明らかに問題があっても触れてはいけない範囲（例：DBへの書き込みロジックは変更しない）
- スタイル制約：チームの命名規則、コーディング規約
Constraintsを書く目的は「AIを縛る」ことではなく、AIが「ここは変えてよい範囲」を正確に把握できるようにすることです。
Success Criteriaは「AIが自分で検証できる」条件にする
「テストスイートが通ること」をSuccess Criteriaに含めると、Claude Codeはテストを実行し、通るまで反復します。
「コードがきれいになること」を書いても、AIは評価指針を持ちません。
良いSuccess Criteriaの3条件は次のように考えられます。
- 測定可能：「全関数50行以内」「bare exceptをゼロにする」など数値で表現できる
- 検証可能：AIが実行・確認できる（テスト実行、lintチェックなど）
- タスク規模に比例：小規模タスクは2〜3項目、複雑なタスクは5〜6項目まで
Success Criteriaのない指示は、評価をあなた自身が行うことになります。
構造化指示の目的のひとつは、完了判断をAIに委ねることです。
構造化指示テンプレートと変換例
構造化指示テンプレート
以下を書き換えて使用してください。
- Context：このコードの役割・接続先・実装経緯・トラフィックや業務上の重要度
- Task：動詞から始まる具体的な作業内容（1文）
- Constraints：
- 変更してはいけないもの①
- 変更してはいけないもの②
- 遵守しなければならないスタイル・仕様
- Success Criteria：
- 測定可能な完了条件①
- 測定可能な完了条件②
- AIが自分で検証できるテスト・チェック
「お願い」→「構造化指示」変換例
実際に変換した比較です。
変換前（お願い）：
「決済処理モジュールをきれいにリファクタリングして」
変換後（構造化指示）：
- Context：src/payments/processor.py。Stripeウェブフックをprocessしてordersテーブルへ書き込む決済処理モジュール。2021年実装。1日約500件処理、本番稼働中。
- Task：process_webhook関数（現在180行）を読みやすく分割する。bare exceptを個別の例外型に置き換える。
- Constraints：
- 関数シグネチャは変更しない（他モジュールが依存）
- DBへの書き込みロジックは変更しない
- Stripeライブラリのバージョンは現行を維持する
- Success Criteria：
- 全関数50行以内
- bare exceptがゼロになる
- 既存テストスイートが全件通過する
「お願い」の指示でも何かは返ってきます。
ただしきちんと動作するコードが返ってくる確率は、構造化指示に比べて大幅に低くなります。
修正ラウンドが2〜3回発生することが一般的です。※一般的なAIコーディングツール利用者の実務感覚に基づく
構造化指示を個人の習慣で終わらせず、チームの標準にすると、効果は複数の方向に広がります。
ROI(投資利益率)が高いチームは、APIアクセス数やセッション使用率が多いチームではなく、構造化指示を書くことをチームの規範にしたチームとも言えます。
まとめ｜試すための3つの判断軸
構造化指示を始めるにあたって、最初から完璧に4要素を埋めようとする必要はありません。次のタスクで試すときに、以下の3点を確認してください。
- 「AIはこのコードが何と連携しているか知っているか」→知らなければContextを1文追加します
- 「絶対に変えてほしくない箇所を指定したか」→していなければConstraintsに1行追加します
- 「AIが自分でこのタスクの完了を判断できるか」→できなければSuccess Criteriaに測定可能な条件を1つ追加します
1回の構造化指示の作成に5分かかります。修正ラウンド1回を省けるなら、その5分は確実に回収できます。
「お願い」をやめて構造化指示を書く習慣が定着した時点で、Claude Codeの使い方は変わります。
