# Install Claude Code
npx @anthropics/claude

# Navigate to your project and start Claude
cd your-project
npx @anthropics/claude

# Project: [Project Name]

## Quick Commands
- `npm run build`: Build the project
- `npm run test`: Run tests
- `npm run lint`: Run linting
- `npm run typecheck`: Type checking

## Code Style & Standards
- Use ES modules (import/export), not CommonJS
- Destructure imports when possible
- Always run tests after code changes
- Prefer single test files over full suites for performance
- Use TypeScript strict mode

## Architecture & Key Files
- Core logic: `src/services/main_service.py`
- API routes: `src/api/routes/`
- Database models: `src/models/`
- Tests: `tests/` (mirrors src structure)

## Workflow Rules
- Branch naming: `feature/description` or `fix/description`
- Always create feature branches from `develop`
- Run linter before commits
- Write tests for new functionality

## Project-Specific Guidelines
- Never uncomment test blocks without explicit instruction
- Reuse existing DAO functions instead of creating redundant ones
- Check existing patterns before implementing new solutions
- IMPORTANT: Always validate input parameters for API endpoints
- YOU MUST: Run type checking after making changes

# Allow safe operations
/permissions add Edit
/permissions add "Bash(git commit:*)"
/permissions add "Bash(git push:*)"

# Allow specific MCP tools
/permissions add mcp__puppeteer__puppeteer_navigate

{
  "allowedTools": [
    "Edit",
    "Bash(git commit:*)",
    "mcp__github__*"
  ]
}

**Phase 1: Explore**
"Read the authentication module and related test files. Don't write any code yet - just explore and understand the current implementation."

**Phase 2: Plan** 
"Think harder about how to add OAuth support. Create a detailed plan considering:
- Integration with existing auth flow
- Database schema changes needed
- Testing strategy
- Security considerations"

**Phase 3: Code**
"Now implement the OAuth feature according to your plan. Verify each component works as you build it."

**Phase 4: Commit**
"Run all tests, fix any issues, and commit with a descriptive message following our conventional commit format."

**Step 1: Write Tests First**
"Write comprehensive tests for the user authentication feature. Cover:
- Valid login scenarios
- Invalid credentials
- Session management
- Edge cases like expired tokens

Be explicit that this is TDD - don't create mock implementations."

**Step 2: Verify Test Failures**
"Run the tests and confirm they fail as expected. Don't write any implementation code yet."

**Step 3: Implement to Pass Tests**
"Now write the minimum code needed to make all tests pass. Don't modify the tests."

**Step 4: Iterate Until Green**
"Keep iterating - run tests, fix issues, repeat until all tests pass."

**Setup Visual Feedback**
"Set up Puppeteer MCP server so you can take screenshots of our React app."

**Implement with Visual Targets**
"Here's the design mock [drag/drop image]. Implement this component, take a screenshot of the result, and iterate until it matches the design."

**Progressive Refinement**
"The layout is close but spacing is off. Take another screenshot and adjust the CSS until the spacing matches the design exactly."

# Run with specific allowed tools (safer approach)
claude --allowedTools "Edit,Bash(eslint:*)" "Fix all ESLint errors in the src/ directory"

"Use subagents to investigate this performance issue:
1. Have one subagent analyze the database queries
2. Have another examine the frontend bundle size
3. Have a third review the caching strategy
Then synthesize their findings into recommendations."

"Before we start, read these files to understand the context:
- @src/auth/auth_service.py
- @tests/auth/test_auth.py  
- @docs/auth_requirements.md

Then let me know when you understand the current authentication architecture."

Please analyze and fix GitHub issue: $ARGUMENTS

Follow our team process:
1. Use `gh issue view` to get issue details
2. Create feature branch: `git checkout -b fix/issue-$ARGUMENTS`
3. Search codebase for relevant files
4. Implement fix following our coding standards
5. Write/update tests to verify the fix
6. Run full test suite and linting
7. Commit with format: `fix: resolve issue #$ARGUMENTS - [description]`
8. Push and create PR with our template

Perform comprehensive code review of recent changes:

1. **Standards Compliance**
   - Check TypeScript/React conventions
   - Verify proper error handling
   - Ensure accessibility standards

2. **Quality Assurance**  
   - Review test coverage
   - Check for security vulnerabilities
   - Validate performance implications

3. **Documentation**
   - Confirm documentation is updated
   - Check for inline comments where needed

Use our established checklist and update CLAUDE.md with new patterns.

# Feature: Real-time Collaboration

## Requirements
- Multiple users can edit documents simultaneously
- Changes sync in real-time
- Conflict resolution for concurrent edits
- Offline support with sync on reconnect

## Technical Approach
- WebSocket connections for real-time updates
- Operational Transform for conflict resolution  
- Redux for state management
- IndexedDB for offline storage

# Implementation Plan

## Phase 1: Backend Infrastructure ✅
- [x] Set up WebSocket server
- [x] Implement basic message routing
- [x] Create user session management

## Phase 2: Real-time Sync (IN PROGRESS)
- [ ] Implement operational transform algorithm
- [ ] Add conflict resolution logic  
- [ ] Create client-side WebSocket handler

## Phase 3: Offline Support
- [ ] Add IndexedDB persistence
- [ ] Implement sync queue
- [ ] Handle reconnection scenarios

## Phase 4: Testing & Polish
- [ ] Write comprehensive test suite
- [ ] Add error handling and edge cases
- [ ] Performance optimization

