# Team Collaboration Workflows

Strategies for using CLAUDE.md in team environments.

## Workflow 1: Onboarding New Developer

### Goal
Get new team members productive immediately using CLAUDE.md as primary documentation.

### Setup

```bash
# Project repository structure
myproject/
├── .claude/
│   └── CLAUDE.md          # Team standards
├── docs/
│   ├── architecture.md
│   ├── conventions.md
│   └── getting-started.md
└── README.md
```

### Process

#### Step 1: Clone Repository

```bash
git clone repo
cd myproject
```

#### Step 2: Claude Reads Memory Automatically

New developer opens Claude Code - memory loads automatically.

#### Step 3: Ask Claude for Orientation

```
New Dev: "What's this project about?"

Claude (using CLAUDE.md): "This is an e-commerce platform using:
- Tech Stack: React + Node.js + PostgreSQL
- Architecture: Microservices pattern
- Key directories: src/api, src/components, src/services
- Start with: npm install && npm run dev
- See docs/getting-started.md for detailed setup"
```

#### Step 4: Productive Immediately

New developer can:
- Ask Claude about any convention
- Get help with setup issues
- Understand architecture decisions
- Follow team standards automatically

### Benefits

- **Zero onboarding docs to read**: Claude explains everything
- **Consistent answers**: Same info for all team members
- **Always up to date**: Update CLAUDE.md, everyone gets it
- **Interactive learning**: Ask questions, get context-aware answers

---

## Workflow 2: Updating Team Standards

### Goal
Change team conventions and have all developers adopt them immediately.

### Scenario
Team decides to switch from npm to pnpm.

### Process

#### Step 1: Update CLAUDE.md

```bash
# Edit .claude/CLAUDE.md
sed -i 's/npm run/pnpm run/g' .claude/CLAUDE.md
sed -i 's/npm test/pnpm test/g' .claude/CLAUDE.md
sed -i 's/npm install/pnpm install/g' .claude/CLAUDE.md
```

Update commands section:

```markdown
## Common Commands
```bash
pnpm run dev      # Start development server
pnpm test         # Run test suite
pnpm run build    # Production build
```

IMPORTANT: This project uses pnpm, not npm.
```

#### Step 2: Commit Change

```bash
git add .claude/CLAUDE.md
git commit -m "docs: switch package manager from npm to pnpm"
git push
```

#### Step 3: Team Pulls Update

```bash
# Each developer
git pull
```

#### Step 4: Claude Uses New Standard

Next time anyone asks Claude to run a command, it uses pnpm automatically.

### Benefits

- **Immediate adoption**: No need to notify team
- **No context switching**: Claude reminds developers
- **Version controlled**: Track convention changes
- **Rollback if needed**: Git history

---

## Workflow 3: Feature-Specific Context

### Goal
Provide context for specific feature areas without bloating root memory.

### Structure

```
project/
├── CLAUDE.md                    # Root context
├── features/
│   ├── auth/
│   │   ├── CLAUDE.md           # Auth-specific context
│   │   └── src/
│   ├── payments/
│   │   ├── CLAUDE.md           # Payment-specific context
│   │   └── src/
│   └── notifications/
│       ├── CLAUDE.md           # Notification-specific context
│       └── src/
```

### Root CLAUDE.md

```markdown
# MyProject

## Feature Areas

Each feature has specific context:
- `features/auth/` - Authentication (see auth/CLAUDE.md)
- `features/payments/` - Payment processing (see payments/CLAUDE.md)
- `features/notifications/` - Notification system (see notifications/CLAUDE.md)

When working in a feature directory, Claude loads that context automatically.
```

### features/auth/CLAUDE.md

```markdown
# Authentication Feature

## Implementation
- JWT + refresh tokens
- Token lifetime: 15min access, 7d refresh
- Password requirements: min 12 chars, bcrypt rounds: 12

## Key Files
- `src/auth.service.ts` - Core auth logic
- `src/jwt.util.ts` - Token generation/validation
- `src/password.util.ts` - Password hashing

## IMPORTANT Security Rules
- Passwords MUST be hashed with bcrypt (min 12 rounds)
- Tokens MUST have expiration
- MFA required for admin accounts
- Log all authentication failures

## Testing
- Unit tests: `tests/auth.test.ts`
- Integration: `tests/auth.integration.test.ts`
- All auth changes need security review
```

### Usage

```bash
# Developer working on auth feature
cd features/auth

# Claude now has both root context + auth-specific context
# Can answer auth-specific questions with full context
```

