项目探测：把老项目的知识变成 AI 的外部记忆

换个人接手老项目，光理解代码就要一周；换一个 AI Agent 接手，每次对话都要把理解过程重来一遍，还按 token 收费。项目探测（project probing）就是在代码库里放一份"机器可读的项目说明书"，让 AI 在开始探索之前先有地图，让知识从代码和人的脑子里，变成可持续更新的外部记忆。

一个老项目，换人如换血

先说结论：老项目最贵的资产不是代码，是代码里没写出来的那部分知识。为什么这么说，拆开看。

一个跑了几年的项目，代码量通常在几十万行往上。新人接手要搞明白的事包括：这个系统到底是干嘛的、为什么当年选了这个方案而不是那个、目录为什么长这样、哪些文件是地雷改不得、构建和测试的命令到底是什么、部署到哪、和哪些外部系统有隐含的契约。这些信息分散在 README、wiki、代码注释、聊天记录，以及最关键的------老成员脑子里。

传统解法是靠传帮带：新人问、老人答，两三个月出徒。这事本身效率就不高，但好歹能沉淀。到了 AI 时代，问题变了性质。

AI 编码 Agent 比新人聪明，但它有个致命的特性：每次会话都是冷启动。它不记得上次对话理解过什么，下次进来又是一个"很聪明但完全不知道你这项目是干嘛的"的实习生。更麻烦的是，它理解项目的成本是可见的、按 token 计费的------一次探索消耗几万 token 很正常，而它走错方向改错文件导致的返工，比 token 本身贵得多。

所以"让 AI 自己翻代码"不是免费的，是所有理解方式里最贵的一种。

为什么 AI 理解老项目这么贵

贵在四个层面，一层比一层隐蔽。

第一层，探索是线性成本。 Agent 理解一个仓库靠的是读文件、跑 grep、看目录结构，一步步拼出全貌。这不像人有直觉和上下文，它必须真的把文件读进去。一次会话花 5 万到 10 万 token 在"理解项目"上，是常态。按现在的模型价格粗算，Claude Sonnet 级别的输入价格 $3/Mtoken左右，一次5万token的探索就是3/M token 左右，一次 5 万 token 的探索就是$ 3/Mtoken左右，一次5万token的探索就是0.15------看着不多，但一天几十次会话、一个团队几个人都在重复这个成本，而且每一次都是全额重付，因为 Agent 不记得上次。

第二层，探索路径不对会改错东西。 这是比 token 更贵的隐性成本。Agent 不知道"支付逻辑必须放在 konordo_payments 模块里"这种约定，就可能在错误的位置堆代码，或者"修复"一个本来不是 bug 的东西。返工一次的人力成本，抵得上几百次探索的 token。

第三层，上下文窗口被挤占。 一个 20 万 token 的窗口，一半拿来装探索到的文件内容和工具输出，留给真正推理和生成代码的空间就少了一大截。有人统计过典型的会话预算：文件读取约 40%、工具输出约 25%、推理约 20%、用户提示约 10%、系统提示加项目上下文文件（缓存后）只占约 5%------而文件读取恰恰是最好优化的部分。上下文不是免费资源，它挤占的是模型"想清楚"的能力。

第四层，知识只存在于人的脑子里。 老项目的关键约束往往没有任何文档记录："这个表不能改结构，下游有定时任务在跑""这个模块处于维护冻结期""这个接口返回格式和文档不一致，以代码为准"。这些是团队用几个月的时间踩坑换来的，AI 读一万遍代码也读不出来。知识不外部化，换谁（人还是 AI）都得重新踩一遍。

把这四层放一起看，本质就一句话：你缺的不是更好的 Agent，而是一个让 Agent 少做无用探索的项目上下文。

项目探测到底探测什么

"项目探测"这个词不是行业标准叫法，但意思很准------给项目做一次体检，把 AI（和人）上手所需的知识探测出来、固化下来。业界对应的实际产物是这么一族东西：

