ai-docs

Prompting best practices

Properties1
tagsprompting, agents, context, tools, thinking, frontend

21 min read

一行要約

prompting の中核は「文脈の乏しい新入社員に説明するつもりで、明示的に書く」ことであり、最新モデルでは「足す prompting」より 旧世代向けに書いた過剰な指示を剥がす prompting のほうが重要になっている。

要点

この文書は3部構成であることが冒頭で明示されている。① モデル固有の差分 → ② 全モデル共通の技法 → ③ 旧世代からの移行。モデル固有の節（Fable 5 / Sonnet 5 / Opus 5 / Opus 4.8）は本体には書かれず、それぞれ別ページへのポインタになっている。

一般原則

明確かつ直接的に書く

Think of Claude as a brilliant but new employee who lacks context on your norms and workflows. Claude は、優秀ではあるがあなたの規範や仕事の流れを知らない新入社員だと考えよ。

Golden rule として次が挙げられている。

Show your prompt to a colleague with minimal context on the task and ask them to follow it. If they’d be confused, Claude will be too. そのタスクの前提をほとんど知らない同僚にプロンプトを見せ、その通りにやってもらえ。その人が戸惑うなら、Claude も戸惑う。

「above and beyond」な振る舞いが欲しいなら、曖昧なプロンプトから推測させずに明示的に要求する。

プロンプト
弱いCreate an analytics dashboard
強いCreate an analytics dashboard. Include as many relevant features and interactions as possible. Go beyond the basics to create a fully-featured implementation.

理由を書く（context を足す）

Claude is smart enough to generalize from the explanation. Claude は、その説明から一般化できるだけの賢さを備えている。

指示の背後にある動機を説明すると、Claude はそこから一般化する。

プロンプト
弱いNEVER use ellipses
強いYour response will be read aloud by a text-to-speech engine, so never use ellipses since the text-to-speech engine will not know how to pronounce them.

例を使う（few-shot / multishot）

例は出力の形式・トーン・構造を steer する最も信頼できる手段。例は relevant（実ユースケースに近い）/ diverse（edge case を含み、意図しないパターンを学習させない）/ structured（<example> タグで囲む、複数なら <examples>） であること。3〜5個が推奨。例そのものの relevance と diversity を Claude に評価させたり、追加生成させたりしてもよい。

XML タグで構造化する

指示・文脈・例・変数入力が混在するプロンプトでは、種類ごとに専用タグ（<instructions>、<context>、<input>）で囲むと誤読が減る。タグ名はプロンプト間で一貫させる。階層があるならネストする（<documents> の中に <document index="n">）。

role を与える

system prompt での role 指定は1文でも効果がある。

long context prompting（20k tokens 超）

  • 長い資料はプロンプトの先頭に置く。クエリ・指示・例より上。これは全モデルで性能が上がる

    Queries at the end can improve response quality by up to 30 percent in tests, especially with complex, multidocument inputs. テストでは、問い合わせを末尾に置くことで応答品質が最大30%向上した。特に複雑で、複数文書にまたがる入力でそうである。

  • 複数文書は <document> に <document_content> と <source> のサブタグを付けて構造化する
  • 引用で接地させる — タスクの前に、関連箇所を引用させてから作業させる

出力と書式

最新モデルは既に簡潔寄り（direct and grounded / conversational / less verbose）。そのためツール呼び出し後の要約を省くことがある。可視性が欲しいなら明示的に頼む。

例外: Claude Opus 5 は既定の応答が従来より長い。しかも effort を上下させても可視の応答長は安定して変わらない。簡潔さは prompt で明示的に要求すること。

書式の steer は4手

  1. 「するな」ではなく「せよ」で書く — Do not use markdown ではなく Your response should be composed of smoothly flowing prose paragraphs.
  2. XML の書式指示子を使う — Write the prose sections of your response in <smoothly_flowing_prose_paragraphs> tags.
  3. プロンプトの文体を出力の文体に合わせる — プロンプトから markdown を減らすと出力の markdown も減る
  4. 細かい要求は詳細なプロンプトで明示する

LaTeX: 最新モデルは数式で LaTeX を既定にする。プレーンテキストが欲しいなら明示的に禁止する。

prefill の廃止（重要な破壊的変更）

