claude-plugins/claude-code/skills/claude-memory/workflows.md

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

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

Process

Step 1: Clone Repository

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

# 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:

## 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

# 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

# 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

# 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

# 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

# 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)

# 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

# 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)

# 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

# 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)

# 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)

# 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)

# 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

# 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

# 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.