Claude Code 大型代码库实战：Harness 框架与最佳实践

Anthropic 发布了《Claude Code 在大代码库中的工作方式：最佳实践与入门指南》，这是「Claude Code 规模化」系列的企业级最佳实践文章。本文提炼核心内容。

Claude Code 如何导航大型代码库

Claude Code 「像软件工程师一样导航代码库：遍历文件系统、读取文件、用 grep 精确查找所需内容、跨代码库追踪引用」。它在开发者本地运行，不需要构建、维护或上传代码库索引到服务器。

与传统 AI 编码工具依赖 RAG 嵌入整个代码库不同，那些系统在大型代码库中会失效——"嵌入管道跟不上活跃工程团队的速度"。等开发者查询索引时，它反映的已经是过时代码。Agentic 搜索避免了这些问题，没有集中式索引需要维护，每个开发者的实例都工作在实时代码库上。

代价：Claude 的导航质量取决于 CLAUDE.md 文件和技能的配置水平。在数十亿行代码的代码库中，模糊的模式会在工作开始前就耗尽上下文窗口。

框架（Harness）比模型本身更重要

一个常见的误解是 Claude Code 的能力由模型决定。实际上，「模型周围的生态系统——框架——决定了 Claude Code 的性能而非模型本身」。

框架由五个扩展点和两个附加能力组成：

CLAUDE.md 文件（优先设置）

每次会话自动读取的上下文文件：根目录文件提供大局观，子目录文件提供局部约定。限制在通用范围可防止成为性能负担。

Hooks（让配置自我改进）

大多数团队把 hooks 理解为防止 Claude 做错事的脚本，但更有价值的用途是持续改进：

stop hook 可以在会话新鲜时反思并提出 CLAUDE.md 更新
start hook 可以动态加载团队特定上下文
对于 linting 和格式化等自动化检查，hooks 提供确定性执行

Skills（按需加载专业知识）

Skills 使用渐进式披露——「将本会争夺上下文的专业工作流和领域知识卸载，仅在任务需要时加载」。例如安全审查 skill 只在评估代码漏洞时加载。Skill 可限定到特定路径。

Plugins（分发有效配置）

Plugin「将 skills、hooks 和 MCP 配置打包成单一可安装包」，新工程师立即拥有与有经验用户相同的上下文和能力。更新可通过托管市场分发到整个组织。

LSP 集成

LSP 为 Claude 提供符号级精度：「它可以追踪函数调用到定义处，跨文件追踪引用，区分不同语言中同名函数」。没有 LSP，Claude 只能模式匹配文本。对于多语言代码库，这是最高价值的投资之一。

MCP 服务器

MCP 服务器连接 Claude 到内部工具、数据源和无法直接访问的 API。

Subagents（将探索与编辑分离）

Subagent 是一个隔离的 Claude 实例，有独立上下文窗口，完成任务后只返回最终结果给父进程。一些团队启动只读 subagent 来映射子系统并将发现写入文件，然后让主 Agent 基于完整视图进行编辑。

三个成功部署配置模式

1. 让代码库可导航

Claude 的能力「受限于找到正确上下文的能力」。过多上下文降低性能，过少让 Claude 盲航。

关键模式：保持 CLAUDE.md 精简分层、在子目录初始化而非仓库根目录、为每个子目录限定测试和 lint 命令、使用 .claude/settings.json 设置排除规则、构建代码库地图、运行 LSP 服务器。

注意：某些极端场景下分层 CLAUDE.md 模式也会失效，比如数十万文件夹的代码库或非 git 版本控制的遗留系统。

2. 随模型进化主动维护 CLAUDE.md

为当前模型编写的指令可能对未来的模型起反作用。为补偿特定模型限制而构建的技能和 hooks，「一旦这些限制消失就变成了开销」。团队应每 3-6 个月以及重大模型发布后进行一次配置审查。

3. 为 Claude Code 管理和推广分配负责人

「仅靠技术配置不会推动采用」。最快落地的团队在广泛开放之前就投入了基础设施。一个新兴角色是Agent Manager——「一个 PM/工程师混合职能，专门负责管理 Claude Code 生态系统」。最小化版本是 DRI（主要负责人），负责配置、权限策略、插件市场和 CLAUDE.md 约定。

上手清单

按照框架组件顺序逐步构建：CLAUDE.md → Hooks/Skills → Plugins → LSP → MCP → Subagents。每 3-6 个月审查一次配置，确保随模型升级而优化。

原文链接：https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start