Claude Code 扩展层
创建时间： 2026-05-24
来源： [[sources/How Claude Code works in large codebases Best practices and where to start]]
相关： Harness-Engineering、Agent-First-Repository-Design、Large-Codebase-Deployment、Managed-Agents、Minimal-Agent-Architecture、Agent-Loop
核心主张
The harness matters as much as the model.
Claude Code 的能力不只由模型定义。围绕模型构建的生态系统——harness——对实际表现的影响超过模型本身。Harness 由五个扩展点构建，每个服务于不同功能，且构建顺序很重要（每一层建立在上一层之上）。加上 LSP 和 Subagents 两个能力，构成完整的扩展体系。
五个扩展点 + 两个能力
| 组件 | 是什么 | 加载时机 | 最适合 | 常见误区 |
|---|---|---|---|---|
| CLAUDE.md | Claude 自动读取的上下文文件 | 每次会话 | 项目约定、代码库知识 | 把应放在 skill 中的可复用专业知识也塞进去 |
| Hooks | 在关键时刻运行的脚本 | 事件触发 | 自动化一致行为、捕获会话学习 | 用 prompt 做本该自动运行的事 |
| Skills | 特定任务类型的打包指令 | 按需、相关时加载 | 跨会话和项目的可复用专业知识 | 把所有东西加载到 CLAUDE.md 里 |
| Plugins | 打包的 skills、hooks、MCP 配置 | 配置后始终可用 | 在组织内分发可用的 setup | 让好的 setup 停留在部落知识 |
| MCP Servers | 连接外部工具和数据 | 配置后始终可用 | 让 Claude 访问原本无法触及的内部工具 | 在基础工作还没做好时就建 MCP 连接 |
| LSP * | 通过语言服务器的实时代码智能 | 配置后始终可用 | 符号级导航、类型语言的自动错误检测 | 以为它是自动的 |
| Subagents * | 用于特定任务的独立 Claude 实例 | 被调用时 | 分离探索和编辑、并行工作 | 在同一会话中混用探索和编辑 |
*LSP 通过插件层访问。Subagents 是委托能力而非配置型扩展点。
逐层详解
CLAUDE.md — 基础层
上下文文件，Claude 在每次会话启动时自动读取。根目录文件提供全局视图，子目录文件提供局部约定。Claude 在代码库中移动时累加式加载它们。
关键原则：保持精简，只放适用于所有任务的内容。过大的 CLAUDE.md 会挤占任务和代码的上下文空间。具体的最佳实践见 CLAUDE.md-分层。
Hooks — 自我改进层
大多数团队把 hooks 当作阻止 Claude 做错事的脚本，但更有价值的用途是持续改进：
- Stop hook：反思会话中发生的事情，在上下文还新鲜时提出 CLAUDE.md 更新建议。
- Start hook：动态加载团队特定上下文，让每个开发者无需手动配置就能获得对应模块的正确设置。
- 自动化检查：linting、格式化等规则通过 hooks 确定性执行，比依赖 Claude 记住指令更一致。
Skills — 渐进式信息披露
大型代码库中有数十种任务类型，不需要所有专业知识都存在于每次会话中。Skills 通过渐进式信息披露解决这个问题：将专业化工作流和领域知识卸载到按需加载的单元中，只在任务需要时才加载。
Skills 还可以按路径限定作用域。拥有支付服务的团队可以将部署 skill 绑定到该目录，当其他人在 monorepo 的其他地方工作时它永远不会自动加载。
与 CLAUDE.md 的分工：
- CLAUDE.md → 适用于所有任务的通用约定
- Skills → 仅在特定任务类型或路径下才需要的专业知识
Plugins — 分发层
解决的核心问题：好的 setup 容易停留在”部落知识”——只有老手知道怎么配。Plugin 将 skills、hooks 和 MCP 配置打包为单个可安装包，新工程师安装插件后立即获得与老手相同的上下文和能力。更新可以通过托管市场在整个组织内分发。
MCP Servers — 外部连接层
让 Claude 连接到内部工具、数据源和 API。最成熟的团队将结构化搜索暴露为 Claude 可直接调用的工具。其他团队连接内部文档、工单系统或分析平台。
注意：在 CLAUDE.md、hooks 和 skills 等基础层工作正常之前，不要急于构建 MCP 连接。
LSP — 符号级精度
Grep 在大型代码库中搜索常见函数名会返回数千个匹配，Claude 会消耗上下文来逐个打开文件判断哪个相关。LSP 只返回指向同一符号的引用，过滤在 Claude 读取任何内容之前就完成了。
对于多语言代码库，这是最高价值的投资之一。需要安装对应语言的 code intelligence 插件和语言服务器二进制文件。
Subagents — 探索与编辑分离
Subagent 是拥有自己上下文窗口的隔离 Claude 实例，接受任务、完成工作、只将最终结果返回给父级。典型模式：启动只读 subagent 映射子系统并将发现写入文件，然后让主 agent 基于完整图景进行编辑。
详见 Generator-Evaluator-Architecture 中的生成器-评估器分离原则。
构建顺序
扩展层的每一层建立在上一层之上。推荐的构建顺序：
- CLAUDE.md — 先让 Claude 理解代码库
- Hooks — 让 setup 自我改进和自动执行
- Skills — 按需加载专业知识，避免上下文膨胀
- Plugins — 将验证过的 setup 分发给团队
- MCP + LSP — 在基础稳固后扩展外部连接和代码导航
/loop 与 /goal
Claude Code 的 /loop 和 /goal 命令是扩展层之上的自主运行入口，将 Harness 从”人类驱动的会话工具”升级为”自主运行的后台系统”。
| 命令 | 机制 | 适用场景 |
|---|---|---|
/goal | 运行循环直到验证模型确认任务完成 | 有明确完成条件的单次任务 |
/loop | 持续运行的循环，可定时调度 | 长期监督、PR 看护、背景修复 |
Boris Cherny 的 canonical starter 示例：
/loop babysit all my PRs. Auto-fix build issues, and when comments come in, use a worktree agent to fix them.
这两个命令的底层使用 cron 做调度，但关键差异在于循环体内嵌入了模型驱动的决策逻辑，而非固定脚本。详见 Agent-Loop。
与 Harness Engineering 的关系
Claude Code 扩展层是 Harness-Engineering 中定义的 harness 工程原则在 Claude Code 产品中的具体实现：
- 渐进式信息披露 → CLAUDE.md 分层 + Skills 按需加载
- 将品味编码为工具 → Hooks 自动化检查
- 分离生成与评估 → Subagents 探索/编辑分离
- 结构化交接工件 → CLAUDE.md 作为跨会话的持久上下文
- Agent Loop →
/loop和/goal将模型驱动的决策循环产品化
参考资料
- 来源：Anthropic《How Claude Code works in large codebases: Best practices and where to start》