【Claude】团队协作与配置共享最佳实践 — 已解决

【Claude】团队协作与配置共享最佳实践 — 已解决适用版本Claude Code v1.0.x 及以上受影响场景多人团队共享配置、统一编码规范、子代理复用、CLAUDE.md 协同维护阅读时长约 25 分钟目录问题现象原理深挖配置层级与共享机制根因分析团队协作的五大痛点多方案解决从规范到自动化验证回归团队配置验证避坑最佳实践附录团队配置速查表1. 问题现象1.1 典型问题表现问题一团队成员 Claude Code 行为不一致# 开发者 A 的 Claude Code: # - 使用 Opus 模型 # - 没有权限限制 # - 没有 CLAUDE.md # 开发者 B 的 Claude Code: # - 使用 Sonnet 模型 # - 有权限配置 # - 有 CLAUDE.md # 结果: 同样的任务A 花费 $5, B 花费 $0.5 # 代码风格也不一致问题二配置无法共享# 开发者 A 花了 2 小时配置完美的 .claude/settings.json # 开发者 B 不知道自己从头配置 # 开发者 C 直接用默认配置 # 团队没有统一的配置标准问题三CLAUDE.md 维护混乱# 5 个开发者各自维护自己的 CLAUDE.md # 内容不一致 # 过时的规则没人更新 # 新成员不知道 CLAUDE.md 的存在问题四子代理/命令无法复用# 开发者 A 写了优秀的代码审查子代理 # 其他成员不知道无法使用 # 每个人重复造轮子问题五新人上手慢# 新成员加入团队 # 需要自己摸索 Claude Code 配置 # 没有统一的团队模板 # 2 周后才达到团队平均效率2. 原理深挖配置层级与共享机制2.1 配置文件层级┌─────────────────────────────────────────────────────┐ │ Claude Code 配置层级 │ ├─────────────────────────────────────────────────────┤ │ │ │ Level 1: 全局默认 (不入 Git) │ │ ~/.claude/settings.json │ │ → 个人全局偏好 (模型、主题等) │ │ │ │ Level 2: 全局个人 (不入 Git) │ │ ~/.claude/settings.local.json │ │ → 个人 API Key、代理等 │ │ │ │ Level 3: 项目共享 (入 Git) ✅ │ │ .claude/settings.json │ │ → 团队共享: 权限、模型、Hook │ │ │ │ Level 4: 项目个人 (不入 Git) │ │ .claude/settings.local.json │ │ → 个人覆盖: 临时权限、测试配置 │ │ │ │ Level 5: CLAUDE.md (入 Git) ✅ │ │ → 项目上下文、编码规范、架构说明 │ │ │ │ Level 6: 子代理/命令 (入 Git) ✅ │ │ .claude/agents/*.json │ │ .claude/commands/*.md │ │ → 团队共享的子代理和自定义命令 │ │ │ └─────────────────────────────────────────────────────┘ Git 跟踪策略: ✅ 入 Git (团队共享): .claude/settings.json .claude/agents/ .claude/commands/ .claude/hooks/ (脚本) CLAUDE.md ❌ 不入 Git (个人): .claude/settings.local.json ~/.claude/settings.json ~/.claude/settings.local.json .env (API Key 等)2.2 配置合并规则配置合并 (从低到高优先级): 全局默认 → 全局个人 → 项目共享 → 项目个人 权限合并: allow: 所有层级取并集 deny: 所有层级取并集 deny 优先于 allow 其他字段: 后者覆盖前者 (如 model、maxTurns) 示例: 全局: modelopus 项目: modelsonnet 个人: (未设置) → 最终: modelsonnet (项目覆盖全局)2.3 CLAUDE.md 加载顺序CLAUDE.md 搜索路径 (从高到低优先级): 1. 当前目录/CLAUDE.md 2. 父目录/CLAUDE.md 3. ... 递归向上 4. ~ /CLAUDE.md (全局) 所有找到的 CLAUDE.md 都会被加载 越近的优先级越高3. 根因分析团队协作的五大痛点3.1 痛点一配置不共享团队没有将.claude/settings.json纳入 Git 管理各人配置独立。3.2 痛点二CLAUDE.md 不统一多人各自维护 CLAUDE.md内容冲突或过时。3.3 痛点三子代理不复用优秀的子代理配置没有共享团队成员重复劳动。3.4 痛点四权限标准不一有的成员权限松散--dangerously-skip-permissions有的严格安全风险不一致。3.5 痛点五无新人引导没有团队配置模板和上手文档新成员需要自行摸索。4. 多方案解决从规范到自动化4.1 方案一团队配置仓库// .claude/settings.json — 团队共享配置 (入 Git) { model: claude-sonnet-4-20250514, smallModel: claude-haiku-4-20250422, permissions: { allow: [ Read(src/**), Read(tests/**), Read(docs/**), Edit(src/**), Edit(tests/**), Write(src/**), Write(tests/**), Bash(npm test*), Bash(npm run lint*), Bash(npm run build*), Bash(npx tsc --noEmit), Bash(git status*), Bash(git diff*), Bash(git log*) ], deny: [ Bash(rm -rf*), Bash(sudo *), Bash(git push --force*), Bash(npm publish*), Read(.env*), Read(**/id_rsa), Read(**/id_ed25519), Write(.env*), Write(.gitignore), Write(package.json), Write(tsconfig.json), Edit(.env*), Edit(package.json), Edit(tsconfig.json) ] }, hooks: { PreToolUse: [ { matcher: *, hooks: [{ type: command, command: python3 .claude/hooks/audit.py }] } ] }, env: { CLAUDE_DAILY_BUDGET: 10 } }// .claude/settings.local.json — 个人配置 (不入 Git) { env: { ANTHROPIC_API_KEY: sk-ant-xxx-personal-key } }# .gitignore — 确保正确忽略 .claude/settings.local.json .env4.2 方案二团队 CLAUDE.md 模板# CLAUDE.md — 项目上下文 (入 Git团队共享) ## 项目概述 - 项目名: MyAPI - 技术栈: TypeScript Node.js Express PostgreSQL - 架构: 微服务API Gateway 模式 - 部署: Docker Kubernetes ## 编码规范 - 使用 TypeScript strict 模式 - 函数必须有 JSDoc 注释 - 使用 async/await不用 Promise.then - 错误处理用自定义 AppError 类 - 测试覆盖率 80% ## 文件结构 - src/controllers/ → HTTP 控制器 - src/services/ → 业务逻辑 - src/repositories/ → 数据访问 - src/models/ → 数据模型 - src/middleware/ → 中间件 - src/utils/ → 工具函数 - tests/ → 测试 (镜像 src/ 结构) ## 命名规范 - 文件: kebab-case (user-service.ts) - 类: PascalCase (UserService) - 函数/变量: camelCase (getUserById) - 常量: UPPER_SNAKE (MAX_RETRY) - 数据库表: snake_case (user_sessions) ## Git 规范 - 分支: feature/*, bugfix/*, hotfix/* - Commit: conventional commits (feat:, fix:, docs:, refactor:) - PR 必须通过 CI 和代码审查 ## 测试规范 - 单元测试: Jest supertest - E2E 测试: Jest Testcontainers - Mock: jest.mock for repositories - 运行: npm test (watch), npm run test:ci (coverage) ## 安全规范 - 密码: bcrypt (rounds12) - JWT: RS256, 24h expiry - SQL: 参数化查询禁止拼接 - 输入验证: zod schemas - 敏感数据: 永不 log ## 已知问题 - #123: 连接池在高并发下泄漏 (临时方案: 重启) - #456: datetime 时区问题 (使用 UTC) ## AI 辅助开发指南 - 修改代码前先运行 npm test 确认基准 - 生成的代码必须通过 npm run lint - 不要修改 package.json 的依赖 - 优先修改现有代码避免创建新文件 - 复杂逻辑写注释简单逻辑不需要4.3 方案三团队子代理共享// .claude/agents/reviewer.json — 代码审查子代理 (入 Git) { name: reviewer, description: 高级代码审查员。检查代码质量、安全性、性能和规范遵循。, model: claude-sonnet-4-20250514, permissions: { allow: [ Read(**) ], deny: [ Write(**), Edit(**), Bash(*) ] }, maxTurns: 5, systemPrompt: 你是项目 MyAPI 的代码审查员。\n\n审查标准:\n1. TypeScript strict 兼容\n2. 有 JSDoc 注释\n3. 错误处理完善\n4. 无 SQL 注入风险\n5. 有对应测试\n6. 命名符合规范\n7. 无硬编码密钥\n\n输出格式:\n- PASS/FAIL\n- 问题列表 (按严重度排序)\n- 修复建议 }// .claude/agents/test-writer.json — 测试编写子代理 (入 Git) { name: test-writer, description: 测试编写专家。为给定代码生成全面的测试用例。, model: claude-sonnet-4-20250514, permissions: { allow: [ Read(src/**), Read(tests/**),  Write(tests/**), Edit(tests/**), Bash(npm test*) ], deny: [ Read(.env*), Write(src/**), Edit(src/**) ] }, maxTurns: 10 }// .claude/agents/security-auditor.json — 安全审计子代理 { name: security-auditor, description: 安全审计专家。扫描代码中的安全漏洞和风险。, model: claude-opus-4-20250514, permissions: { allow: [ Read(**), Bash(npm audit*), Bash(npx eslint*) ], deny: [ Write(**), Edit(**) ] }, maxTurns: 8 }4.4 方案四团队自定义命令!-- .claude/commands/review.md — 代码审查命令 (入 Git) -- 审查当前 Git diff 中的所有变更。 步骤: 1. 运行 git diff 获取变更 2. 分析每个文件的变更 3. 检查: 代码规范、安全性、性能、测试覆盖 4. 生成审查报告 5. 如果有问题提供修复建议 输出格式: ## 代码审查报告 - 总体评价: PASS / NEEDS_CHANGES / FAIL - 文件数: N - 问题数: N (Critical: N, Warning: N, Info: N) ### 问题详情 (按严重度排列)!-- .claude/commands/test-gen.md — 测试生成命令 -- 为指定文件生成测试用例。 使用方式: /test-gen src/services/user-service.ts 步骤: 1. 读取指定源文件 2. 分析函数和逻辑分支 3. 为每个函数生成测试用例 4. 包含: 正常路径、边界情况、错误处理 5. 写入 tests/ 目录 (镜像结构) 6. 运行测试验证 测试要求: - 使用 Jest - 覆盖率 80% - Mock 外部依赖 - 使用 describe/it 结构!-- .claude/commands/migrate-check.md — 迁移检查命令 -- 检查代码中是否使用了弃用的 API 或模型。 步骤: 1. 搜索所有源文件中的 API 调用 2. 检查 Anthropic SDK 版本 3. 检查模型名是否弃用 4. 检查 Claude Code 配置是否过时 5. 生成迁移报告 弃用清单: - 模型: claude-3-*, claude-3-5-* - API: messages.create v1 → v2 - SDK: 0.404.5 方案五配置初始化工具#!/usr/bin/env python3 团队配置初始化工具 新成员运行此脚本即可获取完整的团队配置 import json import os import shutil from pathlib import Path class TeamConfigInitializer: 团队配置初始化器 def __init__(self): self.project_dir Path.cwd() self.claude_dir self.project_dir / .claude def check_existing(self): 检查现有配置 if self.claude_dir.exists(): print(⚠ 发现现有 .claude/ 目录) response input(覆盖? (y/n): ) if response.lower() ! y: print(取消) return False return True def create_settings(self): 创建 settings.json settings { model: claude-sonnet-4-20250514, smallModel: claude-haiku-4-20250422, permissions: { allow: [ Read(src/**), Read(tests/**), Read(docs/**), Edit(src/**), Edit(tests/**), Write(src/**), Write(tests/**), Bash(npm test*), Bash(npm run lint*), Bash(npm run build*), Bash(npx tsc --noEmit), Bash(git status*), Bash(git diff*), Bash(git log*) ], deny: [ Bash(rm -rf*), Bash(sudo *), Bash(git push --force*), Read(.env*), Read(**/id_rsa), Read(**/id_ed25519), Write(.env*), Write(.gitignore), Write(package.json), Edit(.env*), Edit(package.json) ] } } settings_file self.claude_dir / settings.json settings_file.parent.mkdir(parentsTrue, exist_okTrue) with open(settings_file, w) as f: json.dump(settings, f, indent2, ensure_asciiFalse) print(f✓ 创建 {settings_file}) def create_local_settings(self): 创建 settings.local.json (个人配置) local_settings { env: { ANTHROPIC_API_KEY: 在此填入你的 API Key } } local_file self.claude_dir / settings.local.json with open(local_file, w) as f: json.dump(local_settings, f, indent2, ensure_asciiFalse) print(f✓ 创建 {local_file} (请填入你的 API Key)) def create_gitignore(self): 确保 .gitignore 正确 gitignore self.project_dir / .gitignore entries [ .claude/settings.local.json, .env, .env.local, .env.*.local ] existing if gitignore.exists(): existing gitignore.read_text() new_entries [e for e in entries if e not in existing] if new_entries: with open(gitignore, a) as f: if existing and not existing.endswith(\n): f.write(\n) f.write(\n# Claude Code\n) for entry in new_entries: f.write(f{entry}\n) print(f✓ 更新 .gitignore ({len(new_entries)} 条)) def create_claude_md(self): 创建 CLAUDE.md 模板 claude_md self.project_dir / CLAUDE.md if claude_md.exists(): print(f- CLAUDE.md 已存在跳过) return template # CLAUDE.md ## 项目概述 - 项目名: (填入项目名) - 技术栈: (填入技术栈) - 架构: (填入架构说明) ## 编码规范 - (填入编码规范) ## 文件结构 - src/ → 源代码 - tests/ → 测试 - docs/ → 文档 ## 命名规范 - 文件: kebab-case - 类: PascalCase - 函数/变量: camelCase ## Git 规范 - 分支: feature/*, bugfix/*, hotfix/* - Commit: conventional commits ## AI 辅助开发指南 - 修改前先运行测试 - 生成的代码必须通过 lint - 不要修改依赖文件 with open(claude_md, w) as f: f.write(template) print(f✓ 创建 {claude_md} (请填入项目信息)) def create_agents_dir(self): 创建子代理目录 agents_dir self.claude_dir / agents agents_dir.mkdir(parentsTrue, exist_okTrue) # 创建示例子代理 reviewer { name: reviewer, description: 代码审查子代理, model: claude-sonnet-4-20250514, permissions: {allow: [Read(**)], deny: [Write(**), Edit(**)]}, maxTurns: 5 } with open(agents_dir / reviewer.json, w) as f: json.dump(reviewer, f, indent2, ensure_asciiFalse) print(f✓ 创建 {agents_dir}/reviewer.json) def create_commands_dir(self): 创建命令目录 commands_dir self.claude_dir / commands commands_dir.mkdir(parentsTrue, exist_okTrue) # 创建示例命令 with open(commands_dir / review.md, w) as f: f.write(审查当前 Git diff 中的变更。\n检查代码规范、安全性、性能。\n) print(f✓ 创建 {commands_dir}/review.md) def run(self): 执行初始化 print( Claude Code 团队配置初始化 \n) if not self.check_existing(): return self.create_settings() self.create_local_settings() self.create_gitignore() self.create_claude_md() self.create_agents_dir() self.create_commands_dir() print(\n 初始化完成 ) print(\n下一步:) print( 1. 编辑 .claude/settings.local.json 填入 API Key) print( 2. 编辑 CLAUDE.md 填入项目信息) print( 3. 运行 claude 开始使用) print( 4. 将 .claude/ 和 CLAUDE.md 提交到 Git) # 使用 initializer TeamConfigInitializer() initializer.run()4.6 方案六配置同步检查#!/bin/bash # check-team-config.sh — 检查团队成员配置是否同步 echo 团队配置同步检查 PASS0 FAIL0 check() { local name$1 local condition$2 if [ $condition true ]; then echo ✓ $name PASS$((PASS 1)) else echo ✗ $name FAIL$((FAIL 1)) fi } # 1. 共享配置存在 [ -f .claude/settings.json ] check settings.json 存在 true || check settings.json 存在 false # 2. 个人配置不入 Git if git ls-files --error-unmatch .claude/settings.local.json 2/dev/null; then check settings.local.json 不入 Git false else check settings.local.json 不入 Git true fi # 3. .gitignore 正确 grep -q .claude/settings.local.json .gitignore 2/dev/null check .gitignore 排除 local true || check .gitignore 排除 local false # 4. CLAUDE.md 存在 [ -f CLAUDE.md ] check CLAUDE.md 存在 true || check CLAUDE.md 存在 false # 5. 子代理目录 [ -d .claude/agents ] check agents 目录存在 true || check agents 目录存在 false # 6. 命令目录 [ -d .claude/commands ] check commands 目录存在 true || check commands 目录存在 false # 7. 权限配置 if [ -f .claude/settings.json ]; then python3 -c import json with open(.claude/settings.json) as f: data json.load(f) perms data.get(permissions, {}) has_deny bool(perms.get(deny)) has_allow bool(perms.get(allow)) exit(0 if has_deny and has_allow else 1) 2/dev/null check 权限配置完整 true || check 权限配置完整 false fi # 8. 模型配置 if [ -f .claude/settings.json ]; then python3 -c import json with open(.claude/settings.json) as f: data json.load(f) model data.get(model, ) small data.get(smallModel, ) exit(0 if model and small else 1) 2/dev/null check 模型配置完整 true || check 模型配置完整 false fi echo echo 结果: $PASS 通过, $FAIL 失败 4.7 方案七配置版本管理# .claude/CHANGELOG.md — 配置变更日志 (入 Git) # 配置变更时记录让团队知道发生了什么 # Claude Code 配置变更日志 ## [1.2.0] - 2025-01-15 ### Added - 添加 security-auditor 子代理 - 添加 /security-scan 自定义命令 ### Changed - 权限: 移除 Bash(npm install*) 的 allow - 模型: 主模型从 Opus 降为 Sonnet (成本优化) ### Fixed - 修复 hooks 路径在 Windows 上不工作的问题 ## [1.1.0] - 2025-01-10 ### Added - 添加 reviewer 子代理 - 添加 /review 自定义命令 ## [1.0.0] - 2025-01-05 ### Initial - 团队初始配置 - 基础权限规则 - CLAUDE.md 模板 # Git commit 规范 git add .claude/settings.json git commit -m claude(config): 添加 security-auditor 子代理 - 新增 .claude/agents/security-auditor.json - 使用 Opus 模型进行安全扫描 - 只读权限不修改代码 - 最大 8 轮分析5. 验证回归团队配置验证5.1 团队配置验证清单#验证项预期方法1settings.json 入 Git已跟踪git ls-files2settings.local.json 不入 Git未跟踪git ls-files3.gitignore 正确排除 localgrep .gitignore4CLAUDE.md 存在有内容文件检查5权限配置有 allowdenyJSON 检查6子代理目录存在目录检查7命令目录存在目录检查8配置同步团队一致check 脚本5.2 新成员验证流程# 新成员上手检查 echo 新成员 Claude Code 上手检查 # 1. 克隆仓库后检查配置 echo 1. 检查团队配置... if [ ! -f .claude/settings.json ]; then echo ✗ 未找到团队配置请确认已正确克隆仓库 exit 1 fi echo ✓ 团队配置已加载 # 2. 配置个人 API Key echo 2. 配置 API Key... if [ ! -f .claude/settings.local.json ]; then echo 创建个人配置文件... echo {env:{ANTHROPIC_API_KEY:在此填入你的 Key}} .claude/settings.local.json echo ⚠ 请编辑 .claude/settings.local.json 填入 API Key else echo ✓ 个人配置已存在 fi # 3. 验证 Claude Code 可用 echo 3. 验证 Claude Code... claude --version /dev/null 21 echo ✓ Claude Code 可用 || echo ✗ Claude Code 不可用 # 4. 检查 CLAUDE.md echo 4. 项目上下文... [ -f CLAUDE.md ] echo ✓ CLAUDE.md 已加载 || echo ⚠ 无 CLAUDE.md echo echo 检查完成运行 claude 开始 6. 避坑最佳实践6.1 团队配置原则原则 1: 共享入 Git — settings.json, CLAUDE.md, agents/, commands/ 入 Git 原则 2: 个人不入 Git — settings.local.json, .env 不入 Git 原则 3: .gitignore 正确 — 确保 local 文件被忽略 原则 4: 权限统一 — 团队使用相同的 allow/deny 规则 原则 5: CLAUDE.md 共维护 — 团队共同维护项目上下文 原则 6: 子代理共享 — 优秀子代理配置入 Git 共享 原则 7: 命令共享 — 自定义命令入 Git 原则 8: 变更记录 — 配置变更记录在 CHANGELOG 原则 9: 新人引导 — 用初始化工具快速上手 原则 10: 定期同步 — 定期检查配置同步状态6.2 常见陷阱#陷阱后果解决1settings.local.json 入 GitAPI Key 泄露.gitignore 排除2不共享 settings.json行为不一致入 Git 共享3无 CLAUDE.md上下文缺失创建并维护4子代理不共享重复劳动入 Git5权限不统一安全风险不一统一配置6无新人引导上手慢初始化工具7配置变更无记录不知改了什么CHANGELOG8模型不统一成本差异大统一模型配置7. 附录团队配置速查表7.1 文件管理策略文件Git用途所有者.claude/settings.json✅团队配置团队.claude/settings.local.json❌个人配置个人CLAUDE.md✅项目上下文团队.claude/agents/*.json✅子代理团队.claude/commands/*.md✅自定义命令团队.claude/hooks/*.py✅Hook 脚本团队.env❌密钥个人7.2 团队配置 Checklist#检查项完成1settings.json 入 Git☐2settings.local.json 不入 Git☐3.gitignore 正确配置☐4CLAUDE.md 创建并维护☐5权限 allow/deny 配置☐6模型配置 (主小)☐7子代理配置共享☐8自定义命令共享☐9Hook 审计配置☐10CHANGELOG 维护☐11新人初始化工具☐12定期同步检查☐结语团队协作与配置共享是 Claude Code 在团队中高效使用的关键。通过将共享配置纳入 Git、统一权限和模型、共享子代理和命令、维护统一的 CLAUDE.md、提供新人初始化工具可以确保团队成员行为一致、安全合规、高效协作。核心要点回顾共享入 Gitsettings.json、CLAUDE.md、agents/、commands/纳入 Git 管理个人不入 Gitsettings.local.json、.env不入 Git用.gitignore排除统一权限团队使用相同的 allow/deny 规则确保安全标准一致统一模型主模型用 Sonnet小模型用 Haiku避免成本差异CLAUDE.md 共维护团队共同维护项目上下文和编码规范子代理共享代码审查、测试编写、安全审计等子代理配置入 Git新人引导用初始化工具快速配置2 分钟内上手变更记录配置变更记录在 CHANGELOG让团队知道发生了什么