Claude Code 在 monorepo 中：限制上下文并保持准确性

为什么大型 monorepo 会让 Claude 的准确性下降

Claude Code 在 monorepo 中之所以显得不可预测，有一个简单原因：仓库比模型一次能在工作记忆中容纳的内容要大。

“上下文”是指为了完成该任务而向 Claude 展示的一组文件、代码片段、笔记和指令，以及它能从中推断出的信息。当关键细节缺失时，Claude 会用猜测来填补空白。在大型仓库中，这种情况更常见。

有三种常见的失败模式会反复出现：

首先，漏掉文件。看起来在某个文件夹里做的改动是安全的，但实际上依赖于某个共享类型、配置规则或在别处定义的构建步骤。如果该依赖不在上下文中，Claude 可能自信地编辑错误的东西，或者因为看不到真实的事实来源而提前停止。

第二，错误的相似性。Monorepo 常包含多个看起来很像的包：两个认证模块、三个 API 客户端，或几个结构相似的 React 应用。Claude 可能把模式混在一起，更新错包里的辅助函数，或从“几乎正确”的模块名导入。

第三，时间漂移。大型代码库通常同时保留旧的和新的实现方式。如果 Claude 只看到了较旧的文件，它可能会复制已弃用的模式（已废弃的配置选项、遗留 API），即使团队已经迁移到新方式。

一个常见的真实例子：你请求对计费 UI 做一个小改动，Claude 却修改了一个被其他应用共享使用的 payments 组件，因为它从未看到应该改动的应用级包装器。

目标不是把整个 monorepo 都给 Claude。目标是提供更小、经过设计的输入，仍能回答问题：你要改动的包、它的直接依赖，以及一到两个类型和配置的“事实来源”。同时明确指出“不可动”的区域（其他应用、基础设施、生成代码），并确认哪个包拥有该行为。

从定义任务开始，而不是定义仓库

准确性依赖的不是你粘贴了多少代码，而是你多么清晰地描述了任务。

先说明你想要的结果：一个具体的修复、重构或答案。“关于代码的问题”可以保持高层次；“做出改动”的请求需要边界、输入和验收检查。

在分享任何东西之前，写一句完成句子来回答这个短语：“在你完成后，我应该能够……”。例如：“能够在不失败的情况下运行 package X 的单元测试”或“在端点 Y 的 API 响应中看到新字段”。当仓库庞大时，这句话就是北极星。

对于改动，请共享能证明改动正确的最小工件集合：入口点、相关的类型/接口或模式、一个失败的测试或带有预期结果的复现步骤，以及影响该路径的任何配置（路由、特性开关、构建或 lint 规则）。如果有帮助，可以添加一个简短的包文件夹地图，帮助 Claude 理解每个目录的用途。

明确说明不需要查看的内容。比如写明：“忽略生成文件、vendor 文件夹、构建输出、快照和锁文件，除非我要求。”这能防止在你不打算审查的地方浪费时间和进行修改。

同时为不确定性设定期望。要求 Claude 标注假设和未知项，而不是猜测。例如：“如果你看不到这个函数在哪里被调用，请说明并提出两种定位它的方法。”

画出 Claude 不应跨越的清晰边界

在大型 monorepo 中，当模型“好意”地拉入不属于任务的附近代码时，准确性会下降。解决方法很直接：在请求更改前，定义哪些是范围内、哪些是范围外。

从与你仓库组织方式一致的边界开始：一个 package、service、app 或共享库。如果改动是“更新结账 UI”，边界可能是一个 app 包，而不是所有出现“checkout”字样的地方。

能帮助 Claude 保持范围的信号包括文件夹约定（apps/、services/、packages/、libs/）、包清单（exports 和 dependencies）、公共入口点（index 文件、导出的组件、处理器）以及测试（测试通常揭示预期的表面）。文件夹里的 README 常常是最快的边界标记。

边界最有效的情况是你同时点出它们之间的桥接处。说明 Claude 可能会触及的具体接口，并把其他一切视为禁区。典型的桥接包括 HTTP API 协议、事件主题和载荷、共享类型，或少量导出函数。

