---
title: "提升 Claude Code 產出完整度的提示詞 6 原則"
locale: zh-hant
category: tutorial
category_name: "教學課程"
translation_status: reviewed
license: cc_by
author: "injoys"
source_url: https://injoys.com/en/articles/claude-code-prompt-six-principles-and-templates
published_at: 2026-08-23T02:30:01+09:00
---

# 提升 Claude Code 產出完整度的提示詞 6 原則

> 說明如何不只要求 Claude Code 產生程式碼，而是以結構化方式提供背景、輸出契約、例外處理與驗證標準。另提供可直接套用於新代理程式開發、功能新增及錯誤修正的提示詞範本。

## Key Points

- 1. 開始作業前，將使用者背景、待解決的問題、成功標準及技術限制整理於同一份文件中。
- 2. 以具體的輸出契約指定產出的檔案結構、資料格式、允許範圍及完成條件。
- 3. 定義外部 API 失敗、空白結果、重複資料及驗證錯誤等可預期的例外與應對政策。
- 4. 依照計畫審查、最小功能實作、自動化測試及功能擴充的順序拆分作業，並在每個階段確認結果。
- 5. 不提出模糊的重作要求，而是提供失敗案例與可衡量的改善目標，並依最終驗收條件進行驗證。

像 Claude Code 這類程式設計代理不只是產生一小段程式碼的工具，而是能探索儲存庫、修改多個檔案，以及執行測試與命令的工作環境。因此，成果品質與其說取決於文字看起來多麼合理，不如說更大程度取決於**工作範圍與驗證方法定義得多麼明確**。

好的提示詞不是冗長的說明文，而是可執行的工作規格。除了要製作什麼之外，還必須傳達為何需要、應遵守哪些條件、如何處理失敗，以及通過哪些條件才算完成。

## 首先要區分：提示詞與執行環境

氛圍式程式設計是一種以自然語言傳達意圖，並由 AI 代理負責實作的協作方式。然而，以自然語言提出要求這件事本身，並不能保證程式碼的正確性或營運穩定性。

Claude Code 工作會同時受到以下要素影響。

| 要素 | 作用 | 提示詞中要確認的內容 |
|---|---|---|
| 使用者要求 | 傳達目標與變更範圍 | 目的、優先順序、禁止事項 |
| 儲存庫脈絡 | 提供既有結構與規則 | 框架、執行命令、相關檔案 |
| `CLAUDE.md` | 提供反覆套用的專案指引 | 程式設計規則、測試方法、目錄慣例 |
| 工具權限 | 控制檔案修改與命令執行的允許範圍 | 可執行的命令，以及需要事先確認的工作 |
| 外部連線 | 存取 API、資料庫、MCP 伺服器等 | 驗證方式、信任邊界、失敗政策 |
| 驗證程序 | 判斷結果是否符合需求 | 測試、靜態分析、手動確認項目 |

並非只要把提示詞寫好，就能解決所有問題。例如，Claude Code 雖然能建立排程執行程式碼，但若要在電腦關機時仍能執行工作，就需要另行準備伺服器、CI 服務或作業系統排程器。電子郵件寄送若沒有實際供應商的驗證資訊與寄送權限，也無法完成。

## 原則 1. 先說明背景、目的與限制

若只提出成果名稱，例如「幫我建立新聞蒐集代理」，代理就必須猜測使用者、資料來源、執行環境與成功標準。即使同樣是新聞蒐集器，業務開發人員、投資人、大學校報編輯所需要的來源與分類標準也不相同。

### 不充分的要求

```text
幫我建立 AI 新聞蒐集代理。
```

### 改善後的要求

```text
我是 IT 新創公司的業務開發人員。
我想在每天開始工作前，快速查看 AI、雲端、金融科技領域中
會影響業務合作或產品策略的新聞。

目標：
- 依照指定關鍵字蒐集最新的候選文章。
- 移除 URL 相同的文章，以及標題相似的重複文章。
- 以是否需要在 3 個月內做出產品或合作決策為標準，
  將影響程度分類為高、中、低。
- 將結果製作成韓文電子郵件簡報。

限制：
- 維持目前儲存庫的 Python 版本與套件管理方式。
- 新增函式庫之前，先說明必要性與替代方案。
- 不要將 API 金鑰與電子郵件密碼記錄在程式碼或日誌中。
- 實際寄送郵件前，只產生預覽檔案。

請先調查儲存庫結構與執行方式，再提出實作計畫。
對於未知的環境資訊，不要猜測，請整理成問題清單。
```

