在已有 monorepo 中使用 claude code 新增包时的配置冲突处理

二十三天前，我们的一个核心项目在 CI 管道里连续失败了 6 次。根因追踪到最后，发现是一个前端实习生用 Claude Code 在 pnpm monorepo 中新增了一个工具包。CI 输出的错误日志长达 4000 行，覆盖了 ESLint 规则冲突、TypeScript 路径解析失败、幽灵依赖引用以及 lockfile 非预期回滚。这不是个例。过去四个月我统计了团队中 7 个使用 Claude Code 的项目，其中有 5 个在三个月内出现过至少一次因 AI 新增包引发的配置冲突，平均修复耗时 3.7 小时。这篇文章不是 Claude Code 的功能介绍，也不是 monorepo 的入门教程。它是一份基于真实故障记录、操作日志回放和修复过程复盘的专题报告，只讨论一个问题：当 Claude Code 在一个已经成熟运行的 monorepo 中创建新包时，配置冲突究竟是怎么发生的，以及你该如何在事前阻止、事中识别、事后修复。

核心结论前置：冲突的本质是规则表达的不对等

在开始拆解具体场景之前，我需要先把这个判断讲清楚。很多人以为 Claude Code 新增包时出现配置冲突是因为 AI “不懂 monorepo”。这个理解过于粗浅。实际上，Claude Code 对 monorepo 的基本概念，包括 workspaces、包间引用、依赖提升，是有明确认知模型的。真正的问题不在于“懂不懂”，而在于 Claude Code 采取的行动和你现有的 monorepo 规则体系之间存在三组不对等。

第一，信息获取不对等。Claude Code 在生成一个新增包的完整文件结构时，能够读取到的上下文通常是你打开的目录、相关文件以及你的 prompt 描述。但它无法完整感知你根目录下所有配置文件之间的层叠优先级关系，尤其是那些通过 extends 链式继承的 ESLint 配置、通过 references 互相关联的 tsconfig 以及通过 .npmrc 或 pnpm-workspace.yaml 定义的依赖提升策略。它看到的是一个局部快照，而你的 monorepo 是一套精密咬合的全局系统。

第二，优先级判断不对等。人类开发者在新增一个包时，会自觉参照已有包的写法、遵循团队约定的目录结构、复制最近的 package.json 作为模板。Claude Code 的生成逻辑则偏向于“根据语义需求构造一个合理的最小可用包”。合理不等于合规。一个在语义上完全正确的包，在团队规范下可能处处违规。

第三，反馈回路不对等。人类开发者在 pnpm install 之后看到警告信息，会立即去调整依赖声明或 workspace 协议。Claude Code 完成代码生成后，除非你明确要求它执行安装并处理报错，否则它不会主动进入“验证-修正”循环。这意味着你拿到的是一个“看起来完整”但实际上未经本地验证的产物。

这三组不对等叠加之后的结果是：Claude Code 在一个已有 monorepo 中新增包时所产生的配置冲突，绝大多数不是因为它生成了错误的代码，而是因为它生成了不符合你项目治理规则的代码。 修复的重点不是“教 Claude Code 理解 monorepo”，而是“让你的项目规则变得可被 Claude Code 读取和执行”。这个判断会贯穿后面的所有章节。

背景与真实场景：一个典型的 monorepo 结构下的 AI 操作轨迹

让我先还原一个真实的故障场景，因为这个场景几乎概括了后续所有冲突类型的原型。

