Team Collaboration: Tips 86-95

One teammate gets brilliant results from Claude Code. The next one copies a config off Slack, the MCP servers silently fail to load, and they conclude “it doesn’t really work.” The gap is never the model — it’s that nothing about your setup is shared, versioned, or safe by default. The fix is to treat your CLAUDE.md, .mcp.json, custom commands, and permission rules as team infrastructure that lives in git.

What You’ll Walk Away With

• A versioned CLAUDE.md + .mcp.json layout so a fresh clone is productive on day one
• The correct, copy-paste-safe .mcp.json schema (the one Claude Code actually reads)
• A real permissions allow/ask/deny policy instead of unsafe blanket flags
• Shared slash commands for standups, reviews, and onboarding
• A “When This Breaks” checklist for the failure modes shared configs always hit

Shared Infrastructure and Standards

Tip 86: Share CLAUDE.md Files with Your Team

Create a shared knowledge base that benefits everyone:

1. Structure for Team Use

   project/
   ├── CLAUDE.md                    # Team standards
   ├── CLAUDE.local.md             # Personal preferences (git-ignored)
   ├── docs/
   │   └── claude/
   │       ├── onboarding.md       # New member guide
   │       ├── patterns.md         # Common patterns
   │       └── troubleshooting.md  # Known issues

2. Version Control Integration

   # Add team files to git
   git add CLAUDE.md
   git add .claude/commands/
   git add .claude/settings.json
   git add .mcp.json
   
   # Ignore personal files
   echo "CLAUDE.local.md" >> .gitignore
   echo ".claude/personal/" >> .gitignore

3. Regular Updates — run a retrospective on CLAUDE.md after each sprint so it tracks how the codebase actually evolved.

Tip

Copy-paste prompt to keep CLAUDE.md current (run in the repo root after a sprint):

Read CLAUDE.md, then read the last 30 commits (git log --oneline -30) and the
diffs for the 5 largest of those commits. Identify conventions we adopted, fixed,
or abandoned in this sprint that CLAUDE.md does not yet reflect — naming, error
handling, test layout, directory structure, banned patterns. Propose a minimal
diff to CLAUDE.md: only add rules we genuinely follow now, and delete any rule
the recent code contradicts. Show the diff; do not edit until I approve.

Team CLAUDE.md Best Practices

• Document agreed-upon patterns
• Include architecture decisions
• Specify code review focus areas
• List common commands and workflows
• Update based on retrospectives

Example team CLAUDE.md sections:

Code Standards

# Team Coding Standards

## TypeScript
- ALWAYS use strict mode
- PREFER interfaces over types for objects
- REQUIRE explicit return types
- USE branded types for IDs

## Testing
- MINIMUM 80% coverage for new code
- ALWAYS test error paths
- USE data-testid for E2E tests
- MOCK external services

Architecture

# Architecture Decisions

## API Design (illustrative ADR snippet)
- REST over GraphQL for public endpoints
- Versioning via URL path (/v1/, /v2/)
- Standard error format (RFC 7807)
- Rate limiting on all endpoints

## Database
- PostgreSQL for primary data
- Redis for caching only
- No direct SQL, use Prisma
- Soft deletes for audit trail

Tip 87: Create Team-Wide Custom Commands

Standardize common workflows with shared commands:

.claude/commands/feature-start.md

Start a new feature following team process:

Feature: $ARGUMENTS

1. Create branch from latest main
2. Update project board
3. Create feature flag (if needed)
4. Set up monitoring
5. Create initial tests
6. Draft PR description

Follow our feature development checklist.

More team command examples:

.claude/commands/code-review.md

# .claude/commands/hotfix.md
# .claude/commands/release.md
# .claude/commands/incident-response.md
# .claude/commands/performance-check.md

Tip

Store commands in subdirectories for organization: .claude/commands/frontend/, .claude/commands/backend/, etc.

Tip 88: Establish Team Permission Policies