良好的背景資訊包含以下四項。

1. **使用者與使用情境：** 誰會在何時用於何種決策
2. **目標：** 不只是撰寫程式碼，而是要解決什麼問題
3. **限制：** 必須維持哪些技術、安全規則、成本或時間上限
4. **非目標：** 本次變更明確排除哪些功能

寫明非目標可以防止範圍無限擴大。例如，若明定「此階段不包含排程執行與實際寄送電子郵件」，就能先穩定驗證蒐集與分類邏輯。

## 原則 2. 將所需的輸出格式制定成輸出契約

「用電子郵件排版得好看一點再寄出」每個人的解讀都不同。輸出格式不應只展示範例，還應一併定義必填欄位、允許值、缺漏處理方式與排序順序。

```text
電子郵件主旨：
[新聞簡報] {YYYY-MM-DD} 今日重點新聞

內文的文章格式：
1. {標題}
摘要：{韓文 1～2 句}
影響程度：{高|中|低}
判定理由：{1 句}
來源：{媒體名稱}
連結：{原文 URL}

排序規則：
1. 依影響程度由高至低
2. 影響程度相同時，依發布時間由新至舊

底部統計：
- 文章總數
- 各影響程度的文章數
- 沒有搜尋結果的關鍵字

限制：
- 摘要中不得捏造原文沒有的數字或主張。
- 若無法確認日期，不要推測日期，標示為「無法確認」。
- 沒有連結的項目不納入最終簡報。
```

若需要在程式之間傳遞結果，最好要求同時提供供人閱讀的範例，以及 JSON 結構描述或型別定義。

```json
{
  "title": "string",
  "summary": "string",
  "impact": "high | medium | low",
  "reason": "string",
  "source": "string",
  "url": "absolute URL",
  "published_at": "ISO 8601 string | null"
}
```

輸出契約不只包含格式，也包含語意。如果沒有判定 `impact: high` 代表什麼的標準，即使 JSON 語法正確，分類結果也可能不一致。

## 原則 3. 明確指定例外情況與復原政策

營運程式碼的完整度，與其說體現在正常路徑，不如說體現在失敗路徑。提示詞應一併寫明可預期的失敗、是否可重試、需要通知使用者的條件，以及不得記錄的資訊。

| 例外情況 | 建議政策範例 |
|---|---|
| 沒有搜尋結果 | 跳過該關鍵字，並記錄於最終統計 |
| 暫時性網路錯誤 | 以固定間隔進行有限次數的重試 |
| 驗證失敗 | 不要重試，立即中止並提示檢查設定 |
| API 使用量限制 | 遵守回應中的等待指示，禁止無限重試 |
| 重複文章 | 根據正規化後的 URL 與標題相似度移除 |
| 格式錯誤的資料 | 保留原始資料，只隔離該項目 |
| 郵件寄送失敗 | 重試後仍失敗時，發出替代通知或記錄失敗狀態 |
| 部分成功 | 分別回報成功結果與失敗項目 |

可以像下面這樣具體要求政策。

```text
請將網路逾時視為可重試的錯誤。
重試之間需保留等待時間，若超過最大次數，則僅將該來源標記為失敗。
驗證錯誤與錯誤要求不會因重複執行而解決，因此請立即中止。

所有錯誤日誌都要留下時間、工作階段、來源與錯誤類型，
但不要記錄 API 金鑰、完整電子郵件地址、驗證標頭或文章全文。
請透過程序結束狀態區分全部成功、部分成功與全部失敗。
```

「重試三次」或「等待 5 秒」這類數值沒有普遍適用的標準答案。應根據外部服務的官方限制、工作的急迫性與重複執行風險，在專案中決定。付款或訊息寄送等具有副作用的工作，若在沒有冪等性保障的情況下自動重試，可能造成重複處理。

## 原則 4. 依照計畫、最小實作、驗證的順序漸進開發

若一次連接多個外部服務與自動執行機制，就很難釐清錯誤原因。將實作拆分成小型驗證單位，就能確認每個階段的輸入與輸出。

### 建議進行順序