Claude 4.6 系および Claude Mythos Preview 以降、最後の assistant ターンへの prefill は非対応。送ると 400 エラー。移行先は以下。

prefill の用途移行先
出力形式の強制（JSON/YAML、分類）Structured Outputs、または enum フィールドを持つ tool
前置き（“Here is…”）の除去system prompt で直接指示 / XML タグ / structured outputs。漏れたら後処理で削る
不当な拒否の回避不要。user メッセージ内の明確な prompting で足りる
継続（中断された応答の再開）継続を user メッセージに移し、中断した末尾テキストを含める。UX 上問題なければリトライ
context の再注入従来 prefill で入れていたリマインダを user ターンに入れる。複雑な agentic system では tool 経由か compaction 時に注入

ツール使用

最新モデルは字義通りに指示に従う。 「can you suggest some changes」と書けば提案だけして実装しない。行動させたいなら Change this function to improve its performance. のように書く。

既定の積極性は <default_to_action> / <do_not_act_before_instructions> のどちらでも system prompt で振れる。

Claude Opus 4.5 / 4.6 は system prompt への反応が従来より強い。undertriggering 対策で書いた CRITICAL: You MUST use this tool when... のような強い言い回しは、いまや過剰発火の原因になる。Use this tool when... 程度に戻すのが修正手順。

並列ツール呼び出しは既定で行われるが、prompt で ほぼ100% まで引き上げられる（<use_parallel_tool_calls>）。逆に抑えることもできる。

thinking と推論

overthinking への対処（Claude Opus 4.6、特に高 effort）

  • 包括的な既定を、対象を絞った指示に置き換える — Default to using [tool] ではなく Use [tool] when it would enhance your understanding of the problem
  • over-prompting を削る — If in doubt, use [tool] は過剰発火する
  • 最後の手段として effort を下げる

adaptive thinking への移行

  • Claude 4.6 以降と Mythos Preview は thinking: {type: "adaptive"}。Claude が「いつ・どれだけ考えるか」を自分で決める。effort とクエリの複雑さの2要因で調整される
  • 社内評価では adaptive thinking が extended thinking を安定して上回る
  • budget_tokens による上限は Opus 4.6 / Sonnet 4.6 では動くが deprecated。Claude 4.7 以降では budget_tokens を設定すると 400 エラー
  • 既定値がモデルで違う: Opus 4.6〜4.8 / Sonnet 4.6 は thinking 省略でオフ。Opus 5 / Sonnet 5 は省略でオン（Opus 5 は effort high 以下でのみ無効化可）。Fable 5 / Mythos 5 は常時オン

thinking を活かす4点

  • 細かい手順より一般的な指示 — 「think thoroughly」のほうが、人が書いた step-by-step より良い推論になることが多い
  • multishot は thinking にも効く — few-shot 例の中で <thinking> タグを使うと、そのパターンを一般化する
  • thinking オフ時は手動 CoT がフォールバック（<thinking> / <answer> で分離）。ただし Opus 5 では内部 XML タグが可視出力に漏れることがあるので、effort を下げて thinking を残すほうが良い
  • 自己検証させる（Before you finish, verify your answer against [test criteria].）。Opus 5 は例外 — 指示なしでも自己検証するので、旧モデル向けの検証指示は over-verification を招く。移行時は書き換えではなく削除する

extended thinking 無効時、Claude Opus 4.5 は “think” という語とその変化形に特に敏感。consider / evaluate / reason through を使うとよい。

エージェント的システム

複数 context window にまたがるワークフロー（6原則）

  1. 最初の context window だけ別プロンプトにする — 1つ目で枠組み（テスト作成、セットアップスクリプト）を作り、以降は todo リストを回す
  2. テストを構造化形式で書かせる（例: tests.json）。「テストを消したり編集したりするのは許容されない。機能の欠落やバグにつながるから」と重要性を明示的に伝える
  3. QoL ツールを用意させる（init.sh など）。fresh context から再開するたびの作業重複を防ぐ
  4. compaction より新規 context window を検討する — 最新モデルはローカルファイルシステムから状態を復元するのが極めて得意。ただし開始手順は具体的に指示する
    • Call pwd; you can only read and write files in this directory.
    • Review progress.txt, tests.json, and the git logs.
    • Manually run through a fundamental integration test before moving on to implementing new features.
  5. 検証ツールを与える — 自律実行時間が伸びるほど、人のフィードバックなしに正しさを確認する手段が要る（Playwright MCP server、computer use など）
  6. context を使い切らせる — 「途中で切り上げるな、ただし未コミットの作業を大量に抱えたまま枯渇させるな」

