HomeClaude Code for TeamsTeam Workflows & Best Practices

intermediate12 min read· Module 12, Lesson 5

📋Team Workflows & Best Practices

Shared CLAUDE.md, team commands, and collaboration patterns

Team Workflows & Best Practices

As teams grow, individual productivity tools must evolve into shared workflows. Claude Code offers several mechanisms for team-wide consistency: shared CLAUDE.md files, custom slash commands, MCP server configurations, and coding standards enforcement. This lesson covers every aspect of building a productive, consistent team workflow around Claude Code.

Shared CLAUDE.md: The Team Playbook

The CLAUDE.md file is the single most important artifact for team alignment. It tells Claude how your team works, what conventions to follow, and what mistakes to avoid. There are three levels of CLAUDE.md files:

Level	Location	Scope
Global	`~/.claude/CLAUDE.md`	Personal preferences across all projects
Project	`./CLAUDE.md` (repo root)	Shared team standards for a project
Local	`./src/feature/CLAUDE.md`	Module-specific rules

Project-level CLAUDE.md is the team playbook. It should be committed to the repository so every team member and every Claude session inherits the same rules.

What to Include in a Team CLAUDE.md

A well-structured team CLAUDE.md typically contains these sections:

Markdown
# Project: MyApp

## Architecture
- Monorepo with apps/ and packages/ directories
- Backend: Node.js + Express + PostgreSQL
- Frontend: Next.js 14 with App Router
- Shared types in packages/shared-types

## Coding Standards
- Use TypeScript strict mode everywhere
- Prefer named exports over default exports
- All API endpoints must have Zod validation schemas
- Database queries go through the repository pattern
- Never use any type — use unknown and narrow

## Testing Requirements
- Every new function needs unit tests
- Integration tests for API endpoints
- Minimum 80% coverage for new code
- Use vitest for unit tests, playwright for e2e

## Git Conventions
- Branch format: feature/TICKET-123-short-description
- Commit format: type(scope): description
- Always squash merge to main
- Never force push to shared branches

## PR Standards
- Must include a summary and test plan
- All checks must pass before review
- Minimum one approval required
- Link to the relevant ticket in description

## Forbidden Patterns
- Do NOT use console.log in production code — use the logger utility
- Do NOT commit .env files
- Do NOT use raw SQL — use the query builder
- Do NOT skip error handling — wrap async calls in try/catch

Keeping CLAUDE.md Up to Date

A stale CLAUDE.md is worse than none at all. Establish a process:

Review CLAUDE.md in every architecture decision — when you change a pattern, update CLAUDE.md
Add a CI check — lint the CLAUDE.md for common issues
Assign an owner — one person (or a rotating role) reviews CLAUDE.md monthly
Use PRs for changes — treat CLAUDE.md edits like code changes with review

Team Custom Slash Commands

Custom slash commands let you package complex workflows into simple, repeatable actions. They live in the .claude/commands/ directory and are shared via version control.

Creating Team Commands

Create a directory for team-wide commands:

Terminal

mkdir -p .claude/commands

Each command is a markdown file. The filename becomes the command name.

Example: Code Review Command (.claude/commands/review.md)

Markdown
Review the current staged changes with the following checklist:

1. Check for TypeScript type safety issues
2. Verify error handling is complete
3. Ensure all new functions have JSDoc comments
4. Look for potential performance issues
5. Verify naming conventions match our standards
6. Check for security vulnerabilities (SQL injection, XSS, etc.)
7. Ensure tests cover the happy path and at least one error case

Output a structured report with:
- Summary of changes
- Issues found (critical / warning / info)
- Suggestions for improvement
- Overall assessment (approve / request changes)

Example: New Feature Scaffold (.claude/commands/scaffold-feature.md)

Markdown
Create a new feature module with the standard structure:

1. Create the directory: src/features/$ARGUMENTS/
2. Add the following files:
   - index.ts (barrel export)
   - types.ts (TypeScript interfaces)
   - service.ts (business logic)
   - controller.ts (API handler)
   - repository.ts (database access)
   - validator.ts (Zod schemas)
   - __tests__/service.test.ts
   - __tests__/controller.test.ts
3. Register routes in src/routes/index.ts
4. Add the feature to the README features list

Example: Database Migration (.claude/commands/create-migration.md)

Markdown
Create a new database migration for: $ARGUMENTS

Generate a timestamped migration file in db/migrations/
Include both up and down functions
Add appropriate indexes for any new columns
Update the schema types in packages/shared-types
Create or update the repository methods
Add a test for the migration rollback

Organizing Commands by Role

