{"content_id":"vduimuvis9","slug":"claude-code-prompt-six-principles-and-templates","locale":"zh-hant","schema_type":"HowTo","category":"tutorial","category_name":"教學課程","title":"提升 Claude Code 產出完整度的提示詞 6 原則","summary":"說明如何不只要求 Claude Code 產生程式碼，而是以結構化方式提供背景、輸出契約、例外處理與驗證標準。另提供可直接套用於新代理程式開發、功能新增及錯誤修正的提示詞範本。","sponsorship_disclosure":null,"author":{"name":"injoys","url":"https://injoys.com/ko/about"},"key_points":["1. 開始作業前，將使用者背景、待解決的問題、成功標準及技術限制整理於同一份文件中。","2. 以具體的輸出契約指定產出的檔案結構、資料格式、允許範圍及完成條件。","3. 定義外部 API 失敗、空白結果、重複資料及驗證錯誤等可預期的例外與應對政策。","4. 依照計畫審查、最小功能實作、自動化測試及功能擴充的順序拆分作業，並在每個階段確認結果。","5. 不提出模糊的重作要求，而是提供失敗案例與可衡量的改善目標，並依最終驗收條件進行驗證。"],"content_markdown":"像 Claude Code 這類程式設計代理不只是產生一小段程式碼的工具，而是能探索儲存庫、修改多個檔案，以及執行測試與命令的工作環境。因此，成果品質與其說取決於文字看起來多麼合理，不如說更大程度取決於**工作範圍與驗證方法定義得多麼明確**。\n\n好的提示詞不是冗長的說明文，而是可執行的工作規格。除了要製作什麼之外，還必須傳達為何需要、應遵守哪些條件、如何處理失敗，以及通過哪些條件才算完成。\n\n## 首先要區分：提示詞與執行環境\n\n氛圍式程式設計是一種以自然語言傳達意圖，並由 AI 代理負責實作的協作方式。然而，以自然語言提出要求這件事本身，並不能保證程式碼的正確性或營運穩定性。\n\nClaude Code 工作會同時受到以下要素影響。\n\n| 要素 | 作用 | 提示詞中要確認的內容 |\n|---|---|---|\n| 使用者要求 | 傳達目標與變更範圍 | 目的、優先順序、禁止事項 |\n| 儲存庫脈絡 | 提供既有結構與規則 | 框架、執行命令、相關檔案 |\n| `CLAUDE.md` | 提供反覆套用的專案指引 | 程式設計規則、測試方法、目錄慣例 |\n| 工具權限 | 控制檔案修改與命令執行的允許範圍 | 可執行的命令，以及需要事先確認的工作 |\n| 外部連線 | 存取 API、資料庫、MCP 伺服器等 | 驗證方式、信任邊界、失敗政策 |\n| 驗證程序 | 判斷結果是否符合需求 | 測試、靜態分析、手動確認項目 |\n\n並非只要把提示詞寫好，就能解決所有問題。例如，Claude Code 雖然能建立排程執行程式碼，但若要在電腦關機時仍能執行工作，就需要另行準備伺服器、CI 服務或作業系統排程器。電子郵件寄送若沒有實際供應商的驗證資訊與寄送權限，也無法完成。\n\n## 原則 1. 先說明背景、目的與限制\n\n若只提出成果名稱，例如「幫我建立新聞蒐集代理」，代理就必須猜測使用者、資料來源、執行環境與成功標準。即使同樣是新聞蒐集器，業務開發人員、投資人、大學校報編輯所需要的來源與分類標準也不相同。\n\n### 不充分的要求\n\n```text\n幫我建立 AI 新聞蒐集代理。\n```\n\n### 改善後的要求\n\n```text\n我是 IT 新創公司的業務開發人員。\n我想在每天開始工作前，快速查看 AI、雲端、金融科技領域中\n會影響業務合作或產品策略的新聞。\n\n目標：\n- 依照指定關鍵字蒐集最新的候選文章。\n- 移除 URL 相同的文章，以及標題相似的重複文章。\n- 以是否需要在 3 個月內做出產品或合作決策為標準，\n  將影響程度分類為高、中、低。\n- 將結果製作成韓文電子郵件簡報。\n\n限制：\n- 維持目前儲存庫的 Python 版本與套件管理方式。\n- 新增函式庫之前，先說明必要性與替代方案。\n- 不要將 API 金鑰與電子郵件密碼記錄在程式碼或日誌中。\n- 實際寄送郵件前，只產生預覽檔案。\n\n請先調查儲存庫結構與執行方式，再提出實作計畫。\n對於未知的環境資訊，不要猜測，請整理成問題清單。\n```\n\n良好的背景資訊包含以下四項。\n\n1. **使用者與使用情境：** 誰會在何時用於何種決策\n2. **目標：** 不只是撰寫程式碼，而是要解決什麼問題\n3. **限制：** 必須維持哪些技術、安全規則、成本或時間上限\n4. **非目標：** 本次變更明確排除哪些功能\n\n寫明非目標可以防止範圍無限擴大。例如，若明定「此階段不包含排程執行與實際寄送電子郵件」，就能先穩定驗證蒐集與分類邏輯。\n\n## 原則 2. 將所需的輸出格式制定成輸出契約\n\n「用電子郵件排版得好看一點再寄出」每個人的解讀都不同。輸出格式不應只展示範例，還應一併定義必填欄位、允許值、缺漏處理方式與排序順序。\n\n```text\n電子郵件主旨：\n[新聞簡報] {YYYY-MM-DD} 今日重點新聞\n\n內文的文章格式：\n1. {標題}\n摘要：{韓文 1～2 句}\n影響程度：{高|中|低}\n判定理由：{1 句}\n來源：{媒體名稱}\n連結：{原文 URL}\n\n排序規則：\n1. 依影響程度由高至低\n2. 影響程度相同時，依發布時間由新至舊\n\n底部統計：\n- 文章總數\n- 各影響程度的文章數\n- 沒有搜尋結果的關鍵字\n\n限制：\n- 摘要中不得捏造原文沒有的數字或主張。\n- 若無法確認日期，不要推測日期，標示為「無法確認」。\n- 沒有連結的項目不納入最終簡報。\n```\n\n若需要在程式之間傳遞結果，最好要求同時提供供人閱讀的範例，以及 JSON 結構描述或型別定義。\n\n```json\n{\n  \"title\": \"string\",\n  \"summary\": \"string\",\n  \"impact\": \"high | medium | low\",\n  \"reason\": \"string\",\n  \"source\": \"string\",\n  \"url\": \"absolute URL\",\n  \"published_at\": \"ISO 8601 string | null\"\n}\n```\n\n輸出契約不只包含格式，也包含語意。如果沒有判定 `impact: high` 代表什麼的標準，即使 JSON 語法正確，分類結果也可能不一致。\n\n## 原則 3. 明確指定例外情況與復原政策\n\n營運程式碼的完整度，與其說體現在正常路徑，不如說體現在失敗路徑。提示詞應一併寫明可預期的失敗、是否可重試、需要通知使用者的條件，以及不得記錄的資訊。\n\n| 例外情況 | 建議政策範例 |\n|---|---|\n| 沒有搜尋結果 | 跳過該關鍵字，並記錄於最終統計 |\n| 暫時性網路錯誤 | 以固定間隔進行有限次數的重試 |\n| 驗證失敗 | 不要重試，立即中止並提示檢查設定 |\n| API 使用量限制 | 遵守回應中的等待指示，禁止無限重試 |\n| 重複文章 | 根據正規化後的 URL 與標題相似度移除 |\n| 格式錯誤的資料 | 保留原始資料，只隔離該項目 |\n| 郵件寄送失敗 | 重試後仍失敗時，發出替代通知或記錄失敗狀態 |\n| 部分成功 | 分別回報成功結果與失敗項目 |\n\n可以像下面這樣具體要求政策。\n\n```text\n請將網路逾時視為可重試的錯誤。\n重試之間需保留等待時間，若超過最大次數，則僅將該來源標記為失敗。\n驗證錯誤與錯誤要求不會因重複執行而解決，因此請立即中止。\n\n所有錯誤日誌都要留下時間、工作階段、來源與錯誤類型，\n但不要記錄 API 金鑰、完整電子郵件地址、驗證標頭或文章全文。\n請透過程序結束狀態區分全部成功、部分成功與全部失敗。\n```\n\n「重試三次」或「等待 5 秒」這類數值沒有普遍適用的標準答案。應根據外部服務的官方限制、工作的急迫性與重複執行風險，在專案中決定。付款或訊息寄送等具有副作用的工作，若在沒有冪等性保障的情況下自動重試，可能造成重複處理。\n\n## 原則 4. 依照計畫、最小實作、驗證的順序漸進開發\n\n若一次連接多個外部服務與自動執行機制，就很難釐清錯誤原因。將實作拆分成小型驗證單位，就能確認每個階段的輸入與輸出。\n\n### 建議進行順序\n\n1. 調查儲存庫結構、相關檔案與執行命令。\n2. 在變更程式碼前，要求提出計畫與會受影響的檔案。\n3. 使用一個關鍵字與固定的範例資料實作蒐集功能。\n4. 分別測試重複移除與影響程度分類。\n5. 電子郵件不實際寄送，改以本機預覽進行驗證。\n6. 測試通過後，再新增實際供應商整合與排程執行。\n\n第一次要求可以限制如下。\n\n```text\n現在只執行第 1 階段。\n請調查儲存庫並回報以下內容。\n- 目前應用程式的進入點\n- 相關模組與測試檔案\n- 使用的套件管理與測試命令\n- 預計需要變更的檔案\n- 實作前需要決定的問題\n\n目前不要修改檔案。\n```\n\n檢視計畫後，再縮小變更範圍進行實作。\n\n```text\n請只實作已核准計畫中的新聞蒐集與重複移除功能。\n不要新增分類、電子郵件寄送與排程執行。\n請確保能以固定的測試資料執行，\n並在最後摘要說明修改的檔案與執行的測試結果。\n```\n\n如果 Claude Code 環境可以使用計畫專用模式，就能在探索與設計階段加以運用。但計畫看似合理，不代表實作就正確，因此後續仍必須進行實際測試與程式碼檢視。\n\n## 原則 5. 透過失敗案例與數值提供回饋\n\n「結果不太好」、「效能很慢」、「分類錯了」很難用來決定修改方向。必須傳達目前狀態、預期狀態、重現輸入，以及可接受的變更範圍。\n\n### 長度修改要求\n\n```text\n目前電子郵件內文產生約 3,000 字。\n為了能在行動裝置上快速閱讀，我想縮短至 500 字以內。\n請將每篇文章的摘要限制為 1～2 句，並保留判定理由。\n請將原文 URL 連結到標題，移除獨立的連結行。\n保留底部統計。\n```\n\n### 分類標準修改要求\n\n```text\n10 筆測試資料中有 8 筆被分類為「高」。\n請將長期技術展望或一般產品介紹分類為「低」。\n只有在有具體依據顯示 3 個月內必須改變價格、產品路線圖、\n法規因應或合作決策時，才能分類為「高」。\n\n在附加案例中，A 與 B 的正確答案是高，C 的正確答案是低。\n請修改分類規則，並將這些案例新增為迴歸測試。\n```\n\n### 效能修改要求\n\n```text\n相同範例輸入目前的平均執行時間約為 45 秒。\n目標是在相同環境中控制於 30 秒以內。\n請先測量各階段的時間並顯示瓶頸。\n不要移除結果準確度與錯誤處理，\n請比較改善方案的效果與風險，再從最小的變更開始套用。\n```\n\n效能數值只有在測量環境與輸入資料相同時才能比較。不要只憑一次執行結果判斷已有改善，還必須一併固定測量方法、樣本與快取狀態。\n\n## 原則 6. 依工作類型使用提示詞範本\n\n### 建立新代理的範本\n\n```text\n[角色與情境]\n我是{職業/角色}，希望解決{問題情境}。\n此結果將由{使用者或後續系統}使用。\n\n[目標]\n{必須達成的結果與成功標準}\n\n[執行觸發條件]\n{手動執行、事件、排程時間等}\n\n[輸入]\n- 資料來源：{檔案/API/資料庫}\n- 必填欄位：{欄位清單}\n- 驗證方式：{環境變數或祕密管理方式}\n\n[處理邏輯]\n1. {步驟 1}\n2. {步驟 2}\n3. {步驟 3}\n\n[輸出契約]\n{檔案格式、結構描述、範本、排序與缺漏規則}\n\n[例外處理]\n{空結果、逾時、驗證錯誤、部分失敗政策}\n\n[限制與非目標]\n- 必須維持的技術：{項目}\n- 禁止事項：{項目}\n- 本次工作排除的功能：{項目}\n\n[驗證]\n- 必須通過的測試：{項目}\n- 完成報告中應包含的內容：變更檔案、執行命令、測試結果、剩餘風險\n\n請先調查儲存庫並提出實作計畫。\n對於未知資訊，不要猜測，請提出問題。\n```\n\n### 新增既有功能的範本\n\n```text\n請在既有的{代理或模組名稱}中新增{新功能}。\n新功能必須在{既有步驟 A}之後、{既有步驟 B}之前執行。\n\n詳細邏輯：\n- {條件與處理規則}\n- {輸入輸出格式}\n- {失敗時的動作}\n\n維持條件：\n- 不變更既有公開介面與設定格式。\n- 保留所有既有測試。\n- 不修改無關的檔案。\n\n請先說明影響範圍與迴歸風險，\n新增可保留既有行為的測試後再實作。\n```\n\n### 錯誤修正範本\n\n```text\n請重現以下錯誤並修正根本原因。\n\n完整錯誤訊息：\n{已移除祕密資訊與個人資料的錯誤訊息及堆疊追蹤}\n\n發生條件：\n- 執行命令：{命令}\n- 輸入：{最小重現輸入}\n- 環境：{作業系統、執行階段、相關版本}\n- 發生時間點：{在哪個階段}\n\n預期行為：\n{正常情況下應出現的結果}\n\n實際行為：\n{目前觀察到的結果}\n\n要求：\n1. 先重現錯誤。\n2. 根據證據說明原因。\n3. 以最小範圍進行修正。\n4. 新增防止相同錯誤的迴歸測試。\n5. 回報已執行的測試與剩餘風險。\n```\n\n貼上錯誤訊息時，必須移除 API 金鑰、工作階段權杖、客戶資料、內部位址等敏感資訊。\n\n## 完整範例：新聞簡報代理要求\n\n以下範例將六項原則整合到一個要求中。\n\n```text\n我是 SaaS 新創公司的業務開發人員。\n我希望每天只查看 AI、雲端、金融科技市場變化中，\n可能在 3 個月內改變產品或合作決策的新聞。\n\n請調查目前的儲存庫，並設計新聞簡報工具。\n第一階段只實作讀取範例 JSON、移除重複項目、分類影響程度，\n以及建立 HTML 預覽檔案的功能。\n網路搜尋、實際寄送郵件與排程執行不包含在此階段中。\n\n輸入欄位：\n- title, url, source, published_at, body\n\n處理規則：\n- 正規化後的 URL 相同時，視為重複項目。\n- 即使 URL 不同，若標題相似，也標記為重複候選項目。\n- 只有在 3 個月內必須對價格、法規因應、產品路線圖或合作判斷\n  做出具體改變的文章，才分類為影響程度「高」。\n- 若依據不足，不要猜測為高等級。\n\n輸出：\n- 顯示標題、1～2 句摘要、影響程度、判定理由、來源與 URL。\n- 依影響程度由高至低排序。\n- 在底部顯示總筆數、移除的重複筆數與各等級筆數。\n\n例外處理：\n- 不要排除缺少必填欄位的項目，請將其記錄在獨立錯誤清單中。\n- 不要推測錯誤日期，維持為 null。\n- 不要在日誌中留下完整文章內文或驗證資訊。\n\n驗證：\n- 測試正常輸入、空輸入、重複 URL、錯誤日期與缺少必填欄位。\n- 若有既有測試，則必須全部通過。\n\n工作順序：\n1. 調查儲存庫結構與相關檔案。\n2. 提出要修改的檔案與測試計畫。\n3. 在我確認計畫前，不要變更程式碼。\n4. 核准後實作最小功能並回報測試結果。\n```\n\n這項要求並不是要一次將所有必要功能部署到營運環境。其範圍有限，並且同時定義了輸出語意、失敗處理與測試項目，因此容易判定結果。\n\n## 只靠提示詞容易忽略的完整度標準\n\n許多氛圍式程式設計指南著重於撰寫更詳細的指示。然而，真正左右完整度的其他要素是**可驗證性、變更控制、可觀察性、安全邊界**。\n\n### 1. 將驗收條件轉換成測試\n\n不要只說「讓它正常運作」，而應成對提供輸入與預期輸出。重要的分類案例應保留為迴歸測試，以確認後續變更仍能維持結果。\n\n### 2. 不要將代理的自我評估當作最終證據\n\n代理表示「已完成」與測試通過是兩回事。應要求回報執行的命令、測試結果、變更檔案與未解決風險，並由人員檢視 diff。\n\n### 3. 將權限與祕密資訊最小化\n\n不要一次提供不必要的目錄、正式環境資料庫或部署憑證。API 金鑰不要直接放入提示詞或儲存庫，應使用環境變數或經核准的祕密管理系統。不要向來源不明的 MCP 伺服器或指令碼提供敏感儲存庫的存取權限。\n\n### 4. 要求可觀察的程式碼\n\n自動化工作應保留各階段狀態、結構化錯誤、執行時間、處理筆數等查找故障原因所需的資訊。另一方面，應從日誌中移除驗證資訊與個人資料。\n\n### 5. 讓變更可以復原\n\n不要將無關的重構與功能新增混在同一次變更中。以小單位檢視 diff 並記錄於版本控制中，就能更容易分離並復原錯誤變更。\n\n## Claude Code 專案營運技巧\n\n- 將反覆使用的專案規則簡短、具體地記錄在 `CLAUDE.md` 中。\n- 以實際可執行的形式提供建置、測試與 lint 命令。\n- 不要將祕密資訊、一次性錯誤日誌或冗長參考文件放入 `CLAUDE.md`。\n- 大規模變更前，先要求調查相關檔案與相依關係。\n- 新增套件時，檢視其必要性、授權條款與維護風險。\n- 不要自動核准危險的刪除、部署與資料變更命令。\n- 連接外部 API 或 MCP 前，先確認資料會傳送到何處。\n- 完成時，要求摘要說明變更檔案、執行命令、測試結果與剩餘限制。\n\n## 提交前檢查清單\n\n- [ ] 是否已說明使用者與使用情境\n- [ ] 是否已區分目標與非目標\n- [ ] 是否已明確指定既有技術與禁止變更的範圍\n- [ ] 是否已定義輸入資料與輸出格式\n- [ ] 是否已說明分類值與狀態值的意義\n- [ ] 是否具備空結果、驗證失敗、逾時與部分失敗的政策\n- [ ] 是否已逐步區分計畫與實作\n- [ ] 是否具備正常、邊界與失敗案例的測試\n- [ ] 是否已從提示詞與日誌中排除祕密資訊和個人資料\n- [ ] 是否要求提供供人員檢視的 diff 與執行證據\n\n好的 Claude Code 提示詞，重點不在於把命令寫得很長，而在於減少需要代理猜測的部分，並讓第三方也能重現並判定結果是否正確。","content_html":"\u003cp\u003e像 Claude Code 這類程式設計代理不只是產生一小段程式碼的工具，而是能探索儲存庫、修改多個檔案，以及執行測試與命令的工作環境。因此，成果品質與其說取決於文字看起來多麼合理，不如說更大程度取決於\u003cstrong\u003e工作範圍與驗證方法定義得多麼明確\u003c/strong\u003e。\u003c/p\u003e\n\u003cp\u003e好的提示詞不是冗長的說明文，而是可執行的工作規格。除了要製作什麼之外，還必須傳達為何需要、應遵守哪些條件、如何處理失敗，以及通過哪些條件才算完成。\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%E9%A6%96%E5%85%88%E8%A6%81%E5%8D%80%E5%88%86%E6%8F%90%E7%A4%BA%E8%A9%9E%E8%88%87%E5%9F%B7%E8%A1%8C%E7%92%B0%E5%A2%83\" class=\"anchor\" id=\"首先要區分提示詞與執行環境\"\u003e\u003c/a\u003e首先要區分：提示詞與執行環境\u003c/h2\u003e\n\u003cp\u003e氛圍式程式設計是一種以自然語言傳達意圖，並由 AI 代理負責實作的協作方式。然而，以自然語言提出要求這件事本身，並不能保證程式碼的正確性或營運穩定性。\u003c/p\u003e\n\u003cp\u003eClaude Code 工作會同時受到以下要素影響。\u003c/p\u003e\n\u003cdiv class=\"overflow-x-auto\"\u003e\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003e要素\u003c/th\u003e\n\u003cth\u003e作用\u003c/th\u003e\n\u003cth\u003e提示詞中要確認的內容\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"要素\"\u003e使用者要求\u003c/td\u003e\n\u003ctd data-label=\"作用\"\u003e傳達目標與變更範圍\u003c/td\u003e\n\u003ctd data-label=\"提示詞中要確認的內容\"\u003e目的、優先順序、禁止事項\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"要素\"\u003e儲存庫脈絡\u003c/td\u003e\n\u003ctd data-label=\"作用\"\u003e提供既有結構與規則\u003c/td\u003e\n\u003ctd data-label=\"提示詞中要確認的內容\"\u003e框架、執行命令、相關檔案\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"要素\"\u003e\u003ccode\u003eCLAUDE.md\u003c/code\u003e\u003c/td\u003e\n\u003ctd data-label=\"作用\"\u003e提供反覆套用的專案指引\u003c/td\u003e\n\u003ctd data-label=\"提示詞中要確認的內容\"\u003e程式設計規則、測試方法、目錄慣例\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"要素\"\u003e工具權限\u003c/td\u003e\n\u003ctd data-label=\"作用\"\u003e控制檔案修改與命令執行的允許範圍\u003c/td\u003e\n\u003ctd data-label=\"提示詞中要確認的內容\"\u003e可執行的命令，以及需要事先確認的工作\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"要素\"\u003e外部連線\u003c/td\u003e\n\u003ctd data-label=\"作用\"\u003e存取 API、資料庫、MCP 伺服器等\u003c/td\u003e\n\u003ctd data-label=\"提示詞中要確認的內容\"\u003e驗證方式、信任邊界、失敗政策\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"要素\"\u003e驗證程序\u003c/td\u003e\n\u003ctd data-label=\"作用\"\u003e判斷結果是否符合需求\u003c/td\u003e\n\u003ctd data-label=\"提示詞中要確認的內容\"\u003e測試、靜態分析、手動確認項目\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\u003c/div\u003e\n\u003cp\u003e並非只要把提示詞寫好，就能解決所有問題。例如，Claude Code 雖然能建立排程執行程式碼，但若要在電腦關機時仍能執行工作，就需要另行準備伺服器、CI 服務或作業系統排程器。電子郵件寄送若沒有實際供應商的驗證資訊與寄送權限，也無法完成。\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%E5%8E%9F%E5%89%87-1-%E5%85%88%E8%AA%AA%E6%98%8E%E8%83%8C%E6%99%AF%E7%9B%AE%E7%9A%84%E8%88%87%E9%99%90%E5%88%B6\" class=\"anchor\" id=\"原則-1-先說明背景目的與限制\"\u003e\u003c/a\u003e原則 1. 先說明背景、目的與限制\u003c/h2\u003e\n\u003cp\u003e若只提出成果名稱，例如「幫我建立新聞蒐集代理」，代理就必須猜測使用者、資料來源、執行環境與成功標準。即使同樣是新聞蒐集器，業務開發人員、投資人、大學校報編輯所需要的來源與分類標準也不相同。\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#%E4%B8%8D%E5%85%85%E5%88%86%E7%9A%84%E8%A6%81%E6%B1%82\" class=\"anchor\" id=\"不充分的要求\"\u003e\u003c/a\u003e不充分的要求\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e幫我建立 AI 新聞蒐集代理。\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#%E6%94%B9%E5%96%84%E5%BE%8C%E7%9A%84%E8%A6%81%E6%B1%82\" class=\"anchor\" id=\"改善後的要求\"\u003e\u003c/a\u003e改善後的要求\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e我是 IT 新創公司的業務開發人員。\n\u003c/span\u003e\u003cspan\u003e我想在每天開始工作前，快速查看 AI、雲端、金融科技領域中\n\u003c/span\u003e\u003cspan\u003e會影響業務合作或產品策略的新聞。\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e目標：\n\u003c/span\u003e\u003cspan\u003e- 依照指定關鍵字蒐集最新的候選文章。\n\u003c/span\u003e\u003cspan\u003e- 移除 URL 相同的文章，以及標題相似的重複文章。\n\u003c/span\u003e\u003cspan\u003e- 以是否需要在 3 個月內做出產品或合作決策為標準，\n\u003c/span\u003e\u003cspan\u003e  將影響程度分類為高、中、低。\n\u003c/span\u003e\u003cspan\u003e- 將結果製作成韓文電子郵件簡報。\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e限制：\n\u003c/span\u003e\u003cspan\u003e- 維持目前儲存庫的 Python 版本與套件管理方式。\n\u003c/span\u003e\u003cspan\u003e- 新增函式庫之前，先說明必要性與替代方案。\n\u003c/span\u003e\u003cspan\u003e- 不要將 API 金鑰與電子郵件密碼記錄在程式碼或日誌中。\n\u003c/span\u003e\u003cspan\u003e- 實際寄送郵件前，只產生預覽檔案。\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e請先調查儲存庫結構與執行方式，再提出實作計畫。\n\u003c/span\u003e\u003cspan\u003e對於未知的環境資訊，不要猜測，請整理成問題清單。\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e良好的背景資訊包含以下四項。\u003c/p\u003e\n\u003col\u003e\n\u003cli\u003e\n\u003cstrong\u003e使用者與使用情境：\u003c/strong\u003e 誰會在何時用於何種決策\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003e目標：\u003c/strong\u003e 不只是撰寫程式碼，而是要解決什麼問題\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003e限制：\u003c/strong\u003e 必須維持哪些技術、安全規則、成本或時間上限\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003e非目標：\u003c/strong\u003e 本次變更明確排除哪些功能\u003c/li\u003e\n\u003c/ol\u003e\n\u003cp\u003e寫明非目標可以防止範圍無限擴大。例如，若明定「此階段不包含排程執行與實際寄送電子郵件」，就能先穩定驗證蒐集與分類邏輯。\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%E5%8E%9F%E5%89%87-2-%E5%B0%87%E6%89%80%E9%9C%80%E7%9A%84%E8%BC%B8%E5%87%BA%E6%A0%BC%E5%BC%8F%E5%88%B6%E5%AE%9A%E6%88%90%E8%BC%B8%E5%87%BA%E5%A5%91%E7%B4%84\" class=\"anchor\" id=\"原則-2-將所需的輸出格式制定成輸出契約\"\u003e\u003c/a\u003e原則 2. 將所需的輸出格式制定成輸出契約\u003c/h2\u003e\n\u003cp\u003e「用電子郵件排版得好看一點再寄出」每個人的解讀都不同。輸出格式不應只展示範例，還應一併定義必填欄位、允許值、缺漏處理方式與排序順序。\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e電子郵件主旨：\n\u003c/span\u003e\u003cspan\u003e[新聞簡報] {YYYY-MM-DD} 今日重點新聞\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e內文的文章格式：\n\u003c/span\u003e\u003cspan\u003e1. {標題}\n\u003c/span\u003e\u003cspan\u003e摘要：{韓文 1～2 句}\n\u003c/span\u003e\u003cspan\u003e影響程度：{高|中|低}\n\u003c/span\u003e\u003cspan\u003e判定理由：{1 句}\n\u003c/span\u003e\u003cspan\u003e來源：{媒體名稱}\n\u003c/span\u003e\u003cspan\u003e連結：{原文 URL}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e排序規則：\n\u003c/span\u003e\u003cspan\u003e1. 依影響程度由高至低\n\u003c/span\u003e\u003cspan\u003e2. 影響程度相同時，依發布時間由新至舊\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e底部統計：\n\u003c/span\u003e\u003cspan\u003e- 文章總數\n\u003c/span\u003e\u003cspan\u003e- 各影響程度的文章數\n\u003c/span\u003e\u003cspan\u003e- 沒有搜尋結果的關鍵字\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e限制：\n\u003c/span\u003e\u003cspan\u003e- 摘要中不得捏造原文沒有的數字或主張。\n\u003c/span\u003e\u003cspan\u003e- 若無法確認日期，不要推測日期，標示為「無法確認」。\n\u003c/span\u003e\u003cspan\u003e- 沒有連結的項目不納入最終簡報。\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e若需要在程式之間傳遞結果，最好要求同時提供供人閱讀的範例，以及 JSON 結構描述或型別定義。\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e{\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003etitle\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003estring\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003esummary\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003estring\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003eimpact\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003ehigh | medium | low\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003ereason\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003estring\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003esource\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003estring\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003eurl\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003eabsolute URL\u003c/span\u003e\u003cspan\u003e\",\n\u003c/span\u003e\u003cspan\u003e  \"\u003c/span\u003e\u003cspan\u003epublished_at\u003c/span\u003e\u003cspan\u003e\": \"\u003c/span\u003e\u003cspan\u003eISO 8601 string | null\u003c/span\u003e\u003cspan\u003e\"\n\u003c/span\u003e\u003cspan\u003e}\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e輸出契約不只包含格式，也包含語意。如果沒有判定 \u003ccode\u003eimpact: high\u003c/code\u003e 代表什麼的標準，即使 JSON 語法正確，分類結果也可能不一致。\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%E5%8E%9F%E5%89%87-3-%E6%98%8E%E7%A2%BA%E6%8C%87%E5%AE%9A%E4%BE%8B%E5%A4%96%E6%83%85%E6%B3%81%E8%88%87%E5%BE%A9%E5%8E%9F%E6%94%BF%E7%AD%96\" class=\"anchor\" id=\"原則-3-明確指定例外情況與復原政策\"\u003e\u003c/a\u003e原則 3. 明確指定例外情況與復原政策\u003c/h2\u003e\n\u003cp\u003e營運程式碼的完整度，與其說體現在正常路徑，不如說體現在失敗路徑。提示詞應一併寫明可預期的失敗、是否可重試、需要通知使用者的條件，以及不得記錄的資訊。\u003c/p\u003e\n\u003cdiv class=\"overflow-x-auto\"\u003e\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003e例外情況\u003c/th\u003e\n\u003cth\u003e建議政策範例\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"例外情況\"\u003e沒有搜尋結果\u003c/td\u003e\n\u003ctd data-label=\"建議政策範例\"\u003e跳過該關鍵字，並記錄於最終統計\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"例外情況\"\u003e暫時性網路錯誤\u003c/td\u003e\n\u003ctd data-label=\"建議政策範例\"\u003e以固定間隔進行有限次數的重試\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"例外情況\"\u003e驗證失敗\u003c/td\u003e\n\u003ctd data-label=\"建議政策範例\"\u003e不要重試，立即中止並提示檢查設定\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"例外情況\"\u003eAPI 使用量限制\u003c/td\u003e\n\u003ctd data-label=\"建議政策範例\"\u003e遵守回應中的等待指示，禁止無限重試\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"例外情況\"\u003e重複文章\u003c/td\u003e\n\u003ctd data-label=\"建議政策範例\"\u003e根據正規化後的 URL 與標題相似度移除\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"例外情況\"\u003e格式錯誤的資料\u003c/td\u003e\n\u003ctd data-label=\"建議政策範例\"\u003e保留原始資料，只隔離該項目\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"例外情況\"\u003e郵件寄送失敗\u003c/td\u003e\n\u003ctd data-label=\"建議政策範例\"\u003e重試後仍失敗時，發出替代通知或記錄失敗狀態\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"例外情況\"\u003e部分成功\u003c/td\u003e\n\u003ctd data-label=\"建議政策範例\"\u003e分別回報成功結果與失敗項目\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\u003c/div\u003e\n\u003cp\u003e可以像下面這樣具體要求政策。\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e請將網路逾時視為可重試的錯誤。\n\u003c/span\u003e\u003cspan\u003e重試之間需保留等待時間，若超過最大次數，則僅將該來源標記為失敗。\n\u003c/span\u003e\u003cspan\u003e驗證錯誤與錯誤要求不會因重複執行而解決，因此請立即中止。\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e所有錯誤日誌都要留下時間、工作階段、來源與錯誤類型，\n\u003c/span\u003e\u003cspan\u003e但不要記錄 API 金鑰、完整電子郵件地址、驗證標頭或文章全文。\n\u003c/span\u003e\u003cspan\u003e請透過程序結束狀態區分全部成功、部分成功與全部失敗。\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e「重試三次」或「等待 5 秒」這類數值沒有普遍適用的標準答案。應根據外部服務的官方限制、工作的急迫性與重複執行風險，在專案中決定。付款或訊息寄送等具有副作用的工作，若在沒有冪等性保障的情況下自動重試，可能造成重複處理。\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%E5%8E%9F%E5%89%87-4-%E4%BE%9D%E7%85%A7%E8%A8%88%E7%95%AB%E6%9C%80%E5%B0%8F%E5%AF%A6%E4%BD%9C%E9%A9%97%E8%AD%89%E7%9A%84%E9%A0%86%E5%BA%8F%E6%BC%B8%E9%80%B2%E9%96%8B%E7%99%BC\" class=\"anchor\" id=\"原則-4-依照計畫最小實作驗證的順序漸進開發\"\u003e\u003c/a\u003e原則 4. 依照計畫、最小實作、驗證的順序漸進開發\u003c/h2\u003e\n\u003cp\u003e若一次連接多個外部服務與自動執行機制，就很難釐清錯誤原因。將實作拆分成小型驗證單位，就能確認每個階段的輸入與輸出。\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#%E5%BB%BA%E8%AD%B0%E9%80%B2%E8%A1%8C%E9%A0%86%E5%BA%8F\" class=\"anchor\" id=\"建議進行順序\"\u003e\u003c/a\u003e建議進行順序\u003c/h3\u003e\n\u003col\u003e\n\u003cli\u003e調查儲存庫結構、相關檔案與執行命令。\u003c/li\u003e\n\u003cli\u003e在變更程式碼前，要求提出計畫與會受影響的檔案。\u003c/li\u003e\n\u003cli\u003e使用一個關鍵字與固定的範例資料實作蒐集功能。\u003c/li\u003e\n\u003cli\u003e分別測試重複移除與影響程度分類。\u003c/li\u003e\n\u003cli\u003e電子郵件不實際寄送，改以本機預覽進行驗證。\u003c/li\u003e\n\u003cli\u003e測試通過後，再新增實際供應商整合與排程執行。\u003c/li\u003e\n\u003c/ol\u003e\n\u003cp\u003e第一次要求可以限制如下。\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e現在只執行第 1 階段。\n\u003c/span\u003e\u003cspan\u003e請調查儲存庫並回報以下內容。\n\u003c/span\u003e\u003cspan\u003e- 目前應用程式的進入點\n\u003c/span\u003e\u003cspan\u003e- 相關模組與測試檔案\n\u003c/span\u003e\u003cspan\u003e- 使用的套件管理與測試命令\n\u003c/span\u003e\u003cspan\u003e- 預計需要變更的檔案\n\u003c/span\u003e\u003cspan\u003e- 實作前需要決定的問題\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e目前不要修改檔案。\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e檢視計畫後，再縮小變更範圍進行實作。\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e請只實作已核准計畫中的新聞蒐集與重複移除功能。\n\u003c/span\u003e\u003cspan\u003e不要新增分類、電子郵件寄送與排程執行。\n\u003c/span\u003e\u003cspan\u003e請確保能以固定的測試資料執行，\n\u003c/span\u003e\u003cspan\u003e並在最後摘要說明修改的檔案與執行的測試結果。\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e如果 Claude Code 環境可以使用計畫專用模式，就能在探索與設計階段加以運用。但計畫看似合理，不代表實作就正確，因此後續仍必須進行實際測試與程式碼檢視。\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%E5%8E%9F%E5%89%87-5-%E9%80%8F%E9%81%8E%E5%A4%B1%E6%95%97%E6%A1%88%E4%BE%8B%E8%88%87%E6%95%B8%E5%80%BC%E6%8F%90%E4%BE%9B%E5%9B%9E%E9%A5%8B\" class=\"anchor\" id=\"原則-5-透過失敗案例與數值提供回饋\"\u003e\u003c/a\u003e原則 5. 透過失敗案例與數值提供回饋\u003c/h2\u003e\n\u003cp\u003e「結果不太好」、「效能很慢」、「分類錯了」很難用來決定修改方向。必須傳達目前狀態、預期狀態、重現輸入，以及可接受的變更範圍。\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#%E9%95%B7%E5%BA%A6%E4%BF%AE%E6%94%B9%E8%A6%81%E6%B1%82\" class=\"anchor\" id=\"長度修改要求\"\u003e\u003c/a\u003e長度修改要求\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e目前電子郵件內文產生約 3,000 字。\n\u003c/span\u003e\u003cspan\u003e為了能在行動裝置上快速閱讀，我想縮短至 500 字以內。\n\u003c/span\u003e\u003cspan\u003e請將每篇文章的摘要限制為 1～2 句，並保留判定理由。\n\u003c/span\u003e\u003cspan\u003e請將原文 URL 連結到標題，移除獨立的連結行。\n\u003c/span\u003e\u003cspan\u003e保留底部統計。\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#%E5%88%86%E9%A1%9E%E6%A8%99%E6%BA%96%E4%BF%AE%E6%94%B9%E8%A6%81%E6%B1%82\" class=\"anchor\" id=\"分類標準修改要求\"\u003e\u003c/a\u003e分類標準修改要求\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e10 筆測試資料中有 8 筆被分類為「高」。\n\u003c/span\u003e\u003cspan\u003e請將長期技術展望或一般產品介紹分類為「低」。\n\u003c/span\u003e\u003cspan\u003e只有在有具體依據顯示 3 個月內必須改變價格、產品路線圖、\n\u003c/span\u003e\u003cspan\u003e法規因應或合作決策時，才能分類為「高」。\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e在附加案例中，A 與 B 的正確答案是高，C 的正確答案是低。\n\u003c/span\u003e\u003cspan\u003e請修改分類規則，並將這些案例新增為迴歸測試。\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#%E6%95%88%E8%83%BD%E4%BF%AE%E6%94%B9%E8%A6%81%E6%B1%82\" class=\"anchor\" id=\"效能修改要求\"\u003e\u003c/a\u003e效能修改要求\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e相同範例輸入目前的平均執行時間約為 45 秒。\n\u003c/span\u003e\u003cspan\u003e目標是在相同環境中控制於 30 秒以內。\n\u003c/span\u003e\u003cspan\u003e請先測量各階段的時間並顯示瓶頸。\n\u003c/span\u003e\u003cspan\u003e不要移除結果準確度與錯誤處理，\n\u003c/span\u003e\u003cspan\u003e請比較改善方案的效果與風險，再從最小的變更開始套用。\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e效能數值只有在測量環境與輸入資料相同時才能比較。不要只憑一次執行結果判斷已有改善，還必須一併固定測量方法、樣本與快取狀態。\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%E5%8E%9F%E5%89%87-6-%E4%BE%9D%E5%B7%A5%E4%BD%9C%E9%A1%9E%E5%9E%8B%E4%BD%BF%E7%94%A8%E6%8F%90%E7%A4%BA%E8%A9%9E%E7%AF%84%E6%9C%AC\" class=\"anchor\" id=\"原則-6-依工作類型使用提示詞範本\"\u003e\u003c/a\u003e原則 6. 依工作類型使用提示詞範本\u003c/h2\u003e\n\u003ch3\u003e\n\u003ca href=\"#%E5%BB%BA%E7%AB%8B%E6%96%B0%E4%BB%A3%E7%90%86%E7%9A%84%E7%AF%84%E6%9C%AC\" class=\"anchor\" id=\"建立新代理的範本\"\u003e\u003c/a\u003e建立新代理的範本\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e[角色與情境]\n\u003c/span\u003e\u003cspan\u003e我是{職業/角色}，希望解決{問題情境}。\n\u003c/span\u003e\u003cspan\u003e此結果將由{使用者或後續系統}使用。\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[目標]\n\u003c/span\u003e\u003cspan\u003e{必須達成的結果與成功標準}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[執行觸發條件]\n\u003c/span\u003e\u003cspan\u003e{手動執行、事件、排程時間等}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[輸入]\n\u003c/span\u003e\u003cspan\u003e- 資料來源：{檔案/API/資料庫}\n\u003c/span\u003e\u003cspan\u003e- 必填欄位：{欄位清單}\n\u003c/span\u003e\u003cspan\u003e- 驗證方式：{環境變數或祕密管理方式}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[處理邏輯]\n\u003c/span\u003e\u003cspan\u003e1. {步驟 1}\n\u003c/span\u003e\u003cspan\u003e2. {步驟 2}\n\u003c/span\u003e\u003cspan\u003e3. {步驟 3}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[輸出契約]\n\u003c/span\u003e\u003cspan\u003e{檔案格式、結構描述、範本、排序與缺漏規則}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[例外處理]\n\u003c/span\u003e\u003cspan\u003e{空結果、逾時、驗證錯誤、部分失敗政策}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[限制與非目標]\n\u003c/span\u003e\u003cspan\u003e- 必須維持的技術：{項目}\n\u003c/span\u003e\u003cspan\u003e- 禁止事項：{項目}\n\u003c/span\u003e\u003cspan\u003e- 本次工作排除的功能：{項目}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e[驗證]\n\u003c/span\u003e\u003cspan\u003e- 必須通過的測試：{項目}\n\u003c/span\u003e\u003cspan\u003e- 完成報告中應包含的內容：變更檔案、執行命令、測試結果、剩餘風險\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e請先調查儲存庫並提出實作計畫。\n\u003c/span\u003e\u003cspan\u003e對於未知資訊，不要猜測，請提出問題。\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#%E6%96%B0%E5%A2%9E%E6%97%A2%E6%9C%89%E5%8A%9F%E8%83%BD%E7%9A%84%E7%AF%84%E6%9C%AC\" class=\"anchor\" id=\"新增既有功能的範本\"\u003e\u003c/a\u003e新增既有功能的範本\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e請在既有的{代理或模組名稱}中新增{新功能}。\n\u003c/span\u003e\u003cspan\u003e新功能必須在{既有步驟 A}之後、{既有步驟 B}之前執行。\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e詳細邏輯：\n\u003c/span\u003e\u003cspan\u003e- {條件與處理規則}\n\u003c/span\u003e\u003cspan\u003e- {輸入輸出格式}\n\u003c/span\u003e\u003cspan\u003e- {失敗時的動作}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e維持條件：\n\u003c/span\u003e\u003cspan\u003e- 不變更既有公開介面與設定格式。\n\u003c/span\u003e\u003cspan\u003e- 保留所有既有測試。\n\u003c/span\u003e\u003cspan\u003e- 不修改無關的檔案。\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e請先說明影響範圍與迴歸風險，\n\u003c/span\u003e\u003cspan\u003e新增可保留既有行為的測試後再實作。\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#%E9%8C%AF%E8%AA%A4%E4%BF%AE%E6%AD%A3%E7%AF%84%E6%9C%AC\" class=\"anchor\" id=\"錯誤修正範本\"\u003e\u003c/a\u003e錯誤修正範本\u003c/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e請重現以下錯誤並修正根本原因。\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e完整錯誤訊息：\n\u003c/span\u003e\u003cspan\u003e{已移除祕密資訊與個人資料的錯誤訊息及堆疊追蹤}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e發生條件：\n\u003c/span\u003e\u003cspan\u003e- 執行命令：{命令}\n\u003c/span\u003e\u003cspan\u003e- 輸入：{最小重現輸入}\n\u003c/span\u003e\u003cspan\u003e- 環境：{作業系統、執行階段、相關版本}\n\u003c/span\u003e\u003cspan\u003e- 發生時間點：{在哪個階段}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e預期行為：\n\u003c/span\u003e\u003cspan\u003e{正常情況下應出現的結果}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e實際行為：\n\u003c/span\u003e\u003cspan\u003e{目前觀察到的結果}\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e要求：\n\u003c/span\u003e\u003cspan\u003e1. 先重現錯誤。\n\u003c/span\u003e\u003cspan\u003e2. 根據證據說明原因。\n\u003c/span\u003e\u003cspan\u003e3. 以最小範圍進行修正。\n\u003c/span\u003e\u003cspan\u003e4. 新增防止相同錯誤的迴歸測試。\n\u003c/span\u003e\u003cspan\u003e5. 回報已執行的測試與剩餘風險。\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e貼上錯誤訊息時，必須移除 API 金鑰、工作階段權杖、客戶資料、內部位址等敏感資訊。\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%E5%AE%8C%E6%95%B4%E7%AF%84%E4%BE%8B%E6%96%B0%E8%81%9E%E7%B0%A1%E5%A0%B1%E4%BB%A3%E7%90%86%E8%A6%81%E6%B1%82\" class=\"anchor\" id=\"完整範例新聞簡報代理要求\"\u003e\u003c/a\u003e完整範例：新聞簡報代理要求\u003c/h2\u003e\n\u003cp\u003e以下範例將六項原則整合到一個要求中。\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e我是 SaaS 新創公司的業務開發人員。\n\u003c/span\u003e\u003cspan\u003e我希望每天只查看 AI、雲端、金融科技市場變化中，\n\u003c/span\u003e\u003cspan\u003e可能在 3 個月內改變產品或合作決策的新聞。\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e請調查目前的儲存庫，並設計新聞簡報工具。\n\u003c/span\u003e\u003cspan\u003e第一階段只實作讀取範例 JSON、移除重複項目、分類影響程度，\n\u003c/span\u003e\u003cspan\u003e以及建立 HTML 預覽檔案的功能。\n\u003c/span\u003e\u003cspan\u003e網路搜尋、實際寄送郵件與排程執行不包含在此階段中。\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e輸入欄位：\n\u003c/span\u003e\u003cspan\u003e- title, url, source, published_at, body\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e處理規則：\n\u003c/span\u003e\u003cspan\u003e- 正規化後的 URL 相同時，視為重複項目。\n\u003c/span\u003e\u003cspan\u003e- 即使 URL 不同，若標題相似，也標記為重複候選項目。\n\u003c/span\u003e\u003cspan\u003e- 只有在 3 個月內必須對價格、法規因應、產品路線圖或合作判斷\n\u003c/span\u003e\u003cspan\u003e  做出具體改變的文章，才分類為影響程度「高」。\n\u003c/span\u003e\u003cspan\u003e- 若依據不足，不要猜測為高等級。\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e輸出：\n\u003c/span\u003e\u003cspan\u003e- 顯示標題、1～2 句摘要、影響程度、判定理由、來源與 URL。\n\u003c/span\u003e\u003cspan\u003e- 依影響程度由高至低排序。\n\u003c/span\u003e\u003cspan\u003e- 在底部顯示總筆數、移除的重複筆數與各等級筆數。\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e例外處理：\n\u003c/span\u003e\u003cspan\u003e- 不要排除缺少必填欄位的項目，請將其記錄在獨立錯誤清單中。\n\u003c/span\u003e\u003cspan\u003e- 不要推測錯誤日期，維持為 null。\n\u003c/span\u003e\u003cspan\u003e- 不要在日誌中留下完整文章內文或驗證資訊。\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e驗證：\n\u003c/span\u003e\u003cspan\u003e- 測試正常輸入、空輸入、重複 URL、錯誤日期與缺少必填欄位。\n\u003c/span\u003e\u003cspan\u003e- 若有既有測試，則必須全部通過。\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e工作順序：\n\u003c/span\u003e\u003cspan\u003e1. 調查儲存庫結構與相關檔案。\n\u003c/span\u003e\u003cspan\u003e2. 提出要修改的檔案與測試計畫。\n\u003c/span\u003e\u003cspan\u003e3. 在我確認計畫前，不要變更程式碼。\n\u003c/span\u003e\u003cspan\u003e4. 核准後實作最小功能並回報測試結果。\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e這項要求並不是要一次將所有必要功能部署到營運環境。其範圍有限，並且同時定義了輸出語意、失敗處理與測試項目，因此容易判定結果。\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#%E5%8F%AA%E9%9D%A0%E6%8F%90%E7%A4%BA%E8%A9%9E%E5%AE%B9%E6%98%93%E5%BF%BD%E7%95%A5%E7%9A%84%E5%AE%8C%E6%95%B4%E5%BA%A6%E6%A8%99%E6%BA%96\" class=\"anchor\" id=\"只靠提示詞容易忽略的完整度標準\"\u003e\u003c/a\u003e只靠提示詞容易忽略的完整度標準\u003c/h2\u003e\n\u003cp\u003e許多氛圍式程式設計指南著重於撰寫更詳細的指示。然而，真正左右完整度的其他要素是\u003cstrong\u003e可驗證性、變更控制、可觀察性、安全邊界\u003c/strong\u003e。\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#1-%E5%B0%87%E9%A9%97%E6%94%B6%E6%A2%9D%E4%BB%B6%E8%BD%89%E6%8F%9B%E6%88%90%E6%B8%AC%E8%A9%A6\" class=\"anchor\" id=\"1-將驗收條件轉換成測試\"\u003e\u003c/a\u003e1. 將驗收條件轉換成測試\u003c/h3\u003e\n\u003cp\u003e不要只說「讓它正常運作」，而應成對提供輸入與預期輸出。重要的分類案例應保留為迴歸測試，以確認後續變更仍能維持結果。\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#2-%E4%B8%8D%E8%A6%81%E5%B0%87%E4%BB%A3%E7%90%86%E7%9A%84%E8%87%AA%E6%88%91%E8%A9%95%E4%BC%B0%E7%95%B6%E4%BD%9C%E6%9C%80%E7%B5%82%E8%AD%89%E6%93%9A\" class=\"anchor\" id=\"2-不要將代理的自我評估當作最終證據\"\u003e\u003c/a\u003e2. 不要將代理的自我評估當作最終證據\u003c/h3\u003e\n\u003cp\u003e代理表示「已完成」與測試通過是兩回事。應要求回報執行的命令、測試結果、變更檔案與未解決風險，並由人員檢視 diff。\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#3-%E5%B0%87%E6%AC%8A%E9%99%90%E8%88%87%E7%A5%95%E5%AF%86%E8%B3%87%E8%A8%8A%E6%9C%80%E5%B0%8F%E5%8C%96\" class=\"anchor\" id=\"3-將權限與祕密資訊最小化\"\u003e\u003c/a\u003e3. 將權限與祕密資訊最小化\u003c/h3\u003e\n\u003cp\u003e不要一次提供不必要的目錄、正式環境資料庫或部署憑證。API 金鑰不要直接放入提示詞或儲存庫，應使用環境變數或經核准的祕密管理系統。不要向來源不明的 MCP 伺服器或指令碼提供敏感儲存庫的存取權限。\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#4-%E8%A6%81%E6%B1%82%E5%8F%AF%E8%A7%80%E5%AF%9F%E7%9A%84%E7%A8%8B%E5%BC%8F%E7%A2%BC\" class=\"anchor\" id=\"4-要求可觀察的程式碼\"\u003e\u003c/a\u003e4. 要求可觀察的程式碼\u003c/h3\u003e\n\u003cp\u003e自動化工作應保留各階段狀態、結構化錯誤、執行時間、處理筆數等查找故障原因所需的資訊。另一方面，應從日誌中移除驗證資訊與個人資料。\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#5-%E8%AE%93%E8%AE%8A%E6%9B%B4%E5%8F%AF%E4%BB%A5%E5%BE%A9%E5%8E%9F\" class=\"anchor\" id=\"5-讓變更可以復原\"\u003e\u003c/a\u003e5. 讓變更可以復原\u003c/h3\u003e\n\u003cp\u003e不要將無關的重構與功能新增混在同一次變更中。以小單位檢視 diff 並記錄於版本控制中，就能更容易分離並復原錯誤變更。\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#claude-code-%E5%B0%88%E6%A1%88%E7%87%9F%E9%81%8B%E6%8A%80%E5%B7%A7\" class=\"anchor\" id=\"claude-code-專案營運技巧\"\u003e\u003c/a\u003eClaude Code 專案營運技巧\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e將反覆使用的專案規則簡短、具體地記錄在 \u003ccode\u003eCLAUDE.md\u003c/code\u003e 中。\u003c/li\u003e\n\u003cli\u003e以實際可執行的形式提供建置、測試與 lint 命令。\u003c/li\u003e\n\u003cli\u003e不要將祕密資訊、一次性錯誤日誌或冗長參考文件放入 \u003ccode\u003eCLAUDE.md\u003c/code\u003e。\u003c/li\u003e\n\u003cli\u003e大規模變更前，先要求調查相關檔案與相依關係。\u003c/li\u003e\n\u003cli\u003e新增套件時，檢視其必要性、授權條款與維護風險。\u003c/li\u003e\n\u003cli\u003e不要自動核准危險的刪除、部署與資料變更命令。\u003c/li\u003e\n\u003cli\u003e連接外部 API 或 MCP 前，先確認資料會傳送到何處。\u003c/li\u003e\n\u003cli\u003e完成時，要求摘要說明變更檔案、執行命令、測試結果與剩餘限制。\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003e\n\u003ca href=\"#%E6%8F%90%E4%BA%A4%E5%89%8D%E6%AA%A2%E6%9F%A5%E6%B8%85%E5%96%AE\" class=\"anchor\" id=\"提交前檢查清單\"\u003e\u003c/a\u003e提交前檢查清單\u003c/h2\u003e\n\u003cul\u003e\n\u003cli\u003e 是否已說明使用者與使用情境\u003c/li\u003e\n\u003cli\u003e 是否已區分目標與非目標\u003c/li\u003e\n\u003cli\u003e 是否已明確指定既有技術與禁止變更的範圍\u003c/li\u003e\n\u003cli\u003e 是否已定義輸入資料與輸出格式\u003c/li\u003e\n\u003cli\u003e 是否已說明分類值與狀態值的意義\u003c/li\u003e\n\u003cli\u003e 是否具備空結果、驗證失敗、逾時與部分失敗的政策\u003c/li\u003e\n\u003cli\u003e 是否已逐步區分計畫與實作\u003c/li\u003e\n\u003cli\u003e 是否具備正常、邊界與失敗案例的測試\u003c/li\u003e\n\u003cli\u003e 是否已從提示詞與日誌中排除祕密資訊和個人資料\u003c/li\u003e\n\u003cli\u003e 是否要求提供供人員檢視的 diff 與執行證據\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003e好的 Claude Code 提示詞，重點不在於把命令寫得很長，而在於減少需要代理猜測的部分，並讓第三方也能重現並判定結果是否正確。\u003c/p\u003e\n","tags":["提示詞工程","測試框架工程","Claude Code","AI 程式設計","程式設計代理"],"faqs":[{"question":"Claude Code 提示詞越長越好嗎？","answer":"比起長度，更重要的是是否以結構化方式納入工作所需的資訊。背景、目標、限制、輸出契約、例外處理與完成條件應具體說明，但最好移除不相關的說明與重複指示。"},{"question":"不能從一開始就要求建立完整的程式嗎？","answer":"若是小型獨立工具則可以，但同時涉及外部 API、資料庫、電子郵件與排程執行的工作，採取分階段開發會比較安全。先檢視儲存庫調查結果與計畫，再依最小功能、測試、外部整合的順序擴充，會更容易釐清失敗原因。"},{"question":"使用 Plan Mode 就可以省略測試嗎？","answer":"不可以。計畫模式有助於在變更前檢視結構與方法，但無法證明實際程式碼的正確性。實作後仍須另外執行自動化測試、靜態分析、變更內容檢視，以及必要的手動確認。"},{"question":"CLAUDE.md 中應該寫些什麼？","answer":"適合寫入會在多項工作中反覆使用的指示，例如專案結構、程式碼撰寫規範、建置與測試指令，以及不得修改的區域。最好不要放入 API 金鑰、密碼、個人資料、一次性工作說明，以及過長的參考資料。"},{"question":"提出錯誤修正請求時，應提供哪些資訊？","answer":"應一併提供已移除敏感資訊的錯誤訊息與堆疊追蹤、執行指令、最小重現輸入、相關環境、實際行為與預期行為。也最好要求提供原因說明、最小範圍的修正、迴歸測試與執行結果。"},{"question":"可以透過提示詞將 API 金鑰傳給 Claude Code 嗎？","answer":"原則上，不應在提示詞或原始碼中直接記錄真實的 API 金鑰。應使用經核准的環境變數或祕密管理系統，並確保驗證資訊不會暴露在日誌與測試結果中。"},{"question":"提示詞中一定要寫明重試次數和等待時間嗎？","answer":"若是營運自動化，區分可重試的錯誤與應立即中止的錯誤很重要。不過，具體次數與等待時間應在確認外部服務的限制、工作的緊急程度及重複處理風險後決定，不應無條件重試所有錯誤。"},{"question":"如何判斷產生的程式碼是否已完成？","answer":"應依據事先訂定的驗收條件判斷。確認必要功能與例外案例是否通過測試、執行過哪些指令、變更了哪些檔案，以及是否符合效能或安全限制，並由人工檢視程式碼變更內容。"}],"sources":[{"url":"https://docs.anthropic.com/en/docs/claude-code/overview","title":"Claude Code 概覽","type":"source"},{"url":"https://www.anthropic.com/engineering/claude-code-best-practices","title":"Claude Code：代理式編碼的最佳實務","type":"source"},{"url":"https://github.com/anthropics/claude-code","title":"Anthropic Claude Code GitHub 儲存庫","type":"source"}],"images":[{"id":845,"url":"https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MTExNTQsInB1ciI6ImJsb2JfaWQifX0=--9f2d2e2c8a61fc294a6019e4807ece297f36e85a/ai-4caeb237.webp","is_representative":true,"generation_method":"ai_photo","license":"ai_generated","mime_type":"image/webp","translations":{"ko":{"alt":"코드와 작업 흐름이 표시된 대형 모니터 앞에서 작업하는 개발자","caption":"개발자가 여러 화면의 코드와 문서를 검토하며 작업하고 있다.","description":null},"en":{"alt":"Developer working at a desk with code and a workflow diagram on a large monitor","caption":"A developer reviews code and documentation across multiple screens.","description":null},"ja":{"alt":"コードとワークフロー図を映した大型モニターの前で作業する開発者","caption":"開発者が複数の画面でコードとドキュメントを確認している。","description":null},"es":{"alt":"Desarrollador trabajando frente a un monitor grande con código y un diagrama de flujo","caption":"Un desarrollador revisa código y documentación en varias pantallas.","description":null},"id":{"alt":"Pengembang bekerja di depan monitor besar yang menampilkan kode dan diagram alur kerja","caption":"Seorang pengembang meninjau kode dan dokumentasi di beberapa layar.","description":null},"pt":{"alt":"Desenvolvedor trabalhando diante de um monitor grande com código e diagrama de fluxo","caption":"Um desenvolvedor analisa código e documentação em várias telas.","description":null},"zh-hant":{"alt":"開發人員在顯示程式碼與工作流程圖的大型螢幕前工作","caption":"開發人員正透過多個螢幕檢視程式碼與文件。","description":null},"de":{"alt":"Entwickler vor einem großen Monitor mit Code und einem Ablaufdiagramm","caption":"Ein Entwickler prüft Code und Dokumentation auf mehreren Bildschirmen.","description":null}}},{"id":846,"url":"https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MTExNjAsInB1ciI6ImJsb2JfaWQifX0=--285d7ecdc8209e07e0fc4eb68085cd8a304b9a81/ai-062b34c5.webp","is_representative":false,"generation_method":"ai_image","license":"ai_generated","mime_type":"image/webp","translations":{"ko":{"alt":"코드 편집기가 열린 노트북과 요구사항, 표, 오류, 버전 관리, 성과 차트를 연결한 개발 워크플로","caption":"체계적인 프롬프트가 코딩 결과물의 검증과 완성도를 높이는 과정을 보여준다.","description":null},"en":{"alt":"Laptop code editor connected to requirements, tables, errors, version control, and performance charts","caption":"The workflow shows how structured prompts support validation and more polished coding results.","description":null},"ja":{"alt":"要件、表、エラー、バージョン管理、成果グラフにつながるコードエディター搭載ノートPC","caption":"構造化されたプロンプトがコードの検証と完成度向上を支える流れを示している。","description":null},"es":{"alt":"Portátil con editor de código conectado a requisitos, tablas, errores, versiones y gráficos de rendimiento","caption":"El flujo muestra cómo los prompts estructurados ayudan a validar y perfeccionar el código.","description":null},"id":{"alt":"Laptop dengan editor kode yang terhubung ke spesifikasi, tabel, galat, kontrol versi, dan grafik kinerja","caption":"Alur ini menunjukkan bagaimana prompt terstruktur membantu validasi dan penyempurnaan hasil kode.","description":null},"pt":{"alt":"Notebook com editor de código ligado a requisitos, tabelas, erros, controle de versão e gráficos de desempenho","caption":"O fluxo mostra como prompts estruturados ajudam a validar e aprimorar os resultados do código.","description":null},"zh-hant":{"alt":"筆電程式碼編輯器連結需求、表格、錯誤、版本控制與成效圖表","caption":"此流程呈現結構化提示如何協助驗證程式碼並提升成果完成度。","description":null},"de":{"alt":"Laptop mit Code-Editor, verbunden mit Anforderungen, Tabellen, Fehlern, Versionskontrolle und Leistungsdiagrammen","caption":"Der Ablauf zeigt, wie strukturierte Prompts die Prüfung und Verfeinerung von Code unterstützen.","description":null}}}],"published_at":"2026-08-23T02:30:01+09:00","updated_at":"2026-08-23T02:30:01+09:00","license":"cc_by","translation_status":"reviewed","available_locales":["ko","en","ja","es"],"data_locales":["ko","en","ja","es","id","pt","zh-hant","de"],"url":"https://injoys.com/en/articles/claude-code-prompt-six-principles-and-templates"}