用途
该技能帮助 AI 在单体仓库(monorepo)中正确导航与操作。单体仓库会打破许多默认假设:哪个 package.json 才是“真正”的、node_modules 位于何处、应运行哪条测试命令、install 实际做了什么。该技能确保所有操作都针对正确的作用域。
检测
在会话开始或首次编辑文件时,检查以下标志文件:
- pnpm-workspace.yaml → pnpm workspaces
- turbo.json → Turborepo
- nx.json → Nx
- lerna.json → Lerna
- package.json 含 "workspaces": [...] → npm / yarn workspaces
- Cargo.toml 含 [workspace] → Rust workspaces
- go.work → Go workspaces
- pyproject.toml 含 Poetry/uv workspace 配置 → Python workspaces
若检测到上述标志,则进入单体仓库模式,并记录到工作流状态中。后续所有命令都必须遵守包作用域。
主要规则
-
始终先确定目标包。在任何 install、test 或 build 之前,明确改动位于哪个包,并使用完整路径如 packages/<name>/;以作用域方式运行而不是从根目录运行,例如 pnpm --filter <name> test。
-
跨包变更需要协调。如果改动涉及包 A 的 API 且被包 B 使用,应列出所有消费者(例如 grep -r "@your-org/package-a" packages/),在同一 PR 中更新所有消费者,并对所有受影响包运行测试,而不仅是包 A。
-
依赖放置很重要。仅被一个包使用的依赖放入该包的 package.json;被两个及以上包使用的依赖放入共享配置包或根 devDependencies;开发工具(eslint、prettier、jest)放根目录;工作区包在消费者 dependencies 中以 "workspace:*" 列出。
-
构建顺序遵循依赖图,不要假设按字母顺序构建。可查看 Turborepo 的 turbo.json pipeline 字段、Nx 的 nx graph,或运行 pnpm list --recursive --depth=0。
-
测试按作用域运行,而非从根目录运行。错误做法:npm test(运行全部测试,慢且常出错)。正确做法示例:turbo test --filter=[HEAD^1]、nx affected:test、pnpm --filter='...[HEAD^1]' test。[HEAD^1] 计算自上次提交以来受影响的包,CI 应使用相同方式。
常见陷阱
- node_modules 提升:包 A 可能意外使用包 B 的传递依赖,B 变更时 A 会出错。修复方式为显式声明依赖,不依赖提升。
- TypeScript 项目引用:在跨引用运行 tsc --build 之前,包 A 的改动不会出现在包 B 中。检查 tsconfig.json 的 references。
- Jest/Vitest 根配置:可能不会拾取每个包的配置。确认单体仓库工具正确交接(Turborepo 和 Nx 通常可以;原生 pnpm 不行)。
- CI 矩阵:每个 PR 都运行全套测试会浪费成本,应使用仅受影响检测。
- 锁文件:npm 7+ 和 pnpm 在根目录保留单一锁文件,不要提交每个包的锁文件。
与工作流的集成
- 阶段 1 设计:识别计划中涉及的所有包。
- 阶段 2 测试:仅针对受影响的包。
- 阶段 3 构建:运行作用域构建,而非根构建。
- 阶段 4 评审:检查跨包契约(版本间 API 兼容性)。
关联技能
- skills/framework-expert/SKILL.md:所用框架可能有单体仓库特定的集成。
- skills/test-writer/SKILL.md:单体仓库中的测试放置(按包还是共享测试目录)。
- rules/core/verification.md:验证命令在正确作用域中运行(实际执行了哪些测试)。
- commands/run.md:run-orchestrator 在检测到单体仓库标志时加载该技能。
限制
资料未提供收费、价格、平台支持范围或效果数据。