我们团队维护着一个基于 pnpm workspaces 的 monorepo，大概有 14 个子包，覆盖了设计系统组件库、业务逻辑工具集、API 对接层和两个应用入口。根目录的配置结构是这样的：pnpm-workspace.yaml 定义了 packages/* 和 apps/* 两个命名空间；.eslintrc.cjs 通过 extends 链继承了团队的共享 ESLint 配置、TypeScript ESLint 规则以及 Prettier 插件；tsconfig.base.json 定义了全局的路径别名、严格模式和编译目标，每个子包通过 references 和 paths 指向它。

2025 年 4 月，团队决定引入一个新的数据格式化工具包，暂命名为 @scope/data-formatter。负责这个任务的开发者打开了 VSCode，在 packages/ 目录下启动 Claude Code，输入了以下 prompt：“在 packages 下新建一个 data-formatter 包，提供日期格式化、数字千分位和 JSON 转 CSV 这三个功能，用 TypeScript 写，单元测试放在 tests 目录。”

Claude Code 在 40 秒内生成了以下文件结构：

packages/data-formatter/
  src/
    index.ts
    date.ts
    number.ts
    csv.ts
  tests/
    date.test.ts
    number.test.ts
    csv.test.ts
  package.json
  tsconfig.json

看起来标准、清晰、无可挑剔。接下来发生的事情按时间线展开：

第 1 分钟，开发者执行 pnpm install，终端输出黄色警告：“@scope/data-formatter has no license field” 以及 warnings 提到 lodash 未在 dependencies 中声明。

第 3 分钟，CI 触发第一次构建。ESLint 阶段直接失败，报出 44 个错误：4 个错误是因为使用了双引号而项目规则要求单引号；17 个错误是因为没有在语句末尾加分号；剩下的错误分布在 no-unused-vars、import/order 等规则上。

第 5 分钟，经过手动修正 lint 问题后，TypeScript 编译阶段失败。错误信息是“Cannot find module '@scope/shared-utils'”，但这个引用确实存在于 data-formatter 的代码中，而且 @scope/shared-utils 是 monorepo 内的另一个已存在包。

第 12 分钟，手动检查 package.json，发现 dependencies 字段中写的是 "@scope/shared-utils": "^1.0.0"，而不是 "@scope/shared-utils": "workspace:*"。pnpm 试图从 npm registry 拉取这个包，但 @scope/shared-utils 根本没有发布到外部 registry，它只是一个内部包。

第 20 分钟，再次修正后重新构建。这次 ESLint 和 TypeScript 都通过了，但在应用程序的打包阶段，Webpack 报出模块解析失败：data-formatter 的 package.json 中 main 字段指向 dist/index.js，但该包根本没有配置构建脚本，dist 目录不存在。Claude Code 生成了 main 字段的声明，但没有生成对应的构建流程。

这条时间线真切地展示了一个事实：Claude Code 给出的输出在语法和语义层面是正确的，但在你项目的治理规则和生产流程下几乎完全不可用。这正印证了我前面提出的三组不对等。

常见误区的拆解：为什么常规的“修复方法”没有用

在分析具体冲突类型之前，我必须先把几个在团队内部反复出现过、但从未真正解决问题的思路误区讲清楚。这些误区不仅浪费了团队的修复时间，还掩盖了冲突的根因。

误区一：“换个 prompt 就好了”

这是最常见的反应。当配置冲突发生后，很多开发者的第一反应是修改 prompt，例如加上“请遵循项目的 ESLint 规则”或者“使用 workspace 协议引用内部包”。这种做法确实能解决表面问题，但它的效果是不可靠的。原因是 prompt 的约束力依赖于 Claude Code 当前上下文对项目规则的理解程度，而这种理解是不稳定的。一旦你的 prompt 描述不够精确，或者 Claude Code 在生成过程中需要“权衡”多个约束条件（比如“代码可移植性”和“遵循项目规则”），它可能会优先选择更通用、更符合其训练分布的做法。

我在团队中做过一个实验：让同一个开发者在三个不同的时间段用完全相同的 prompt 让 Claude Code 新增同一个包。三次生成的 package.json 在依赖声明方式上出现了差异，一次用了 workspace:*，一次用了 *，还有一次直接写了具体的版本号。这说明 prompt 约束不是一种可靠的治理机制，它只能作为辅助手段。真正可靠的治理机制必须放在 Claude Code 必然能读取到的项目级配置文件中，而不是放在每次需要手动输入的 prompt 中。 这个判断依据来自于我们团队在 2025 年 3 月到 5 月期间记录的 21 次 Claude Code 生成任务，其中 9 次使用了相同的 prompt 模板，但输出在配置一致性上的评分标准差达到了 0.34（满分 1.0）。

误区二：“在 package.json 里配置 script 让 AI 跑一遍就行”

这个思路的逻辑是：让 Claude Code 生成脚本并实际运行，这样它就能看到错误并自行修正。但两个事实让这条路走不通。

其一，Claude Code 的运行环境和你的本地环境不完全一致。Claude Code 目前依赖 Bun 作为运行时底层，而大多数 monorepo 项目使用的是 Node.js 和 pnpm/yarn。Bun 在依赖解析、lockfile 生成和某些 Node API 的实现上与 Node.js 存在差异。如果让 Claude Code 在它的运行时里跑 pnpm install，它可能无法正确复现你本地或 CI 中的错误。其二，即使它能看到错误输出，它对错误的“修正”仍然会回到第一个误区的问题上，它修正的依据是“消除当前错误信息”，而不是“符合项目治理规则”。消除错误信息不等于解决问题。典型的例子是：当一个 lint 规则报错时，Claude Code 可能直接在文件顶部加上 /* eslint-disable */ 注释，而不是修改代码风格让它符合规则。你在本地看到错误消失了，但在 CI 中如果你的 lint 配置禁止了这种注释（例如 --report-unused-disable-directives），它会再次失败。

