一、一段"高度相关"的代码，来自一个已经删除的模块
你让 Agent 处理一个任务：给订单取消流程加幂等处理——同一个订单重复取消，第二次要返回已经取消的结果，而不是报错。为了避免它到处乱翻，你打开了代码检索工具，让它先检索相关实现。
它检索回来五条片段，其中一条看起来非常对口：一个名为CancelOrderHandler的类，里面有完整的幂等判断逻辑，甚至有注释写着"重复请求返回上一次结果"。它基于这条片段给出了方案：在CancelOrderHandler里补一个分支，复用已有的幂等键逻辑。
问题是，这个类在半年前的架构调整里已经被删掉了，替代它的是order_service.py里的一个函数。检索工具不知道这件事，因为它的索引建立在那之前的某个时间点，而且从此没有再更新过；更细一点说，索引里存的是当时那份代码的快照，而代码库早就往前走了。
你的评审如果不够仔细，就会进入一个尴尬的局面：一个基于不存在的类写出来的方案，看起来完整、命名一致、逻辑自洽，却无法落地。修改它的成本甚至比从零开始更高——你要先解释为什么这个类不存在，再重新讨论方案。
这一篇处理的就是这一类问题：检索系统告诉你"这段代码和问题相关"，但它不会告诉你"这段代码还是当前版本"。相关内容与正确内容是两件事，中间需要一层版本信息来连接。
把这件事放到日常节奏里看，它出现的频率比想象的高：新同事入职时看的项目文档、上个季度整理的技术方案、从其他团队复制过来的示例代码——它们都带着"曾经正确"的属性，而使用它们的人常常默认"现在也正确"。代码检索只是把这个问题工程化、规模化地呈现出来。处理方式也一致：给材料带上来源和时间，在使用前校验一次。
二、先把几个词讲明白
检索：从一大堆材料里找出和问题相关的一小部分。你搜关键字是检索，向量搜索也是检索，代码检索工具是检索，RAG 这个说法里的 R 也是检索。
RAG：先检索、再把检索到的内容交给模型生成答案的做法。它的好处是模型不必"记住"所有代码，坏处是它会对检索回来的内容照单全收——包括过期的内容。
相关性分数：检索结果和查询的接近程度的数值。分数高说明"像"，不说明"对"。生活里的类比是图书馆找书：目录系统能告诉你"这本书和你的题目接近"，但不能告诉你"这本书里写的是旧版规范"。
索引：为了让检索变快而建立的数据结构。对于代码来说，索引是一份快照——某个时刻的代码被切块、编号、存储下来。索引不会自动跟随代码更新。
切片（chunk）：把长文件切成一段一段，方便检索和放入上下文。切片的问题是上下文会被截断：一个函数的前后条件、调用者、被调用者都可能被切开，剩下的片段看起来仍然"相关"。
符号全名：函数、类、方法在代码里的完整名字，比如OrderService.cancel_order。它是判断"这段片段是否还有效"最直接的线索——符号改名或者删除，检索结果里的引用就失效了。
元数据：附加在材料上的信息：来自哪个仓库、哪条分支、哪个提交、什么时候索引、文件内容哈希。元数据不参与相关性打分，但它决定了你能不能判断这份材料的时效。
失效（stale）：材料曾经正确、现在不再描述现实。索引失效是最常见的失效形式：代码变了，索引还停在过去。
引用头：放在片段前面的一小段说明，写清来源、版本和用途。它不参与检索，但决定了这段材料进入上下文时是"事实"还是"历史参考"。
三、为什么"相关"不能保证"正确"
3.1 检索的目标是相似度，不是真实性
检索系统的设计目标是"从大量内容里找出最有可能有帮助的一小部分"。它对"有可能有帮助"的度量方式是相似度：词重合、语义接近、结构相仿。这个度量对时效性是完全无感的——一段三个月前的代码，和今天的问题可能比当前代码更"像"，因为旧代码里可能恰好有一段更贴近你描述的注释。
于是出现一个反直觉的现象：越具体的旧片段，越容易被检索系统排到前面。一段包含详细的幂等处理、注释完整、命名清晰的旧代码，在相似度上往往胜过当前版本里那段写得朴实、几乎没有注释的替代实现。检索没有错，它忠实执行了它的规则；错的是把它返回的结果当作了当前事实。
3.2 代码有三个容易出错的维度
具体到代码检索，失效集中在三个维度上：
第一是位置。文件被移动、重命名、拆分，让片段里的路径和行号不再指向原来的内容。位置失效最容易被发现，因为你打开那个路径会发现不存在或者内容对不上。
第二是版本。同一条分支上的代码前后不同，不同分支上的同一路径内容也可能不同。检索索引如果建立在旧提交上，或者在多个分支之间混着建，返回的片段就和你手上的工作区不一致。版本失效最隐蔽，因为路径存在、内容也合理，只是它属于过去。
第三是符号。函数被重命名、类被删除、方法被移动，片段里的符号在新代码里不再存在。符号失效会以"无法解析"的形式暴露，但前提是你去验证。
三个维度可以同时出现，也可以各自独立。判断时需要逐个查：路径对不对、版本对不对、符号在不在。
还有一个补充的观察：三个维度里，"位置"和"符号"可以靠一次搜索发现，"版本"不能。路径存在、符号存在、代码看上去也合理，但它是旧版本的——这种失效在表面上没有任何异常。所以在三种校验里，版本校验的优先级最高，也最容易被跳过，因为它不像"文件不存在"那样会主动把你的注意力拉过来。
3.3 索引是快照，代码是活的
索引的构建过程通常是：扫描代码、切块、计算表示、写入存储。整个过程发生在某个时间点，之后索引就静止了，除非有人再次构建。代码则在持续变化：合并、回滚、重构、删除。两条时间线一旦分开，索引就开始积累失效内容，而且它积累的速度和团队的提交速度相关。
这里有一个容易忽略的后果：索引的失效不会自我暴露。一条索引记录不会"过期变红"，它只是在被使用时给出一个过去的答案。发现失效的唯一办法，是在使用的那一刻去校验它——这就是为什么元数据和校验流程是这套机制里不可替代的部分。
换个角度说，索引把"时间"这个维度藏起来了：它保存了内容，却没有保存"这份内容属于哪个时刻"的意识。使用者的工作，就是把时间维度补回去——补的方式就是元数据和校验。理解这一点之后，"为什么要多存几个字段"就不再是额外的负担，而是让检索结果可用的前提条件。
3.4 用元数据把"相关性"升级成"可用性"
让检索结果变得可用的方法很朴素：给每条结果附带足够的元数据，让使用者在用之前能自己判断。一个最小集合是六项：
仓库 + 路径 片段来自哪里 分支 它在哪条分支上有效 提交（commit） 索引时刻对应的提交 符号全名 片段里主要符号的完整名字 行号范围 片段在文件里的位置 索引时间 + 哈希 何时索引、内容指纹六项的作用各不相同：路径和符号回答"它是什么"；分支和提交回答"它是什么时候的"；行号和哈希回答"它还是不是原样"。后两项是校验依据——把片段对应的文件当前哈希算出来，和记录里的哈希比一比，就能知道这一块内容有没有变过。
有了元数据，使用规则也可以固定下来：使用前两步校验，任何一步不通过就重新读取当前文件，不要继续用缓存片段。
第一步，校验版本：索引记录的提交是不是当前工作区的版本（或者至少在同一个分支且没有涉及该文件的改动）？
第二步，校验内容：当前文件的哈希和记录里的是否一致？
两步都通过，可以放心使用；有一步不通过，就以当前文件为准，并把索引记录标记为需要重建。
3.5 引用格式：让"我看到的是哪一版"写清楚
校验之外，还有一个成本极低的习惯：给每一条进入上下文的代码片段加上引用头。格式可以用三行：
来源：src/orders/services/order_service.py#L41-L58 版本：main@9f3c1ab（2026-09-29） 校验：哈希一致，内容与索引时相同三行的作用，是让"我看到的是哪一版"从脑子里的一团印象变成纸面上的事实。它同时服务于三件事：评审时能核对；任务结束后能追溯；下次任务能直接复用（如果版本没变，这三行就是现成的）。
还有一个细节：当片段来自历史参考（失效但可借鉴的内容）时，引用头要显示不同的措辞：
来源：src/orders/handlers/cancel_handler.py（模块已删除） 版本：feature/old-arch@8d0a1f2（2026-03-11） 用途：仅参考幂等设计思路，实现勿参照"用途"这一行是给模型看的指令，它把"这段内容和现状无关"这件事明确说出来了。没有这一行，历史片段和当前片段在上下文里的地位是一样的。
四、完整例子：五条检索结果，逐个校验
4.1 任务与检索
任务（虚构示例）：shop订单服务要改进取消流程的幂等性——同一个订单重复调用取消，第二次返回"已取消"的结果，而不是报错；审计事件不能因为重复请求而多写。
你允许 Agent 使用代码检索工具，要求它把检索结果的原样元数据一并写出。它返回了五条片段，整理成一张表：
| # | 来源路径 | 符号 | 分支 | 提交 | 索引时间 | 判定 |
|---|---|---|---|---|---|---|
| 1 | src/orders/handlers/cancel_handler.py | CancelOrderHandler | feature/old-arch | 8d0a1f2 | 2026-03-11 | 失效（模块已删除） |
| 2 | src/orders/services/order_service.py | OrderService.cancel_order | main | 9f3c1ab | 2026-09-28 | 可用 |
| 3 | src/orders/generated/order_api_client.py | OrderApiClient.cancel | main | 9f3c1ab | 2026-09-28 | 排除（生成代码） |
| 4 | src/orders/repositories/order_repo_old.py | OrderRepoOld.save | main | 4c2e77a | 2026-06-02 | 失效（备份文件） |
| 5 | src/orders/domain/order.py | ensure_cancellable | main | 9f3c1ab | 2026-09-28 | 可用 |
（示例数据。）五条结果里，真正可用的只有两条，一条来自旧分支、一条属于生成代码、一条属于备份文件。如果不做校验，直接把这五条一起交给模型，它有很大概率会把第一条当成主线实现来参考——因为它在语义上最"对口"。
4.2 校验过程
对每一条做两步校验，过程写下来：
# 第一步：版本校验（索引提交 vs 当前 HEAD） $ git rev-parse HEAD 9f3c1ab... # 当前 main 的提交 # 索引提交 = 9f3c1ab 的片段通过版本校验； # 索引提交为 8d0a1f2、4c2e77a 的片段需要进一步检查文件是否存在。 # 第二步：内容校验（文件哈希 vs 索引哈希） $ git ls-files -s src/orders/services/order_service.py 100644 7be2... 0 src/orders/services/order_service.py # 与索引记录里的哈希一致 -> 该片段与索引时内容相同，可以直接使用（示例输出。）校验里有两个细节值得注意。第一个是"版本校验不通过但内容校验通过"的情况：比如索引提交较旧，但该文件此后没有变过——这种情况下片段依然可用，只要把它标注为"内容一致、版本较旧"。第二个是"文件不存在"的情况：路径src/orders/handlers/cancel_handler.py在当前分支查不到，这条结果直接判失效，不需要再做内容校验。
4.3 校验之后的使用方式
校验完，把结果分成三类，交给模型时的处理方式也不同：
| 类别 | 片段 | 处理方式 |
|---|---|---|
| 可直接使用 | #2、#5 | 原样给出，附带元数据 |
| 排除 | #3（生成代码） | 不进入上下文，说明原因 |
| 失效参考 | #1、#4 | 可作为历史背景，必须标注"模块已删除，勿参照" |
注意第三类不是"删掉不用"。旧架构里的幂等设计可能包含有价值的思路：幂等键怎么生成、重复请求怎么识别、审计事件怎么去重。这些思路可以借鉴，但借鉴的前提是明确知道它不是现状——所以标注"勿参照实现、仅参考思路"比直接丢弃更合理。
4.4 模型在这两种输入下的差别
同一个任务跑两遍（示例记录）：一遍把五条片段不加标注地给出去，一遍用上面校验之后的输入。
第一遍的方案是围绕CancelOrderHandler展开的：它建议在处理器里加幂等分支、复用CancelOrderHandler的键生成逻辑，还建议把新字段加进这个类的构造函数。方案的每一句都建立在一个不存在的类上，评审时需要从头解释。
第二遍的方案落在order_service.py和domain/order.py上：它先确认了当前是函数式编排，然后给出"在取消用例中读取已有审计事件"的幂等判断，并把"重复请求不新增审计事件"写进了改动说明。这个方案和当前代码结构一致，验收条件也直接可测。
两次的差别不在于模型的判断能力，而在于输入是否描述了一个真实存在的世界。给过期材料，就是在请它对一个不存在的世界做设计。
这也解释了为什么"校验"不该被视为对模型的不信任。它和给人类新同事准备材料是同一件事：你会告诉新同事"这份文档是去年的，接口已经改了，以代码为准"。模型需要的正是同一句话，因为它的处境和新同事一样——没有历史，只能从材料里判断现状。
4.5 把校验做成流程里的一个动作
校验不该依赖人的细心。把它做成一个固定动作，两种做法都可以：
第一种，在检索工具的输出里自动附带元数据（路径、分支、提交、索引时间、哈希），并在使用规则里写明"元数据缺失的片段不得使用"。成本在于工具改造，收益是全覆盖。
第二种，用一个很小的脚本做批量校验：读入检索结果列表，对每一条查git rev-parse和文件哈希，输出"可用 / 版本较旧 / 失效 / 缺失"四类。脚本不需要复杂，二十行左右就够；它把"我知道要校验"变成"每次都会校验"。
两种做法都需要一个前提：索引本身要带元数据。如果索引只存了文本和分数，那么无论用什么流程，你都无法判断时效。这件事在引入检索工具时就该问清楚：它记录什么、更新频率如何、支持不支持按分支索引。
4.6 索引怎么维护才不容易失效
维护索引有三条可用的策略，按成本从低到高：
第一条是定期重建。每天或者每次合并之后重跑一次索引构建。它的好处是简单，坏处是两次构建之间仍然存在窗口期的失效；对变化快的仓库，窗口期可能正好覆盖你这次任务。
第二条是按分支分别建索引，并只使用当前分支的索引做检索。这能解决"同一条路径在不同分支内容不同"的问题，代价是索引数量和构建频率上升。
第三条是按需校验，也就是前面说的使用前两步校验。它不依赖索引是否最新，代价是每次使用多两个查询。实践中最稳的组合是第二条加第三条：分支独立，使用前再校验一次内容。
无论选哪种，都建议把"索引版本"写进使用记录：这次任务用的索引对应哪个提交、构建时间是什么。出现"检索给的片段和现状不符"时，第一时间能定位到索引的年龄。
4.7 结果进上下文之前的整理动作
校验完成之后、把材料交给模型之前，还有一个三十秒的整理动作，顺序固定：
1. 去掉重复：同一符号的多个切片只保留最完整的一段 2. 补上边界：被切片截断的函数，补回签名和关键注解 3. 加上引用头：来源、版本、校验结论三行 4. 标注用途：可用 / 仅参考思路 / 排除（排除项不放进上下文） 5. 记录清单：本次用了哪几条、来自哪个提交第一步和第二步对应切片的固有缺陷：检索按块工作，块边界常常切在函数中间，删掉了签名或者参数说明。补回边界比"多给几段"更有效——多给几段会重新引入噪音，补边界只补齐理解所必需的部分。
第五步的清单建议随手写进任务的记录文件。它的作用在下次任务才完全显现：同一个模块的任务反复出现时，你能看到"哪些片段每次都要用"，这些片段就值得从检索结果升级成第一层材料。
4.8 那个二十行脚本长什么样
上一节说"二十行左右就够"，下面把它写出来。脚本读一份检索结果清单，逐条对比当前工作区：文件还在不在、内容哈希和索引时是否一致。
# tools/check_snippets.py：逐条校验检索结果是否仍然可用# 用法：python tools/check_snippets.py snippets.tsv# 清单每行格式：相对路径<TAB>索引时记录的哈希前缀importhashlibimportpathlibimportsysforlineinpathlib.Path(sys.argv[1]).read_text(encoding="utf-8").splitlines():ifnotline.strip():continuepath,_,recorded=line.rpartition("\t")p=pathlib.Path(path)ifnotp.exists():print(f"失效{path}文件已不存在")continuenow=hashlib.sha256(p.read_bytes()).hexdigest()[:12]ifnotrecorded:print(f"待补{path}结果里没有版本元数据")elifnow==recorded:print(f"可用{path}哈希一致{now}")else:print(f"较旧{path}索引{recorded}-> 现在{now}")运行结果（示例）：
$ python tools/check_snippets.py snippets.tsv 可用 src/orders/services/order_service.py 哈希一致 4a91c0f7d2e8 较旧 src/orders/repositories/order_repo.py 索引 88b0e5c1ff02 -> 现在 1c73ba90dd41 失效 src/orders/legacy/cancel_v1.py 文件已不存在 待补 docs/design/error-codes.md 结果里没有版本元数据四类输出对应四种处理动作。可用的片段带引用头直接用；较旧的先重读当前文件再决定去留，因为内容变了不等于不相关，可能只改了注释或者格式；失效的直接从材料里删掉，同时记一笔"索引里还留着已删除的文件"，这是索引该维护的信号；待补的最有用——它提醒你这条结果来自一个不记录版本的来源，单独看它时没有任何时效保障，只能作为线索，不能作为现状依据。
还有一条边界要写清楚：哈希一致只说明文件本身没变，不代表这段代码在架构里还有效——举例来说，order_repo.py一个月没改过，但调用它的服务层已经换了一套事务边界，那段片段作为"现状"依然会误导人。所以哈希校验解决的是"文件变没变"，剩下的判断仍然靠引用头里的两行：这段片段说明了什么、这次打算怎么用它。
怎么检查脚本真的在起作用：故意做一次破坏性试验。把清单里某一行的哈希改掉一个字符，重跑，脚本应该把这条标成较旧。如果它仍然输出可用，说明哈希那一段没生效，常见原因是脚本读的是一个缓存副本而不是当前文件。这个试验值得在接入检索工具的头一周做一次，它能证明你的校验链条真的连着工作区。
五、反例与代价：四种让检索误导人的做法
5.1 反例一：看分数不看元数据
做法：按相关性分数从高到低取前几条，直接放进上下文。
它为什么看起来能行：分数是检索系统给出的唯一量化指标，用它排序是最自然的做法。
最后的代价是"高分过期"被优先使用。前面说过，旧片段常常因为注释更完整、描述更具体而获得更高分。分数高的片段反而更容易是失效的——这个反直觉现象解释了为什么很多团队一开始用检索时觉得效果很好（索引新鲜），过了一段时间就开始出现"引用了不存在的东西"（索引变旧）。
值得补一句的是，这个问题不会自然好转。索引越用越旧，除非有人重建；团队提交越快，索引和现状的差距越大。把一个"使用前校验"的动作加进流程，是这类问题的唯一系统性解法——它不是一次性修复，而是每次使用都要经历的一道门。
5.2 反例二：索引不记录版本
做法：索引里只存文本和向量，不记录提交、分支和时间。
它为什么看起来能行：存储更省、构建更快，检索出来照样能用文本做对比。
最后的代价是失效不可判断。使用者无法区分"这段代码还是原样"和"这段代码三个版本前就改了"；工具无法提示"这条结果来自已删除的文件"。更麻烦的是责任模糊：出问题时你会归咎于"模型乱说"，而实际原因是系统没有提供判断依据。修复的代价也会高——往往需要重建整套索引结构。
5.3 反例三：把缓存片段当现状使用，从不重读
做法：第一次检索之后把片段缓存起来，后续任务直接复用，不再读文件。
它为什么看起来能行：省钱省时间，尤其是多次迭代同一个任务的场景——每次都重读文件既慢又啰嗦。
最后的代价是缓存和代码分叉。同一个任务的多次迭代之间，代码可能已经被改动（包括被模型自己改的）；继续用旧片段做判断，就会出现"它对着一小时前的代码讨论现在的修改"。实用的折中方案是给缓存设一个短的有效期，并在做关键判断（改代码、定方案）之前重读涉及的文件——缓存用于探索，重读用于决策。
5.4 反例四：把生成代码、备份文件、测试夹具都纳入索引
做法：索引整个仓库，不做过滤。
它为什么看起来能行：覆盖全面，谁知道哪段代码有用呢；过滤规则本身也需要维护。
最后的代价是噪音进入结果。生成代码（协议客户端、脚手架）、备份文件、测试夹具、示例配置，在语义上和主线实现高度相似，很容易排到结果前列。检索系统不可能替你判断"这段是生成的，不要改"；它只知道内容像。过滤应该发生在索引构建阶段：通过路径规则排除生成目录和备份文件，或者至少给它们打上类型标签，让使用规则能区分对待。
有一点需要澄清：这四种反例的共同特征是"看起来更省事"。不做校验省一次查询，不记录版本省几个字段，缓存复用省一次读文件，不过滤省一次配置。它们每一个单独看都很划算，代价却统一落在"判断依据不可靠"上——而依据不可靠时，省下来的时间会以返工的形式加倍还回去。
六、落地步骤：让检索结果带着版本使用
七步里，前三步是"了解你的索引"，中间三步是"使用前校验"，最后一步是"把结果变成经验"。如果团队刚开始使用检索工具，可以先做第 2、3、4、5 步——它们直接决定结果能不能用；第 1 步和第 7 步属于长期维护，可以稍后补齐。
第一步，盘点索引覆盖范围。写清楚索引包含哪些仓库、哪些分支、哪些路径被排除。为什么先做这一步？因为索引里有什么，决定了你能检索到什么；索引里混着什么，决定了结果会有哪些噪音。怎么检查：随机抽三条结果，核对它们是否都在当初声明的范围内。
第二步，确认每条结果带齐元数据。六项：路径、分支、提交、符号、行号、索引时间与哈希。为什么元数据必须检查？因为它是后面所有判断的依据，缺一项就有一条校验做不了。怎么检查：把三条结果的元数据摊开看，字段是否齐全、是否可解析。
第三步，做版本校验。拿索引提交和当前工作区对比：一致就通过；不一致就查涉及的路径有没有变化。为什么以路径为粒度？因为你不需要整仓库一致，只需要"这个文件没变"。怎么检查：脚本能输出通过或者"需进一步检查"的明确结论。
第四步，做内容校验。计算当前文件哈希，和索引记录比对；不一致就重新读取当前文件。为什么哈希比时间戳可靠？因为时间戳可能因为检出、格式化等原因变化，而内容哈希只对内容敏感。怎么检查：故意修改一个文件后跑校验，确认结果从"通过"变成"不一致"。
第五步，按类别处理结果。可用（元数据齐全、两项校验通过）、版本较旧但内容一致（标注后可用）、失效（文件不存在或者已被替换，只作历史参考）、排除（生成代码、备份文件、夹具）。为什么分类而不是丢弃？因为历史参考仍然有价值，只要标注清楚。怎么检查：每一类是否都有对应的处置说明。
第六步，把校验写进流程。用脚本或者工具规则固化：检索结果先过校验，再进入上下文。为什么必须固化成流程？因为人的注意力会被"看起来对"的内容带走，这一步靠自觉维持不了。怎么检查：把校验脚本故意跳过一次，看看交付质量有没有变化。
第七步，记录并复盘。每次任务记录：用了几条结果、几条失效、失效的类型分布。为什么值得记？因为失效分布直接提示索引策略该往哪调整——如果失效集中在某个目录，可能是那个目录变化太快需要更频繁的构建；如果集中在某条分支，可能是分支索引策略需要改。怎么检查：下一轮任务里，失效比例有没有下降。
可复制的使用清单：
[ ] 检索结果六项元数据齐全（路径/分支/提交/符号/行号/索引时间+哈希） [ ] 版本校验：索引提交与当前工作区一致，或涉及文件未变 [ ] 内容校验：文件哈希一致 [ ] 失效结果已分类：可用 / 较旧可用 / 仅历史参考 / 排除 [ ] 所有进入上下文的结果都带来源标注 [ ] 索引构建时间与覆盖范围已记录 [ ] 本次任务的失效统计已回填七、常见问题
问：检索分数高，是不是就代表更应该采纳？
不是。分数衡量的是"像不像"，不是"对不对"。在代码检索里，分数高的片段常常是描述详细、注释完整的旧代码——它们因为信息密度高而更容易和你的问题匹配。正确的采纳顺序是：先校验元数据（路径、分支、提交、哈希），再按校验结果分类，最后才考虑相关性。把分数当排序依据可以，把它当质量依据不行。
问：怎么知道索引是什么时候建的、覆盖哪些分支？
问工具或者看记录，两个问题的具体形式是：“上次构建时间"和"支持按分支过滤吗”。如果工具没有提供，要在使用规范里写清楚"元数据缺失的检索结果不得直接使用"，并把这件事当成选型时的评估项。索引的构建时间是这套机制里最重要的一个数字，它决定了所有结果的"新鲜度上限"。
问：旧代码里的设计思路确实有用，怎么用才安全？
把"思路"和"实现"分开使用。做法是：对失效片段做一次提炼，把可借鉴的部分写成两三句原则（比如"重复请求通过唯一键识别、审计按事件键去重"），标注来源和"已废弃"的说明；把实现细节整体排除。这样它进入上下文时是一段历史经验，而不是一段可以照抄的代码。提炼还有一个附带好处：写原则的过程会逼你自己确认"这条思路在当前架构下还成立吗"。
问：索引重建的成本高，做不到很频繁，怎么办？
两条路可以并行。第一条是分层构建：变化频繁的目录（业务代码）高频重建，变化少的目录（基础设施、脚本）低频重建，各自记录构建时间。第二条是把校验作为兜底：无论索引多旧，使用前都做版本和内容校验，失效的当场剔除。分层解决"尽量新鲜"，校验解决"万一不新鲜也不出错"。两者结合，索引频率就不再是单点风险。
问：团队同时在多个分支上工作，索引该怎么建？
优先保证"当前分支可用"。三种做法按复杂度排列：只索引默认分支，使用时把结果当作"默认分支的参考"，并且必须校验；按分支分别建索引，检索时只用当前分支的索引；按需构建，谁需要谁触发。无论哪种，都要在使用记录里写明"本次结果来自哪条分支的索引"，否则评审时无法判断结论的适用范围。
问：生成代码应该纳入索引吗？
默认不纳入。生成代码（协议客户端、序列化类、脚手架）有两个问题：内容多、和主线实现相似度高，挤占结果位置；改动它通常没有意义（下次生成会覆盖）。如果确实需要检索生成产物（比如确认某个字段名），把它单独标记为一类，使用时明确"这是生成代码，只读取不做修改"。测试夹具、示例配置同理：可以用，但要能被识别出来。
问：检索和直接读文件，哪个更好？
它们分工不同，理想流程是"检索定位、读文件确认"。检索的作用是从大范围里找到候选，成本低、覆盖广；读文件的作用是拿到权威内容，成本略高、结果可信。把两者连起来的方式是前面说的校验：检索给出候选和元数据，校验判断时效，最后读文件确认内容。跳过读文件直接使用片段，就等于把候选当成了结论。
问：模型自己带检索能力时，怎么约束它的输出？
用格式约束。要求它在引用代码时使用固定格式：路径 + 符号 + 提交（或"当前工作区"），没有这三项的引用不采信。这条要求有两个作用：迫使它区分"检索到的"和"确认过的"；让你在评审时一眼看出哪些结论有依据。如果它无法提供提交信息（比如工具不支持），就要求它把引用范围限制在"这次提供的材料里"，超出范围的内容必须明确标注"未验证"。
问：怎么尽早发现"看起来很对但其实过期"的结论？
三个信号值得记住。第一，提到的符号在当前代码里搜不到——直接判定失效。第二，路径对不上（文件不存在或者内容完全不符）——同样判定失效。第三，描述的行为和当前测试矛盾——这时以测试为准，回头检查材料。三个信号都能用很低的成本检查：搜一次符号、打开一次路径、跑一次测试。把这三步固定成"引用检查"，就能拦下大部分过期结论。
问：索引里的内容被删除了怎么办？
删除有两种含义，处理方式不同。一种是文件被整体删除（重构、功能下线），索引记录要保留但标记为"已删除"，检索时默认不返回，需要时作为历史参考。另一种是文件还在、内容被改写，这时索引的切片会指向一段已经不存在的内容——这类记录在内容校验时会失败，按"重新读取"处理。两种情况的共同点是：不要因为校验失败就静默丢弃记录，而是把它标记出来，因为失效记录本身是有用的数据——它能告诉你索引哪一部分在快速变化。
问：怎么让"校验"不影响正常的检索速度？
把校验分成两档。快档只做版本校验里的一个动作：比较索引提交和当前提交是否相同——相同就直接通过，不做任何文件级检查；只有在提交不同时，才对涉及的少量文件做哈希校验。这样绝大多数请求只多一次很轻的比较，成本几乎可以忽略。慢档用于关键判断（改动代码之前、写进方案之前），对涉及的文件逐个开哈希校验。快档覆盖日常，慢档保关键路径——分级之后，"校验太慢"就不再是跳过它的理由。
问：如果团队还没有代码检索工具，这一篇还有用吗？
有用，因为"检索"的范围比你想象的宽。除专门的工具之外，还有三类常见的检索：在聊天里搜索以前贴过的代码片段（这类片段最容易过期）、在文档里搜索接口说明（文档比代码更容易过期）、以及从别处复制过来的示例代码（来源往往不明）。这三类都适用同样的规则：带着来源和版本使用，使用前校验。哪怕只是养成一个习惯——把来源、时间和"是否仍有效"三行写在每段材料前面——也能解决大部分问题。
问：校验失败之后，要不要立刻重建索引？
分情况。如果失败的是少数几个文件（大多数结果校验通过），不需要立刻重建——用"使用前重新读取"兜住就够了，重建可以按原计划进行。如果失败比例明显偏高（比如五条里三条失效），说明索引已经整体落后，这时候重建的收益大于成本，值得立刻做一次。判断依据最好来自记录：把每次任务的失效条数和总数记下来，比例的趋势比单次结果更有信息量——连续几次比例上升，就是重建或者调整策略的信号。
问：怎么把这一篇的规则讲给不用命令行同事听？
用一个生活化版本。把检索结果比作"图书馆里的旧剪报"：剪报说的事可能曾经是真的，但报纸出版的时间和现在的现实是两回事。使用前先看三样东西——出处（哪份报纸）、日期（什么时候的）、以及和手头资料对不对得上（有没有新版）。对不上就去查最新的原文，而不是直接照剪报办事。这套说法不需要任何术语，覆盖的规则和元数据校验完全一致：来源、时间、内容比对。
问：我的项目没有检索工具，这些还有用吗？
有用，只是形态不同。“检索结果"不只来自检索系统：编辑器里搜出来的片段、聊天记录里粘贴过的代码、同事口头描述的"我们那边是这么写的”，都是同一种东西，时效风险一模一样，甚至更高——它们连相似度分数都没有，你连"看起来有多相关"都判断不了。落到动作上还是三件事：给每个片段的来源标一条路径和一个时间；用它之前重读当前文件；把"只是参考思路"和"可以照着写"分开标注。这三件事不需要任何工具，而且一旦养成习惯，将来接入检索工具时你会自然地把同一套规则套上去。工具的作用是把人工动作变成自动动作，它不会替你决定什么是能用的证据。
八、动手练习与小结
练习：给你的检索结果加一层校验
如果你正在使用任何代码检索工具（或者只是习惯用关键词搜索加复制片段），按下面四步做一次。
第一步，挑一次最近的任务，把当时用到的片段找出来。没有留档的话，用检索工具重跑一次同样的查询，把前五条结果导出。为每一条补齐六项元数据：路径、分支、提交、符号、行号、索引时间与哈希；缺的字段先留空，空缺本身就是发现。
第二步，做两步校验。用git rev-parse HEAD确认当前提交；用当前分支的文件内容计算哈希，和索引记录比对。把每条结果标成"可用 / 较旧可用 / 失效 / 排除"。
第三步，重做一次那个任务（或者至少重做方案部分），这次只给校验后的结果，并且每条都带来源标注。记录方案的差异：它这次落在哪些文件上、有没有出现"引用了不存在的东西"。
第四步，把校验固化。写一个二十行左右的脚本批量做校验，或者在使用规范里加一条"检索结果先过校验"；把本次的失效统计（几条失效、原因是什么）记录下来，作为下一次调整索引策略的依据。
做完的产出是一份校验清单、一段校验脚本（或规范条文）、以及一份失效统计。第三次做同样的事情时，你会发现校验变成自动的了。
小结
这一篇讲的是检索结果的时效问题。核心结论有三条。第一，检索按相似度工作，相关性不提供版本证据；越具体的旧片段可能得到越高的分数，所以"看起来最对口"反而需要额外警惕。第二，代码失效集中在三个维度：分支、版本、位置（含符号），判断时要逐个检查；索引是快照、代码是活的，失效不会自我暴露。第三，解决方式是把元数据和校验固定进流程：六项元数据（路径、分支、提交、符号、行号、时间与哈希）、两步校验（版本、内容）、四类处置（可用 / 较旧可用 / 仅历史参考 / 排除）。
三个使用习惯值得带走：所有进入上下文的结果都带来源标注；历史材料标注"勿参照实现、仅参考思路"；把失效统计回填，用它调整索引策略，而不是凭感觉。
到这里，"材料怎么给"这条线走完了一个完整段落：上一篇讲一次修改的影响面怎么找——决定给哪些材料；这一篇讲检索回来的材料怎么校验——决定材料能不能用。两篇合起来是一套输入侧的卫生习惯：范围要准，材料要新。再往前接的是更早的两篇——材料按任务挑选，代码按接口与实现分层给。
从下一篇开始，主题转到输出侧的另一半：检查本身可靠不可靠。我们会从最常见的一句话开始——"测试通过"这四个字到底意味着什么，以及怎样把这句话变成可以被检查的证据。
补充：三条最容易执行的纪律
如果这一篇只能带走三件事，建议是下面三条，它们都能在十分钟内落地。
第一条，凡是用到检索结果，先看它的元数据是否齐全；不齐的先补齐，补不齐的就不要当作事实使用。这一条能拦下最常见的一类问题——把过去的代码当成现在的代码。
第二条，凡是要改代码或者写方案，涉及的文件必须重新读取一次；检索结果只用来定位，不用来确认。这一条把"缓存"和"决策依据"分开，避免对着旧版本讨论新问题。
第三条，凡是引用历史材料，写清"仅参考思路"或者"勿参照实现"。这一条让历史材料保持价值，同时不污染当前判断。
三条纪律都不需要新工具，只需要在流程里加几个动作。它们的共同目标是同一件事：让每一次判断都建立在"这一版代码"上，而不是"某一次看过的某一段代码"上。
补充：一张图记住整套机制
把这一篇的内容压成一条链，方便随时回想：
检索（相似度） → 元数据（它是哪一版） → 校验（版本 + 内容） → 分类（可用/较旧/历史/排除） → 引用头（来源 + 版本 + 用途） → 进入上下文 → 记录（用了什么、失效多少）链条上有两个位置最容易被跳过，也正是问题的高发点。一个是"元数据"——它决定了后面所有判断能不能做；另一个是"引用头"——它决定了模型能不能分辨事实和历史。把这两个位置补上，整条链就闭环了；缺任何一个，检索结果就会以"看起来对"的形式进入上下文。
还有一句提醒值得记下：链条的目的不是让检索变慢，而是让检索结果变得敢用。带着版本使用的结果，你可以直接拿去做方案、写改动、交给评审；不带版本的结果，你只能在心里给每条打一个问号，而这个问号会一直带到评审桌上。
补充：把这套习惯和已有流程接上
最后说怎么落地，不新增流程也能接上：
- 接在任务单的"材料"一节：写清本次检索使用了几条结果、来自哪个提交、校验结论如何。
- 接在评审清单里：加一条"引用是否带来源与版本"。
- 接在任务记录的回填里：加一行"失效条数 / 总条数"，用于观察索引健康度。
- 接在入职文档里：把"使用前校验、引用带来源"写成新人的默认习惯，而不是口口相传的默契。
四处接入点的共同点是，它们都是已经存在的动作，只是多写了一两行信息。这类"顺手就做"的改法，比新增一个独立流程更容易长期维持——流程会被人绕过，习惯不会。