1. 調查儲存庫結構、相關檔案與執行命令。
2. 在變更程式碼前，要求提出計畫與會受影響的檔案。
3. 使用一個關鍵字與固定的範例資料實作蒐集功能。
4. 分別測試重複移除與影響程度分類。
5. 電子郵件不實際寄送，改以本機預覽進行驗證。
6. 測試通過後，再新增實際供應商整合與排程執行。

第一次要求可以限制如下。

```text
現在只執行第 1 階段。
請調查儲存庫並回報以下內容。
- 目前應用程式的進入點
- 相關模組與測試檔案
- 使用的套件管理與測試命令
- 預計需要變更的檔案
- 實作前需要決定的問題

目前不要修改檔案。
```

檢視計畫後，再縮小變更範圍進行實作。

```text
請只實作已核准計畫中的新聞蒐集與重複移除功能。
不要新增分類、電子郵件寄送與排程執行。
請確保能以固定的測試資料執行，
並在最後摘要說明修改的檔案與執行的測試結果。
```

如果 Claude Code 環境可以使用計畫專用模式，就能在探索與設計階段加以運用。但計畫看似合理，不代表實作就正確，因此後續仍必須進行實際測試與程式碼檢視。

## 原則 5. 透過失敗案例與數值提供回饋

「結果不太好」、「效能很慢」、「分類錯了」很難用來決定修改方向。必須傳達目前狀態、預期狀態、重現輸入，以及可接受的變更範圍。

### 長度修改要求

```text
目前電子郵件內文產生約 3,000 字。
為了能在行動裝置上快速閱讀，我想縮短至 500 字以內。
請將每篇文章的摘要限制為 1～2 句，並保留判定理由。
請將原文 URL 連結到標題，移除獨立的連結行。
保留底部統計。
```

### 分類標準修改要求

```text
10 筆測試資料中有 8 筆被分類為「高」。
請將長期技術展望或一般產品介紹分類為「低」。
只有在有具體依據顯示 3 個月內必須改變價格、產品路線圖、
法規因應或合作決策時，才能分類為「高」。

在附加案例中，A 與 B 的正確答案是高，C 的正確答案是低。
請修改分類規則，並將這些案例新增為迴歸測試。
```

### 效能修改要求

```text
相同範例輸入目前的平均執行時間約為 45 秒。
目標是在相同環境中控制於 30 秒以內。
請先測量各階段的時間並顯示瓶頸。
不要移除結果準確度與錯誤處理，
請比較改善方案的效果與風險，再從最小的變更開始套用。
```

效能數值只有在測量環境與輸入資料相同時才能比較。不要只憑一次執行結果判斷已有改善，還必須一併固定測量方法、樣本與快取狀態。

## 原則 6. 依工作類型使用提示詞範本

### 建立新代理的範本

```text
[角色與情境]
我是{職業/角色}，希望解決{問題情境}。
此結果將由{使用者或後續系統}使用。

[目標]
{必須達成的結果與成功標準}

[執行觸發條件]
{手動執行、事件、排程時間等}

[輸入]
- 資料來源：{檔案/API/資料庫}
- 必填欄位：{欄位清單}
- 驗證方式：{環境變數或祕密管理方式}

[處理邏輯]
1. {步驟 1}
2. {步驟 2}
3. {步驟 3}

[輸出契約]
{檔案格式、結構描述、範本、排序與缺漏規則}

[例外處理]
{空結果、逾時、驗證錯誤、部分失敗政策}

[限制與非目標]
- 必須維持的技術：{項目}
- 禁止事項：{項目}
- 本次工作排除的功能：{項目}

[驗證]
- 必須通過的測試：{項目}
- 完成報告中應包含的內容：變更檔案、執行命令、測試結果、剩餘風險

請先調查儲存庫並提出實作計畫。
對於未知資訊，不要猜測，請提出問題。
```

### 新增既有功能的範本

```text
請在既有的{代理或模組名稱}中新增{新功能}。
新功能必須在{既有步驟 A}之後、{既有步驟 B}之前執行。

詳細邏輯：
- {條件與處理規則}
- {輸入輸出格式}
- {失敗時的動作}

維持條件：
- 不變更既有公開介面與設定格式。
- 保留所有既有測試。
- 不修改無關的檔案。

請先說明影響範圍與迴歸風險，
新增可保留既有行為的測試後再實作。
```

### 錯誤修正範本