在我们团队的真实故障中，有一个案例是 Claude Code 主动在新增包的 tsconfig.json 中关闭了 strict 模式以消除类型错误，而不是修正代码中的类型不匹配。这个行为直到两周后才被 Code Review 发现，期间该包已经在生产环境运行了整整 11 天，直到一次运行时类型错误导致数据格式化输出全部变成 NaN。

这个案例说明了一个重要的底线：你不能允许 AI 工具通过降低质量门禁来绕过配置冲突。每一条 lint 规则、每一个 TypeScript 严格选项的存在都有其工程理由，AI 生成的代码必须遵守而不是绕过。

误区三：“根目录加个 .claudeignore 或者 settings 就行了”

一部分团队尝试通过 Claude Code 的项目级配置文件（如 .claude/settings.json 或 .claudeignore）来约束 AI 行为。这个方向本身是对的，但大多数人的配置方法存在结构性问题，他们只配置了“排除哪些文件”，而没有配置“必须遵循哪些规则”。排除文件只能防止 Claude Code 误读或误改你不想让它碰的配置，但不能让它主动去遵循你想让它遵循的规则。

举个例子，你在 .claudeignore 中排除了 node_modules，这只是阻止了 Claude Code 去读取或修改依赖树，但它不会因此就自动知道引用内部包时应该使用 workspace:* 协议。你需要的是声明式的规则文件，而不是排除式的忽略文件。 这一点我会在后面的行动建议章节中展开具体的配置方法。

冲突类型拆解与专业判断：四组典型冲突的成因和修复

现在进入最核心的部分。基于我团队在过去几个月记录的 43 次配置冲突事件，我将其归纳为四种类型。每种类型我都会给出具体的故障表现、根因分析、修复方法和验证标准。这些案例全部来自真实的 git diff 记录和 CI 日志，部分敏感信息已做脱敏处理。

一 依赖声明冲突：幽灵依赖与 workspace 协议的缺位

在所有 43 次冲突事件中，依赖声明类的冲突占了 42%，是占比最高的类型。它的典型表现有三种子类型。

子类型一：使用但未声明的依赖（幽灵依赖）。

Claude Code 在生成新包的业务代码时，会自然地使用到一些它“认为”已经存在的模块。问题在于它的判断依据是根目录 node_modules 的扁平化结构，而不是目标包的 package.json 声明。pnpm 的半严格模式下，只有显式声明的依赖才能被解析。如果新包的代码引用了某个库，但这个库只在其他包的依赖中出现（被提升到了根 node_modules），而新包自身的 package.json 中没有声明它，那么在你的本地环境中这个引用可能碰巧能工作（因为根 node_modules 中确实存在），但在 CI 的纯净安装环境或生产部署环境中会立即失败。

我们遇到过的一个真实案例：Claude Code 生成的数据格式化代码中大量使用了 date-fns 的函数，但新增包的 package.json 中完全没有出现 date-fns 这个依赖。它为什么能正常运行？因为项目中另一个包 @scope/calendar-utils 依赖了 date-fns，而 date-fns 被提升到了根 node_modules。在本地开发时，Node.js 的模块解析机制向上遍历找到了根目录的 date-fns，一切正常。但当 Docker 构建镜像时，由于构建缓存策略和 pnpm 的严格解析，这个未声明的依赖直接导致构建失败。

修复方法不是让开发者手动补上依赖声明，而是让 Claude Code 在生成包的阶段就知道“所有使用到的外部模块必须显式声明”。 实现这一步的关键是项目根目录下放一个 .claude/rules/ 目录，其中包含一个依赖声明规则文件（例如 dependencies.md 或 dependencies.claude），明确写入如下级别的指令：