For larger teams, organize commands by role or function:

.claude/commands/
  review.md
  scaffold-feature.md
  create-migration.md
  fix-lint.md
  write-tests.md
  update-docs.md
  debug-issue.md
  optimize-query.md

Onboarding New Team Members

A strong onboarding workflow helps new developers become productive quickly. Claude Code can accelerate this significantly.

The Onboarding CLAUDE.md Section

Add an onboarding section to your CLAUDE.md:

Markdown
## Onboarding

### First Day Setup
1. Clone the repo and run: npm install
2. Copy .env.example to .env and fill in local values
3. Start the database: docker compose up -d postgres
4. Run migrations: npm run db:migrate
5. Start dev server: npm run dev
6. Run tests to verify: npm run test

### Key Concepts
- We use the repository pattern for all database access
- API validation happens at the controller level with Zod
- Auth is handled via JWT tokens stored in httpOnly cookies
- Background jobs run through BullMQ with Redis

### Where to Find Things
- API routes: src/routes/
- Business logic: src/features/
- Shared types: packages/shared-types/
- Database schemas: db/schemas/
- E2E tests: tests/e2e/

Onboarding Slash Command

Create a dedicated onboarding command (.claude/commands/onboard.md):

Markdown
Help me understand this codebase. Walk me through:

1. The overall architecture and directory structure
2. How a typical API request flows through the system
3. The database schema and key relationships
4. The testing strategy and how to run tests
5. The deployment pipeline
6. Any critical things a new developer should know

Be thorough but concise. Use diagrams where helpful.

Code Review Standards

Consistent code reviews are essential for code quality. Define clear standards and use Claude to enforce them.

Automated Review Checklist

Create a review standards document and reference it in your CLAUDE.md:

Markdown
## Code Review Standards

### Must Pass (Blocking)
- No TypeScript errors or warnings
- All tests pass
- No secrets or credentials in code
- Error handling for all async operations
- Input validation for all external data
- No breaking changes to public APIs without version bump

### Should Pass (Non-blocking)
- Functions under 50 lines
- Files under 300 lines
- Clear variable and function names
- JSDoc for exported functions
- Performance considerations documented
- Accessibility compliance for UI changes

### Nice to Have
- Code examples in documentation
- Benchmark results for performance-sensitive changes
- Screenshots for UI changes

Using Claude for PR Reviews

You can integrate Claude into your PR review workflow:

Terminal
# Review a specific PR
gh pr diff 42 | claude "Review this PR diff against our team standards in CLAUDE.md"

Create a CI step that runs Claude review automatically:

YAML
# .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
      - name: Run Claude Review
        run: |
          gh pr diff ${{ github.event.pull_request.number }} > diff.txt
          claude --print "Review this diff against our CLAUDE.md standards" < diff.txt

Shared MCP Servers

Model Context Protocol (MCP) servers extend Claude's capabilities with external tools. Teams can share MCP server configurations for consistency.

Team MCP Configuration

MCP servers are configured in .claude/settings.json at the project level:

JSON
{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres", "postgresql://localhost:5432/myapp"],
      "env": {}
    },
    "jira": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-jira"],
      "env": {
        "JIRA_URL": "https://myteam.atlassian.net",
        "JIRA_TOKEN_ENV": "JIRA_API_TOKEN"
      }
    },
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN_ENV": "GITHUB_TOKEN"
      }
    }
  }
}

Best Practices for Team MCP Servers

Use environment variable references — never hardcode tokens in shared configs
Document required environment variables — add them to .env.example
Version pin MCP server packages — avoid breaking changes from updates
Test MCP servers in CI — ensure they start correctly
Limit server permissions — use read-only database connections where possible

Coding Standards Enforcement

Beyond documentation, you can actively enforce standards through Claude Code.

Pre-commit Hooks with Claude

Add Claude-powered checks to your workflow:

Terminal
# .claude/commands/pre-commit-check.md
Check the staged files for:
1. Any use of console.log (should use logger)
2. Missing error handling in async functions
3. Raw SQL queries (should use query builder)
4. Hardcoded secrets or API keys
5. Missing TypeScript types (no implicit any)

Report violations with file paths and line numbers.

Style Guide Enforcement

Include specific style rules in CLAUDE.md that Claude will follow:

Markdown
## Style Enforcement

### Naming Conventions
- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase with use prefix (useAuth.ts)
- Utilities: camelCase (formatDate.ts)
- Constants: SCREAMING_SNAKE_CASE (MAX_RETRY_COUNT)
- Types/Interfaces: PascalCase with no I prefix (UserProfile, not IUserProfile)

