# .CLAUDE Template

This file provides configuration and context for Claude Code when working on this project.

## Project Overview

**Project Name:** [Your Project Name]
**Description:** [Brief description of what this project does]
**Tech Stack:** [List main technologies, frameworks, and versions]

## Code Style and Conventions

### Language/Framework Specifics
- **Language Version:** [e.g., Python 3.11, Node 18.x, Java 17]
- **Package Manager:** [e.g., npm, pip, maven, cargo]
- **Build Tool:** [e.g., webpack, vite, gradle, cargo]

### Coding Standards
- **Style Guide:** [e.g., PEP 8, Airbnb, Google Java Style]
- **Linter:** [e.g., eslint, pylint, checkstyle]
- **Formatter:** [e.g., prettier, black, google-java-format]
- **Line Length:** [e.g., 80, 100, 120 characters]
- **Indentation:** [e.g., 2 spaces, 4 spaces, tabs]

### Naming Conventions
- **Files:** [e.g., kebab-case, camelCase, PascalCase]
- **Variables:** [e.g., camelCase, snake_case]
- **Constants:** [e.g., UPPER_SNAKE_CASE, SCREAMING_SNAKE_CASE]
- **Classes:** [e.g., PascalCase]
- **Functions/Methods:** [e.g., camelCase, snake_case]

### Code Organization Patterns
```
Describe your preferred patterns:
- Functional vs Object-Oriented
- Component structure
- File organization
- Import ordering
- Error handling patterns
```

## Testing Requirements

### Test Framework
- **Unit Tests:** [e.g., Jest, pytest, JUnit]
- **Integration Tests:** [e.g., Supertest, pytest, TestContainers]
- **E2E Tests:** [e.g., Playwright, Cypress, Selenium]

### Test Coverage
- **Target Coverage:** [e.g., 80%, 90%]
- **Required Coverage:** [List critical paths that must be tested]

### Test Patterns
```
Describe test organization:
- Test file naming: [e.g., *.test.js, *_test.py, *Test.java]
- Test structure: [e.g., Arrange-Act-Assert, Given-When-Then]
- Mock/Stub approach
- Fixture patterns
```

## Architecture Patterns

### Project Structure
```
Brief description of your directory structure:
src/
  components/     - Reusable UI components
  services/       - Business logic
  utils/          - Utility functions
  types/          - TypeScript types/interfaces
tests/
  unit/           - Unit tests
  integration/    - Integration tests
```

### Design Patterns
List preferred patterns:
- [e.g., Repository pattern for data access]
- [e.g., Factory pattern for object creation]
- [e.g., Observer pattern for events]
- [e.g., Dependency injection]

### State Management
- **Pattern:** [e.g., Redux, Context API, Vuex, MobX]
- **Guidelines:** [Key principles for state management in this project]

## Dependencies and External Services

### Core Dependencies
```
List key dependencies and their purpose:
- [dependency-name] - [purpose and version constraints]
```

### External Services
```
List integrated services:
- [service-name] - [what it's used for]
- [API endpoints or documentation links]
```

### Adding New Dependencies
```
Guidelines for adding dependencies:
- Check for existing similar dependencies
- Prefer well-maintained libraries
- Consider bundle size impact
- Document reason for addition
```

## API and Interface Contracts

### API Design
- **REST/GraphQL/gRPC:** [Specify which]
- **Versioning:** [How APIs are versioned]
- **Authentication:** [OAuth, JWT, API keys, etc.]
- **Error Handling:** [Standard error response format]

### Data Models
```
Key data models and validation rules:
- User: [fields and constraints]
- [Other key models]
```

## Security Guidelines

### Authentication & Authorization
```
Describe approach:
- How users are authenticated
- How permissions are checked
- Session management
```

### Input Validation
```
Requirements:
- Always validate user input
- Sanitize before database queries
- Use parameterized queries
- Escape output for display
```

### Secrets Management
- **Never commit:** API keys, passwords, certificates
- **Use:** Environment variables or secret management service
- **Location:** `.env` files (gitignored), secret manager

### Known Security Patterns
```
List security patterns to follow:
- CSRF protection
- XSS prevention
- SQL injection prevention
- Rate limiting
```

## Performance Considerations

### Requirements
- **Response Time:** [e.g., < 200ms for API calls]
- **Bundle Size:** [e.g., < 500KB initial load]
- **Database Queries:** [e.g., optimize N+1 queries]

### Optimization Strategies
```
Preferred approaches:
- Caching strategy
- Lazy loading
- Code splitting
- Database indexing
```

## Documentation

### Code Documentation
- **Comments:** [When to comment and how]
- **JSDoc/Docstrings:** [Required for public APIs]
- **README:** [Update when adding major features]

### API Documentation
- **Tool:** [e.g., Swagger, OpenAPI, JSDoc]
- **Location:** [Where docs are generated/stored]

## Git Workflow

### Branch Naming
- **Feature:** `feature/description`
- **Bugfix:** `bugfix/description`
- **Hotfix:** `hotfix/description`

### Commit Messages
```
Format: [type]: [subject]

Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation
- style: Formatting
- refactor: Code restructuring
- test: Adding tests
- chore: Maintenance

Example: "feat: add user authentication with JWT"
```

### Pull Request Guidelines
```
Requirements:
- Descriptive title and description
- Link to issue/ticket
- Tests added/updated
- Documentation updated
- All checks passing
```

## Common Gotchas

### Known Issues
```
Document known issues or limitations:
1. [Issue description and workaround]
2. [Issue description and workaround]
```

### Environment-Specific Notes
```
Development:
- [Special considerations]

Staging:
- [Special considerations]

Production:
- [Special considerations]
```

## File Locations

### Key Files
```
Important files to be aware of:
- Configuration: [config files]
- Environment: [.env.example]
- Documentation: [docs/]
- Tests: [tests/ or __tests__/]
```

### Generated Files (Don't Modify)
```
Files that are auto-generated:
- [list generated files]
- [build artifacts]
```

## Local Development

### Setup
```bash
# Clone and setup
git clone [repo-url]
cd [project-name]

# Install dependencies
[installation command]

# Setup environment
cp .env.example .env
# Edit .env with your values

# Run development server
[dev command]
```

### Useful Commands
```bash
# Run tests
[test command]

# Lint
[lint command]

# Format
[format command]

# Build
[build command]
```

## Working with Claude Code

### Context Optimization
- **Include:** Files you're actively modifying, related tests, key interfaces
- **Exclude:** See `.claudeignore` for excluded files
- **Focus:** Keep workspace focused on current task

### Effective Prompts
```
When requesting changes, include:
1. Clear description of what you want
2. Reference to existing patterns (link to example file)
3. Any constraints or requirements
4. Test requirements

Example:
"Add pagination to the user list API endpoint. Follow the pattern in 
src/api/posts.ts for pagination. Return max 50 items per page. Include 
tests following the pattern in tests/api/posts.test.ts."
```

### Code Review Requests
```
For reviews, be specific:
"Review this code for:
- Security issues, especially [specific concern]
- Performance with [expected load]
- Compliance with [specific standard]
- Edge cases around [specific scenario]"
```

## Questions?

If you're unsure about:
- **Code style:** Check existing similar files for patterns
- **Architecture:** Refer to docs/architecture.md (if exists)
- **Testing:** Follow patterns in existing test files
- **APIs:** Check docs/api.md or OpenAPI spec (if exists)

## Updating This File

This file should be updated when:
- New conventions are adopted
- Architecture changes
- New dependencies/services added
- Common patterns evolve

---

**Note:** This is a template. Remove this line and customize for your project.
