30 人团队如何让 Agent 对话默认携带源码解读

30 人团队、每人每天多次对话，全量预载有三个致命问题：token 成本爆炸、上下文窗口挤占、解读过期。Claude Code、Cursor、Devin 等业界产品演化出的标准架构是：

L0 解决「问什么都先懂这个仓库」，L1/L2 解决「问到具体函数时能看到真代码」。只做 L0 会答不准，只做 L1/L2 每次都要重新摸索、又慢又贵。

业界事实标准：AGENTS.md 是正在形成的开放规范（OpenAI Codex CLI、Cursor、Gemini CLI 等均已支持），Claude Code 使用 CLAUDE.md。文件放在仓库里随代码走，每次对话自动加载，无需任何人手动粘贴。

落地示例：仓库根目录放一份「平台架构总览」，server/src/services/ios/ 放「iOS 内存剖析服务的设计与坑」，client/ 放前端结构说明。半小时即可让全组受益。

👉 每人环境各不相同时如何同步？见下方专题一。

方案 A 的短板是靠人维护会过期。解法是让 AI 在 CI 里自动生成和更新解读：

• 每次合入 main 触发流水线：用 agent 对变更模块重新解读，更新仓库里的 docs/codebase-brief.md（或直接更新 AGENTS.md 的附录段落）；
• Cognition 的 DeepWiki 是该模式的公开产品化（对 GitHub 仓库生成 wiki 式解读），可参考其产物结构：架构图、模块职责表、数据流说明、FAQ；
• 关键纪律：解读文档是生成物，进 Git 但打上「自动生成」标记，避免和手写文档漂移。

建一份全队共享的代码索引（embedding + BM25 混合检索效果最好）：

• 商用：Cursor 的 codebase indexing、Sourcegraph Cody，开箱即用；
• 自建：对代码做 AST 感知切片（按函数/类切，不按固定行数切）→ embedding → 存入向量库 → 30 人共用一份索引，建一次索引全员复用，这是团队级规模效应所在；
• 注入方式：对话开始时根据用户问题检索 top-k 相关片段自动注入。Aider 的 tree-sitter repo map 是该思路的轻量版（不建向量库，只给符号骨架）。

MCP（Model Context Protocol）是当前 agent 生态的事实标准协议。团队部署一个共享 MCP server，暴露 search_code / get_module_architecture / find_symbol（LSP 语义跳转，如开源的 Serena）等工具，每个人的 agent 客户端连接同一个 server。好处：

• 解读结果不占上下文，agent 需要时才调用，成本可控；
• 换 agent 客户端不用重做集成，协议通用（DSH 内部已捆绑 MCP SDK，具备接入基础）。

👉 内部知识库如何对使用者保持闭源？见下方专题二。

30 人共用同一段 L0 常驻解读时，务必走 prompt / context caching（Anthropic、OpenAI、DeepSeek 均支持）：相同前缀的缓存命中后成本降到原价的约 10%，且首 token 延迟大幅下降。如果团队统一走自建网关（如 LiteLLM），可以在网关层强制给每个请求注入同一段简报前缀——「默认加载」不再依赖每个人自觉配置，而是被平台保证的。

持久记忆适合存个人偏好和历史结论（「这位同事负责 websocket 模块」），不适合存代码事实——代码事实会过期，且记忆系统天然缺乏「随代码演进」的机制。团队级代码知识应优先使用 A–E。

结论：能用，而且方案 A 恰恰是最不怕环境差异的。它的同步机制非常干净——AGENTS.md 是仓库里的普通文件，走 Git 同步，不依赖任何人的本地配置，git pull 下来就有。这正是它成为业界标准的原因：把「agent 需要知道什么」当代码资产的一部分管理，而不是每个人的私有配置。

1. 同步机制拆解：哪些走 Git，哪些天生就是个人的

关键认知：这个体系故意把内容分成两类——代码知识进 Git（全队共享、随代码演进），个人偏好留本地（互不干扰）。你不需要「把每个人的环境同步成一样」，需要同步的只有前者，而前者本来就是 Git 的本职。

