Claude Code团队协作与入职：从单兵到团队规模化实战

~/.claude/CLAUDE.md          ← 全局配置（所有项目共享）
├── /project-a/CLAUDE.md     ← 项目配置（团队共享，提交到Git）
├── /project-a/.claude/CLAUDE.md  ← 项目内部配置（可.gitignore）
└── /project-b/CLAUDE.md     ← 另一个项目的配置

# 项目名称：OrderFlow

## 技术栈
- 后端：Go 1.22 + Gin框架 + PostgreSQL 16
- 前端：React 19 + TypeScript 5.4 + TanStack Query
- 基础设施：Docker Compose（开发）、K8s（生产）

## 代码规范
- Go：遵循Effective Go，使用golangci-lint v1.57+
- TypeScript：ESLint + Prettier，strict模式
- 提交信息：Conventional Commits格式
- 分支命名：feat/xxx、fix/xxx、refactor/xxx

## 架构约束
- 禁止在handler层直接访问数据库，必须通过service层
- 所有外部API调用必须封装为client包
- 错误处理统一使用pkg/errors包，禁止裸panic
- 数据库迁移使用golang-migrate，禁止手动改表

## 测试要求
- 新增功能必须有单元测试，覆盖率≥80%
- API端点必须有集成测试
- 运行测试命令：make test（单元）、make test-integration（集成）

## 禁止事项
- 不要自动提交代码到Git
- 不要修改go.mod/go.sum，依赖变更由负责人处理
- 不要生成mock数据在生产环境代码中
- 不要使用any或interface{}类型

## 常用命令
- 启动开发环境：make dev
- 运行linter：make lint
- 数据库迁移：make migrate-up
- 生成API文档：make swagger

# 个人全局配置

## 偏好
- 代码注释使用中文
- 变量命名使用英文
- 喜欢详细的错误信息而非简短提示
- 优先使用函数式写法

## 常用工具路径
- Go安装路径：/usr/local/go/bin
- Docker Compose路径：/usr/bin/docker-compose

{
  "permissions": {
    "allow": [
      "Bash(go test ./...)",
      "Bash(make lint)",
      "Bash(docker compose *)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push *)",
      "Bash(kubectl apply *)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx eslint --fix $FILE_PATH"
      }
    ]
  }
}

# 在项目根目录运行
claude
> /team-onboarding

team-onboarding-guide.md
├── 1. 项目概览（自动从CLAUDE.md提取）
├── 2. 开发环境搭建（基于最近30天的命令历史）
├── 3. 常用工作流（基于高频操作模式）
├── 4. 代码库导航（关键文件和目录说明）
├── 5. 团队约定（从提交历史和代码模式推断）
└── 6. 常见问题（基于错误日志和修复记录）

# 团队入职增强指南

## 开发环境一键搭建
# 我们增强了自动生成的环境搭建部分
make setup-dev    # 一键安装所有依赖
make seed-db      # 填充测试数据
make verify-env   # 验证环境完整性

## 关键代码路径
# 自动生成不会覆盖这些团队特定的上下文
- 订单核心逻辑：internal/order/service.go
- 支付回调处理：internal/payment/webhook.go
- 权限中间件：internal/middleware/auth.go
- 测试工厂：testutil/factory/（新增测试必须用这里的工厂方法）

## 团队特殊约定
# 这些约定可能不会被自动检测到
- PR必须至少有一个Reviewer审批
- 发布分支命名：release/v{版本号}
- 紧急修复走hotfix/分支，合并后立即删除

# 新成员入职验证脚本（可加入Makefile）
.PHONY: verify-claude-setup
verify-claude-setup:
    @echo "=== Claude Code 团队配置验证 ==="
    @claude --version || (echo "❌ Claude Code未安装" && exit 1)
    @test -f CLAUDE.md || (echo "❌ 项目CLAUDE.md缺失" && exit 1)
    @claude -p "列出本项目的测试命令" 2>/dev/null | grep -q "make test" \
        || (echo "⚠️  Claude Code未读取到项目配置")
    @echo "✅ Claude Code团队配置验证通过"

team-skills/
├── README.md
├── skills/
│   ├── api-design/
│   │   └── skill.md        # API设计规范Skill
│   ├── db-migration/
│   │   └── skill.md        # 数据库迁移Skill
│   ├── code-review/
│   │   └── skill.md        # 代码审查Skill
│   └── incident-response/
│       └── skill.md        # 故障响应Skill
└── install.sh              # 一键安装脚本

#!/bin/bash
# 团队Skills一键安装
SKILLS_DIR="$HOME/.claude/skills"
REPO_URL="https://github.com/your-org/team-skills.git"

