Claude Prompting Best Practices

清楚且直接（Be Clear and Direct）

把 Claude 當作一位聰明但缺乏脈絡的新員工。就像你不會給新員工模糊的指示一樣，你也不應該給 Claude 模糊的 prompt。

Claude 會嚴格遵照字面意思回應。如果你要求它「列出要考慮的因素」，它會列出但不會執行分析。如果你要求它做分析，就直接說：「分析以下數據並提供建議。」

// 不好：模糊
"告訴我關於效能優化的事"

// 好：清楚直接
"分析以下 Python 函式的效能瓶頸，
 並提供 3 個具體的優化建議，
 每個建議包含修改前後的程式碼對比。"

加入背景脈絡（Provide Context）

解釋「為什麼」比僅僅告訴「做什麼」更重要。Claude 會從你的解釋中泛化（generalize），理解你真正想要什麼。就像跟實習生解釋工作目的可以幫助他們做更好的決策。

// 沒有脈絡
"把這段文字翻譯成日文"

// 有脈絡
"把這段文字翻譯成日文。
 這是一篇技術部落格的摘要，
 目標讀者是日本的軟體工程師，
 請使用正式但不過於生硬的語氣，
 技術術語保留英文原文並加上日文解釋。"

有效使用範例（Use Examples Effectively）

提供 3-5 個 few-shot examples 是最有效的方式之一。範例應該具備三個特性：相關（Relevant）、多樣（Diverse）、結構化（Structured）。使用 <example> 標籤包裝。

<examples>
  <example>
    <input>使用者問：「我的訂單在哪裡？」</input>
    <output>
      分類：物流查詢
      優先級：中
      建議回覆：感謝您的詢問！請提供您的訂單編號，
      我會立即為您查詢最新的物流狀態。
    </output>
  </example>
  <example>
    <input>使用者問：「這個產品有沒有紅色的？」</input>
    <output>
      分類：產品諮詢
      優先級：低
      建議回覆：感謝您的興趣！讓我為您確認這款產品
      的可用顏色選項。
    </output>
  </example>
</examples>

XML 標籤結構化（Use XML Tags）

XML 標籤幫助 Claude 區分 prompt 的不同部分：指令、脈絡、輸入資料、輸出格式。常用標籤包括 <instructions>、<context>、<input>、<output_format>。

<instructions>
你是一位資深程式碼審查員。請審查以下程式碼，
找出潛在的安全漏洞和效能問題。
</instructions>

<context>
這是一個 Node.js Express API 的認證中間件，
部署在生產環境中。
</context>

<input>
{{code_to_review}}
</input>

<output_format>
以 JSON 格式輸出：
{
  "severity": "high|medium|low",
  "issues": [...],
  "recommendations": [...]
}
</output_format>

賦予角色（Assign a Role）

在 system prompt 中設定角色是最簡單卻最有效的技巧之一。一句話就能讓 Claude 的回應方式完全不同。角色設定會影響 Claude 的語氣、專業程度、回應格式和思考方式。

// System prompt
"你是一位有 15 年經驗的 Kubernetes 架構師，
 專精於大規模微服務部署和效能調優。
 你傾向實用主義而非過度工程化，
 會先確認問題再提供解決方案。"

長文脈絡處理（Long Context）

當你有大量文件要給 Claude 處理時，把長文放在 prompt 的上方可以提升回應品質（可提升約 30%）。用 XML 標籤包裝文件，並要求 Claude 引用原文來佐證其回答。

<documents>
  <document id="1" title="架構設計文件">
    {{architecture_doc}}
  </document>
  <document id="2" title="API 規格">
    {{api_spec}}
  </document>
</documents>

<instructions>
根據以上文件回答問題。
回答時請引用文件中的相關段落作為佐證，
格式為 [Doc X, Section Y]。
如果文件中沒有足夠的資訊，請明確說明。
</instructions>

<question>{{user_question}}</question>

模型自我認知（Model Self-Identification）

