Claude Code Team Collaboration: Multi-Agent Workflows

1. The Memory Hierarchy: CLAUDE.md as Organizational Knowledge

CLAUDE.md files aren't just configuration - they're your team's compounding memory system. Every mistake caught and documented becomes permanent knowledge that benefits everyone.

The Three-Level Memory Architecture

Memory Hierarchy:

1. →Global - ~/.claude/CLAUDE.md (All projects)
2. →Project - /project/CLAUDE.md (Team shared)
3. →Local - /project/.claude/CLAUDE.md (Personal prefs)

Priority: Local > Project > Global

The Minimum Viable CLAUDE.md

Most projects only need three things:

# Project Name

Brief one-sentence description of what this project does.

## Commands
- `pnpm dev` - Start development server
- `pnpm test` - Run tests
- `pnpm lint` - Check code style

That's it for most projects. Claude automatically detects:

• →Tech stack (from package.json, go.mod, Cargo.toml, etc.)
• →Directory structure (via exploration)
• →Existing conventions (from the code itself)

Add more only when needed - when Claude makes a mistake twice because of missing context, add that context.

Team adoption of Claude Code looks nothing like individual adoption, and the discussions on r/ExperiencedDevs and r/engineeringmanagers make this unusually clear. A single engineer can thrive with a messy CLAUDE.md and a mental model of where the landmines are; a 12-person team cannot. The moment the second developer joins, every implicit rule becomes a coordination problem, and the tool that felt like a productivity multiplier starts producing divergent patterns across PRs because everyone's settings.local.json diverged quietly.