### Import Order
1. Node built-ins (path, fs)
2. External packages (react, express)
3. Internal packages (@myapp/shared)
4. Relative imports (./utils)
5. Type imports (type { User })

### File Structure
- Exports at the top
- Types and interfaces next
- Constants after types
- Main logic in the middle
- Helper functions at the bottom

Collaboration Patterns

Effective team collaboration with Claude requires agreed-upon patterns.

The Session Handoff Pattern

When one developer starts work and another continues:

Document context in comments — leave TODO comments explaining the current state
Use descriptive branch names — include the ticket number and a brief description
Write a handoff note — summarize what was done, what remains, and any blockers
Commit frequently — small commits make it easier for the next person to understand progress

The Pair Programming Pattern

Two developers can use Claude together effectively:

Driver writes code with Claude — one person runs Claude and makes changes
Navigator reviews in real-time — the other person watches and catches issues
Switch roles regularly — every 30 minutes, swap who controls Claude
Share the session context — use a shared CLAUDE.md with pair-specific notes

The Review-First Pattern

Before writing code, use Claude to review the approach:

Terminal
claude "I need to implement user authentication with OAuth 2.0.
Review our current auth setup in src/auth/ and suggest the best
approach that fits our existing patterns."

This prevents wasted effort on approaches that do not fit the codebase.

The Documentation-Driven Pattern

Write documentation before implementation:

Write the API contract first (OpenAPI spec or TypeScript types)
Have Claude review the contract for completeness
Implement the feature following the contract
Claude validates the implementation matches the contract

Measuring Team Productivity

Track how Claude impacts your team's productivity to justify investment and improve workflows.

Key Metrics to Track

Metric	How to Measure	Target
Time to First Commit	Track from onboarding start to first merged PR	Under 2 days
PR Cycle Time	Time from PR open to merge	Under 24 hours
Code Review Turnaround	Time from review request to first review	Under 4 hours
Bug Escape Rate	Bugs found in production vs caught in review	Under 5%
Test Coverage Delta	Coverage change per sprint	Positive trend
Developer Satisfaction	Monthly survey score	Above 8/10

Tracking Claude Usage

Monitor how your team uses Claude to identify improvement opportunities:

Markdown
## Weekly Claude Retrospective Questions
What tasks did Claude handle well this week?
Where did Claude struggle or produce incorrect output?
Are there new patterns we should add to CLAUDE.md?
Did anyone discover a useful new workflow?
Are there repetitive tasks we should automate with commands?

Migration Guide: Adopting Team Workflows

If your team is already using Claude individually, follow this migration path to adopt team workflows.

Phase 1: Foundation (Week 1)

Create the project CLAUDE.md — gather input from all team members
Document existing conventions — write down what people already follow informally
Set up the commands directory — create 2-3 initial team commands
Commit everything — push CLAUDE.md and commands to the shared repo

Phase 2: Standardization (Week 2-3)

Add code review standards — define the review checklist
Configure shared MCP servers — set up database and project management integrations
Create onboarding documentation — write the onboarding section and command
Train the team — run a workshop on using shared commands and CLAUDE.md

Phase 3: Optimization (Week 4+)

Collect feedback — run the weekly retrospective
Refine CLAUDE.md — update based on real-world usage
Add new commands — automate frequently requested workflows
Measure impact — track the metrics defined above

Common Migration Mistakes

Mistake	Why It Happens	How to Avoid
Overloading CLAUDE.md	Trying to document everything at once	Start with top 10 rules, expand gradually
Ignoring personal preferences	Forcing everyone into identical workflows	Allow personal CLAUDE.md for individual style
Not updating docs	CLAUDE.md drifts from reality	Monthly review process with assigned owner
Too many commands	Creating commands for rare tasks	Only automate tasks done at least weekly
Skipping training	Assuming people will figure it out	Run a 30-minute intro session for the team

Summary

Building effective team workflows with Claude Code requires:

A shared CLAUDE.md that documents architecture, standards, and conventions
Custom slash commands for repeatable team workflows
Structured onboarding that gets new members productive quickly
Clear code review standards enforced consistently
Shared MCP servers for consistent tooling across the team
Coding standards enforcement through documentation and automation
Collaboration patterns that fit your team's working style
Measurable metrics to track and improve productivity
A phased migration plan to adopt workflows incrementally

The key principle is consistency over perfection. A simple, shared workflow that everyone follows is far more valuable than a complex system that only one person understands.

Module 12

5/5

💬 Claude Code in Slack

RAG — Retrieval-Augmented Generation 🔍

5/5