你可以在 system prompt 中指定 Claude 如何識別自己。如果你是在建構一個產品，可以告訴 Claude 正確的模型名稱字串，讓使用者知道他們在跟哪個模型互動。

// System prompt 中加入模型識別
"You are powered by the model named Opus 4.6.
 The exact model ID is claude-opus-4-6.
 When users ask which model they are talking to,
 respond with this information."

Claude 4.6 的輸出特性

Claude 4.6 的輸出風格更加簡潔、直接、口語化。它不會像舊版本那樣冗長或過度禮貌。如果你發現回應太短，可以明確要求更詳細的回答。

控制輸出格式的 4 種方式

"回覆時使用簡短段落，每段不超過 3 句話。
 使用項目符號列出具體步驟。
 技術術語首次出現時附上簡短解釋。"

"請用以下格式回覆：
<analysis>
  <summary>一句話摘要</summary>
  <findings>詳細發現</findings>
  <action_items>建議行動</action_items>
</analysis>"

LaTeX 控制

Opus 4.6 預設在數學相關內容中使用 LaTeX 格式。如果你的應用不支援 LaTeX 渲染，可以明確要求 Claude 使用純文字。

// System prompt 加入
"Do not use LaTeX formatting for mathematical expressions.
 Use plain text Unicode symbols instead.
 For example, use x² instead of $x^2$,
 and use √ instead of $\sqrt{}$."

文件建立能力

Claude 擅長建立各類文件：簡報（HTML slides）、動畫（SVG/CSS animations）、視覺化文件（圖表、流程圖）。特別是在 Artifacts 或程式碼輸出模式下，可以產出完整的互動式文件。

Prefilled Responses（已棄用）

明確叫 Claude 行動，不只建議

當 Claude 有工具可用時，你需要明確告訴它去使用工具，而不是只描述該怎麼做。一個常見的問題是：Claude 會告訴你「你可以使用 X 工具來做這件事」而不是直接使用它。

// 不好：Claude 可能只描述步驟
"幫我查一下這個問題"

// 好：明確要求行動
"使用 search 工具搜尋相關文件，
 然後使用 read_file 工具閱讀找到的檔案，
 最後給我分析結果。"

default_to_action vs do_not_act_before_instructions

這兩個 XML 標籤用來控制 Claude 的主動性等級：

<default_to_action>
When the user asks to fix a bug,
immediately use the tools to
investigate and fix it.
Do not ask for permission first.
</default_to_action>

<do_not_act_before_instructions>
Before deleting any files or making
destructive changes, always explain
what you plan to do and wait for
explicit user confirmation.
</do_not_act_before_instructions>

Opus 4.5/4.6 對 System Prompt 更敏感

Opus 4.5 和 4.6 對 system prompt 的指令更加敏感和遵從。這意味著你在 system prompt 中放的規則會被更嚴格地執行。好處是行為更可控，但也意味著模糊或矛盾的指令會造成更大的問題。

平行 Tool Calling

當多個 tool calls 之間沒有依賴關係時，Claude 可以同時發出多個 tool calls，大幅提升效率。你可以在 system prompt 中提示 Claude 利用這個能力。

"When multiple tool calls are independent
 of each other, make them in parallel
 within the same response.

 For example, if you need to read 3 files
 that don't depend on each other,
 issue all 3 read_file calls at once
 instead of sequentially."

Opus 4.6 的前期探索

Opus 4.6 在回答之前會做更多的前期探索（upfront exploration）。它會先思考問題的各個面向，然後再給出回答。這讓它的回答通常更全面、更有深度，但也意味著回應時間可能更長。

Adaptive Thinking 取代 Extended Thinking

在 Claude 4.6 中，Adaptive thinking 取代了之前的 Extended thinking。主要差異在於：Adaptive thinking 會根據問題的複雜度自動調整思考的深度和長度，不再需要固定的 budget token。