What genuinely helps: treat CLAUDE.md as code, review it in PRs, version it with the repo, and refuse to accept "silent" edits. Teams that keep changelogs for their AI context file (## 2026-01-15: removed the "always suggest commits" line because it was spamming) end up with far fewer surprise regressions. The pattern is endorsed in several open-source repos that ship a CLAUDE.md — see how projects on github.com/anthropics structure theirs, with explicit sections and dated revisions.

Where the community correctly pushes back: resist the urge to turn CLAUDE.md into a style guide encyclopedia. If your engineers need a style guide, write a style guide and link to it. The agent context file should encode constraints that change model behavior, not re-state what's already in .eslintrc or CONTRIBUTING.md. And the hardest part is political, not technical: someone on the team has to own the file, or it will drift into a committee document nobody trusts.

2. Continuous Context Updates

Don't just react to errors - proactively document discoveries during development sessions.

What to Capture by Category

3. The .claude/ Folder Structure

The .claude/ folder is your project's Claude Code directory for memory, settings, and extensions.

.claude/
├── CLAUDE.md              # Local instructions (gitignored)
├── settings.json          # Hook configuration (team shared)
├── settings.local.json    # Personal permissions (gitignored)
├── agents/                # Custom agent definitions
├── commands/              # Custom slash commands
├── hooks/                 # Event-driven scripts
├── rules/                 # Auto-loaded conventions
├── skills/                # Knowledge modules
└── plans/                 # Saved plan files

4. Single Source of Truth Pattern

When using multiple AI tools (Claude Code, CodeRabbit, SonarQube, Copilot...), they can conflict if each has different conventions.

Solution: One source of truth for all tools:

/docs/conventions/
├── coding-standards.md    # Style, naming, patterns
├── architecture.md        # System design decisions
├── testing.md             # Test conventions
└── anti-patterns.md       # What to avoid

Then reference from everywhere:

# In CLAUDE.md
@docs/conventions/coding-standards.md
@docs/conventions/architecture.md

# In .coderabbit.yml
knowledge_base:
  code_guidelines:
    filePatterns:
      - "docs/conventions/*.md"

5. Custom Agents for Team Workflows

Agents are specialized sub-processes that Claude can delegate tasks to. They encapsulate expertise.

When to Create an Agent

Agent Template

Create agents in .claude/agents/:

---
name: code-reviewer
description: Use for code quality reviews, security audits, and performance analysis
model: sonnet
tools: Read, Grep, Glob
skills:
  - security-guardian
---

# Code Reviewer

## Role Definition
You are a senior code reviewer with expertise in:
- Code quality and maintainability
- Security best practices (OWASP Top 10)
- Performance optimization
- Test coverage analysis

## Methodology
1. **Understand Context**: Read the code and understand its purpose
2. **Check Quality**: Evaluate readability, maintainability, DRY principles
3. **Security Scan**: Look for OWASP Top 10 vulnerabilities
4. **Performance Review**: Identify potential bottlenecks
5. **Provide Feedback**: Structured report with severity levels

Model Selection Guide

6. Skills: Reusable Knowledge Modules

Skills are knowledge packages that agents can inherit - think of them as libraries of expertise.

Interactive Skill Builder

Create your own custom skill with this step-by-step wizard. Choose a skill type, configure its capabilities, and generate a ready-to-use SKILL.md file:

Why Skills?

Without skills:

Agent A: Has security knowledge (duplicated)
Agent B: Has security knowledge (duplicated)
Agent C: Has security knowledge (duplicated)

With skills:

security-guardian skill: Single source of security knowledge
Agent A: inherits security-guardian
Agent B: inherits security-guardian
Agent C: inherits security-guardian

Creating a Skill

Skills live in .claude/skills/{skill-name}/:

security-guardian/
├── SKILL.md          # Main instructions
├── reference.md      # Detailed documentation
├── checklists/
│   ├── owasp-top10.md
│   └── auth-security.md
└── examples/
    ├── secure-auth.ts
    └── insecure-auth.ts

SKILL.md:

---
name: security-guardian
description: Expert guidance for security problems
allowed-tools: Read, Grep, Bash
---

# Security Guardian

You are a security expert specializing in:
- OWASP Top 10 vulnerabilities
- Authentication and authorization
- Input validation and sanitization
- Secure coding practices

## When Invoked
- Review code for security issues
- Audit authentication flows
- Check for injection vulnerabilities

7. Multi-Agent Orchestration Patterns

For complex tasks, orchestrate multiple agents working together.

Interactive Workflow Builder

Use this drag-and-drop tool to design multi-tool workflows. Combine research tools like Perplexity, coding assistants like Claude Code, and deployment platforms into seamless pipelines:

The Split-Role Analysis Pattern

Launch specialized agents with different perspectives:

Example prompt:

Analyze this PR with the following perspectives:
1. Senior Engineer: Architecture and patterns
2. Security Expert: Vulnerabilities and risks
3. Performance Engineer: Bottlenecks and optimizations
4. Junior Dev: Readability and documentation
5. QA Engineer: Testability and edge cases

The 7-Parallel-Task Method

For complete features, launch 7 specialized sub-agents in parallel:

1. →Components → Create React components
2. →Styles → Generate Tailwind styles
3. →Tests → Write unit tests
4. →Types → Define TypeScript types
5. →Hooks → Create custom hooks
6. →Integration → Connect with API/state
7. →Config → Update configurations

All run in parallel, then final consolidation

8. Cost-Optimized Team Workflows

Use model orchestration for cost efficiency:

Orchestration Pattern:

• →Orchestrator: Sonnet 4.5 (plans and coordinates)
• →Workers: 3x Haiku (execute parallel tasks)
• →Validator: Sonnet 4.5 (reviews and consolidates)

Cost: 2-2.5x cheaper than using Opus everywhere

Cost Optimization Example:

Scenario: Refactoring 100 files

❌ Naive approach:
- Opus for everything
- Cost: ~$50-100
- Time: 2-3h

✅ Optimized approach:
- Sonnet: Analysis and plan (1x)
- Haiku: Parallel workers (100x)
- Sonnet: Final validation (1x)
- Cost: ~$5-15
- Time: 1h (parallelized)

9. TeammateTool: Experimental Multi-Agent

For truly complex orchestration, Claude Code includes an experimental TeammateTool for persistent multi-agent communication:

Patterns:

• →Parallel Specialists: Leader spawns 3 teammates → Each reviews different aspect → Teammates work concurrently → Report back → Leader synthesizes
• →Swarm Pattern: Leader creates shared task queue → Teammates self-organize and claim tasks → Independent execution → Async updates

10. Team Onboarding Best Practices

Progressive CLAUDE.md Growth

Week 1: 5 rules  →  5 mistakes prevented
Week 4: 20 rules → 20 mistakes prevented
Month 3: 50 rules → 50 mistakes prevented + faster onboarding

Multi-Machine Sync

Option 1: Git + symlinks

# Machine 1 (setup)
cd ~/claude-config-backup
git add agents/ commands/ hooks/ skills/
git commit -m "Add latest configs"
git push

# Machine 2 (sync)
cd ~/claude-config-backup
git pull
# Symlinks automatically sync ~/.claude/ directories

Option 2: Cloud storage symlinks

# Both machines - move ~/.claude/ to cloud storage
mv ~/.claude ~/Dropbox/claude-config
ln -s ~/Dropbox/claude-config ~/.claude
# Changes sync automatically via Dropbox

Summary: Team Collaboration Keys

1. →CLAUDE.md as Organizational Memory: Capture mistakes once, prevent them forever
2. →Three-Level Hierarchy: Global → Project → Local with clear precedence
3. →Single Source of Truth: Align all AI tools to the same conventions
4. →Agents for Expertise: Encapsulate domain knowledge in reusable agents
5. →Skills for Sharing: Create knowledge modules that multiple agents inherit
6. →Multi-Agent Patterns: Split-role analysis and parallel workers for complex tasks
7. →Cost Optimization: Use model orchestration (Sonnet orchestrator + Haiku workers)
8. →Continuous Updates: Capture discoveries during every session