"We're implementing TDD. First, write comprehensive tests for the shopping cart feature:
- Add items to cart
- Remove items from cart  
- Update quantities
- Calculate totals with tax
- Handle discount codes
- Manage cart persistence

Don't implement any actual cart logic yet - just the test cases."

# In Claude Code terminal
/install-github-app

direct_prompt: |
  Review this PR focusing on:
  - Security vulnerabilities and input validation
  - Logic errors and edge cases  
  - Performance implications
  - Code maintainability
  
  Be concise - only report significant issues, not style preferences.

# .pre-commit-config.yaml  
repos:
  - repo: local
    hooks:
      - id: tests
        name: Run test suite
        entry: npm test
        language: system
      - id: typecheck  
        name: TypeScript check
        entry: npm run typecheck
        language: system
      - id: lint
        name: ESLint check
        entry: npm run lint
        language: system

"Set up pytest with these fixtures and test patterns:
- Database fixtures with rollback
- API client fixtures  
- Mock external services
- Coverage reporting with minimum 80% threshold"

"Configure Jest with:
- Component testing with React Testing Library
- Integration tests for API endpoints
- E2E tests with Playwright
- Visual regression tests for UI components"

## Security Requirements

### Input Validation
- ALWAYS validate and sanitize user input
- Use parameterized queries for database operations
- Implement proper authentication checks

### Sensitive Data Handling  
- Never log sensitive data (passwords, tokens, PII)
- Use environment variables for secrets
- Implement proper session management

### Security Testing
- Run dependency vulnerability scans
- Test for common OWASP vulnerabilities
- Validate API authentication and authorization

"Review this authentication endpoint as a security expert. Focus on:
1. Input validation and sanitization
2. SQL injection vulnerabilities  
3. Authentication bypass scenarios
4. Session management security
5. Rate limiting and brute force protection

Identify any security risks and provide specific fixes."

"Create Terraform configuration for:
- Auto-scaling web servers
- RDS database with backups
- Redis cache cluster
- Load balancer with SSL
- CloudWatch monitoring

Follow security best practices for network isolation and access control."

"Set up GitHub Actions workflow that:
1. Runs security scans on dependencies
2. Executes full test suite
3. Builds production artifacts
4. Deploys to staging environment
5. Runs smoke tests
6. Promotes to production with approval gate
7. Sends Slack notifications for status updates"

# Check current session usage
/usage

# View conversation statistics
/stats

"Process these 15 similar API endpoints in batch:
1. Add input validation
2. Update error handling  
3. Add logging
4. Update tests
5. Generate documentation

Work through them systematically, committing after each group of 3."

# Terminal 1: Frontend work
cd frontend && claude

# Terminal 2: Backend API  
cd backend && claude

# Terminal 3: Testing
cd tests && claude

# Create worktrees for parallel work
git worktree add ../project-feature-a -b feature-a
git worktree add ../project-feature-b -b feature-b  
git worktree add ../project-bugfix -b bugfix

# Start Claude in each
cd ../project-feature-a && claude
# (repeat in separate terminals)

"Implement the new payment processing feature according to the spec in @docs/payment-spec.md"

"Review the payment processing code that was just implemented. Focus on:
- Security vulnerabilities
- Error handling completeness  
- Test coverage
- Code maintainability"

"Integrate the reviewed payment code with feedback from the reviewer. Address all security concerns and add missing tests."

# Architecture Agent
"Act as a senior architect. Design the microservice structure for our e-commerce platform."

# Security Agent  
"Act as a security expert. Review the authentication system for vulnerabilities."

# Performance Agent
"Act as a performance engineer. Optimize the database queries and caching strategy."

claude mcp install @modelcontextprotocol/server-github

claude mcp install @modelcontextprotocol/server-brave-search

claude mcp install @modelcontextprotocol/server-puppeteer

claude mcp install @modelcontextprotocol/server-postgresql

"Use the GitHub MCP server to:
1. Fetch all README files from our repositories
2. Analyze common documentation patterns
3. Generate comprehensive docs for our new microservice
4. Create standardized README template for future projects"

"Use Puppeteer MCP server to:
1. Navigate to our staging environment
2. Test the complete user registration flow
3. Take screenshots at each step
4. Generate automated test report with visual validation"

// Custom MCP server for internal APIs
const server = new McpServer({
  name: 'company-internal-api',
  version: '1.0.0'
});

server.addTool({
  name: 'query_user_analytics',
  description: 'Query our internal user analytics API',
  inputSchema: {
    type: 'object',
    properties: {
      metric: { type: 'string' },
      timeRange: { type: 'string' }
    }
  }
});

"Before continuing, create a summary of our current progress and save it to progress.md. Then use /compact to optimize context."

# Add commonly used tools to allowlist
/permissions add Edit
/permissions add "Bash(git:*)"
/permissions add "Bash(npm:*)"

## Code Quality Standards

❌ Bad: Direct database queries in controllers
```python
def get_user(user_id):
    return db.execute("SELECT * FROM users WHERE id = %s", user_id)

def get_user(user_id):
    return UserRepository.find_by_id(user_id)

"Analyze this stack trace and production logs. Trace the control flow through our codebase and identify:
1. Root cause of the error
2. Contributing factors  
3. Specific fix needed
4. Prevention strategies for similar issues"

"Use subagents to investigate this performance issue:
1. Database Agent: Analyze slow queries and indexing
2. Frontend Agent: Check bundle size and render performance  
3. Network Agent: Review API response times and caching
Synthesize findings with specific optimization recommendations."