状態管理

対象形式
構造化情報（テスト結果、タスク状態）JSON など構造化形式
進捗メモ自由記述テキスト
履歴とチェックポイントgit。最新モデルは複数セッションにまたがる状態追跡で git をうまく使う

context awareness: Sonnet 5 / 4.6 / 4.5 と Haiku 4.5 は残り context window（token budget）を自分で把握できる。compaction や外部ファイル保存を備えた harness を使っているなら、その旨を prompt に書く。書かないと Claude は限界が近いと判断して勝手に作業を切り上げようとすることがある。

自律性と安全性のバランス: Opus 4.6 は、指示がないと取り返しのつかない操作（ファイル削除、force push、外部サービスへの投稿）を実行しうる。可逆性と影響範囲で判断させ、破壊的操作の前に確認させるプロンプトが挙げられている。「障害に当たったとき、破壊的操作を近道として使うな（--no-verify で安全チェックを迂回しない、見慣れないファイルを作業中かもしれないのに捨てない）」まで含む。

subagent の統率: 最新モデルは指示なしでも subagent に委譲する。問題は過剰なほう。

Claude Opus 4.6 has a strong predilection for subagents and may spawn them in situations where a simpler, direct approach would suffice. Claude Opus 4.6 は subagent を強く好み、もっと単純で直接的なやり方で足りる場面でも subagent を立てることがある。

直接 grep すれば済む探索に subagent を立てる、が具体例として挙がっている。Opus 5 も同様の傾向。

over-engineering の抑制: Opus 4.5 / 4.6 は余計なファイル・不要な抽象・頼まれていない柔軟性を作りがち。抑制プロンプトが scope / documentation / defensive coding / abstractions の4観点で示されている。

The right amount of complexity is the minimum needed for the current task. 適切な複雑さの量とは、いま取り組んでいるタスクに必要な最小限である。

テストを通すことへの過剰適合の抑制: ハードコードや helper script による回避ではなく一般解を書かせる。「タスクが無理筋、またはテストが間違っているなら、回避せずに報告せよ」まで含めるのがポイント。

agentic coding での hallucination 抑制: <investigate_before_answering> — 開いていないコードについて推測しない、ファイルを参照されたら必ず読んでから答える。

能力別の tips

  • vision: Opus 4.5 / 4.6 は画像処理・データ抽出が改善。crop tool や agent skill を与えて「ズーム」させると画像 eval が一貫して向上する
  • frontend: 指示がないと “AI slop” 美学に収束する。typography / color & theme / motion / backgrounds の4観点で steer する

移行時の注意

  1. 望む振る舞いを具体的に書く
  2. 修飾語で品質と詳細度を上げる
  3. アニメーション等は明示的に要求する
  4. thinking 設定を adaptive + effort に更新する
  5. prefill から移行する
  6. anti-laziness prompting を弱める — 旧モデル向けの「もっと徹底的に」は過剰発火の原因

そのまま使える具体例

並列ツール呼び出しを最大化する:

<use_parallel_tool_calls>
If you intend to call multiple tools and there are no dependencies between the tool
calls, make all of the independent tool calls in parallel. Prioritize calling tools
simultaneously whenever the actions can be done in parallel rather than sequentially.
For example, when reading 3 files, run 3 tool calls in parallel to read all 3 files into
context at the same time. Maximize use of parallel tool calls where possible to increase
speed and efficiency. However, if some tool calls depend on previous calls to inform
dependent values like the parameters, do NOT call these tools in parallel and instead
call them sequentially. Never use placeholders or guess missing parameters in tool
calls.
</use_parallel_tool_calls>

over-engineering を抑える:

Avoid over-engineering. Only make changes that are directly requested or clearly
necessary. Keep solutions simple and focused:
 
- Scope: Don't add features, refactor code, or make "improvements" beyond what was
asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need
extra configurability.
 