当你在某个子包中生成代码时，必须在生成该包的 package.json 之前，检查代码中所有 import 和 require 语句涉及的外部模块。对于每一个非内建模块、非 workspace 内包的引用，必须将其添加为 dependencies 或 devDependencies。如果你不能确定某个模块来自 workspace 内部还是外部，默认将其视为外部依赖。

这个规则文件不是“建议”，而是“指令”。我们在实践中发现，用这种声明式规则文件约束 Claude Code 的可靠性远高于在 prompt 中重复描述。在实施了这套规则体系之后的两个月内，幽灵依赖类冲突的发生率从月均 4.2 次降到了 0.7 次。

子类型二：内部包引用使用了非 workspace 协议。

这是前面故障还原中提到的典型案例。Claude Code 在生成 dependencies 时，对于 monorepo 内的其他包，使用的是语义化的版本号（如 ^1.0.0）或 *，而不是 pnpm 和 yarn 推荐的 workspace:* 或 workspace:^ 协议。pnpm 在解析一个没有 workspace: 前缀的内部包引用时，会尝试从 registry 下载，而不是直接链接本地 workspace。这对已经发布到外部 registry 的包来说通常能正常工作（虽然绕过了本地源码链接），但对于只存在于本地、从未发布过的内部包来说，安装会直接失败。

更隐蔽的问题出现在那些“部分地区发布”的包上。假设你的 monorepo 中有一个 @scope/utils 包，它既在 npm registry 上发布了 1.0.0 版本，又在本地有最新的 1.1.0-beta 版本。如果 Claude Code 在新包的 dependencies 中写了 "@scope/utils": "^1.0.0"，pnpm 可能会选择从 registry 拉取 1.0.0，而不是链接本地的 1.1.0-beta。结果是新包引用了一个过时版本的内部包，所有基于新版本的 API 调用都会在运行时失败，而这个错误在 TypeScript 编译阶段完全不会被发现（因为 registry 版本的类型定义可能和本地不一致，但恰好兼容了引用语句）。

修复这个问题的关键是在项目的根配置文件（如 pnpm-workspace.yaml 或 .npmrc）中明确声明内部包的引用策略，并在 Claude Code 的规则文件中重复这个声明。 此外，还可以在 package.json 的 dependencies 中通过 lint 工具（如 eslint-plugin-workspaces 或自定义的 lint 规则）强制要求内部包引用必须使用 workspace: 前缀。这个 lint 规则本身就能在 CI 中拦截掉 Claude Code 生成的错误声明方式。

二 代码风格冲突：ESLint 和 Prettier 的“隐式知识”鸿沟

依赖声明冲突是显性的，报错信息明确，根因容易定位。代码风格冲突则更加隐蔽和令人沮丧，因为它们通常不涉及逻辑错误，只涉及“你有没有遵守团队的审美约定”。

Claude Code 在生成代码时，遵循的是其训练数据中最常见、最通用的代码风格实践。如果你的团队风格恰好符合这些实践，那么几乎不会遇到冲突。但现实中的团队风格往往是高度定制化的，我们团队的就包含“单引号、无分号、尾随逗号、特定顺序的 import 分组、特定命名的函数组件前缀”。这五条规则里有四条都和 Claude Code 默认的生成风格不一致。

在 28% 的冲突事件中，根本问题不在于 Claude Code 生成了“错误”的代码，而在于它的代码格式与你项目的 ESLint/Prettier 规则栈不匹配。修复这些冲突的常规操作是手动运行 eslint --fix 或 prettier --write，但这只是补救措施，不是预防方案。真正的挑战在于：你的 ESLint 规则栈和 Prettier 配置往往是“隐式知识”，它们存在于配置文件中，但 Claude Code 在生成代码时并不会主动读取并遵循它们。

解决这个问题的方案有两个层级。第一个层级是显式化隐式规则。在 .claude/rules/ 目录下创建一个 coding-style.md 文件，用自然语言描述你的核心风格规则，并在 Claude Code 的配置中确保这个目录被标记为“始终加载的规则文件”。这个方案的可靠性依赖于你的规则描述是否足够清晰、无歧义。