在改动不应影响它们时，明确标记“不可修改”区域。常见的有基础设施与部署配置、安全与认证逻辑、计费与支付、数据迁移与生产模式，以及被多个团队使用的共享库。

一个有帮助的具体提示示例：

“仅在 packages/cart/ 及其测试中做修改。你可以读取 packages/types/ 中的共享类型，但不要修改它们。不编辑 infra、auth 或 billing。”

如何撰写有用的本地摘要

当你提供一张小而稳定的地图时，准确性会提升。所谓“本地摘要”就是这张地图：足够短以便快速阅读，足够具体以防猜测。

每个摘要保持在大约 10 到 20 行。把它写成你把代码交给只需要触及该边界的新同事的方式。用简单语言和代码中的真实名字：文件夹、包、导出的函数。

一个有用的本地摘要应回答五个问题：

• 这个包/服务的用途是什么，以及不负责什么（范围界定）
• 工作从哪里开始（主要入口点，如关键文件、路由、命令或组件）
• 对外可安全调用的是什么（公共 API、导出模块、事件、端点）
• 它依赖什么（数据库、队列、缓存、配置、外部服务）
• 这里有哪些规则很重要（命名规范、错误风格、日志，以及测试的写法）

追加一句“注意事项”。这是避免昂贵错误的地方：隐藏缓存、特性开关、迁移步骤以及任何会悄然出问题的东西。

下面是一个紧凑的模板（可复制并使用）：

Local summary: <package/service name>
Purpose: <1 sentence>
Scope: <what to touch> | Not: <what not to change>
Entry points: <files/routes/commands>
Public surface: <exports/endpoints/events>
Data sources: <tables/collections/queues/caches>
Conventions: errors=<how>, logging=<how>, tests=<where/how>
Gotchas: <flags/caching/migrations/edge cases>

示例：如果你在编辑一个计费包，记下创建发票的确切函数、它写入的表名，以及关于可重试错误的规则。这样 Claude 就能专注于该边界，而不是漫游到共享认证、配置或不相关包中。

摘要放在哪儿以及如何保持其更新

最好的摘要就是在需要时 Claude 能看到的那份。把它放在描述代码的旁边，这样不容易被忽视且易于更新。例如，在每个 package、service 或 app 目录中保留短小的 SUMMARY.md（或在 README.md 中的一节），而不是把所有内容放在仓库根目录的一个大文档里。

一个简单、可重复的结构有助于维护。保持摘要足够短，以便人们愿意维护：

• 这个文件夹是什么（1-2 句说明目的）
• 公共表面（主要入口点、导出模块或 API）
• 关键依赖（内部和外部）
• 边界（不得导入或修改的内容）
• 如何测试（最快的本地检查方式）
• Last updated: YYYY-MM-DD - <what changed in one sentence>

摘要会因为可预测的原因变旧。把更新摘要当成完成工作的一个步骤，就像更新类型定义一样，而不是一项单独的任务。

在重构更改结构或名称、新模块成为主要方式、API/事件/模式发生改变（即使测试仍然通过）、包之间的边界移动，或依赖被移除或替换时，更新摘要。

一个实用习惯：合并变更时，在 PR 中添加一行“Last updated”说明发生了什么。像 Koder.ai 这样的工具可以帮助你更快地推进代码更改，但摘要才是保持未来变更准确的关键。

一个遵守正确上下文的逐步工作流程

准确性常常取决于你如何节奏化对话。让 Claude 以小步子“挣取”上下文，而不是从一个巨大的快照中猜测。

第 1 步：先请求一个简短地图

在任何编辑之前，要求 Claude 描述它所看到的内容和它还需要什么。一个好的地图很短：涉及的关键包、流程入口、测试或类型所在位置。

提示示例：

“Create a map of this change: packages involved, main flow, and likely touch points. Do not propose code yet.”

第 2 步：从一个切片和一个边界开始

选择一个狭窄的切片：一个功能、一个包、一个用户流程。明确边界（例如：“仅修改 packages/billing-api/。不要触碰 shared-ui 或 infra。”）。