// 使用 Adaptive thinking
const response = await anthropic.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 16000,
  thinking: {
    type: "enabled",
    // 不再需要 budget_tokens
    // 模型會自動調整思考深度
  },
  messages: [{
    role: "user",
    content: "分析這段程式碼的時間複雜度..."
  }]
});

effort 參數控制思考深度

effort 參數讓你控制 Claude 投入多少思考在一個問題上。這在批量處理或延遲敏感的場景中特別有用。

// 低 effort — 簡單分類任務
const response = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 256,
  thinking: {
    type: "enabled",
    effort: "low"  // 快速回應
  },
  messages: [{ role: "user", content: "這封 email 是垃圾郵件嗎？" }]
});

// 高 effort — 複雜推理任務
const response = await anthropic.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 16000,
  thinking: {
    type: "enabled",
    effort: "high"  // 深度思考
  },
  messages: [{ role: "user", content: "證明這個演算法的正確性..." }]
});

減少過度思考

有時 Claude 會過度思考簡單的問題。以下是一些減少過度思考的技巧：

• 使用低 effort 參數
• 在 prompt 中明確說「直接回答，不需要解釋推理過程」
• 給出明確的輸出格式，減少 Claude 思考要如何呈現的時間
• 對於是/否問題，要求只回答「是」或「否」加一句簡短理由

"Answer directly and concisely.
 Do not over-explain or hedge.
 If the answer is simple, keep it simple.
 Only elaborate if the question genuinely
 requires detailed analysis."

Long-horizon Reasoning 與狀態追蹤

在 agentic 場景中，Claude 需要跨越多個步驟維持推理連貫性。關鍵是幫助 Claude 追蹤它在長任務中的進度和狀態。

"Before each action, briefly summarize:
 1. What you've done so far
 2. What you're about to do and why
 3. What remains after this step

 This helps maintain coherence across
 long multi-step tasks."

Context Awareness 與 Multi-window Workflows

在多視窗工作流程中（例如同時處理多個檔案或多個對話），確保 Claude 清楚知道目前的脈絡。使用明確的標記來區分不同的工作區。

狀態管理最佳實踐

對於長期運行的 agent 任務，使用持久化的狀態管理：

{
  "task": "migrate-database",
  "current_step": 3,
  "total_steps": 7,
  "completed": [
    "backup_created",
    "schema_updated",
    "data_migrated"
  ],
  "remaining": [
    "verify_data",
    "update_indexes",
    "test_queries",
    "switch_traffic"
  ]
}

"After completing each major step,
 create a git commit with a
 descriptive message. This serves
 as a checkpoint you can revert
 to if something goes wrong."

平衡自主性和安全性

在 agentic 系統中，你需要在自主性（讓 Claude 獨立完成任務）和安全性（防止破壞性操作）之間取得平衡。建議的方法是：

• 讀取操作：完全自主（搜尋、讀檔、查詢）
• 寫入操作：自主但會通知（建立檔案、編輯程式碼）
• 破壞性操作：必須等待確認（刪除檔案、git force push、修改生產環境）
• 外部操作：必須等待確認（傳送訊息、建立 PR、部署）

研究與資訊收集

Agent 系統最強大的能力之一是研究和資訊收集。指導 Claude 使用廣度優先的搜尋策略，先廣泛搜尋再深入。

"When investigating a problem:
 1. Start broad: search for the error message,
    check related files, look at recent changes
 2. Form hypotheses based on initial findings
 3. Test hypotheses one at a time
 4. Document your findings as you go
 5. If stuck, try a completely different angle

 Do NOT tunnel-vision on the first hypothesis."

Subagent Orchestration

Claude 4.6 原生支援 subagent orchestration（產生子 agent 來處理子任務）。但要注意：4.6 可能會過度使用 subagent，在不需要的情況下也產生子 agent。

Prompt Chaining（自我修正模式）

Prompt chaining 是將一個大任務拆解成多個步驟，每一步的輸出成為下一步的輸入。自我修正模式是一種特殊的 chaining，讓 Claude 檢查自己的輸出並修正錯誤。