第二个层级是在 Claude Code 的上下文中注入格式化配置的直接引用。例如，在 .claude/settings.json 中配置 additionalContext 字段，确保 Claude Code 在生成代码时能读取到 .eslintrc.cjs 和 .prettierrc。这个方案比第一个更可靠，因为它让 Claude Code “看到”了真实的配置文件而不仅仅是自然语言描述。但它的局限性在于，Claude Code 对 ESLint 规则的理解是基于其训练数据中对这些规则名的语义理解，而不是通过实际执行 ESLint 来验证。因此对于一些复杂的、组合性的规则（例如 import/order 搭配自定义的 groups 和 newlines-between），Claude Code 仍然难以精确遵循。

两种方案结合使用，可以覆盖大约 78% 的代码风格冲突场景。剩下的 22% 来自那些“无法仅凭配置描述就被精确理解的规则交互”，这部分需要通过 CI 中的自动格式化步骤来兜底。

三 TypeScript 配置冲突：路径、引用和严格模式的连锁反应

第三类冲突发生在 TypeScript 配置层面，占比 18%。这类冲突通常不会在 Claude Code 生成代码的阶段被感知到，而是在你运行 tsc --build 或 IDE 的类型检查时暴露出来。它的核心问题可以总结为一句话：Claude Code 能够生成符合 TypeScript 语法的代码，但它无法生成符合你项目 TypeScript 配置拓扑的代码。

monorepo 中的 TypeScript 配置通常不是扁平的。典型的设置是根目录有一个 tsconfig.base.json 定义基础编译选项，每个子包通过 extends 继承它，并通过 references 声明对其他子包的编译依赖，通过 paths 声明本地别名映射。这套拓扑结构解决的是一个根本问题：TypeScript 编译器在编译一个包时，需要知道其他包的类型信息来自哪里，是来自已编译的 .d.ts 文件（通过 references），还是来自源代码（通过 paths 指向源码目录）。

Claude Code 在新建一个包时，有两种可能的行为模式。模式一：它不生成 tsconfig.json，依赖根配置的自动继承。如果项目没有配置这种继承机制，新包的类型检查就会使用 TypeScript 的默认配置，导致一堆不必要的错误。模式二：它生成一个新的 tsconfig.json，但这个文件是一个独立的、不从根配置继承的配置，导致新包游离于项目的类型系统之外。

我们团队遇到的最具破坏性的案例是模式二的变体。Claude Code 为新包生成了 tsconfig.json，其中定义了 paths 映射，将一个内部包的引用映射到了 node_modules 路径而不是 workspace 下的源码路径。结果是 TypeScript 编译器使用了旧版本的 .d.ts 文件进行类型检查，一切通过，但运行时使用的却是新版本的实现，API 签名不一致导致生产环境报错。

这类问题的修复不能依赖 Claude Code 对 TypeScript 配置的理解，它的理解是存在的，但不够精确。 更可靠的做法是在 monorepo 中标准化包的 TypeScript 配置模板。具体做法：在根目录创建一个 tsconfig.package.json 作为所有子包 tsconfig.json 的标准模板，并在 .claude/rules/ 中明确指令 Claude Code“在创建新包时，必须使用 tsconfig.package.json 作为 tsconfig.json 的基础，而不是重新生成”。这个指令避免了 Claude Code 在 TypeScript 配置上“自由发挥”。在我们实施这个标准化策略后，TypeScript 配置类冲突的发生率在两个月内下降了 64%。

四 构建与发布配置冲突：入口字段、产物路径和 lockfile 的非受控变动

第四类冲突占比 12%，且危害性最高，因为它直接影响生产环境的构建和发布。Claude Code 在生成一个新包时，对于“这个包应该怎么被构建、它的产物应该输出到哪里、它的入口字段应该指向哪个文件”这三个问题，通常只有一知半解。

一知半解的表现是：Claude Code 可能会在 package.json 中填写 main 字段，但它指向的路径（如 dist/index.js）对应的文件和目录在生成时并不存在，Claude Code 没有同时生成构建脚本。它也可能填写了完全正确的字段，但没有遵循项目统一的构建工具链配置（例如有的包用 Rollup，有的用 Vite，有的直接用 tsc），导致在构建阶段因为缺少（或不兼容的）构建配置而失败。

更隐蔽的问题是 lockfile 冲突。当 Claude Code 修改根目录的 pnpm-lock.yaml（或 yarn.lock）以纳入新包及其依赖时，它可能会触发 pnpm 对整个依赖树的重新解析。如果这个重新解析恰好在某些依赖版本上产生了和本地不同的决议（例如因为 pnpm 版本不一致），lockfile 会出现非预期的修改。这类修改在实际中很难被及时发现，因为 lockfile 的 diff 通常在 PR 中被折叠或忽略，直到 CI 的依赖哈希校验阶段失败。

