为什么不能直接让 AI 读全量代码？
大多数工程师使用 Claude Code 的方式是：遇到问题，让它读几个相关文件，然后回答。这在小项目里完全够用。但如果是 47 个开发维护了 4 年的 Spring Boot 单体、180K 行代码、模块间依赖错综复杂，一个业务改动往往牵扯 5 到 8 个 Service。
在这种场景下，用传统的“喂文件”方式让 Claude 读代码，有两个致命的“死穴”：
1. 上下文窗口（Context Window）的限制：Claude Code 拥有 200K tokens 的上下文，但一次深度分析很容易把它耗光。按每个 Java 文件 300 行、每行 10 tokens 估算，200K tokens 大约能装 600 个文件。读起来不少，但 Claude 读依赖时是递归的——你问一个 OrderService，它会连带读 PaymentService、InventoryService、UserService。读完一轮，上下文就已经满了一半。
2. 注意力稀释与低效：在全量读取 60 个文件时，真正和问题相关的可能只有 5 个。让 Claude 读完再找答案，相当于让一个工程师把整个代码库背一遍再回答你的问题，不仅极度缓慢，其注意力也容易被非关键代码稀释，从而导致幻觉或遗漏。
Model Context Protocol（MCP）的解决思路是反过来的：不是直接给 Claude 代码，而是给 Claude 智能检索代码的能力。这就像给一个新工程师 IDE 的搜索和跳转功能，而不是印一本 180K 行的代码全集强行塞给他。
工具数量超限的“静默失效”大坑
我们搭建的第一版 MCP Server 暴露了 60 个工具：按模块细分的依赖查询、按服务维度的接口列表、历史 PR 摘要、配置项检索等。在跑了两周后，我们发现 Claude 的表现时好时坏。有时候它能给出精准结果，有时候却说“我没有查询依赖关系的工具”。
我们一开始以为是 Prompt 调优问题，后来在官方仓库中发现了原因：当 MCP Server 注册的工具数量过多时，客户端在启动时可能会发生静默失败。没有任何报错和警告，工具就是直接消失了。根据社区反馈，10 个工具的 Server 极稳定，50 个工具的 Server 偶发失败，而 100 个以上的 Server 是高频失败。
这里还有一个隐藏维度：工具描述消耗的 Context 超乎想象。工具描述在对话开始前就会占用你的 Context 空间。如果暴露的工具过多，单单工具定义就能吃掉上万个 tokens。而且，研究表明当 LLM 面临超过 15-20 个工具选择时，会出现“认知过载”，开始混淆或选错工具。
我们的解法分两步：
第一步：合并工具，用参数区分意图
将原本按模块细分的 60 个独立工具，聚合成 12 个通用工具，用内部参数去承载具体的模块定位。
// ❌ 错误做法：4个独立工具
search_order_service_deps()
search_payment_service_deps()
search_inventory_service_deps()
search_user_service_deps()
// 正确做法：1个工具，用参数区分
search_service_dependencies(service_name: string)
// 同理，将多种查询模式合并
query_codebase(query: string, scope: "service" | "api" | "config" | "pr_history" | "metrics")
这一步将工具数量从 60 个直降到 12 个，工具描述占用的 Tokens 消耗减少了近 80%。
第二步：压缩描述至极限
工具描述只需要告诉 Claude「这个工具是干什么的」，而不需要教它「怎么去调用这个工具」——具体怎么调应当交给参数的 JSON Schema。我们将工具描述的平均 Tokens 从 87 压到了 15 左右：
// ❌ 优化前（87 tokens）
"description": "This tool allows you to search for dependencies between microservices in our Spring Boot monolithic architecture. Provide a service name to get a complete list of all services that depend on it and all services it depends on, including transitive dependencies..."
// 优化后（15 tokens）
"description": "Query service dependency graph. service_name: target service."
结构化代码检索的“三层设计”
在第一版架构设计中，我们走了一个严重的弯路：让 MCP 工具直接返回大段的 Service 代码文本。这相当于把“全量读文件”的问题转移到了工具返回阶段，并未解决根本问题。
我们重新设计了三层检索架构，遵循“高层级摘要 -> 符号定位 -> 局部获取”的递进逻辑：
第一层：意图识别层（Intent Recognition）
返回高度摘要的信息，帮助 Claude 判断“值不值得深挖”。平均每次只消耗约 200 tokens。
• 输入：{ service: "OrderService", depth: 1 }
• 输出：json{"direct_dependencies": ["PaymentService", "InventoryService"],"depended_by": ["ApiGateway", "BatchProcessor"],"last_modified": "2026-04-12","complexity_score": 7.2}
第二层：符号级查询层（Symbol Query）
精确定位到具体的函数或接口级别，告诉 Claude “应该去哪里读源码”。
• 输入：{ interface: "PaymentGateway" }
• 输出：json{"implementations": [{ "class": "AlipayGateway", "file": "src/payment/AlipayGateway.java", "line": 23 },{ "class": "WechatPayGateway", "file": "src/payment/WechatPayGateway.java", "line": 18 }]}
第三层：原文获取层（Text Retrieval）
仅在 Claude 锁定了具体文件和行号后，才按需调用该工具获取原文片段。
• 输入：{ file: "src/payment/AlipayGateway.java", start_line: 23, end_line: 80 }
• 输出：具体的 57 行代码片段（约 600 tokens）。
三层递进架构下，每次提问的 Context 消耗从平均 15,000 tokens 降到了 2,500 tokens 左右，降幅达 83%，同时回答速度和精确度明显提升。
LSP 集成：给 Claude 装上 IDE 的眼睛
仅仅能查文件和依赖还是不够的，当面对“这个 processPayment 方法在哪些地方被调用了”这类问题时，如果只用 grep 进行文本匹配，会将无关的注释、变量名、字符串里的同名内容全部搜出来。在大项目中，真正的调用路径必须通过 AST（抽象语法树）级别的语义分析来获取。
这正是 LSP（Language Server Protocol） 的核心长处。我们将开源的 cclsp 引入 MCP，暴露了 6 个核心 LSP 接口：
• find_definition(symbol: "PaymentGateway")
• find_references(symbol: "processPayment")
• rename_symbol(symbol: "processPayment", new_name: "executePayment")
• get_diagnostics(file: "src/payment/AlipayGateway.java")
LSP 与 Grep 的实测性能对比
在大规模 Spring Boot 单体库（180K 行）中，我们针对常见导航操作进行了实测：
| 导航任务 | 传统文本 Grep 搜索方式 | 集成 cclsp 语义导航方式 |
|---|---|---|
| 定位接口全部实现点 | 依赖文本匹配，易遗漏，平均耗时 ~30s | 100% 准确跨文件定位，耗时 ~30ms |
| 查找方法调用点 | 混杂大量注释/字符串，需人工过滤，耗时 ~45s | AST 级解析，无误报，耗时 ~50ms |
| 跨文件重命名 | 简单正则替换，极其危险，易改错 | AST 级修改，跨文件绝对安全，耗时 ~100ms |
| 实时语法诊断 | 不支持（无法实时发现编译错误） | 支持，精确获取行级语法 Warn/Error |
通过 LSP 赋能，Claude 拥有了与 IDE 等价的语义代码导航能力，定位和重构代码的错误率几乎降为零。
插件化打包：实现 Day 1 满配 Context Onboarding
我们完成这套 MCP 工具设计后，遇到了一个新的工程化问题：如何让几十个工程师迅速配齐这套环境？
“让大家去修改 ~/.claude/mcp.json，安装各种 npm 依赖，配置本地环境变量……” 这种手动分发的方式很不现实，没过几天就会有一半的人因为环境和版本配置不对而求助。
Claude Code 提供的 Plugin 机制 是目前最完美的解法。一个 Plugin 是一个包含了 Skills、Hooks 和 MCP 配置的三件套包：
codebase-intelligence-plugin/
├── .claude-plugin/
│ └── plugin.json # 插件元信息（名称、版本、描述）
├── skills/
│ ├── code-review/
│ │ └── SKILL.md # 代码审查规范与 workflow
│ └── arch-query/
│ └── SKILL.md # 架构查询规范与 workflow
├── hooks/
│ └── hooks.json # 比如 PostToolUse：写完文件自动跑静态分析
└── .mcp.json # 统一配置的 MCP Servers（cclsp + 自建 codebase-server）
团队将该插件托管在私有的插件源上，新员工入职后的 Onboarding 流程直接缩减为一条命令：
claude plugin install @team/codebase-intelligence
安装完毕后，新员工的 Claude Code 自动配齐了团队自建 of MCP 代码检索服务、cclsp 以及统一的代码审查与静态分析 Hooks。这一优化将团队新成员的架构上手时间从原本的 6 周（由于系统庞大）直接压到了 10 天以内。
常见问题解答与踩坑指南
Q：我的代码库才 1 万行，有必要折腾这套 MCP 检索层吗？
答：没有必要。这套设计的收益随代码库规模的增长呈指数级放大。对于 1 万行以下的小项目，直接在根目录配置一个精简的 CLAUDE.md，把核心模块的路径解释清楚就足够了。我们建议的起步阈值是：代码量超过 3 万行、模块间解耦不彻底、或者团队开发人员在 5 人以上，才值得去构建 MCP 检索层。
Q：代码库的索引（Index）怎么保持实时更新？
答：如果每次查询都去实时扫描 180K 行代码，那么每次工具调用的延迟都会在 10 秒以上，体验极差。我们的做法是：MCP Server 在启动时执行一次增量 diff，只对发生改变的文件/模块重建索引（通常在 30 秒内完成）。工程师在 push 代码后，CI 管道会自动跑一个全量 Index 编译任务。在本地开发时，宁可让 Claude 使用 10 分钟前轻微过期的缓存 Index，也不要让它在无缓存的情况下实时扫库。
Q：当 Plugin 中的 MCP 命名和项目本地的 .mcp.json 冲突时怎么办？
答：两者的配置会自动合并。如果遇到重名 server，会以项目根目录的配置为准。在开发团队 Plugin 时，强烈建议将插件内的 MCP 服务器加上团队专属的前缀（例如 team-codebase-server），避免与社区通用的公共 Server 重名。
Q：Claude Code 经常不调工具，直接凭记忆瞎猜回答，怎么破？
答：有两个有效解法。一是在项目全局的 CLAUDE.md 中用大写醒目字体写入规则："IMPORTANT: When answering questions about code architecture, you MUST call the query_service_graph tool to verify"；二是在定制的 Skill（SKILL.md）中强制编写有严格依赖的 workflow，规定它必须将上一步工具的输出作为下一步的输入，这样它就无法跳过工具调用了。
Q：这套检索层对未来的架构重构有什么深远价值吗？
答：这套检索层的副产物非常亮眼：它迫使团队通过代码自动化生成并维护了一份精确的依赖 Graph。这套元数据不仅供 AI 消费，由于其格式是规范的 JSON/Markdown，现在也成了我们新人入职 and 系统重构时，比任何手写架构设计书都准确百倍的“活文档”。
长按二维码关注 “边学边练”
