Claude Code 在大代码库里怎么部署

核心论点

Harness 的重要性等于甚至超过模型本身

关于 Claude Code 最常见的误解：以为能力取决于模型。团队研究 benchmark、对比 SWE-Bench 分数，但在百万行 monorepo 里——决定它好不好用的，是围绕模型搭起来的那一圈生态。Anthropic 把这一圈叫做 harness。模型是引擎，harness 是整台车——底盘、传动、悬挂、轮胎。没有 harness，模型的能力无处施展；有了 harness，模型的每一代进步都能被放大。

这篇文章拆解 Anthropic 观察到的部署 pattern：搜索策略、扩展架构、可导航代码库、配置半衰期、以及组织推广路径。

§I

Agentic Search vs RAG

Claude Code 不用索引。它像工程师一样导航——遍历文件系统、读文件、grep、跟踪引用。文件被重命名、函数被删除——agentic search 在运行时看到的是真实状态。

RAG 的 embedding pipeline 在大规模下跟不上：每次 push 后重建索引代价高，stale embeddings 导致幻觉。Agentic search 的代价不同——它需要足够的起始 context 来知道从哪里开始找。

RAG — 预构建索引

Agentic — 实时遍历

§II

The Harness — 7 个扩展层

五个扩展点加两个附加能力，按顺序构建。每层在前一层基础上增加一种表达能力。

1. CLAUDE.md

每 session 自动读取。root + 子目录分层。只放广泛适用的内容——不是 README，不是 wiki，是给 agent 的行为指导。

# acme-monorepo
TypeScript everywhere. Rust for services/edge-*.

## Test commands
- root: pnpm test --filter <pkg>
- per-service: see subdirectory CLAUDE.md

## Critical gotchas
- Never import from internal/ outside parent
- Migrations in db/migrations/ — no inline SQL

2. Hooks

不是防出错——是持续改进。stop hook 提议更新 CLAUDE.md，start hook 动态加载 context。生命周期事件驱动的自我进化。

#!/bin/bash
# .claude/hooks/on-stop
claude reflect \
  --propose-updates-to CLAUDE.md \
  --while-context-fresh

3. Skills

Progressive disclosure。按路径绑定——只有在相关目录工作时才激活。避免 context 膨胀。

# .claude/skills/security-review.yaml
name: security-review
trigger: "auditing code for vulns"
scope: ["services/**"]

4. Plugins

打包分发。skills + hooks + MCP 捆绑为一个插件。新工程师 day 1 即用——无需自己搭配。

{
  "name": "retail-analytics",
  "skills": ["pull-perf-data"],
  "hooks": ["log-query-shape"],
  "mcp": ["analytics-warehouse"]
}

5. MCP Servers

连接外部工具、数据、API。Claude 通过 tool calling 与 MCP server 交互——搜索引擎、数据库、CI 系统都可以暴露为 tool。

{
  "servers": {
    "code-search": {
      "cmd": "internal-search-mcp",
      "tool": "structured_search"
    }
  }
}

6. LSP Integration

go-to-def / find-refs 的符号级精度。某企业在 C/C++ 推广前先部署 LSP——给 agent 装上和 IDE 一样的导航能力。

{
  "plugins": ["code-intelligence"],
  "languageServers": {
    "cpp": "clangd",
    "rust": "rust-analyzer"
  }
}

7. Subagents

独立 context window。探索与编辑分离——subagent 负责大面积扫描，main agent 拿到结论后精准编辑。

> spawn read-only subagent
> task: map auth subsystem → docs/auth-map.md
← 247 refs across 18 files
  main agent edits with full picture

§III · Pattern 1

让代码库可导航

Claude 在大代码库中的能力上限 = 它找到正确 context 的能力。加载太多 context 进每个 session → 性能下降；加载太少 → 盲目导航。最有效的部署都把功夫花在前期：让代码库对 Claude 可读。

这不是"让 Claude 更聪明"的问题——是"让代码库更容易被探索"的问题。Anthropic 观察到六个反复出现的实践：

acme-monorepo/

├── CLAUDE.md ⊕ root: pointers + gotchas only

├── .claude/

│ └── settings.json ⊕ permissions.deny rules

├── apps/

│ ├── web/

│ │ ├── CLAUDE.md ⊕ per-subdir test/lint

│ │ └── src/

│ └── mobile/

├── services/

│ ├── payments/

│ │ ├── CLAUDE.md ⊕ init here, not root

│ │ └── ...

│ └── auth/

├── codebase-map.md ⊕ directory index

