iterative-retrieval

iterative-retrieval 技能總覽

iterative-retrieval 技能是一種用來解決 agentic 工作中「上下文問題」的工作流程模式：子代理一開始掌握的資訊太少，不知道自己真正需要什麼，接著再逐步縮小範圍，找到正確的檔案、術語與模式。它最適合工作流程設計者、程式碼庫探索者，以及任何在建立 iterative-retrieval for Workflow Automation、而且首輪檢索通常不完整的人。

使用者通常在意的不是理論，而是這個技能能不能幫代理避開兩個常見失誤：送進去的上下文太多，超出成本；或送得太少，導致卡住。iterative-retrieval 的主要價值，在於它把探索變成迴圈，而不是一次性的猜測。

iterative-retrieval 解決了什麼問題

當任務依賴無法事先知道的程式碼庫脈絡時，就該使用這個技能：例如找出實作模式、辨識相關檔案，或在第一次搜尋後再修正搜尋詞。當代理必須在沒有人工直接指引的情況下推理大型 repo 時，它尤其有用。

iterative-retrieval 為什麼不同

不同於一般只會說「先四處看看再決定」的提示詞，iterative-retrieval 提供的是具體的檢索迴圈：派送、評估、修正、重複。這讓你更容易編排子代理，尤其是在你的流程需要可預測的上下文成長，而不是大量、雜亂輸出時。

iterative-retrieval 最適合的使用情境

這個技能適合架構探索、RAG 風格的程式碼探索，以及首輪檢索刻意不完整的多代理工作流程。若答案本來就很靠近、repo 非常小，或你可以一開始就給出精確的檔案清單，它的效益就比較有限。

如何使用 iterative-retrieval 技能

安裝並啟用 iterative-retrieval

先用你的 skill manager 安裝技能路徑，再把代理工作流程指向 skills/iterative-retrieval/SKILL.md。在這個 repo 裡，典型的 iterative-retrieval 安裝方式是：

npx skills add affaan-m/everything-claude-code --skill iterative-retrieval

若要得到最佳效果，請在任務依賴上下文探索時就呼叫它，不要等到你已經手動整理好所有相關檔案之後才使用。

把模糊目標改成可用的提示詞

這個技能最有效的情況，是你的提示詞能同時給代理一個目標、一個邊界，以及一個停止條件。強而有力的輸入會像這樣：

• 目標：“Find the auth flow and explain where token refresh is handled.”
• 邊界：“Search only production code, not tests.”
• 限制：“Keep each retrieval pass under a few files.”
• 成功條件：“Return the smallest file set that supports a confident answer.”

這一點很重要，因為 iterative-retrieval usage 的核心是逐步修正上下文，而不是叫模型靠一個模糊請求就推斷整個 repo。

先讀這些檔案

先從 SKILL.md 開始，再查看 repo 提供的任何支援文件。在這個 repo 裡，實際入口仍然是 SKILL.md；如果你的安裝只複製了技能本文，那它就是唯一的事實來源。之後，如果你的環境中還有鄰近的工作流程文件，也請一併檢查，這樣才能把迴圈與你自己的編排規則對齊。

跑起檢索迴圈

一個好的流程是：先發出窄範圍搜尋，評估回傳的上下文是否足夠，再根據缺少的資訊修正下一次搜尋，然後重複，直到代理有足夠證據可以採取行動。關鍵在於，把每一輪新發現的術語帶進下一輪，而不是只是換個說法重送同一個問題。

iterative-retrieval 技能 FAQ

iterative-retrieval 只適合大型程式碼庫嗎？

不是。規模會影響效果，但真正的觸發條件是不確定性。只要代理在閱讀前無法預測哪些檔案重要，iterative-retrieval 即使在中等大小的 repo 裡也能派上用場。

什麼情況下不該使用 iterative-retrieval？

當任務範圍已經很清楚、相關檔案已知，或直接提供固定輸入的提示詞就足夠時，就不要用 iterative-retrieval。在這些情況下，迴圈只會增加額外成本，卻不會讓答案更好。

這比一般提示詞更好嗎？

對探索型任務來說，是。一般提示詞常常假設模型能先猜到正確上下文；而 iterative-retrieval 指南更適合在讀過部分結果後調整提示，並且最終答案確實取決於這種調整的情境。

iterative-retrieval 適合新手嗎？

適合，只要你照著迴圈真的做。最大的學習門檻不是語法，而是要先選出一個夠小、能派上用場，同時又夠廣、能帶出正確術語的首輪檢索。

如何改進 iterative-retrieval 技能

讓第一輪更精準

最大的品質提升，來自更好的初始框架。不要只說「找相關程式碼」，而是指定某個行為、子系統，或決策點。把你已知的內容、你推測的方向，以及什麼才算有用線索都寫進去。這會讓 iterative-retrieval usage 效率高得多。

留意常見失敗模式

最常見的失敗是檢索過量：代理拉回太多檔案，結果反而停止從結果中學習。另一種失敗是檢索不足：上下文太少，無法辨識下一個搜尋詞。如果第一輪回來的是很泛的檔案，與其把搜尋範圍拉得更大，不如改問術語、呼叫點或進入點。

用證據迭代，不要用猜測

第一輪輸出之後，只回饋最有資訊量的材料：檔名、函式名稱、錯誤訊息，或陌生術語。不要在沒有新增證據的情況下，只叫代理「再看一次」。對 iterative-retrieval for Workflow Automation 來說，最強的改進方式，是把這個證據迴圈直接編進你的編排中，讓每一輪都能改變搜尋空間。

依照你的 repo 規則調整

如果你的環境有命名慣例、資料夾邊界，或代理交接規則，就要在第一次檢索前把它們寫進提示詞。這個技能最強的時候，是它會尊重你 repo 的真實結構，而不是把每個程式碼庫都當成同一種通用搜尋問題。