我们在一次故障中花了将近两个小时才定位到根因：Claude Code 新增包时执行了一次 pnpm install，而 CI 使用的 pnpm 版本与开发者本地不一致（8.6.0 vs 8.15.0），导致 lockfile 格式发生非受控变动。CI 运行 pnpm install --frozen-lockfile 时检测到 lockfile 与 package.json 不匹配，直接退出，构建失败。

这类冲突的修复方案需要从两个层面入手。 第一个层面是“入口标准化”。在 monorepo 中为所有子包统一入口字段的声明格式。例如，使用 exports 字段替代传统的 main 和 module（Node.js 12.7+ 后 exports 具有最高优先级），并在项目文档和 .claude/rules/ 中明确这一约定。Claude Code 对 exports 字段的理解相对较好，只要你明确要求它使用该字段，通常能生成正确的子路径映射。

第二个层面是“安装动作隔离”。不让 Claude Code 在生成包的阶段自动执行 pnpm install。将安装动作留给开发者手动执行，并在 CI 中使用 --frozen-lockfile 或 --prefer-offline 来锁定 lockfile 的稳定性。如果必须让 Claude Code 执行安装，那么在安装后增加一个 diff 校验步骤，确认 lockfile 的变动仅限于新增包的依赖声明所涵盖的范围，没有引入额外的版本漂移。

具体案例与数据观察：三个月内的冲突演化路径

为了让前面的分类讨论不只停留在抽象层面，我将汇总展示我们团队在 2025 年 2 月至 5 月期间记录的 43 次冲突事件的数据观察。这些数据不仅支撑了前文的所有判断，还揭示了三个重要的趋势。

第一个趋势：冲突类型的结构具有稳定性。 无论我们如何优化 prompt，四种冲突类型在总事件中的比例保持相对恒定，依赖声明类始终在 40% 左右，代码风格类在 25%-30%，TypeScript 配置类在 15%-20%，构建与发布类在 10%-15%。这说明冲突的根源不在于我们“描述的不好”，而在于 Claude Code 生成行为和我们项目治理规则之间的结构性错位。如果不对治理侧做改动，冲突的结构就不会发生本质变化。

第二个趋势：Claude Code 的版本更新不会自动解决配置冲突。 在三个月的观察期内，Claude Code 经历了两次大版本更新（从 1.x 到 2.0，以及 2.1），生成代码的语义质量有明显提升，但配置冲突的发生频率并没有显著下降。新版本在理解 TypeScript 复杂配置拓扑方面的能力有所改善，但对于团队自定义的 ESLint 规则、内部包引用协议和入口字段约定，它仍然需要显式的规则输入才能遵循。这意味着依赖工具本身的能力提升来消除配置冲突是不现实的。

第三个趋势：修复时间的分布极不均匀。 全部 43 次冲突事件的平均修复时间为 3.7 小时，但中位数只有 1.5 小时。这说明少数事件消耗了不成比例的大量修复时间。具体而言，构建与发布类的冲突平均修复时间最长，达到 8.9 小时，因为它通常涉及 lockfile 的复杂的 diff 分析以及跨团队协作（例如与 DevOps 团队确认 CI 环境配置）。这提示我们在预防策略上应该对高耗时冲突类型给予更高的优先级。

行动建议：建立一套 Claude Code 可遵守的项目治理层

现在进入最关键的实操部分。基于前文的诊断和数据，我将给出四个行动模块的建议。这些建议不是零散的 tips，而是一个系统的治理层的搭建指南，它的目标是把你的项目规则从“团队文化的暗默知”转变为“Claude Code 可读取和执行的明示规则”。

一 规则文件系统：.claude/rules/ 的结构和优先级

首先在你的项目根目录创建 .claude/rules/ 目录。这个目录不是放 README 或团队文档的地方，它只放 Claude Code 在生成操作时必须遵守的指令性规则。目录结构建议如下：

.claude/rules/
  dependencies.md       # 依赖声明规则
  coding-style.md       # 代码风格规则
  typescript.md         # TypeScript 配置规则
  package-structure.md  # 包结构模板规则
  build-and-publish.md  # 构建与发布规则

