Skill refresh
This commit is contained in:
movq
624
claude-code/skills/claude-memory/workflows.md
Normal file
624
claude-code/skills/claude-memory/workflows.md
Normal file
@@ -0,0 +1,624 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user