一个能让你保持掌控的工作流：

• 用一句话定义目标和边界。\n- 要求列出假设和未知项（Claude 必须罗列）。\n- 要求它说明接下来需要的精确文件（限制在 3 到 6 个）。\n- 只提供那些文件，然后重复该流程。\n- 在应用补丁前要求一个简短计划。

第 3 步：强制列出假设和所需文件

如果 Claude 缺少某些东西，它应当说明。要求它写出： (1) 它做出的假设，(2) 哪些情况会证明这些假设是错的，(3) 下一个需要确认的文件。

示例：你需要在某个包的 Invoice 响应中添加字段。Claude 请求处理器、DTO/类型定义和一个测试。你只分享这些。如果你在使用基于聊天的构建器（例如 Koder.ai），同样规则适用：先提供最小的一组源文件，然后仅在确实需要更多时再扩展。

在提示中使用约束与契约

防止错误修改的最好办法是在提示里写一个小“契约”：说明可触及的文件、你如何判断成功，以及它必须遵守的规则。

从一个易于遵守且便于验证的边界开始。明确说明允许编辑的地方，并点出“不可触碰”的区域，以避免漫游的诱惑。

契约模板示例：

• 仅修改 packages/payments/ 下的文件。\n- 不要编辑 packages/auth/、infra/ 或任何共享配置。\n- 如果需要在范围外修改，先停下并询问。\n- 保持改动最小：修复 bug，避免重构。

然后定义验收检查。没有这些，Claude 可能会产生看起来正确但违背仓库真实规则的代码。

• 运行该包的单元测试（写明你使用的命令）。\n- 运行 lint/format（写明工具或说明“使用现有配置”）。\n- 运行类型检查/构建该包。\n- 确认应用仍能启动（一个简单的运行命令即可）。

样式约束也很重要。告诉 Claude 哪些模式该遵循、哪些应避免，基于你代码库已有的做法。例如： “在此包使用现有的错误处理 helpers；不要引入新依赖；函数名保持 camelCase；不要引入新的架构层。”

最后，在任何编辑前要求提交一个简短的变更计划：

“在编辑前，列出你预期要改动的 3–5 个文件和确切的行为变化。等待批准。”

示例：

“修复发票总额的四舍五入问题。仅编辑 packages/billing/src/ 和 packages/billing/test/ 下的测试。验收：运行 pnpm -C packages/billing test 并通过类型检查。遵循现有的金额工具，不要重写 API 类型。先提供 4 步计划。”

导致漂移和错误修改的常见陷阱

让 Claude 一次看到太多内容是导致错误修改的最快方式。当你粘贴一大堆代码，它常常退回到通用模式，而不是遵循你仓库已有的具体设计。

另一个陷阱是让它猜架构。如果你不展示真实的入口点，它可能会选择看起来可行的第一个文件并在那里接线。实践中，准确性来自一小组“事实来源”的文件（入口模块、路由、服务注册、包边界文档）。如果这些不在上下文中，模型会去填空。

名字也会误导它。Monorepo 常有 ui、ui-kit、shared-ui 之类的包，或在多个地方有重复的辅助函数 date.ts。如果你混合来自两处的片段，Claude 可能会修改一个文件，同时在脑中以另一个文件为依据。举例：你要求更改一个按钮样式，它编辑了 packages/ui/Button.tsx，但应用实际导入的是 packages/ui-kit/Button.tsx。差异看起来没问题，但生产环境没有变化。

配置也是导致静默漂移的源头。行为可能依赖于环境变量、特性开关、构建设置或工作区工具。如果你不提及这些，Claude 可能会删掉一个“奇怪”的检查（该检查只有在某个开关打开时才重要），或加入破坏构建步骤的代码。

一些表明你正在漂移的红旗：

• 回答只谈“典型模式”而不点出你真实的文件\n- 引入新的共享工具而不是使用已有的\n- 更改跨包导入\n- 忽略特性开关或与环境相关的分支\n- 建议向核心共享包添加依赖

把跨包导入当作一个决策，而不是默认行为。除非你有意扩展范围，否则保持改动本地化。