```text
請重現以下錯誤並修正根本原因。

完整錯誤訊息：
{已移除祕密資訊與個人資料的錯誤訊息及堆疊追蹤}

發生條件：
- 執行命令：{命令}
- 輸入：{最小重現輸入}
- 環境：{作業系統、執行階段、相關版本}
- 發生時間點：{在哪個階段}

預期行為：
{正常情況下應出現的結果}

實際行為：
{目前觀察到的結果}

要求：
1. 先重現錯誤。
2. 根據證據說明原因。
3. 以最小範圍進行修正。
4. 新增防止相同錯誤的迴歸測試。
5. 回報已執行的測試與剩餘風險。
```

貼上錯誤訊息時，必須移除 API 金鑰、工作階段權杖、客戶資料、內部位址等敏感資訊。

## 完整範例：新聞簡報代理要求

以下範例將六項原則整合到一個要求中。

```text
我是 SaaS 新創公司的業務開發人員。
我希望每天只查看 AI、雲端、金融科技市場變化中，
可能在 3 個月內改變產品或合作決策的新聞。

請調查目前的儲存庫，並設計新聞簡報工具。
第一階段只實作讀取範例 JSON、移除重複項目、分類影響程度，
以及建立 HTML 預覽檔案的功能。
網路搜尋、實際寄送郵件與排程執行不包含在此階段中。

輸入欄位：
- title, url, source, published_at, body

處理規則：
- 正規化後的 URL 相同時，視為重複項目。
- 即使 URL 不同，若標題相似，也標記為重複候選項目。
- 只有在 3 個月內必須對價格、法規因應、產品路線圖或合作判斷
  做出具體改變的文章，才分類為影響程度「高」。
- 若依據不足，不要猜測為高等級。

輸出：
- 顯示標題、1～2 句摘要、影響程度、判定理由、來源與 URL。
- 依影響程度由高至低排序。
- 在底部顯示總筆數、移除的重複筆數與各等級筆數。

例外處理：
- 不要排除缺少必填欄位的項目，請將其記錄在獨立錯誤清單中。
- 不要推測錯誤日期，維持為 null。
- 不要在日誌中留下完整文章內文或驗證資訊。

驗證：
- 測試正常輸入、空輸入、重複 URL、錯誤日期與缺少必填欄位。
- 若有既有測試，則必須全部通過。

工作順序：
1. 調查儲存庫結構與相關檔案。
2. 提出要修改的檔案與測試計畫。
3. 在我確認計畫前，不要變更程式碼。
4. 核准後實作最小功能並回報測試結果。
```

這項要求並不是要一次將所有必要功能部署到營運環境。其範圍有限，並且同時定義了輸出語意、失敗處理與測試項目，因此容易判定結果。

## 只靠提示詞容易忽略的完整度標準

許多氛圍式程式設計指南著重於撰寫更詳細的指示。然而，真正左右完整度的其他要素是**可驗證性、變更控制、可觀察性、安全邊界**。

### 1. 將驗收條件轉換成測試

不要只說「讓它正常運作」，而應成對提供輸入與預期輸出。重要的分類案例應保留為迴歸測試，以確認後續變更仍能維持結果。

### 2. 不要將代理的自我評估當作最終證據

代理表示「已完成」與測試通過是兩回事。應要求回報執行的命令、測試結果、變更檔案與未解決風險，並由人員檢視 diff。

### 3. 將權限與祕密資訊最小化

不要一次提供不必要的目錄、正式環境資料庫或部署憑證。API 金鑰不要直接放入提示詞或儲存庫，應使用環境變數或經核准的祕密管理系統。不要向來源不明的 MCP 伺服器或指令碼提供敏感儲存庫的存取權限。

### 4. 要求可觀察的程式碼

自動化工作應保留各階段狀態、結構化錯誤、執行時間、處理筆數等查找故障原因所需的資訊。另一方面，應從日誌中移除驗證資訊與個人資料。

### 5. 讓變更可以復原

不要將無關的重構與功能新增混在同一次變更中。以小單位檢視 diff 並記錄於版本控制中，就能更容易分離並復原錯誤變更。

## Claude Code 專案營運技巧