AGENTS.md：跨工具的项目上下文文件，仓库根目录放一份，Agent 开工前自动读。OpenAI Codex 推广，后来交给 Linux Foundation 旗下的 Agentic AI Foundation 托管，目前是事实上的开放标准，6 万多个开源仓库在用，Copilot、Codex、Cursor、Gemini CLI、Zed、Aider、Warp、Devin、Windsurf 等 40 多种工具都认它。
CLAUDE.md：Claude Code 的项目上下文文件，作用和 AGENTS.md 相同，单工具绑定。
llms.txt ：Jeremy Howard（fast.ai 和 Answer.AI 联创）2024 年 9 月提的提案，给"网站/文档"用的 AI 清单------告诉模型这个站点最重要的是哪些页面。Anthropic、Cloudflare、Perplexity 自己都发布了。思路和项目探测一脉相承：给 AI 一张精选清单，而不是让它自己翻遍所有内容。
代码→上下文转换工具：code2prompt（Rust，7k+ star，能把整个代码库打包成单文件 prompt，带 token 计数、git 上下文、MCP server）、gpt-repository-loader、open-repoprompt 这类，适合一次性把仓库喂给模型，属于"探测"的自动化手段。
索引与检索层：vectorcode、codemap 这类给代码库建索引、按需拉取相关片段；Sourcebot 自托管代码理解；GitNexus 做知识图谱加 Graph RAG；cocoindex-code 用 tree-sitter 索引代码、返回紧凑的相关片段来压低 agent 的上下文用量。
生成与保鲜工具：AI Agent Context Optimizer 这类 GitHub Action，在 CI 里自动分析代码库、生成或更新 AGENTS.md 草稿；Drift 这类工具做架构漂移检测，帮你看代码是不是已经跑得和文档不一样了。
成本监控：BurnRate、Burnd、skillreaper 这类工具解析 Agent 的会话记录，找出哪些上下文被加载了却从没用上------量化 token 浪费，然后剪掉。

这里要分清两件事：项目探测 ≠ 把 README 翻新一遍 （那是给人看的，AI 看了作用有限）；项目探测也不等于全量 RAG 索引（索引解决"找得到"，解决不了"该往哪个方向想"）。探测的核心动作是：把"代码里读不出来、但做决定时必须知道"的知识，写成一份机器可读、人也能维护的文件。

一个必须正视的反面证据

写到这里，如果我只报喜不报忧，那这篇文章就白写了。2026 年 2 月，ETH Zurich 的 SRI Lab 和 LogicStar.ai 发了一篇论文（Gloaguen et al.，ICLR 2026 Workshop），题目就叫《Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?》，第一次严格测了这类上下文文件到底有没有用。结论相当打脸：

LLM 生成的上下文文件，让任务成功率降了 2%~3%，比完全不提供还差，推理成本却涨了 20% 以上；
开发者手写的上下文文件，成功率提升约 4%，但成本同样涨了近 20%，平均每个任务还多走了约 4 步；
Agent 不是没读文件------它们忠实执行了，工具调用频率涨到原来的 2.5 倍。问题是指令越多，探索越多，步数越多，路径反而更长；
关键发现：LLM 生成的文件大部分内容是在重复仓库里已有的文档和 README。当研究者把文档文件从仓库里移除后，同样的上下文文件反而带来了 2.7% 的提升------说明它的信息不是没用，而是重复。你在给 Agent 一份它自己翻两下就能看到的地图，然后还收它两份阅读费。

这篇论文传递的信息不是"别做项目探测了"，恰恰相反：它证明了探测文件的内容选材才是成败的关键。 冗余的代码库概述是噪音；真正有价值的是"仓库里找不到、开发者脑子里才有"的信息------工具链偏好、工作流要求、约定俗成的边界、不能碰的禁区。论文的建议也直接：从空文件开始，按实际摩擦增量添加（start empty, build incrementally），每条指令都要问一句：去掉它，Agent 会不会犯一个自己无法恢复的错误？

这跟"团队成员持续更新"的做法正好咬合：一次性生成、然后忘掉的探测文件，注定要烂掉。它必须是一个活的、跟着代码演进的东西。

推荐做法：分层上下文 + 按摩擦迭代

综合上面这些，我给老项目的落地建议是四层结构，成本从低到高，价值密度从高到低：

第一层：常驻简报（AGENTS.md / CLAUDE.md），这是杠杆最大的一步。 放"代码里找不到的东西"，严格控制在 60~100 行以内：