### Benefits

- **Contextual memory**: Right info at right time
- **No bloat**: Root memory stays lean
- **Feature ownership**: Each team owns their feature docs
- **Isolated changes**: Update feature context independently

---

## Workflow 4: Architecture Decision Records (ADR)

### Goal
Document why decisions were made and have Claude reference them.

### Structure

```
project/
├── .claude/
│   └── CLAUDE.md
└── docs/
    └── adr/
        ├── 001-use-postgresql.md
        ├── 002-microservices-architecture.md
        ├── 003-graphql-over-rest.md
        └── template.md
```

### CLAUDE.md Reference

```markdown
# MyProject

## Architecture Decisions

All architectural decisions are documented in ADRs.

See @docs/adr/ for all decisions.

When making architectural changes:
1. Propose via ADR
2. Get team review
3. Update CLAUDE.md if needed
```

### ADR Format (docs/adr/003-graphql-over-rest.md)

```markdown
# 3. Use GraphQL Instead of REST

Date: 2024-01-15
Status: Accepted

## Context
Need API design pattern for new features.

## Decision
Use GraphQL for new APIs, maintain REST for legacy.

## Consequences
**Positive:**
- Flexible queries
- Reduced over-fetching
- Strong typing

**Negative:**
- Learning curve
- More complex caching

## Implementation
See @docs/graphql-guide.md
```

### Usage

Developer asks Claude: "Why do we use GraphQL?"

Claude references ADR and explains the decision context.

### Benefits

- **Historical context**: Understand past decisions
- **Onboarding**: New devs understand "why"
- **Consistency**: Reference when making new decisions
- **Change tracking**: Git history of decisions

---

## Workflow 5: Code Review Automation

### Goal
Use CLAUDE.md to establish review standards, have Claude enforce them.

### .claude/CLAUDE.md

```markdown
# MyProject

## Code Review Checklist

Before approving PRs, verify:

### Functionality
- [ ] Tests pass locally
- [ ] New features have tests
- [ ] Coverage > 80%

### Code Quality
- [ ] Follows style guide
- [ ] No linter warnings
- [ ] Functions < 50 lines
- [ ] Clear variable names

### Security
- [ ] No hardcoded secrets
- [ ] Input validation present
- [ ] SQL uses parameterized queries
- [ ] Auth checks on protected routes

### Documentation
- [ ] API changes documented
- [ ] Complex logic has comments
- [ ] README updated if needed

## NEVER Approve PRs With
- Failing tests
- Linter errors
- Hardcoded credentials
- console.log statements
```

### Usage in Review

```
Reviewer: "Review this PR: #123"

Claude (reads PR, checks against CLAUDE.md):
"Reviewing PR #123 against team standards:

✓ Tests pass
✓ Coverage maintained (85%)
✗ Found console.log in auth.ts:42
✗ Missing input validation in user.controller.ts:67
✗ API changes not documented

Recommendation: Request changes before approval.

Specific issues:
1. auth.ts:42 - Remove console.log (violates standards)
2. user.controller.ts:67 - Add Zod validation for email field
3. Missing: Update API.md with new /users/profile endpoint
```

### Benefits

- **Consistent reviews**: Same standards for all reviewers
- **Automated checks**: Claude catches issues
- **Teaching tool**: Shows reviewers what to look for
- **Living standards**: Update CLAUDE.md as standards evolve

---

## Workflow 6: Multi-Repository Consistency

### Goal
Maintain consistent standards across multiple repositories.

### Setup

```
~/.claude/CLAUDE.md              # Personal + org standards

org-repo-1/
└── .claude/
    └── CLAUDE.md               # Repo-specific (imports personal)

org-repo-2/
└── .claude/
    └── CLAUDE.md               # Repo-specific (imports personal)
```

### ~/.claude/CLAUDE.md (Shared Across All Repos)

```markdown
# Organization Standards

Applied to all our repositories.

## Git Workflow
- Branch from main
- Squash merge PRs
- Conventional commits

## Code Quality
- Tests required
- Linting enforced
- 80% coverage minimum

## Security
- No hardcoded secrets
- Input validation required
- Security review for auth changes

## Documentation
@~/docs/org-standards.md
```

### org-repo-1/.claude/CLAUDE.md

```markdown
# Repo 1

Frontend React application.

## Repo-Specific
- React 18 + TypeScript
- Tailwind for styling
- Jest + RTL for testing

## Tech Stack
@docs/tech-stack.md

All organization standards apply (see ~/.claude/CLAUDE.md)
```