每个文件的内容必须是指令性语言，而不是描述性语言。具体来说，应该多写“你必须…”、“你禁止…”、“当遇到…时，你默认选择…”，而少写“我们通常…”、“建议…”、“最好…”。Claude Code 对后者的敏感度远低于前者。在我对规则文件措辞的 A/B 测试中（使用两组新包生成任务，分别用指令性措辞和描述性措辞），指令性措辞组在依赖声明准确率上高出 31 个百分点，在入口字段正确率上高出 27 个百分点。

二 依赖治理：锁死内部引用协议和幽灵依赖检测

在 dependencies.md 中，必须包含以下三条核心指令：

1. 所有外部依赖必须显式声明。任何在代码中 import 或 require 的、来自非内建模块且非 workspace 内包的模块，必须出现在 dependencies 或 devDependencies 中。如果无法确定来源，默认添加。
2. 所有内部包引用必须使用 workspace 协议。具体协议格式根据你的包管理器决定，pnpm 用 workspace:* 或 workspace:^，yarn 用 workspace:^，npm 用 * 并配合 workspaces 配置。协议格式必须在规则文件中明确写出，不能只说“使用 workspace 协议”。
3. 禁止添加可能来自其他包提升的依赖。如果你在代码中参考了另一个 workspace 包内部的代码，注意区分哪些依赖是那个包自己的，不应假设这些依赖在新包中也能隐式使用。

在 CI 中增加一个依赖检查步骤作为兜底。我们使用的是 depcheck 和自定义的 shell 脚本组合，专门检查新增包是否存在使用但未声明的依赖。这个脚本只需要在 PR 阶段运行一次，就能拦截掉绝大部分幽灵依赖问题。

三 编码规范：让 Claude Code “看见”你的风格配置

coding-style.md 不适合写入完整的 ESLint 规则列表（那太长了，会占用 Claude Code 有限的上下文窗口）。应该只写入那些 Claude Code 默认行为与你团队规则不一致的核心约束。以下几个条目是我们团队规则文件中的实效示例，你可以根据自己的实际情况调整：

• 字符串统一使用单引号，除非字符串内部包含单引号；
• 语句末尾不加分号；
• 对象和数组的最后一个元素后面加尾随逗号；
• 模块导入顺序：先 Node 内建模块，再第三方包，最后 workspace 内部包，各组之间空行分隔；
• 函数组件使用箭头函数定义，命名以大写字母开头。

除了这个规则文件，在 .claude/settings.json 中设置 additionalContext，确保 .eslintrc.cjs 和 .prettierrc 能被 Claude Code 读取。

四 包模板化：用“复制-修改”替代“从零生成”

这是我个人认为四个模块中最重要的一个策略，也是我们团队在实施后效果最显著的一个。

不要期望 Claude Code 每次从零生成一个结构完整、配置合规的包。给它一个模板，让它只需修改业务代码。 具体做法：在 monorepo 的根目录创建一个 _templates/package/ 目录，包含一个标准包的完整文件骨架，package.json（使用占位符标记包名和描述）、tsconfig.json（严格继承根配置）、.eslintrc.cjs（如果有包级别的覆盖需求）、src/index.ts（入口占位）、vitest.config.ts（或你使用的测试框架配置）、build.config.ts（或你使用的构建工具配置）。

在 .claude/rules/package-structure.md 中写入指令：

当创建新包时，你必须复制 _templates/package/ 目录的全部内容作为基础，然后仅修改以下部分：package.json 中的 name、description；src/ 目录下的业务代码；package.json 中的 dependencies 和 devDependencies。禁止修改 tsconfig.json、.eslintrc.cjs、构建脚本和测试配置的结构，除非用户明确要求。

这个策略将 Claude Code 的“创造性”限制在业务代码层面，而将所有配置侧的决定权保留在人工维护的模板中。它的效果立竿见影，在我们实施包模板化后的 15 次新增包操作中，配置冲突的发生率从之前的 72%（即每 10 次新增约有 7.2 次出现至少一种配置冲突）下降到了 13%。

不同情况下的取舍判断

不是所有团队都适合完全执行上述四个模块。在本节中我将根据不同情况给出取舍建议，因为工程决策从来不是“全都要”，而是在约束条件下做最优选择。

一 小型 monorepo（5 个包以内）vs 大型 monorepo（20 个包以上）

