

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

## 一个老项目，换人如换血

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

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

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

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

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

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

![1.png](https://developer.qcloudimg.com/http-save/yehe-11177336/d00b655f5d41dcaf2d1629982861b34e.png)


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

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

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

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

![2.png](https://developer.qcloudimg.com/http-save/yehe-11177336/7428ef93f3f23472556b8b7407bd14bb.png)


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

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

## 项目探测到底探测什么

![3.png](https://developer.qcloudimg.com/http-save/yehe-11177336/51326b6679ef6a211d6abe4738be51be.png)


"项目探测"这个词不是行业标准叫法，但意思很准——给项目做一次体检，把 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 会不会犯一个自己无法恢复的错误？

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

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

![4.png](https://developer.qcloudimg.com/http-save/yehe-11177336/1bebadbb62fcc13297b320003d992925.png)


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

**第一层：常驻简报（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 代码索引、或者知识图谱。这层解决的是"具体文件在哪"，静态层解决的是"该往哪个方向想"，两者不冲突。

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

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

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

## 给老项目的落地清单

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

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

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


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

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

高级软件开发工程师

编程语言

开发工具

人工智能

项目探测通过AGENTS.md等机器可读文件固化老项目隐性知识，让AI编码代理避免重复冷启动探索，降低token消耗与改错风险。采用分层上下文与按摩擦迭代策略，从空文件起步、增量添加高价值约束，配合CI自动保鲜，实现写一次省百次的高杠杆知识复用。

知识图谱

集成测试

代码解释

数据流

路由

Agent

ReAct 

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

项目探测：把老项目的知识变成 AI 的外部记忆-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