Cursor 多根工作区实战Monorepo 里用 文件夹 任务拆分压低无效搜索Monorepo 很香共享包、原子提交、统一 CI。对 Agent 却很辣一次「帮我看看仓库」模型可能在apps/、packages/、生成物与锁文件之间来回翻Token 与噪音齐飞最后 diff 还跨了三个不相关包。问题往往不是模型笨而是工作集没有边界。本文给出可落地的组合拳多根工作区按任务选根文件夹/文件圈定范围跨包需求拆会话。目标不是「永远不搜」而是把无效搜索压到可接受。适合 pnpm/yarn/npm workspaces、Bazel 风格大仓以及「前端后端共享包」同仓团队。摘要不要默认打开整仓根按任务只加相关 package 为工作区根。提问强制24 个路径锚点写清「不要动」的包。跨包拆会话一会话一目标阶段交接后再开下一包。先 Ask 定位再 Agent 改降低无锚点探索税。用包级命令验收类型检查/测试按 filter 跑不靠「感觉好了」。结论Monorepo 里 Agent 的效率首先来自工作集治理其次才是模型档位。结论卡手段解决什么反模式多根工作区缩小默认可见图永远打开全仓文件夹明确本轮材料空泛「看看整个 monorepo」任务拆分控制 diff 半径一会话改 webapidbAsk→Agent减少盲目搜索一上来就高权限乱改包级验证证明只影响相关包只看 Agent 口头「通过」背景与边界Cursor / VS Code 支持多根工作区.code-workspace多 folder。Agent 仍可能通过工具搜索工作区外或通过 git 根发现更多文件因此多根不是沙箱只是强烈的默认边界提示。本文不承诺具体省 Token 百分比不讨论构建系统细节 monorepo 工具链以你仓库为准。边界安全上仍要靠 Rules、审 diff、CI多根不能替代密钥门禁。原理无效搜索从哪来一次无边界 Agent 回合典型浪费链是语义搜索打到无关包读取巨型生成文件或锁文件错误假设跨包依赖开始「顺手修」历史线程堆积失败日志下一轮继续回灌。多根与的作用是把步骤 12 的先验压窄任务拆分防止步骤 3阶段新开防止步骤 4。步骤 1按任务建立多根工作区示例web-ui.code-workspace{folders:[{name:web,path:apps/web},{name:ui,path:packages/ui}],settings:{}}示例api-db.code-workspace{folders:[{name:api,path:apps/api},{name:db,path:packages/db}]}用法改官网按钮时打开web-ui改迁移时打开api-db。需要全仓大图时再开 monorepo 根但默认不要。注意路径相对.code-workspace文件位置把 workspace 文件放在仓根通常最省事。步骤 2提问模板——文件夹 边界apps/web packages/ui 目标调整 PrimaryButton 的悬停样式并更新 Storybook。 不要动apps/api、packages/db、任何环境变量文件。 验收在 apps/web 下运行既有 story/test 命令给出你仓库真实命令总结改动文件列表。固定四要素锚点、目标、禁止、验收。缺「禁止」时Agent 最容易跨包发挥。再给一个 API 向模板apps/api/src/routes packages/shared 目标为 /v1/orders 列表增加分页参数校验。 不要动数据库迁移与前端页面。 先输出计划与影响面我确认后再改。 验收相关单测命令 期望结果。「先计划后改」在 Monorepo 尤其重要确认影响面比炫技一次改完更便宜。步骤 3跨包需求拆成可验收子任务反例把下单链路从 UI 到 DB 全部打通并优化。正例拆分会话 AAsk阅读现有下单链路输出序列图与文件清单只读。会话 BAgentwebui只改前端校验与错误展示。会话 CAgentapi只改 API 校验与单测。会话 DAgentdb如需迁移与回滚说明。会话 EAsk/人工对照清单做集成验收。每会话结束写交接## 已完成 - ... ## 未完成 - ... ## 验证命令 - ... ## 禁止下一会话做的事 - 不要改另一包已合并的接口形状除非更新契约测试步骤 4先 Ask 定位再 Agent 下手无锚点时优先apps/api 只用只读方式定位创建订单的入口文件与测试在哪列路径不要改代码。拿到路径后再开 Agent并精确文件。这会显著减少「读了五份无关实现」的回合。步骤 5包级验收命令按工具链改写例如 pnpmpnpm--filterwebtestpnpm--filterapitestpnpm--filterdbtest或nx run web:test nx run api:lint把真实命令写进 Rules 或 README要求 Agent回传命令与退出含义而不是「测试应该没问题」。若改动声明只影响web却跑全仓测试且大面积失败先怀疑工作集失控或环境问题而不是继续让 Agent 「顺手修红」。步骤 6配合 ignore 与 Rules.cursorignore挡dist、coverage、巨大快照域 Rulesapps/web/**与packages/db/**分开Always只留安全与验证约定。多根是「看见谁」Rules 是「对看见的人说什么话」两者叠加才完整。场景表任务工作区根建议改按钮样式web uipackages/uiapps/web相关页面改 API 契约api shared路由文件 契约类型修 migrationdbapi迁移目录 调用方全仓重命名先 Ask 计划按包分会话推进查清依赖方向全仓只读明确「只输出图不改」陷阱以为多根等于沙箱仍可能搜到或读到预期外文件靠审 diff。了根目录当安慰剂/过大等于没锚点。一会话跨三包重构失败成本极高拆开。验收命令写假的仓库没有的 npm script 不要瞎编。长线程不切段上包的失败日志污染下包。忽略生成物没 ignore 时 Agent 爱读 build 输出。验证清单工作区根是否只含本任务相关包提问是否带 24 个锚点是否写明禁止改动的包跨包是否拆成可验收子任务是否先 Ask 再 Agent复杂任务是否用包级命令验证长线程是否在阶段边界新开diff 是否出现无关包有则回溯边界一周练习计划天练习1为两个高频任务各建一个.code-workspace2把个人常用提问改成「锚点禁止验收」模板3选一个跨包需求强制拆成三次会话4补.cursorignore与域 Rules5复盘一次「无关包出现在 diff」的事故67写成团队短公约三句话团队公约可以短到三句按任务选根提问必跨包必拆会话。与 DevDay 启示的衔接云端 Space 强调共场知识本地 Monorepo 更要强调共场但分片不是把全仓知识一次性塞进上下文而是让「此刻相关的包」进场。Decisions 式固定选项也可用于 monorepo 路由只读画依赖/只改 web/只改 api/停手升级。实战案例一次「改按钮」如何避免改到 API背景设计要求调整PrimaryButton悬停色并更新 Storybook。仓内同时有apps/web、apps/api、packages/ui、packages/db。错误打开方式打开 monorepo 根对 Agent 说「把主按钮悬停色改成设计稿那样」。常见后果模型去搜「Primary」字符串改到 API 错误码文案、文档站点、甚至 e2e 快照diff 噪声巨大。推荐路径打开web-ui.code-workspace仅 webui。Askpackages/ui主按钮组件与 Story 路径在哪只列路径。Agentpackages/ui/src/PrimaryButton.tsx packages/ui/.../PrimaryButton.stories.tsx明确「不要动 apps/api 与任何非 UI 包」。验收在 ui/web 包运行 story/test人工看悬停效果。PR 描述列出文件清单若出现 api 路径立刻拒绝合并并回溯提问边界。把这个案例写成团队示例比抽象口号更有效每个人都经历过「只想改个颜色」。实战案例跨包契约变更背景API 列表接口新增必填分页参数前端必须同步。拆分会话模式范围产出1Askapi shared契约与调用点清单2Agentshared类型/schema 变更 单测3Agentapi校验逻辑 单测4Agentweb调用与错误展示5人工集成手动点路径 CI会话之间用交接模板不共用被失败日志污染的超长线程。契约测试放在 shared 或独立契约包避免「前端猜字段」。工作区文件管理建议把常用.code-workspace提交进仓不含本机绝对路径偏好也行。命名可读ws-web-ui.code-workspace、ws-api-db.code-workspace。README 写「改 UI 请打开某某工作区」——降低新人打开全仓的概率。不要把密钥放进 workspace 的settings。观测怎么知道无效搜索下降了不必上复杂平台先做轻量对比选 5 个真实小任务改样式、修单测、加校验、改文案、修类型错误。全仓根 无各跑一遍可在个人分支记录工具调用次数、是否误碰无关包、是否需回滚。多根 拆分再跑一遍对比误碰次数与回滚次数。关注误碰与回滚比纠结绝对 Token 数更可解释。若误碰降了但 Token 仍高再查 Always Rules 与 MCP。与 Rules、MCP 的协作顺序建议治理顺序多根 工作集Rules 分层前缀税MCP 按需工具税模式分流 Ask/Agent/Manual。颠倒顺序时常见现象是Rules 写得很美但每次仍对全仓无锚点喊话——体感仍「Agent 很瞎」。FAQ多根工作区常见疑问Q多根会不会让跳转定义失效取决于语言插件与 tsconfig/project references 是否仍能解析到包。若跳转受影响可在 workspace 中保留共享包根或在全仓根用「窗口复用」但提问仍强制。多根是默认边界不是唯一打开方式。QAgent 仍然读到了工作区外的文件怎么办把它当成常态风险多根不是安全沙箱。用「禁止事项」写进提示词用 diff 审查用 CI path filter。必要时在 Rules 写明「未经允许不要修改某路径」。Q一个 workspace 里放太多 folder 行不行folder 一多就回到「软全仓」。建议每个 workspace 24 个根对应一种任务类型。QBazel / 超大仓也适用吗适用而且更必要。优先按目标依赖闭包选根而不是按「整个 repo」。提问时到具体 package 目录。Q和 Composer 多文件编辑冲突吗不冲突。Composer/Agent 批量改文件时更需要事先圈定包边界否则批量能力会放大误改半径。先计划、再批量、再包级验收。可复制PR 描述模板Monorepo## 范围 - 触及包 - 明确未触及包 ## 验证 - 命令 - 结果 ## Agent 使用说明可选 - 工作区 - 锚点 - 是否拆分会话要求提交者填写「未触及包」能从流程上逼出边界意识写得出来通常就想过写不出来多半没想过。配图说明封面四包示意多根正反例、提问模板、Before/After、检查清单全部位于 images 目录正文已用相对路径引用。收尾提醒如果你只改一件事就改提问方式从「帮我看看 monorepo」改为「这两三个目录 不要动那些包 用这条命令验收」。工作区文件可以后补这句话今晚就能用。等误碰次数下降后再把成功经验写进 README 与 Rules让新人少付学费。Monorepo 的复杂性不会消失但可以把 Agent 的默认视野从「整座城」收成「今晚要修的那两条街」。一句话带走Monorepo 里的 Agent 效率是工作集问题不是嘴炮问题。多根选对根选对文件夹跨包拆会话再用包级命令验收——无效搜索会先降下来然后你才有资格讨论要不要换更强模型。草稿未发布 · 作者 梧桐秋海 · 活动九月创作之星、工具实践
Cursor 多根工作区实战Monorepo 里用 文件夹 任务拆分压低无效搜索Monorepo 很香共享包、原子提交、统一 CI。对 Agent 却很辣一次「帮我看看仓库」模型可能在apps/、packages/、生成物与锁文件之间来回翻Token 与噪音齐飞最后 diff 还跨了三个不相关包。问题往往不是模型笨而是工作集没有边界。本文给出可落地的组合拳多根工作区按任务选根文件夹/文件圈定范围跨包需求拆会话。目标不是「永远不搜」而是把无效搜索压到可接受。适合 pnpm/yarn/npm workspaces、Bazel 风格大仓以及「前端后端共享包」同仓团队。摘要不要默认打开整仓根按任务只加相关 package 为工作区根。提问强制24 个路径锚点写清「不要动」的包。跨包拆会话一会话一目标阶段交接后再开下一包。先 Ask 定位再 Agent 改降低无锚点探索税。用包级命令验收类型检查/测试按 filter 跑不靠「感觉好了」。结论Monorepo 里 Agent 的效率首先来自工作集治理其次才是模型档位。结论卡手段解决什么反模式多根工作区缩小默认可见图永远打开全仓文件夹明确本轮材料空泛「看看整个 monorepo」任务拆分控制 diff 半径一会话改 webapidbAsk→Agent减少盲目搜索一上来就高权限乱改包级验证证明只影响相关包只看 Agent 口头「通过」背景与边界Cursor / VS Code 支持多根工作区.code-workspace多 folder。Agent 仍可能通过工具搜索工作区外或通过 git 根发现更多文件因此多根不是沙箱只是强烈的默认边界提示。本文不承诺具体省 Token 百分比不讨论构建系统细节 monorepo 工具链以你仓库为准。边界安全上仍要靠 Rules、审 diff、CI多根不能替代密钥门禁。原理无效搜索从哪来一次无边界 Agent 回合典型浪费链是语义搜索打到无关包读取巨型生成文件或锁文件错误假设跨包依赖开始「顺手修」历史线程堆积失败日志下一轮继续回灌。多根与的作用是把步骤 12 的先验压窄任务拆分防止步骤 3阶段新开防止步骤 4。步骤 1按任务建立多根工作区示例web-ui.code-workspace{folders:[{name:web,path:apps/web},{name:ui,path:packages/ui}],settings:{}}示例api-db.code-workspace{folders:[{name:api,path:apps/api},{name:db,path:packages/db}]}用法改官网按钮时打开web-ui改迁移时打开api-db。需要全仓大图时再开 monorepo 根但默认不要。注意路径相对.code-workspace文件位置把 workspace 文件放在仓根通常最省事。步骤 2提问模板——文件夹 边界apps/web packages/ui 目标调整 PrimaryButton 的悬停样式并更新 Storybook。 不要动apps/api、packages/db、任何环境变量文件。 验收在 apps/web 下运行既有 story/test 命令给出你仓库真实命令总结改动文件列表。固定四要素锚点、目标、禁止、验收。缺「禁止」时Agent 最容易跨包发挥。再给一个 API 向模板apps/api/src/routes packages/shared 目标为 /v1/orders 列表增加分页参数校验。 不要动数据库迁移与前端页面。 先输出计划与影响面我确认后再改。 验收相关单测命令 期望结果。「先计划后改」在 Monorepo 尤其重要确认影响面比炫技一次改完更便宜。步骤 3跨包需求拆成可验收子任务反例把下单链路从 UI 到 DB 全部打通并优化。正例拆分会话 AAsk阅读现有下单链路输出序列图与文件清单只读。会话 BAgentwebui只改前端校验与错误展示。会话 CAgentapi只改 API 校验与单测。会话 DAgentdb如需迁移与回滚说明。会话 EAsk/人工对照清单做集成验收。每会话结束写交接## 已完成 - ... ## 未完成 - ... ## 验证命令 - ... ## 禁止下一会话做的事 - 不要改另一包已合并的接口形状除非更新契约测试步骤 4先 Ask 定位再 Agent 下手无锚点时优先apps/api 只用只读方式定位创建订单的入口文件与测试在哪列路径不要改代码。拿到路径后再开 Agent并精确文件。这会显著减少「读了五份无关实现」的回合。步骤 5包级验收命令按工具链改写例如 pnpmpnpm--filterwebtestpnpm--filterapitestpnpm--filterdbtest或nx run web:test nx run api:lint把真实命令写进 Rules 或 README要求 Agent回传命令与退出含义而不是「测试应该没问题」。若改动声明只影响web却跑全仓测试且大面积失败先怀疑工作集失控或环境问题而不是继续让 Agent 「顺手修红」。步骤 6配合 ignore 与 Rules.cursorignore挡dist、coverage、巨大快照域 Rulesapps/web/**与packages/db/**分开Always只留安全与验证约定。多根是「看见谁」Rules 是「对看见的人说什么话」两者叠加才完整。场景表任务工作区根建议改按钮样式web uipackages/uiapps/web相关页面改 API 契约api shared路由文件 契约类型修 migrationdbapi迁移目录 调用方全仓重命名先 Ask 计划按包分会话推进查清依赖方向全仓只读明确「只输出图不改」陷阱以为多根等于沙箱仍可能搜到或读到预期外文件靠审 diff。了根目录当安慰剂/过大等于没锚点。一会话跨三包重构失败成本极高拆开。验收命令写假的仓库没有的 npm script 不要瞎编。长线程不切段上包的失败日志污染下包。忽略生成物没 ignore 时 Agent 爱读 build 输出。验证清单工作区根是否只含本任务相关包提问是否带 24 个锚点是否写明禁止改动的包跨包是否拆成可验收子任务是否先 Ask 再 Agent复杂任务是否用包级命令验证长线程是否在阶段边界新开diff 是否出现无关包有则回溯边界一周练习计划天练习1为两个高频任务各建一个.code-workspace2把个人常用提问改成「锚点禁止验收」模板3选一个跨包需求强制拆成三次会话4补.cursorignore与域 Rules5复盘一次「无关包出现在 diff」的事故67写成团队短公约三句话团队公约可以短到三句按任务选根提问必跨包必拆会话。与 DevDay 启示的衔接云端 Space 强调共场知识本地 Monorepo 更要强调共场但分片不是把全仓知识一次性塞进上下文而是让「此刻相关的包」进场。Decisions 式固定选项也可用于 monorepo 路由只读画依赖/只改 web/只改 api/停手升级。实战案例一次「改按钮」如何避免改到 API背景设计要求调整PrimaryButton悬停色并更新 Storybook。仓内同时有apps/web、apps/api、packages/ui、packages/db。错误打开方式打开 monorepo 根对 Agent 说「把主按钮悬停色改成设计稿那样」。常见后果模型去搜「Primary」字符串改到 API 错误码文案、文档站点、甚至 e2e 快照diff 噪声巨大。推荐路径打开web-ui.code-workspace仅 webui。Askpackages/ui主按钮组件与 Story 路径在哪只列路径。Agentpackages/ui/src/PrimaryButton.tsx packages/ui/.../PrimaryButton.stories.tsx明确「不要动 apps/api 与任何非 UI 包」。验收在 ui/web 包运行 story/test人工看悬停效果。PR 描述列出文件清单若出现 api 路径立刻拒绝合并并回溯提问边界。把这个案例写成团队示例比抽象口号更有效每个人都经历过「只想改个颜色」。实战案例跨包契约变更背景API 列表接口新增必填分页参数前端必须同步。拆分会话模式范围产出1Askapi shared契约与调用点清单2Agentshared类型/schema 变更 单测3Agentapi校验逻辑 单测4Agentweb调用与错误展示5人工集成手动点路径 CI会话之间用交接模板不共用被失败日志污染的超长线程。契约测试放在 shared 或独立契约包避免「前端猜字段」。工作区文件管理建议把常用.code-workspace提交进仓不含本机绝对路径偏好也行。命名可读ws-web-ui.code-workspace、ws-api-db.code-workspace。README 写「改 UI 请打开某某工作区」——降低新人打开全仓的概率。不要把密钥放进 workspace 的settings。观测怎么知道无效搜索下降了不必上复杂平台先做轻量对比选 5 个真实小任务改样式、修单测、加校验、改文案、修类型错误。全仓根 无各跑一遍可在个人分支记录工具调用次数、是否误碰无关包、是否需回滚。多根 拆分再跑一遍对比误碰次数与回滚次数。关注误碰与回滚比纠结绝对 Token 数更可解释。若误碰降了但 Token 仍高再查 Always Rules 与 MCP。与 Rules、MCP 的协作顺序建议治理顺序多根 工作集Rules 分层前缀税MCP 按需工具税模式分流 Ask/Agent/Manual。颠倒顺序时常见现象是Rules 写得很美但每次仍对全仓无锚点喊话——体感仍「Agent 很瞎」。FAQ多根工作区常见疑问Q多根会不会让跳转定义失效取决于语言插件与 tsconfig/project references 是否仍能解析到包。若跳转受影响可在 workspace 中保留共享包根或在全仓根用「窗口复用」但提问仍强制。多根是默认边界不是唯一打开方式。QAgent 仍然读到了工作区外的文件怎么办把它当成常态风险多根不是安全沙箱。用「禁止事项」写进提示词用 diff 审查用 CI path filter。必要时在 Rules 写明「未经允许不要修改某路径」。Q一个 workspace 里放太多 folder 行不行folder 一多就回到「软全仓」。建议每个 workspace 24 个根对应一种任务类型。QBazel / 超大仓也适用吗适用而且更必要。优先按目标依赖闭包选根而不是按「整个 repo」。提问时到具体 package 目录。Q和 Composer 多文件编辑冲突吗不冲突。Composer/Agent 批量改文件时更需要事先圈定包边界否则批量能力会放大误改半径。先计划、再批量、再包级验收。可复制PR 描述模板Monorepo## 范围 - 触及包 - 明确未触及包 ## 验证 - 命令 - 结果 ## Agent 使用说明可选 - 工作区 - 锚点 - 是否拆分会话要求提交者填写「未触及包」能从流程上逼出边界意识写得出来通常就想过写不出来多半没想过。配图说明封面四包示意多根正反例、提问模板、Before/After、检查清单全部位于 images 目录正文已用相对路径引用。收尾提醒如果你只改一件事就改提问方式从「帮我看看 monorepo」改为「这两三个目录 不要动那些包 用这条命令验收」。工作区文件可以后补这句话今晚就能用。等误碰次数下降后再把成功经验写进 README 与 Rules让新人少付学费。Monorepo 的复杂性不会消失但可以把 Agent 的默认视野从「整座城」收成「今晚要修的那两条街」。一句话带走Monorepo 里的 Agent 效率是工作集问题不是嘴炮问题。多根选对根选对文件夹跨包拆会话再用包级命令验收——无效搜索会先降下来然后你才有资格讨论要不要换更强模型。草稿未发布 · 作者 梧桐秋海 · 活动九月创作之星、工具实践