项目是干什么的，一句话说清，不写营销话术；
技术栈和版本，精确到"Node 22 + TypeScript strict + Fastify 5 + PostgreSQL 16 via Drizzle"，不是"React 项目"；
可执行命令，带参数：pnpm test:run、pnpm lint:fix，让 Agent 能原样照跑；
硬性不变量和禁区：哪些文件绝不能动、哪些约定是代码风格之外的（"结果对象用 Result<T, E>，见 src/lib/result.ts"）；
指向深层文档的指针，而不是把深层文档塞进来。

一个可以起步的骨架：

markdown 复制代码

# AGENTS.md

> 项目：XX 交易中台。核心约束：资金类操作必须走统一账务模块，禁止绕过。

## 命令
- 开发：pnpm dev
- 类型检查：pnpm check
- 测试：pnpm test:run（单测）+ pnpm test:integration（集成）
- Lint：pnpm lint:fix（提交前必须跑）

## 架构
- 服务：api（Fastify 5）/ worker（BullMQ 消费账务事件）/ admin（React 面板）
- 数据流：订单 → 账务模块（唯一写库入口）→ 事件 → worker
- 目录约定：路由在 src/api/routes/，查询只进 src/repositories/，禁止在路由里写 SQL

## 硬约束
- 永不修改 src/db/migrations/ 下已提交的迁移文件
- 外部依赖引入前先和团队确认
- 所有新接口必须有集成测试才能合入

## 详细文档
- 部署与运维：docs/agent/deployment.md
- 账务一致性设计：docs/agent/accounting.md

第二层：按需文档，渐进式披露。 细节放 docs/agent/ 或模块级嵌套的 AGENTS.md 里，根文件只给指针。Monorepo 里每个 package 可以有自己的 AGENTS.md，离改动文件最近的优先。OpenAI 自己的主仓库就放了 88 个嵌套的 AGENTS.md，这是这个模式在大规模仓库上的实证。注意一个坑：写"详见 docs/xxx.md"等于没说，Agent 大概率不会主动去读。要么把关键段落直接粘进上下文文件，要么用工具显式引用。

第三层：动态检索，按任务拉取。 大仓库光靠静态文件不够，再配一层索引------语义搜索、tree-sitter 代码索引、或者知识图谱。这层解决的是"具体文件在哪"，静态层解决的是"该往哪个方向想"，两者不冲突。

第四层：保鲜机制，这是老项目最容易栽的地方。 代码每天都在动，探测文件一周不更新就开始骗人。三个手段：

把"更新探测文件"写进 PR 的完成定义（Definition of Done）------改了架构、动了目录、加了约束，必须同步改探测文件，和"跑了测试"一个级别；
用 Agent 审计漂移------定期让 Agent 对比探测文件描述和代码现状，标出不一致（Drift 这类工具就是干这个的）；
按摩擦迭代------从空文件开始，谁（人或 AI）发现 Agent 反复犯同一个错、反复问同一个问题，谁就往里加一条。加进去的每条指令都要能通过"去掉它会犯无法恢复的错误"的检验。

最后算一笔账：一份 100 行的探测文件，一次性写入的成本远小于一次探索浪费的 token；写入后被缓存，每次会话按十分之一的价格计费，只占预算的 5% 左右。而它换来的是一次次免于冷启动、免于走错方向的正确率。写一次，省一百次。这笔账怎么算都划算------前提是文件里的内容对，且不烂。

给老项目的落地清单

真要动手，别想一步到位，按这个顺序来：

用一个代码→上下文工具（code2prompt 这类）跑一遍，拿一份自动生成的仓库全景当草稿------它只当清单用，不当成品；
人工修剪：删掉所有"代码里本来就有的信息"，只留"代码里读不出来的知识"；把文件压到 100 行以内；
从空开始也行------直接放一个最小 AGENTS.md（项目一句话 + 命令表 + 禁区），然后按摩擦增量添加，这是 ETH 那篇论文数据最支持的路子；
定规矩：更新探测文件进 PR 流程；架构变动必须同步；
三个月后跑一次漂移审计，把烂掉的部分修回来。

项目探测这件事，本质上是把"团队记忆"工程化。代码是事实，文档是历史，探测文件是给机器看的地图。地图不用详尽到每条街，但必须标对关键的路口和雷区------标错了，比没有地图更糟。