### Benefits

- **DRY**: Don't repeat org standards in each repo
- **Consistency**: Same standards everywhere
- **Easy updates**: Change once, applies to all
- **Repo specifics**: Each repo adds its unique context

---

## Workflow 7: Gradual Migration

### Goal
Migrate existing documentation to CLAUDE.md progressively.

### Phase 1: Start Small (Week 1)

```markdown
# CLAUDE.md (50 lines)

## Common Commands
```bash
npm run dev
npm test
npm run build
```

## Key Conventions
- 2-space indentation
- ESLint + Prettier
```

### Phase 2: Add Core Info (Week 2-3)

```markdown
# CLAUDE.md (100 lines)

[Previous content]

## Tech Stack
- Backend: Node.js + Express
- Frontend: React + TypeScript
- Database: PostgreSQL

## Architecture
@docs/architecture.md

## IMPORTANT Rules
- Tests required before merge
- No commits to main
```

### Phase 3: Import Existing Docs (Week 4)

```markdown
# CLAUDE.md (150 lines)

[Previous content]

## Detailed Documentation
- Architecture: @docs/architecture.md
- API Reference: @docs/api.md
- Style Guide: @docs/style-guide.md
- Testing: @docs/testing-guide.md
```

### Phase 4: Optimize (Ongoing)

- Move inline content to imports
- Compress verbose sections
- Test with team
- Gather feedback
- Iterate

### Benefits

- **Low risk**: Start small, grow gradually
- **Learn as you go**: Discover what works
- **Team adoption**: Give team time to adjust
- **Continuous improvement**: Iterate based on usage

---

## Workflow 8: Cross-Team Collaboration

### Goal
Enable multiple teams to work on shared codebase with team-specific context.

### Structure

```
monorepo/
├── .claude/
│   └── CLAUDE.md                    # Shared standards
├── packages/
│   ├── frontend/
│   │   └── .claude/
│   │       └── CLAUDE.md           # Frontend team context
│   └── backend/
│       └── .claude/
│           └── CLAUDE.md           # Backend team context
```

### Root .claude/CLAUDE.md (Shared)

```markdown
# Monorepo Standards

## Shared Across All Teams
- pnpm workspaces
- Conventional commits
- Test coverage > 80%
- Code review required

## Team-Specific Context
- Frontend: packages/frontend/CLAUDE.md
- Backend: packages/backend/CLAUDE.md

When in a package directory, team-specific context loads automatically.
```

### packages/frontend/.claude/CLAUDE.md

```markdown
# Frontend Team Context

**Team**: Frontend (React specialists)

## Our Stack
- React 18 + TypeScript
- Tailwind + shadcn/ui
- Zustand for state
- React Query for data

## Our Conventions
- Atomic design pattern
- Mobile-first responsive
- Dark mode support required

## Our PR Process
- 2 frontend developers must approve
- Accessibility check required
- Browser testing checklist

## Contact
- Lead: @alice
- Questions: #frontend-team
```

### packages/backend/.claude/CLAUDE.md

```markdown
# Backend Team Context

**Team**: Backend (API specialists)

## Our Stack
- Node.js + Express + TypeScript
- PostgreSQL + Prisma
- Redis caching
- JWT authentication

## Our Conventions
- RESTful API design
- OpenAPI documentation
- Rate limiting all endpoints

## Our PR Process
- 2 backend developers must approve
- Security review for auth changes
- Load testing for perf-critical paths

## Contact
- Lead: @bob
- Questions: #backend-team
```

### Benefits

- **Team autonomy**: Each team defines their standards
- **Shared foundations**: Common org-wide rules
- **Context switching**: Right context automatically
- **Cross-team awareness**: See other team's standards

---

## Summary: Team Success Patterns

1. **Start Simple**: Begin with 50-100 lines, grow organically
2. **Version Control**: Track changes, review updates
3. **Team Buy-In**: Get feedback, iterate together
4. **Clear Ownership**: Assign responsibility for updates
5. **Regular Reviews**: Monthly check for outdated content
6. **Measure Impact**: Track onboarding time, review consistency
7. **Document Decisions**: Use ADRs for architecture
8. **Progressive Disclosure**: Core in CLAUDE.md, details in imports
9. **Feature Contexts**: Use subfolders for feature-specific guidance
10. **Cross-Repo Standards**: Share common standards across projects

**Goal**: Make CLAUDE.md the single source of truth for team development practices.