// Step 1: 生成程式碼
const codeResponse = await generateCode(task);

// Step 2: 自我審查
const reviewResponse = await anthropic.messages.create({
  model: "claude-opus-4-6",
  system: `Review the following code for bugs,
    security issues, and edge cases.
    Be critical and thorough.`,
  messages: [{
    role: "user",
    content: `Review this code:\n${codeResponse}`
  }]
});

// Step 3: 根據審查修正
const fixedCode = await anthropic.messages.create({
  model: "claude-opus-4-6",
  messages: [{
    role: "user",
    content: `Original code:\n${codeResponse}\n\n
     Review feedback:\n${reviewResponse}\n\n
     Fix all identified issues.`
  }]
});

常見問題與解決方法

"ALWAYS prefer editing existing files.
 NEVER create new files unless absolutely
 necessary. Before creating a file,
 check if an existing file can be modified."

"Prefer simple, pragmatic solutions.
 Do not over-engineer or add unnecessary
 abstractions. Solve the problem at hand,
 not hypothetical future problems."

"Never hardcode values like URLs, API keys,
 file paths, or configuration values.
 Use environment variables, config files,
 or constants defined at the top of the file."

"If you are unsure about something,
 say so explicitly. Do not guess or
 fabricate information. It's better to
 say 'I'm not certain about X' than to
 provide incorrect information."

Vision 能力提升

Claude 4.6 的視覺理解能力顯著提升。它可以更準確地理解圖表、截圖、UI mockups。一個實用的技巧是使用 crop tool：當圖片很大或細節很多時，裁切出你關注的區域可以顯著提升辨識準確度。

// 提升 Vision 準確度的技巧：
// 1. 提供明確的圖片描述上下文
"這是一張 Grafana dashboard 的截圖，
 顯示過去 24 小時的 CPU 使用率。
 請分析趨勢並指出異常時段。"

// 2. 使用裁切聚焦
"我已裁切出圖表中 14:00-18:00 的區段，
 請仔細分析這段時間的 spike 原因。"

// 3. 多圖比較
"以下兩張截圖分別是部署前後的效能指標，
 請比較差異並評估部署影響。"

Frontend Design — 避免 AI Slop

Claude 可以生成完整的前端程式碼，但預設的美學傾向可能產出「AI slop」風格（過度使用漸層、圓角、emoji、千篇一律的設計）。使用 <frontend_aesthetics> 標籤來指定設計風格。

<frontend_aesthetics>
Design style: Clean, minimal, professional.
Do NOT use:
- Excessive gradients or shadows
- Rounded corners everywhere
- Generic stock-photo aesthetics
- Emojis as decorative elements
- Purple/blue gradient backgrounds

DO use:
- Clear typography hierarchy
- Adequate whitespace
- Subtle, purposeful animations
- A cohesive, restrained color palette
- Real content, not "Lorem ipsum"
</frontend_aesthetics>

遷移到 4.6 的 6 個重點

Sonnet 4.5 → Sonnet 4.6 遷移指南

從 Sonnet 4.5 遷移到 4.6 時的關鍵調整：

// Sonnet 4.5（舊）
const response = await anthropic.messages.create({
  model: "claude-sonnet-4-5-20250514",
  max_tokens: 16000,
  thinking: {
    type: "enabled",
    budget_tokens: 10000  // 固定 budget
  },
  messages: [...]
});

// Sonnet 4.6（新）
const response = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 16000,
  thinking: {
    type: "enabled",
    effort: "medium"  // 使用 effort 參數
  },
  messages: [...]
});

Extended Thinking → Adaptive Thinking 遷移

遷移步驟：

1. 移除 budget_tokens 參數
2. 改用 effort 參數（low / medium / high）
3. 測試關鍵使用案例，確認思考深度是否適當
4. 對於延遲敏感的任務，從 low 開始逐步提升
5. 監控 token 使用量和回應品質的變化