018、多项目工作区配置：workspace 隔离、项目级策略与通用模板的平衡

018、多项目工作区配置workspace 隔离、项目级策略与通用模板的平衡一个让我熬夜到凌晨三点的bug上周五晚上我正用Claude Code重构一个微服务网关项目。这个项目依赖三个内部库分别放在libs/auth、libs/logger和libs/config目录下。我习惯性地在项目根目录执行了claude code然后开始写一个路由中间件。Claude Code帮我生成了代码自动导入了internal/auth和internal/logger。看起来一切正常。但当我运行测试时TypeScript报了一堆路径解析错误——Claude Code把internal/auth解析到了node_modules里的某个同名包而不是我本地的libs/auth。更诡异的是我同事的机器上同样的配置却能正常工作。我们对比了claude.json、tsconfig.json、package.json甚至对比了Node版本最后发现问题是我的工作区根目录下有一个全局的.claude/workspace.json它覆盖了项目级别的路径映射配置。这个bug让我意识到多项目工作区的配置隔离问题远比想象中复杂。今天就把我踩过的坑和总结的经验写下来。workspace隔离别让一个项目污染另一个Claude Code的workspace机制本质上是一个上下文隔离层。每个workspace有自己的对话历史、文件索引、工具调用记录。但问题在于workspace的边界定义并不直观。显式创建workspace别依赖自动检测很多人习惯直接cd project-a claude code让Claude Code自动创建workspace。这在单项目场景下没问题但当你同时维护多个项目时自动检测会频繁误判。我现在的做法是// 在 ~/.claude/workspaces/ 下手动创建// project-a.json{name:project-a-gateway,root:/Users/me/work/project-a,include:[src/**/*,libs/**/*,config/**/*],exclude:[node_modules,dist,.git],maxTokens:32000}这里有个关键点include路径一定要精确。我之前图省事写include: [**/*]结果Claude Code把node_modules里几百MB的依赖全索引了每次启动慢得像蜗牛而且经常把第三方库的代码当成项目代码来建议修改。环境变量隔离一个血泪教训更隐蔽的问题是环境变量。我有两个项目都用了DATABASE_URL这个环境变量但指向不同的数据库。Claude Code在workspace A里记住了数据库连接信息切到workspace B时它居然从历史记录里把A的数据库URL拿过来用了。解决方案是在每个workspace配置里显式声明环境变量// project-a.json{name:project-a,env:{DATABASE_URL:postgres://localhost:5432/project_a,NODE_ENV:development,API_KEY:${PROJECT_A_API_KEY}// 从系统环境变量读取别硬编码}}别这样写把API密钥直接写在workspace配置文件里然后提交到Git仓库。我见过有人这么干结果密钥被CI日志打印出来了。项目级策略每个项目都有自己的脾气不同项目对Claude Code的行为要求完全不同。一个前端React项目和一个后端Go服务它们的代码风格、测试框架、构建工具链天差地别。项目级策略就是告诉Claude Code“在这个项目里按我的规矩来。”策略文件的放置位置我习惯在每个项目根目录放一个.claude/rules.md文件。这个文件定义了项目特有的规则# Project Rules for Gateway Service ## 代码风格 - 使用ESM模块禁止CommonJS - 函数参数超过3个必须用对象解构 - 错误处理统一使用Result模式不要throw ## 测试规范 - 单元测试放在 __tests__ 目录与源码同层级 - 集成测试放在 tests/integration/ - 测试覆盖率目标分支覆盖率 85% ## 依赖管理 - 禁止直接修改 package-lock.json - 新增依赖必须经过团队评审 - 内部库优先使用workspace协议workspace:* ## 工具链 - 使用pnpm不要用npm或yarn - 构建命令pnpm build:gateway - 格式化工具Prettier配置在 .prettierrc这个文件写清楚后Claude Code生成的代码基本不会跑偏。但有个坑规则文件不要写得太长。我见过有人写了200多行的规则结果Claude Code每次生成代码前都要花10秒解析规则而且经常忽略后半部分的内容。经验是控制在50行以内重点突出。策略的优先级谁说了算当全局策略和项目级策略冲突时Claude Code的优先级是这样的当前对话中的显式指令最高项目级.claude/rules.md全局~/.claude/config.json默认行为最低这个优先级顺序意味着如果你在对话中说了“用CommonJS”它会覆盖项目规则里的ESM要求。所以团队协作时要约定好不要在对话中随意覆盖项目规则。通用模板别重复造轮子但要有选择地复用我维护了一个claude-templates仓库里面放了各种项目类型的模板配置。但直接复制粘贴会导致问题——每个项目都有特殊性。模板的层次结构我的模板仓库结构是这样的claude-templates/ ├── base/ # 所有项目通用的基础配置 │ ├── claude.json │ └── rules.md ├── node-backend/ # Node.js后端项目 │ ├── claude.json │ ├── rules.md │ └── prompts/ │ └── api-design.md ├── react-frontend/ # React前端项目 │ ├── claude.json │ └── rules.md └── go-service/ # Go服务项目 ├── claude.json └── rules.md使用模板时我写了一个简单的脚本来自动化#!/bin/bash# 这里踩过坑直接cp会把模板里的占位符也复制过去# 所以用sed替换项目名PROJECT_NAME$1PROJECT_TYPE$2cp-r~/claude-templates/$PROJECT_TYPE/* ./# 替换占位符sed-is/{{PROJECT_NAME}}/$PROJECT_NAME/g.claude/rules.mdsed-is/{{PROJECT_NAME}}/$PROJECT_NAME/g.claude/claude.jsonecho模板已应用请检查 .claude/ 目录下的配置文件模板的“可覆盖点”模板里我会用{{PLACEHOLDER}}标记出需要每个项目自定义的地方。比如// claude.json 模板{workspace:{name:{{PROJECT_NAME}},root:{{PROJECT_ROOT}},maxTokens:{{MAX_TOKENS}}},rules:{files:[.claude/rules.md],priority:project},tools:{allowed:[read,edit,execute,search],disallowed:[browser]// 后端项目一般不需要浏览器工具}}别这样写把maxTokens设成固定值。不同项目复杂度不同一个简单的CLI工具可能8000 tokens就够了但一个大型微服务项目可能需要64000 tokens。根据项目规模动态调整。平衡的艺术什么时候隔离什么时候共享这是最考验经验的部分。完全隔离会导致重复配置完全共享又会互相干扰。应该共享的配置基础工具链配置比如Prettier、ESLint的规则这些通常团队统一安全策略禁止执行某些危险命令如rm -rf /日志格式Claude Code的输出格式偏好必须隔离的配置环境变量不同项目的数据库、API密钥完全不同文件索引范围每个项目的源码目录结构不同测试命令不同项目的测试框架和命令不同构建工具Webpack、Vite、esbuild各有各的配置一个实用的判断标准当你发现自己在两个项目里反复做同样的操作比如“生成API文档”那就应该把这个操作提取成共享模板。反之如果某个配置只在一个项目里生效就别强行塞进全局配置。我的个人经验清单写到最后分享几个让我少加班的经验每个项目单独一个workspace不要复用。即使两个项目看起来很像也要分开。我吃过亏两个React项目共用一个workspace结果Claude Code把A项目的组件路径推荐给了B项目。项目级规则文件要版本控制。.claude/rules.md应该提交到Git仓库这样团队成员才能共享。但.claude/workspace.json可以加入.gitignore因为每个人的本地路径可能不同。定期清理workspace缓存。Claude Code会在~/.claude/workspaces/下缓存大量数据时间长了可能占用几个GB。我写了个cron任务每周清理超过30天未使用的workspace。用环境变量区分不同环境。我在~/.zshrc里设置了export CLAUDE_WORKSPACE_DIR$HOME/.claude/workspaces然后在不同终端窗口设置不同的CLAUDE_PROJECT环境变量这样可以在同一个终端里快速切换项目上下文。不要迷信模板。模板只是起点每个项目最终都会有自己的特殊性。我见过有人花大量时间维护一个“万能模板”结果每个项目用之前都要改一堆东西反而降低了效率。保持模板简单项目级配置灵活。最后说一句Claude Code的配置没有银弹。你花时间打磨配置它会在后续的开发中十倍回报你。但如果你一开始就追求完美配置可能永远也写不完第一行代码。先跑起来再优化这是工程化的铁律。