echo "🔧 安装团队共享Skills..."
git clone "$REPO_URL" /tmp/team-skills
mkdir -p "$SKILLS_DIR"
cp -r /tmp/team-skills/skills/* "$SKILLS_DIR/"
rm -rf /tmp/team-skills

echo "✅ 已安装以下Skills："
ls -1 "$SKILLS_DIR"

---
name: team-code-review
description: 团队标准代码审查流程，确保PR符合团队规范
---

# 代码审查Skill

## 触发条件
当用户要求审查代码、Review PR或检查Pull Request时使用。

## 审查清单

### 安全性（P0）
- [ ] 无SQL注入风险（检查原生SQL查询）
- [ ] 无硬编码的密钥或Token
- [ ] 用户输入已验证和清理
- [ ] 认证和授权检查到位

### 代码质量（P1）
- [ ] 遵循项目CLAUDE.md中的架构约束
- [ ] 错误处理符合团队规范（使用pkg/errors）
- [ ] 没有重复代码（DRY原则）
- [ ] 函数复杂度不超过15

### 测试（P1）
- [ ] 新增功能有对应测试
- [ ] 测试覆盖边界条件
- [ ] 测试不会依赖外部服务（使用mock）

### 性能（P2）
- [ ] 无N+1查询问题
- [ ] 大数据集使用分页
- [ ] 无不必要的同步操作

## 输出格式
按P0→P1→P2优先级输出审查结果，每条包含：
- 文件路径和行号
- 问题描述
- 建议的修复方案

{
  "mcpServers": {
    "team-postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost:5432/orderflow_dev"],
      "env": {
        "PG_PASSWORD": "${DEV_DB_PASSWORD}"
      }
    },
    "team-artifact": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-artifact"],
      "description": "共享设计规范和文档"
    },
    "team-k8s": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-kubernetes"],
      "description": "K8s集群只读查询（开发环境）"
    }
  }
}

flowchart TD
    A[团队成员发起请求] --> B{Claude Code}
    B --> C[MCP网关层]
    C --> D{权限检查}
    D -->|只读操作| E[允许：查询数据库]
    D -->|写入操作| F{环境检查}
    F -->|开发环境| G[允许：DDL/DML]
    F -->|生产环境| H[拒绝：需审批]
    D -->|危险操作| I[拒绝：DROP/TRUNCATE]

# 审查当前分支的所有变更
claude -p "审查当前分支相对于main的所有变更，按团队code-review skill的清单逐项检查"

# 自动审查指定PR
claude -p "审查PR #123，重点关注安全性和性能"

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash(git commit *)",
        "command": "claude -p '简要审查刚刚的提交内容是否符合CLAUDE.md规范' --output-format json >> .claude/review-log.jsonl"
      }
    ]
  }
}

# .github/workflows/claude-review.yml
name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Claude Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "审查PR变更，输出P0/P1/P2分级审查结果" \
            --allowedTools "Read,Glob,Grep,Bash(git diff *)" \
            > review-result.md
      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review-result.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: review
            });

## Claude Code 审查报告

**PR**: #123 - 新增订单批量导出功能
**审查时间**: 2026-05-20 14:30
**审查范围**: 12个文件，+340/-28行

### P0 - 必须修复（2项）
1. `internal/order/export.go:47` - SQL查询未使用参数化，存在注入风险
   - 当前：`fmt.Sprintf("SELECT * FROM orders WHERE id IN (%s)", ids)`
   - 建议：使用`pgx`的`ANY`操作符传递参数数组

2. `internal/order/export.go:89` - 未设置查询超时，大数据集可能导致连接池耗尽
   - 建议：`ctx, cancel := context.WithTimeout(ctx, 30*time.Second)`

### P1 - 建议修复（3项）
[...]

### P2 - 可选优化（1项）
[...]

### 审查通过条件
- [ ] P0项全部修复
- [ ] P1项修复或给出合理说明
- [ ] 新增测试通过

flowchart LR
    subgraph 权限层级
        L1[Level 1: 只读分析]
        L2[Level 2: 代码编辑]
        L3[Level 3: 系统操作]
        L4[Level 4: 基础设施]
    end

    subgraph 角色
        R1[新成员/实习生]
        R2[开发者]
        R3[高级开发者]
        R4[技术Lead]
    end

    R1 --> L1
    R2 --> L1
    R2 --> L2
    R3 --> L1
    R3 --> L2
    R3 --> L3
    R4 --> L1
    R4 --> L2
    R4 --> L3
    R4 --> L4

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(go test ./...)",
      "Bash(make lint)",
      "Bash(git log *)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Edit",
      "Write",
      "Bash(git push *)",
      "Bash(git commit *)",
      "Bash(rm *)"
    ]
  }
}

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Bash(go test ./...)",
      "Bash(make *)",
      "Bash(docker compose *)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(git push *main*)",
      "Bash(rm -rf *)",
      "Bash(kubectl apply *)",
      "Bash(DROP *)",
      "Bash(TRUNCATE *)"
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "bash .claude/hooks/validate-command.sh"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "bash .claude/hooks/auto-lint.sh"
      }
    ],
    "Notification": [
      {
        "matcher": "*",
        "command": "bash .claude/hooks/team-notify.sh"
      }
    ]
  }
}

#!/bin/bash
# 读取Claude Code传入的JSON输入
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

# 危险命令黑名单
DANGEROUS_PATTERNS=(
  "rm -rf /"
  "DROP DATABASE"
  "TRUNCATE TABLE"
  "git push --force"
  "kubectl delete namespace"
  ":(){:|:&};:"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qi "$pattern"; then
    echo "BLOCKED: 命令包含危险操作: $pattern"
    exit 1
  fi
done

exit 0

# 在团队共享的环境变量中配置
export CLAUDE_CODE_LOG_DIR=".claude/logs/$(date +%Y-%m)"
export CLAUDE_CODE_LOG_FORMAT="jsonl"

{
  "timestamp": "2026-05-20T14:30:22Z",
  "user": "[email protected]",
  "session_id": "abc123",
  "tool": "Edit",
  "file": "internal/order/service.go",
  "action": "modified",
  "lines_changed": 12,
  "prompt_hash": "sha256:..."
}

gantt
    title Claude Code团队部署48小时时间线
    dateFormat HH:mm
    axisFormat %H:%M

    section Day 1 - 上午
    Lead配置项目CLAUDE.md      :a1, 09:00, 2h
    Lead配置settings.json      :a2, 11:00, 1h

    section Day 1 - 下午
    Lead创建共享Skills         :b1, 14:00, 2h
    Lead部署MCP服务器          :b2, 16:00, 1h
    Lead运行/team-onboarding   :b3, 17:00, 30m

    section Day 1 - 晚上
    Lead编写入职验证脚本       :c1, 19:00, 1h
    Lead编写安装文档           :c2, 20:00, 1h

    section Day 2 - 上午
    全员安装Claude Code        :d1, 09:00, 1h
    全员运行验证脚本           :d2, 10:00, 30m
    全员完成入门任务           :d3, 10:30, 2h

    section Day 2 - 下午
    结对编程实践               :e1, 14:00, 2h
    首次PR审查实战             :e2, 16:00, 1h
    收集反馈并调优             :e3, 17:00, 1h

# 在项目根目录
claude
> 请根据我们的项目结构，生成一份完整的CLAUDE.md，包含：
> 1. 从go.mod和package.json推断技术栈
> 2. 从现有代码风格推断代码规范
> 3. 从Makefile推断常用命令
> 4. 从最近10次提交推断提交信息格式

mkdir -p .claude/profiles
# 为每个角色创建配置文件

# 1. 安装Claude Code
npm install -g @anthropic-ai/claude-code

# 2. 克隆团队Skills
bash <(curl -s https://raw.githubusercontent.com/your-org/team-skills/main/install.sh)

# 3. 复制角色配置
cp .claude/profiles/level-${YOUR_LEVEL}.json ~/.claude/settings.json

# 4. 验证
make verify-claude-setup

claude
> 我是新加入的团队成员，请帮我完成以下入门任务：
> 1. 阅读CLAUDE.md并总结项目的3个核心架构约束
> 2. 运行make dev启动开发环境
> 3. 在internal/order/service.go中找到CreateOrder方法
> 4. 为CreateOrder方法写一个单元测试
> 5. 运行测试确保通过

claude
> 请审查PR #42，使用team-code-review skill的清单，重点关注安全性

{
  "permissions": {
    "deny": [
      "Read(*.env*)",
      "Read(*credentials*)",
      "Read(*secret*)",
      "Read(*.pem)",
      "Read(*.key)"
    ]
  }
}

效率提升率 = (任务基准工时 - 使用Claude Code后的实际工时) / 任务基准工时 × 100%

flowchart TB
    subgraph 团队Lead
        A[创建项目CLAUDE.md] --> B[配置settings.json权限]
        B --> C[开发团队Skills]
        C --> D[部署MCP服务器]
        D --> E[运行/team-onboarding]
        E --> F[编写入职验证脚本]
    end

    subgraph 团队成员
        F --> G[安装Claude Code]
        G --> H[安装共享Skills]
        H --> I[配置角色权限]
        I --> J[运行验证脚本]
        J --> K[完成入门任务]
    end

    subgraph 日常协作
        K --> L[使用Claude Code开发]
        L --> M[触发代码审查]
        M --> N{审查通过?}
        N -->|是| O[提交PR]
        N -->|否| L
        O --> P[CI/CD自动审查]
        P --> Q{CI检查通过?}
        Q -->|是| R[合并到主分支]
        Q -->|否| L
    end

    subgraph 持续优化
        R --> S[收集使用数据]
        S --> T[优化CLAUDE.md]
        T --> U[更新Skills]
        U --> L
    end