2. 「每个人环境不一样」逐条对上

30 个人只要都能 git clone 这个仓库，方案 A 就自动对全员生效，零额外配置。

3. 让它长期不腐烂的工程纪律

• 单一事实源：解读只存在于仓库的 AGENTS.md 里，严禁用 IM / 邮件 / 网盘传副本——副本一旦出现，漂移就开始了；
• 当代码审：AGENTS.md 的改动走 PR + code review，可在 CODEOWNERS 里指定架构负责人必须审批；
• .gitignore 加一条：AGENTS.local.md / CLAUDE.local.md，防止个人偏好误提交污染全队；
• CI 卡口（衔接方案 B）：流水线加轻量检查——AGENTS.md 存在、体积不超预算（如 16 KB）、覆盖的模块与目录结构对得上，人工忘更新时 CI 提醒；
• 模块负责人制：根文件管全局，子目录文件由对应模块 owner 维护，避免单文件变成 30 人都在改的冲突热点。

4. 两个常见坑

• 坑 1：把个人偏好写进仓库级 AGENTS.md。比如「回答请用中文」，一个人写了 30 人被动继承——这类内容放 AGENTS.local.md 或 ~/.dsh/AGENTS.md；
• 坑 2：靠「分发文件」来同步。一旦有人手动复制 AGENTS.md 到别处，就产生了第二事实源。记住：唯一的分发渠道是 Git。

结论：可以，而且「内容闭源」恰恰是 MCP 相对方案 A / C 的核心优势。这源于 MCP 的根本特性——信任边界反转：方案 A 和 C 是把知识「分发」到每个人手里（文件、索引），MCP 是把知识「留在服务端」，别人只能隔着接口问。你的知识库、源码、索引、embedding 一 byte 都不用离开你的基础设施。

1. MCP 客户端到底能看到什么？

服务端的实现代码、知识库原文、向量索引、embedding、内部文档——全都不在协议暴露面上。用户拿到的只是「问 → 答」的结果流，就像你可以调用一家公司的客服，却不可能拿到它的内部手册。

2. 闭源架构：把 MCP 做成「知识网关」而不是「文件代理」

关键设计决策：暴露什么粒度的工具，决定了泄露多少。

最强闭源形态：工具内部做「RAG 检索 → 服务端 LLM 合成 → 只回传最终答案」，调用方的 agent 从头到尾没见过任何原始切片，只见过结论——「给答案，不给语料」（answer, not corpus）。

3. 先认清「闭源」能做到哪一步

针对右列的配套管控（均为 MCP 服务端的标准做法）：

• 认证 + 授权：每人独立 token（MCP 规范 2025-06-18 版内置 OAuth 2.1 授权框架）；按角色开放不同工具——正式员工全套、外包只给 ask_kb、访客只读模块地图；
• 审计日志：每次工具调用留痕（谁、何时、问了什么、返回多少）——方案 A / C（文件在各人机器上）根本做不到，MCP 让「知识访问」从不可观测变成完全可观测；
• 限流 + 异常检测：单用户 QPS / 日配额；检测「遍历式提问」模式（短时间内系统性扫全库）并熔断；
• 输出整形：单次返回长度上限；引用只给文档 ID + 段落号不给原文；敏感字段打码；
• 工具描述本身别泄密：schema 的 description 是明文发给客户端的，不要写内部术语和系统细节。

4. 必须直面的权衡：输出越「闭」，调用方 agent 的推理能力越弱

「内容可闭源」= 知识库原文能否不给使用者；「访问可审计」= 能否留痕谁在何时问了什么。两项都是 MCP（方案 D）的独有优势，详见专题二。

补充：一个现成的参照物

本团队环境中已有一个 xnu-source-analysis 技能——它就是「预制源码解读结果打包成可复用知识」的活样本（XNU 内核内存管理源码的结构化解读笔记，按需加载）。这与方案 B 的产物形态是同一件事：把解读沉淀为随仓库演进的资产，而不是每次对话现场重读源码。