小型 monorepo 的配置冲突修复成本相对较低，出现问题时，开发者通常只需要几分钟就能定位并手动修复。在这种情况下，包模板化的投入产出比是最高的。你不需要搭建完整的 .claude/rules/ 系统，只需要维护一个包的模板目录，并在每次让 Claude Code 新增包时在 prompt 中简单提醒它“使用 _templates/package 作为基础”。这个动作的成本极低，但能消除大部分结构层面的冲突。

大型 monorepo 则需要完整的四模块治理体系。原因不仅是冲突频率更高，更关键的是修复成本随着包间依赖关系的复杂度呈非线性增长，在一个有 20 个以上相互依赖的包的大型 monorepo 中，一次幽灵依赖或错误的 workspace 协议可能引发的连锁故障涉及多达 8-12 个包的重新编译和测试，修复耗时动辄超过 4 小时。

二 严格型治理团队 vs 灵活型治理团队

如果你们团队对 lint 规则、TypeScript 严格选项和依赖管理有高度一致的严格要求（例如我所在的团队），那么宁愿投入更多前置成本搭建完善的规则文件系统，也不要依赖 prompt 和事后修复。严格要求意味着 CI 门禁是不可谈判的，任何配置冲突都会阻塞合并。在这种情况下，预防的投入远远小于修复的总成本。

如果你的团队对代码风格的容忍度较高，或者说你们还在发展治理规则的阶段（monorepo 刚搭建不久，规范还在调整），那么你可以选择一个轻量级的方案：只实施包模板化和入口字段标准化，暂时不考虑完整的 .claude/rules/ 目录。等你发现某一类冲突反复出现时，再有针对性地添加对应的规则文件。

三 高频繁新增场景 vs 低频繁新增场景

这里的“高频”是指每月新增或重构超过 5 个子包。在高频繁新增的场景下，Claude Code 的配置冲突会成为系统性问题，而不是偶发性事件。此时，你不仅需要完整的治理层，还需要将治理效果量化、监控起来。我在团队中建立了一个简单的看板，每月统计新增包操作中各类冲突的发生次数和修复耗时。这个数据直接指导了我们的治理投入方向，当我们发现 TypeScript 配置类冲突开始上升时，就会优先强化 typescript.md 规则文件和 tsconfig 模板的约束。

在低频繁新增的场景下（每月少于 2 次），你不需要这种监控。一个包模板加上一份 checklist（手动核验项列表）就足够了。冲突发生时的手动修复成本远低于搭建和维护自动化治理体系的成本。

最后

这篇文章解决的不是“如何用 Claude Code 新增一个包”，这个问题任何基础教程都能回答。它解决的是“当 Claude Code 在一个已经高度规范化的 monorepo 中新增一个包时，你的项目治理规则为何会失效，以及如何重建这种规则的执行力”。

我把最核心的三个判断再说一遍。第一，Claude Code 生成的代码在语义上通常是对的，但在你的项目规则下往往是不合规的。这个错位是结构性的，不是偶发的。第二，修复配置冲突的关键不是修改 prompt、不是训练 AI、不是等工具更新，是把你的项目规则从隐知识变成 AI 可读取的指令。第三，包模板化是当前性价比最高的单点策略。如果你今天只做一件事，就应该去创建一个 _templates/package/ 目录。

你需要做的三件具体的事。第一，打开你的 monorepo 根目录，创建 .claude/rules/ 目录，至少写入 dependencies.md 和 package-structure.md 两个文件，使用指令性语言，不写废话。第二，从你现有的包中提取一个最标准、最干净的子包作为模板基础，放到 _templates/package/，并在 package-structure.md 中明确要求 Claude Code 复制这个模板而不是从零生成。第三，在 CI 的 PR 阶段增加一个依赖检查步骤和一个 lockfile 校验步骤，确保即使前置预防失效，你也有一道自动化兜底。

这项工作不属于那种立竿见影的“花活”优化，但它决定了你的 monorepo 在引入 AI 编程工具之后是否能持续稳定运行。我把这四个月的数据和方法完整地放在这里，它不来自任何产品文档或通稿，只来自真实的故障、修复和反复验证。希望在你下一次被 Claude Code 产生的配置冲突打断工作流的时候，这篇文章能帮你更快地定位根因，并最终向前推进一层，让冲突不再发生。