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 技能

安装并激活它

先用你的 skill manager 按技能安装路径安装，然后把 agent 工作流指向 skills/iterative-retrieval/SKILL.md。在这个仓库里，典型的 iterative-retrieval 安装方式是：

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

为了获得最佳效果，应当在任务依赖上下文发现时再调用它，而不是等你已经手工筛选完所有相关文件之后才用。

把模糊目标改写成可执行提示词

这个技能最适合的输入，是同时给代理一个目标、一个边界和一个停止条件。好的输入应当像这样：

• 目标：“找出认证流程，并说明 token refresh 是在哪里处理的。”
• 边界：“只搜索生产代码，不看测试。”
• 约束：“每一轮检索不要超过几份文件。”
• 成功条件：“返回能支撑明确结论的最小文件集合。”

这一点很重要，因为 iterative-retrieval usage 关注的是上下文的逐步收敛，而不是让模型靠一句模糊请求去猜整个 repo。

先读这些文件

先看 SKILL.md，再检查仓库提供的任何配套文档。在这个 repo 里，最实用的入口依然是 SKILL.md；如果你的安装只复制了 skill 本体，那它就是唯一可信来源。之后，再看看你环境里附近的 workflow 文档，方便把这个循环和你自己的编排规则对齐。

跑通检索循环

一个好的流程是：先发起一次窄范围搜索，判断返回的上下文够不够，再根据缺失的信息细化下一次搜索，然后循环，直到代理拥有足够证据可以行动。关键在于，把每一轮新发现的术语继续带到下一轮里，而不是只换个说法重复同一个查询。

iterative-retrieval 技能 FAQ

iterative-retrieval 只适合大型代码库吗？

不是。规模很重要，但真正的触发条件是不确定性。如果代理在阅读前无法预测哪些文件重要，iterative-retrieval 即使在中等规模 repo 里也很有帮助。

什么时候不该用它？

当任务边界已经很清晰、相关文件已知，或者用一个带固定输入的直接提示就足够时，不要用 iterative-retrieval。在这些情况下，循环只会增加开销，不会提升答案质量。

它比普通提示更好吗？

对于发现类任务，是的。普通提示常常默认模型能提前猜中正确上下文。iterative-retrieval 指南更适合那种必须在阅读部分结果后继续调整提示、而最终答案又依赖这种调整的场景。

它对新手友好吗？

友好，只要你严格按循环来做。最大的上手门槛不是语法，而是如何选择第一次检索：既要足够小，真的有用；又要足够宽，能把正确术语暴露出来。

如何改进 iterative-retrieval 技能

让第一轮目标更精准

最大的质量提升，往往来自更好的初始 framing。不要只说“找相关代码”，而要明确具体行为、子系统或决策点。把你已经知道的、你怀疑的，以及什么算得上有价值的线索都写进去。这样 iterative-retrieval usage 会高效得多。

关注常见失败模式

最常见的失败是过度检索：代理拉回太多文件，结果反而停止从结果中学习。另一种失败是检索不足：上下文太少，连下一步该搜什么都不知道。如果第一轮只返回了很泛的文件，就不要简单扩大搜索范围，而应改为要求给出术语、调用点或入口点。

用证据迭代，不要靠猜

第一次输出后，只反馈最有信息量的内容：文件名、函数名、错误信息，或者不熟悉的术语。不要在没有新增证据的情况下，只让代理“再看看”。对于 iterative-retrieval for Workflow Automation 来说，最有效的改进，是把这套证据循环编码进你的编排逻辑里，让每一轮都真正改变搜索空间。

让它适配你的仓库规则

如果你的环境里有命名规范、目录边界或代理交接规则，一定要在第一次检索前就写进提示词。这个技能最强的时候，是它尊重你的仓库真实结构，而不是把每个代码库都当成通用搜索问题来处理。