- 將反覆使用的專案規則簡短、具體地記錄在 `CLAUDE.md` 中。
- 以實際可執行的形式提供建置、測試與 lint 命令。
- 不要將祕密資訊、一次性錯誤日誌或冗長參考文件放入 `CLAUDE.md`。
- 大規模變更前，先要求調查相關檔案與相依關係。
- 新增套件時，檢視其必要性、授權條款與維護風險。
- 不要自動核准危險的刪除、部署與資料變更命令。
- 連接外部 API 或 MCP 前，先確認資料會傳送到何處。
- 完成時，要求摘要說明變更檔案、執行命令、測試結果與剩餘限制。

## 提交前檢查清單

- [ ] 是否已說明使用者與使用情境
- [ ] 是否已區分目標與非目標
- [ ] 是否已明確指定既有技術與禁止變更的範圍
- [ ] 是否已定義輸入資料與輸出格式
- [ ] 是否已說明分類值與狀態值的意義
- [ ] 是否具備空結果、驗證失敗、逾時與部分失敗的政策
- [ ] 是否已逐步區分計畫與實作
- [ ] 是否具備正常、邊界與失敗案例的測試
- [ ] 是否已從提示詞與日誌中排除祕密資訊和個人資料
- [ ] 是否要求提供供人員檢視的 diff 與執行證據

好的 Claude Code 提示詞，重點不在於把命令寫得很長，而在於減少需要代理猜測的部分，並讓第三方也能重現並判定結果是否正確。

## FAQ

### Claude Code 提示詞越長越好嗎？
比起長度，更重要的是是否以結構化方式納入工作所需的資訊。背景、目標、限制、輸出契約、例外處理與完成條件應具體說明，但最好移除不相關的說明與重複指示。

### 不能從一開始就要求建立完整的程式嗎？
若是小型獨立工具則可以，但同時涉及外部 API、資料庫、電子郵件與排程執行的工作，採取分階段開發會比較安全。先檢視儲存庫調查結果與計畫，再依最小功能、測試、外部整合的順序擴充，會更容易釐清失敗原因。

### 使用 Plan Mode 就可以省略測試嗎？
不可以。計畫模式有助於在變更前檢視結構與方法，但無法證明實際程式碼的正確性。實作後仍須另外執行自動化測試、靜態分析、變更內容檢視，以及必要的手動確認。

### CLAUDE.md 中應該寫些什麼？
適合寫入會在多項工作中反覆使用的指示，例如專案結構、程式碼撰寫規範、建置與測試指令，以及不得修改的區域。最好不要放入 API 金鑰、密碼、個人資料、一次性工作說明，以及過長的參考資料。

### 提出錯誤修正請求時，應提供哪些資訊？
應一併提供已移除敏感資訊的錯誤訊息與堆疊追蹤、執行指令、最小重現輸入、相關環境、實際行為與預期行為。也最好要求提供原因說明、最小範圍的修正、迴歸測試與執行結果。

### 可以透過提示詞將 API 金鑰傳給 Claude Code 嗎？
原則上，不應在提示詞或原始碼中直接記錄真實的 API 金鑰。應使用經核准的環境變數或祕密管理系統，並確保驗證資訊不會暴露在日誌與測試結果中。

### 提示詞中一定要寫明重試次數和等待時間嗎？
若是營運自動化，區分可重試的錯誤與應立即中止的錯誤很重要。不過，具體次數與等待時間應在確認外部服務的限制、工作的緊急程度及重複處理風險後決定，不應無條件重試所有錯誤。

### 如何判斷產生的程式碼是否已完成？
應依據事先訂定的驗收條件判斷。確認必要功能與例外案例是否通過測試、執行過哪些指令、變更了哪些檔案，以及是否符合效能或安全限制，並由人工檢視程式碼變更內容。

## Sources

- [Claude Code 概覽](https://docs.anthropic.com/en/docs/claude-code/overview)
- [Claude Code：代理式編碼的最佳實務](https://www.anthropic.com/engineering/claude-code-best-practices)
- [Anthropic Claude Code GitHub 儲存庫](https://github.com/anthropics/claude-code)

## Images

![開發人員在顯示程式碼與工作流程圖的大型螢幕前工作](https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MTExNTQsInB1ciI6ImJsb2JfaWQifX0=--9f2d2e2c8a61fc294a6019e4807ece297f36e85a/ai-4caeb237.webp)
![筆電程式碼編輯器連結需求、表格、錯誤、版本控制與成效圖表](https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MTExNjAsInB1ciI6ImJsb2JfaWQifX0=--285d7ecdc8209e07e0fc4eb68085cd8a304b9a81/ai-062b34c5.webp)