Chapter 19 · Team Collaboration Norms

Chapter goals: Establish team-level Claude Code usage norms — shared CLAUDE.md templates, code review flows, MCP/Skills configuration management, and new member onboarding — so the whole team "collaborates with AI in the same way."

19.1 Team CLAUDE.md Template

Personal CLAUDE.md can be随心所欲, but the version committed to the repo is the team's contract — it determines行为一致性 for every member (and agents in CI).

A battle-tested team template:

# CLAUDE.md

## Project Overview
E-commerce backend, Node 20 + TypeScript + PostgreSQL 15.

## Environment and Commands
- Install: pnpm install
- Tests: pnpm test (single file: pnpm vitest run <path>)
- Build: pnpm build
- Lint: pnpm lint && pnpm format

## Code Norms
- Functions over classes; exported functions must have JSDoc
- DB operations always go through the repository layer in src/db/
- API error responses统一 use the AppError class
- No `any` type; `unknown` must be narrowed before use

## Git Conventions
- Branch names: feat/<ticket> / fix/<ticket>
- Commit messages use Conventional Commits
- PR title = commit subject

## Notes
- Do not modify already-applied migrations under migrations/
- .env.local contains local secrets; never read or modify it

Version Control Strategy

Commit CLAUDE.md and .claude/settings.json to git; add .claude/settings.local.json and .claude/credentials to .gitignore. The former is the team contract; the latter is personal preference.

Multi-Layer CLAUDE.md

In a monorepo, place additional CLAUDE.md files in subdirectories:

repo/
├── CLAUDE.md                  # Global norms
├── packages/api/CLAUDE.md     # API-specific conventions
└── packages/web/CLAUDE.md     # Frontend-specific conventions

Claude自动 loads all CLAUDE.md files from the current working directory and its ancestors,实现 "global norms + local overrides."

19.2 Code Review Process Integration

PR Review Assistance

One of Claude Code's most valuable team scenarios: automated preliminary review:

# On the feature branch, generate a change summary for reviewers
claude -p "Compare with the main branch; summarize what this PR changes and what潜在 risks exist" \
  --allowedTools "Read" "Bash(git diff*)" \
  > pr-summary.md

GitHub Actions Automated Review

Integrate Claude into CI for a first-round review:

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

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Claude Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npm install -g @anthropic-ai/claude-code
          claude -p "Review this PR's code changes. Focus on: security issues, logic errors, performance hazards.
                   Output discovered issues and their severity as a markdown list." \
            --allowedTools "Read" "Bash(git diff*)" \
            --output-format text >> review-comment.md
      - name: Post Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const body = fs.readFileSync('review-comment.md', 'utf8');
            await github.rest.issues.createComment({
              ...context.repo,
              issue_number: context.issue.number,
              body
            });

Positioning

AI review is初筛 not终审 — it catches format violations, obvious bugs, and missing tests, but architecture decisions仍需 human judgment. The team should明确标注 "Claude reviewed" to避免重复劳动.

19.3 Shared MCP and Skills Configuration

Project-Level MCP Config

Write MCP server configs into .mcp.json at the repo root and commit:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "figma": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-figma"]
    }
  }
}

After cloning, team members run claude mcp list and immediately see all预配置 servers — zero-config onboarding.

Team Skills Directory

Place commonly used skills in .claude/skills/ and distribute with the repo:

.claude/skills/
├── deploy-checklist/SKILL.md    # Release checklist流程
├── db-migration/SKILL.md        # Migration file writing norms
└── api-endpoint/SKILL.md        # New endpoint scaffolding

Any member's agent自动 loads these skills when matching relevant tasks, ensuring output follows the same流程.

19.4 New Member Onboarding

Traditional onboarding takes 1–2 weeks; with thorough Claude Code configuration, compress to days:

Day 1: Clone repo → start claude → agent自动 loads CLAUDE.md
       Ask Claude: "What is this project's architecture? What is the core business flow?"
       (Much faster than reading Wiki — the agent directly reads code to answer)

Day 2: Use /init or manually完善 CLAUDE.md (newbie perspectives常能发现文档盲区)
       Tackle the first good-first-issue, pair with Claude全程

Day 3+: Submit a PR → trigger Claude Review → learn the team's code review standards

Key insight: the process of a new member improving CLAUDE.md is itself the most efficient learning process — to explain clearly to AI, you must first clarify your own understanding.

19.5 Team Anti-Patterns Checklist

Anti-Pattern	Consequence	Remedy
Each person maintains their own CLAUDE.md without sharing	Inconsistent behavior, high reviewcost	Unify into git; personal prefs go to local
Committing keys into settings.json	Keyleak	Keys via env vars or apiKeyHelper
Blindly accepting AI review without human复核	Hallucinated suggestions merged	AI标注 as "建议"; merge decided by humans
Skills/MCP configs散落各人文档	Non-reproducible	Converge all into .claude/ and .mcp.json

Chapter Summary

• CLAUDE.md is the team contract: commit to git, personal prefs in settings.local.json;
• Monorepos leverage multi-layer CLAUDE.md for "global + local" rule叠加;
• GitHub Actions + claude -p搭建 automated preliminary review pipelines;
• .mcp.json and .claude/skills/让 tools and knowledge distribute with the repo;
• New memberscomplete the most efficient onboarding by "reading and improving CLAUDE.md."

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. When a team uses Claude Code, which files should be committed to git?

2. In a monorepo where both the root and packages/api/ have a CLAUDE.md, how does Claude handle it?

3. Regarding AI code review in a team, what is the mostreasonable attitude?

4. Why is "having new members improve CLAUDE.md" considered an efficient onboarding method?

🛠️ Hands-on Practice

1. Write a complete CLAUDE.md for your team repo (tech stack + constraints + commands); after committing, have two members test the same task and compare output一致性. 2.搭建 the GitHub Actions review pipeline from this chapter; run it on a real PR; evaluate the quality and false-positive rate of issues Claude发现.
2. Write a .claude/skills/deploy-checklist/SKILL.md containing your team's release checklist steps;验证 it auto-triggers when "deploy" is mentioned.

Next chapter: Capstone Project