Claude Code reads permissions from a permissions object in .claude/settings.json with three arrays — allow, ask, and deny — plus an optional defaultMode. Rules use the Tool or Tool(specifier) form, and Bash specifiers are space-globs (Bash(git diff *)), never colon-separated. Rules evaluate deny first, then ask, then allow. There is no allowedTools/autoAllow/requireApproval/blocked key, and the tools are Read/Edit/Write/Bash — not View/Create/Delete.

Development

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(npm run test *)",
      "Bash(npm run lint)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(npm install *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Staging / CI

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Read",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(npm run test *)"
    ],
    "ask": [
      "Edit",
      "Write",
      "Bash(git push *)"
    ],
    "deny": [
      "Bash(npm run deploy *)",
      "Bash(rm -rf *)",
      "Read(./.env)"
    ]
  }
}

Production-adjacent

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Read",
      "Bash(git status)",
      "Bash(git log *)"
    ],
    "ask": [],
    "deny": [
      "Edit",
      "Write",
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

Note

Filesystem and network limits are expressed as Read, Edit, and WebFetch rules — for example Read(./secrets/**) in deny or WebFetch(domain:internal.example.com) in allow — not as a separate sandbox block. SQL statements like DROP TABLE are not Bash commands; gate those in your database MCP server’s own allow/deny config, not in Bash rules.

Document permission rationale:

# Permission Guidelines

## Development Environment
- Full permissions for rapid development
- Auto-allow safe read operations
- Manual approval for destructive operations

## Staging Environment
- Limited to testing and debugging
- No direct database modifications
- Deployment requires approval

## Production Environment
- Read-only access only
- All changes through CI/CD
- Emergency access requires two approvals

Tip 89: Document Team Coding Standards

Use CLAUDE.md to enforce consistency:

# Team Coding Standards

## Naming Conventions
- Components: PascalCase (UserProfile, LoginForm)
- Utilities: camelCase (formatDate, validateEmail)
- Constants: UPPER_SNAKE_CASE (MAX_RETRIES)
- Files: kebab-case (user-service.ts)

## Code Organization
\`\`\`
src/
├── components/     # UI components
├── services/       # Business logic
├── utils/          # Shared utilities
├── types/          # TypeScript types
└── constants/      # App constants
\`\`\`

## Error Handling
\`\`\`typescript
// ALWAYS use custom error classes
class ValidationError extends AppError {
  constructor(field: string, message: string) {
    super(`Validation failed for ${field}: ${message}`);
  }
}

// ALWAYS handle errors explicitly
try {
  await riskyOperation();
} catch (error) {
  logger.error('Operation failed', { error, context });
  throw new OperationError('User-friendly message');
}
\`\`\`

## Testing Standards
- Test file naming: *.test.ts or *.spec.ts
- Describe blocks for class/module
- It blocks for specific behaviors
- AAA pattern: Arrange, Act, Assert

Tip 90: Share MCP Configurations

Standardize tool access across the team:

// .mcp.json (checked into git)
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "atlassian": {
      "url": "https://mcp.atlassian.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${ATLASSIAN_API_TOKEN}"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_TOKEN": "${SLACK_TOKEN}"
      }
    }
  }
}

Team MCP Benefits

• Consistent tool availability
• Shared automation capabilities
• Standardized integrations
• Reduced setup time
• Team-wide productivity gains

Team Workflows and Processes

Tip 91: Create Onboarding Documentation

Help new team members get productive quickly:

# Claude Code Onboarding Guide

## Initial Setup (30 minutes)
1. Install Claude Code: `npm install -g @anthropic-ai/claude-code`
2. Configure authentication: launch `claude` and use `/login` in the REPL
3. Clone team repository
4. Run setup script: `./scripts/claude-setup.sh`

## First Day Tasks
1. Read team CLAUDE.md file
2. Try example commands:
   - `/feature-start my-first-feature`
   - `/team-standards`
3. Pair with team member on real task
4. Join #claude-code Slack channel

## Best Practices
- Use the team permissions allowlist in .claude/settings.json (allow/ask/deny)
- Reserve --dangerously-skip-permissions for sandboxed/throwaway environments only,
  never a shared dev machine or anything touching prod
- Clear context between unrelated tasks
- Check /cost daily to understand usage
- Use team commands from .claude/commands/

## Common Issues
- Too many permission prompts: extend the allow list in settings.json, do not skip
- MCP not working: run `claude mcp list`, then check the env vars in .mcp.json
- New .mcp.json server keeps prompting: `claude mcp reset-project-choices`
- High costs: use Sonnet 4.6 for routine tasks, Opus 4.8 for hard ones, Fable 5 (`/model fable`) only when peak intelligence justifies the cost (see [model comparison](/en/appendices/model-comparison/))

## Resources
- Team knowledge base: /docs/claude/
- Video tutorials: /onboarding/claude-code/
- Slack channel: #claude-code

Tip 92: Establish Code Review Workflows

Integrate Claude Code into your review process:

Automated Reviews

The official action is anthropics/claude-code-action@v1 (repo: github.com/anthropics/claude-code-action). Drive review scope through the prompt input and pass any CLI options via claude_args. There is no claude-code-review action and no focus:/ignore: inputs.

.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
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review this PR for security vulnerabilities, logic errors,
            performance issues, and missing tests. Be specific and suggest
            fixes. Ignore style, naming, and documentation — linting owns those.
          claude_args: "--max-turns 10 --model claude-opus-4-8"

Manual Reviews

Store a reusable review command at .claude/commands/review-pr.md and run it as /review-pr 1234 inside the REPL:

Review the PR at $ARGUMENTS focusing on:

1. Business logic correctness
2. Security vulnerabilities
3. Performance implications
4. Test coverage
5. Error handling

Ignore style issues - those are handled by linting.
Be specific about issues and suggest fixes.

Tip

Copy-paste prompt for a high-signal review pass on the current diff (run after staging your changes):

Review the staged diff (git diff --staged). Flag only things that would cause a
bug, a security hole, a data-loss path, or a missing test for new behavior. For
each finding, give the file:line, one sentence on why it is wrong, and the exact
fix. Skip style, naming, and formatting — linting handles those. If nothing is
wrong, say so in one line instead of inventing nitpicks.

Treat automated review as a first pass, not a gate: Claude Code reliably catches missing-test and error-handling gaps, while humans still own architectural and product judgment.

Tip 93: Share Learning and Best Practices

Create a culture of continuous improvement:

1. Weekly Tips Session

   # Weekly Claude Code Tips
   - 15-minute team standup
   - One person shares a discovered technique
   - Document in team knowledge base
   - Try the technique together

2. Workflow Show-and-Tell — inside the REPL, run /export session.md to write the conversation to a file (omit the filename to copy it to the clipboard), then drop it in your team knowledge base. Note that /export is an in-REPL slash command, so it takes a filename argument rather than a shell redirect.

3. Cost Optimization Reviews — review usage with /cost in the REPL and your org’s analytics dashboard, then right-size models per task.

4. Pattern Mining — run a quarterly pass to fold recurring patterns into CLAUDE.md.

Tip

Copy-paste prompt to mine your codebase for conventions worth promoting into CLAUDE.md:

Scan src/ for patterns that repeat across at least three files: error-handling
shape, the way we structure services vs. components, test file layout, and any
home-grown utilities people reinvent. List the top five, each with two real
file:line examples, and write the exact CLAUDE.md rule that would make Claude
follow it automatically. Skip one-off patterns and anything already in CLAUDE.md.

Tip 94: Coordinate Large Refactoring Efforts

Use multiple team members with Claude Code for large projects:

# Microservices Migration Plan

## Team Assignment
- Alice: User Service (Terminal 1)
- Bob: Order Service (Terminal 2)
- Carol: Payment Service (Terminal 3)
- Dan: Integration Tests (Terminal 4)

## Coordination
1. Morning sync to assign services
2. Shared interface definitions in .claude/shared/
3. Hourly check-ins on Slack
4. End-of-day integration test

## Claude Code Setup
\`\`\`bash
# Each developer
claude --add-dir ./services/[assigned-service]
\`\`\`

## Shared Resources
- API contracts: .claude/shared/api/
- Test utilities: .claude/shared/testing/
- Migration guide: .claude/shared/migration.md

Coordination Tools

• Shared filesystem for contracts
• Slack integration for updates
• Git branches for isolation
• Regular sync meetings
• Automated integration tests

Tip 95: Create Team-Specific Slash Commands

Develop commands that match your team’s workflow. Save this as .claude/commands/team/standup.md, then run /team:standup in the REPL to generate your daily update from real git history.

Tip

Copy-paste this into .claude/commands/team/standup.md so the whole team gets identical standups:

Generate my standup from real signals, not guesses.

Yesterday: run `git log --author="$(git config user.name)" --since="24 hours ago"
--oneline` and summarize what shipped in 3-5 bullets, grouped by feature.

Today: read the current branch name and any open TODO/FIXME comments I touched
this week; list the 2-3 most likely next tasks.

Blockers: run the test suite headline (npm test 2>&1 | tail -20) and call out any
failing suites or obvious tech debt blocking the above. Keep the whole thing under
120 words.

More team commands:

# Sprint planning
.claude/commands/team/sprint-plan.md

# Incident response
.claude/commands/team/incident.md

# Release notes
.claude/commands/team/release-notes.md

# Technical debt tracking
.claude/commands/team/tech-debt.md

Building a Claude Code Culture

Successful team adoption requires more than just technical setup:

Leadership and Advocacy

• Identify Claude Code champions
• Share success stories
• Celebrate productivity wins
• Address concerns openly

Training and Support

• Regular workshops
• Pair programming sessions
• Internal documentation
• Slack support channel

Metrics and Improvement

• Track productivity metrics
• Monitor cost per developer
• Measure code quality improvements
• Regular retrospectives

Common Adoption Patterns

Small Team (2-5)

Week 1: Individual exploration
Week 2: Share discoveries
Week 3: Standardize workflows
Week 4: Full team adoption

Focus: Rapid experimentation

Medium Team (5-20)

Month 1: Pilot with early adopters
Month 2: Develop team standards
Month 3: Gradual rollout
Month 4: Full adoption

Focus: Standardization

Large Team (20+)

Quarter 1: Pilot teams
Quarter 2: Department rollout
Quarter 3: Organization-wide
Quarter 4: Optimization

Focus: Governance and scale

Team Success Metrics

Track these indicators of successful team adoption:

1. Velocity Increase: 2-4x typical
2. Code Quality: Fewer bugs in production
3. Test Coverage: Higher and more comprehensive
4. Documentation: Always up to date
5. Onboarding Time: 50% reduction
6. Developer Satisfaction: Increased engagement

When This Breaks

Shared configuration fails in a handful of predictable ways. Here is how to recognize and recover from each.

1. Teammate’s .mcp.json servers don’t load. Almost always the wrong top-level key — Claude Code reads mcpServers, not servers. Confirm the running servers with claude mcp list. If the key is right but a server is missing, an unexpanded env var (${GITHUB_TOKEN}) is usually the cause — see the next item.

2. A new project-scoped server keeps prompting for approval, or you approved it once and want to re-decide. Claude Code asks before trusting servers from a project .mcp.json. Run claude mcp reset-project-choices to clear those decisions, then re-open the project and approve intentionally.

3. .mcp.json works on one machine but not another. The config references env vars (${GITHUB_TOKEN}, ${SLACK_TOKEN}) that exist in one shell profile and not the other. Document the required vars in onboarding and have each developer export them in their shell rc; never hardcode secrets into the committed .mcp.json.

4. CLAUDE.md merge conflicts on every PR. Split it: keep stable, rarely-changing standards in the committed CLAUDE.md, and move personal or fast-moving notes into git-ignored CLAUDE.local.md. Resolve conflicts by section, not line — the file is prose, so prefer keeping both rules unless they contradict.

5. A teammate is on --dangerously-skip-permissions and edited something they shouldn’t have. Stop recommending the flag for shared machines. Ship the permissions allow/ask/deny policy from Tip 88 in .claude/settings.json, and set disableBypassPermissionsMode to "disable" in managed settings for anything near prod.

Next Steps

With team collaboration mastered, you’re ready for the final set of tips. Continue to Troubleshooting and Best Practices for common issues and proven patterns for long-term success.