主题
10.2 团队标准化配置
把一个人的高效配置，变成整个团队的默认基线。
读完你能做什么：设计一套可提交、可共享、可演进的团队 Claude 配置。
一、目标：新人克隆即上手
理想状态：
text
新成员 git clone 项目
→ 打开 Claude Code
→ 自动拥有：项目记忆、编码规范、审查流程、安全护栏、内部系统接入
→ 不用任何额外配置就能按团队标准工作这靠一组提交进 git 的配置文件实现。
二、可共享的配置清单
text
提交到 git（团队共享）：
├── .claude/CLAUDE.md 项目记忆
├── .claude/rules/ 分模块规范
│ ├── frontend.md
│ └── backend.md
├── .claude/settings.json 权限、hook、团队规则
├── .claude/skills/ 团队技能
│ ├── release-check/
│ └── code-review/
├── .claude/agents/ 团队子代理
│ └── security-reviewer.md
├── .claude/hooks/ 钩子脚本
│ ├── auto-format.sh
│ └── guard-git.sh
└── .mcp.json 共享的连接器（密钥用环境变量）
加入 .gitignore（个人/敏感）：
├── .claude/settings.local.json
├── CLAUDE.local.md
└── .claude/agent-memory-local/三、逐项配置
3.1 项目记忆（CLAUDE.md）
团队共享的事实与规则，保持精简（< 200 行）：
markdown
# <项目名>
## 构建与测试
- 构建：`make build`
- 测试：`make test`
## 绝对规则
- 金额用 decimal 类型，禁止 float
- 不在 main 直接改
- 接口 IPaymentCallback 签名不能改
## 约定
- commit 用 conventional commits
- 新渠道适配器放 internal/channels/<name>/
## 已知坑
- 支付宝 SDK 非线程安全，不要缓存 client详见 05.6。
3.2 分模块规范（rules）
不同部分的规范用 paths 作用域，只在处理相关文件时加载：
markdown
---
paths:
- "src/api/**/*.ts"
---
# API 规范
- 所有 endpoint 必须输入校验
- 错误响应用统一格式3.3 权限护栏（settings.json）
团队统一的安全底线：
json
{
"permissions": {
"defaultMode": "acceptEdits",
"allow": ["Bash(npm *)", "Bash(git status)", "Bash(git diff *)", "Read", "Edit", "Write"],
"ask": ["Bash(git push *)"],
"deny": ["Bash(rm -rf *)", "Read(./.env*)", "Bash(git push --force*)"]
}
}3.4 强制机制（hooks）
确定性的团队规则用 hook，不靠自觉：
json
{
"hooks": {
"PostToolUse": [
{ "matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": ".claude/hooks/auto-format.sh" }] }
],
"PreToolUse": [
{ "matcher": "Bash",
"hooks": [{ "type": "command", "command": ".claude/hooks/guard-git.sh" }] }
]
}
}自动格式化 + 危险 git 操作拦截，全团队一致。见 06.5。
3.5 团队技能（skills）
把团队工作法固化：release 检查、代码审查、事故复盘…… 见 08.6 实战示例集。
3.6 共享连接器（.mcp.json）
内部系统接入，密钥用环境变量：
json
{
"mcpServers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": { "Authorization": "Bearer ${GITHUB_MCP_TOKEN}" }
},
"db": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@bytebase/dbhub", "--dsn", "${READONLY_DB_DSN}"]
}
}
}新人只需设两个环境变量。见 07.2。
四、个人层与团队层的分离
关键设计：团队规范提交，个人偏好本地。
| 内容 | 放哪 | 提交 |
|---|---|---|
| 团队编码规范 | .claude/settings.json | 是 |
| 团队权限护栏 | .claude/settings.json | 是 |
| 你偏好用 Opus | .claude/settings.local.json | 否 |
| 你的本地临时目录 | .claude/settings.local.json | 否 |
| 你个人的调试笔记 | CLAUDE.local.md | 否 |
个人层覆盖团队层的同名键，但只对你、只在本地生效。见 06.8。
五、一份新人上手文档
在项目里放一份 docs/claude-setup.md：
markdown
# 用 Claude Code 开发本项目
## 一次性配置
1. 安装 Claude Code（见 code.claude.com/docs）
2. 设置环境变量（放进你的 shell 配置）：
export GITHUB_MCP_TOKEN=<你的 token>
export READONLY_DB_DSN=<只读库连接串>
3. 在项目根目录运行 `claude`，确认 /context 里加载了项目 CLAUDE.md
## 你自动获得的
- 项目记忆、编码规范
- 自动格式化（改完代码自动跑）
- 危险操作拦截
- release-check、code-review 等技能
- GitHub 和只读数据库的接入
## 个人偏好
在 .claude/settings.local.json 里放你自己的偏好（不会提交）。Claude Code 还能自动生成这类文档：
text
> /team-onboarding它分析你近期的使用历史，生成一份团队上手指南。
六、演进：让配置随团队成长
标准化不是一次性的。持续演进：
text
Claude 犯了同样的错第二次 → 加进 CLAUDE.md
代码审查反复发现同类问题 → 加进 rules 或做成检查技能
某个操作总是要手动确认且很烦 → 评估是否配 allow 规则
团队摸索出新的工作法 → 做成 Skill定期回顾：
text
> 检查我们的 .claude/ 配置，指出：
1. 有没有互相矛盾的规则
2. 有没有已经过时的内容
3. CLAUDE.md 有没有超过 200 行需要精简的配合 /doctor 精简 CLAUDE.md（见 05.6）。
七、打包成插件分发
当配置成熟且要跨多个项目复用时，打包成 Plugin（见 10.1）：
text
项目内共享（.claude/ 提交）
→ 适合单个项目的团队
打包成 Plugin
→ 适合跨多个项目、多个团队复用同一套标准八、标准化的收益
| 收益 | 说明 |
|---|---|
| 新人上手快 | 克隆即拥有全套配置 |
| 质量一致 | 全员同样的规范和护栏 |
| 减少低级错误 | hook 确定性拦截 |
| 知识沉淀 | 经验固化进配置，不随人员流动丢失 |
| 安全底线统一 | 权限护栏全员一致 |