└── (LSP: clangd running) ⊕ symbol search

⊕ CLAUDE.md 精简分层 — root 只放全局指针与 gotchas

⊕ 从子目录初始化 — cd services/payments && claude

⊕ 按子目录 scope test/lint 命令

⊕ .ignore 排除噪音 — build artifacts / node_modules

⊕ 构建 codebase map — 目录级索引文件

⊕ 运行 LSP server — 符号级搜索

Edge case：数十万文件夹 + 数百万文件的代码库、非 git 版本控制的遗留系统——即便分层 CLAUDE.md 也会失效。Anthropic 表示会在本系列后续文章中专门处理这些场景。

§IV · Pattern 2

配置有半衰期

每条 CLAUDE.md 规则都是写给"某一代模型"的。模型在迭代，但配置不会自动跟着进化——上一代模型需要的限制和补偿，可能在下一代模型上变成阻碍。

反作用有两种典型表现：

旧规则继续生效但反向阻碍——指导 Claude "把每次重构限制为单文件修改"，在旧模型上帮助保持轨道，但在新模型上阻止了它擅长的跨文件协调编辑
补偿性工具变成开销——为弥补模型特定限制构建的 skills 和 hooks，限制消除后依然运行，增加复杂度但不再带来收益

下面的曲线图展示了两个真实配置项的"价值衰减"轨迹：

Perforce hook 案例详解：早期 Claude Code 不懂 Perforce 工作流，团队构建了一个 hook 拦截文件写入以强制 p4 edit——当时是必要补偿。后来 Claude Code 添加原生 Perforce 模式后，hook 变成多余的。如果团队没做 review，它会继续运行：增加复杂度，不再带来收益。

建议节奏每 3–6 个月 做一次有意义的配置 review；大版本模型发布后，若性能感觉 停滞不前（plateaued），也值得做一次。

§V · Pattern 3

Infrastructure Before Access

技术配置不能独自驱动采纳。前两个 Pattern 解决的是"单次任务能不能跑完"和"配置六个月后还成不成立"，但如果没有组织层面的投入，好配置会停留在部落知识阶段——一个人搞定了，其他人不知道。

Anthropic 观察到的扩散最快的推广模式：在广泛开放访问之前，先有一小组人（有时就一个人）把工具链接好。让开发者首次接触 Claude Code 时，它就已经适配了工作流——plugins 装好、MCP 能连、CLAUDE.md 写好了——第一体验是 productive 而非 frustrating，采纳自然扩散。

案例 1：几个工程师提前构建了一套 plugins 和 MCPs，day 1 就可用。
案例 2：一支专门管理 AI coding 工具的团队，在推广开始前就准备好了基础设施。

这和"先开放访问，让大家自己摸索"形成鲜明对比：

谁来做这件事？

承担 Claude Code 部署的团队通常归属在 developer experience / developer productivity 职能下。多个组织里正在出现一个新兴角色——Agent Manager：混合 PM / 工程师职能，专门管理 Claude Code 生态系统。

没有专职团队的最小可行版本：一个 DRI——对 Claude Code 配置、settings、permissions policy、plugin marketplace、CLAUDE.md conventions 有所有权和决策权的个人。

治理问题（尤其受监管行业）：

谁控制哪些 skills 和 plugins 可用
如何防止数千工程师独立重复建设同一东西
如何确保 AI 生成代码经过与人类代码相同的 review 流程

建议起手：从定义好的 approved skills set、required code review、limited initial access 开始 → 信心建立后扩大。最顺畅的部署都是尽早建立跨职能工作组——工程 + 信息安全 + 治理代表共同定义需求与推广路线图。

适用边界

Scope

设计目标

工程师 + Git + 标准目录
Monorepo 或多仓库
C/C++/C#/Java/PHP 超预期
常规工程环境

需额外工作

游戏引擎二进制资产
非常规 VCS（Perforce 等）
非工程师贡献者
极大文件（自动生成代码）

未来覆盖

百万文件规模
非 Git 遗留系统
全程无人工介入
跨组织边界协作

结语

关键引文

"The harness matters as much as the model. The smoothest rollouts had a dedicated infrastructure investment before broad access."

— Anthropic Applied AI Team, 2026-05-14

Sources

来源

Primary Anthropic Blog — How Claude Code works in large codebases
Slide Deck 本站 PPTX (13 slides)
Method Fact-check 4 轮通过
Credits Anthropic Applied AI 团队 + Amit Navindgi (Zoox)

Claude Code 在大代码库里不只是"怎么工作"——怎么部署