在请求之前的快速检查清单

获得正确改动的最快方法是以限制开始，而不是以大量信息开始。一个好的提示应该有点严格：告诉 Claude 去哪儿看、忽略什么，以及“完成”意味着什么。

在你粘贴代码前，写一段简短的前言，把工作固定到仓库中的一个位置。写明包名、确切文件夹和具体目标。然后附上本地摘要（目的、关键依赖、重要约定）和锚定改动的入口文件。

检查清单：

• 边界：仅在 \u003cpackage\u003e/\u003cpath\u003e 工作。目标：\u003cone sentence\u003e。除非另行说明，否则忽略其他内容。\n- 上下文起点：本地摘要：\u003c5-10 lines\u003e。入口文件：\u003cpath/to/file\u003e。\n- 约束：允许的文件夹：\u003c...\u003e。不得修改：\u003cfolders/files or APIs\u003e。保持行为：\u003cwhat must stay true\u003e。\n- 先要文件请求：“在提出改动前，列出你需要查看的最少文件（最多 5 个）并说明原因。”\n- 输出格式：先回复一个简短计划。确认后，按文件给出补丁式建议。

如果 Claude 提议做范围外的改动，把它当作一个信号：要么收紧提示，要么有意扩展范围并重新声明边界。

示例：在一个包内做改动而不叫醒整个 monorepo

假设你的 monorepo 有 apps/web-store（一个 React 应用）和 packages/ui-kit（共享按钮、输入和样式）。你想做一个小功能：在购物车页面添加一个“稍后保存”按钮，使用来自 ui-kit 的新 SaveIcon。其他内容都不应改变。

在请求编辑之前，为两个区域创建本地摘要来作为边界。保持简短、具体，并强调重要点。

# apps/web-store/LOCAL_SUMMARY.md
Purpose: Customer shopping UI.
Entry points: src/routes.tsx, src/pages/cart/CartPage.tsx
Cart rules: cart state lives in src/cart/useCart.ts
Do not touch: checkout flow (src/pages/checkout), payments, auth.
Tests: npm test -w apps/web-store

# packages/ui-kit/LOCAL_SUMMARY.md
Purpose: shared UI components.
Exports: src/index.ts
Icons: src/icons/*, add new icons by exporting from index.
Do not touch: theming tokens, build config.
Tests: npm test -w packages/ui-kit

然后把循环保持紧凑：

1. 地图：“此更改仅限 CartPage 和 ui-kit 图标。不修改 checkout/auth。”\n2. 假设：要求列出假设并等待确认。\n3. 文件请求：只批准它确实需要的文件（CartPage、useCart、ui-kit 图标、ui-kit index）。\n4. 计划：确认符合边界。\n5. 编辑：做最小差异，然后请求更新后的测试。

更改完成后，记录下来以便未来上下文保持小：

• 更新两个本地摘要，说明新增的导出和确切修改的文件。\n- 在购物车页面的注释头部添加简短说明：按钮的作用及状态在哪里处理。\n- 记录通过的测试命令（以及任何更新的快照）。

接下来：为你的团队把它变成可重复的流程

如果这种方式对一个人有效但对团队不起作用，缺失的通常是可重复性。把“良好的上下文卫生”设为默认，而不是个人习惯。

把最佳提示变成团队模板

保存一个提示骨架，供每个人复制并填写。保持简短但严格。包含目标（什么是“完成”）、允许的范围、硬性边界（以及原因）、本地摘要和输出契约（先计划，然后按 diff 风格给出改动和测试）。

以轻量的节奏保持摘要最新

跳过没人做的大型月度审查。在变更影响行为、依赖或 API 时，把摘要更新作为同一个 PR 的一部分。

一个简单规则：如果某个同事会问“这东西在哪里？”或“谁依赖它？”，说明摘要已经过时。

如果你偏好以聊天为主的工作流，Koder.ai 能帮助你把这种迭代方式做得更安全。Planning 模式能在编辑前就达成范围共识，快照与回滚功能让你在猜测出现错误时快速恢复。