- Documentation: Don't add docstrings, comments, or type annotations to code you didn't
change. Only add comments where the logic isn't self-evident.
 
- Defensive coding: Don't add error handling, fallbacks, or validation for scenarios
that can't happen. Trust internal code and framework guarantees. Only validate at system
boundaries (user input, external APIs).
 
- Abstractions: Don't create helpers, utilities, or abstractions for one-time
operations. Don't design for hypothetical future requirements. The right amount of
complexity is the minimum needed for the current task.

compaction 前提の harness で早期終了を防ぐ:

Your context window will be automatically compacted as it approaches its limit, allowing
you to continue working indefinitely from where you left off. Therefore, do not stop
tasks early due to token budget concerns. As you approach your token budget limit, save
your current progress and state to memory before the context window refreshes. Always be
as persistent and autonomous as possible and complete tasks fully, even if the end of
your budget is approaching. Never artificially stop any task early regardless of the
context remaining.

破壊的操作の前に確認させる:

Consider the reversibility and potential impact of your actions. You are encouraged to
take local, reversible actions like editing files or running tests, but for actions that
are hard to reverse, affect shared systems, or could be destructive, ask the user before
proceeding.
 
Examples of actions that warrant confirmation:
- Destructive operations: deleting files or branches, dropping database tables, rm -rf
- Hard to reverse operations: git push --force, git reset --hard, amending published commits
- Operations visible to others: pushing code, commenting on PRs/issues, sending
messages, modifying shared infrastructure
 
When encountering obstacles, do not use destructive actions as a shortcut. For example,
don't bypass safety checks (e.g. --no-verify) or discard unfamiliar files that may be
in-progress work.

subagent の乱用を抑える:

Use subagents when tasks can run in parallel, require isolated context, or involve
independent workstreams that don't need to share state. For simple tasks, sequential
operations, single-file edits, or tasks where you need to maintain context across steps,
work directly rather than delegating.

テストへの過剰適合を防ぐ:

Please write a high-quality, general-purpose solution using the standard tools
available. Do not create helper scripts or workarounds to accomplish the task more
efficiently. Implement a solution that works correctly for all valid inputs, not just
the test cases. Do not hard-code values or create solutions that only work for specific
test inputs. Instead, implement the actual logic that solves the problem generally.
 
Focus on understanding the problem requirements and implementing the correct algorithm.
Tests are there to verify correctness, not to define the solution. Provide a principled
implementation that follows best practices and software design principles.
 
If the task is unreasonable or infeasible, or if any of the tests are incorrect, please
inform me rather than working around them. The solution should be robust, maintainable,
and extendable.

hallucination を抑える:

<investigate_before_answering>
Never speculate about code you have not opened. If the user references a specific file,
you MUST read the file before answering. Make sure to investigate and read relevant
files BEFORE answering questions about the codebase. Never make any claims about code
before investigating unless you are certain of the correct answer - give grounded and
hallucination-free answers.
</investigate_before_answering>

複数文書の構造化:

<documents>
  <document index="1">
    <source>annual_report_2023.pdf</source>
    <document_content>
      {{ANNUAL_REPORT}}
    </document_content>
  </document>
  <document index="2">
    <source>competitor_analysis_q2.xlsx</source>
    <document_content>
      {{COMPETITOR_ANALYSIS}}
    </document_content>
  </document>
</documents>
 
Analyze the annual report and competitor analysis. Identify strategic advantages and recommend Q3 focus areas.

budget_tokens から effort への移行:

# Before: extended thinking with a manual budget (older models)
client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "..."}],
)
 
# After: adaptive thinking with effort
client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "..."}],
)

状態ファイルの持ち方:

// tests.json
{
  "tests": [
    { "id": 1, "name": "authentication_flow", "status": "passing" },
    { "id": 2, "name": "user_management", "status": "failing" },
    { "id": 3, "name": "api_endpoints", "status": "not_started" }
  ],
  "total": 200,
  "passing": 150,
  "failing": 25,
  "not_started": 25
}
// progress.txt
Session 3 progress:
- Fixed authentication token validation
- Updated user model to handle edge cases
- Next: investigate user_management test failures (test #2)
- Note: Do not remove tests as this could lead to missing functionality

原典で言及されている関連文書

未取得の派生リンク

グラフビュー

バックリンク