# Using the .CLAUDE Template for Your Projects

## What is a .CLAUDE File?

A `.CLAUDE` file is a project-specific configuration file that provides context and guidelines for Claude Code when working on your repository. Think of it as a "README for Claude" - it helps the AI understand your project's conventions, patterns, and requirements.

## Why Use It?

### Benefits

1. **Consistency**: Ensures Claude generates code that matches your style and patterns
2. **Context**: Provides project-specific context without repeating it in every prompt
3. **Efficiency**: Reduces back-and-forth by establishing conventions upfront
4. **Onboarding**: Helps new developers (and AI) understand project standards
5. **Quality**: Improves generated code quality by setting clear expectations

### When to Use

- Multi-developer projects with established conventions
- Projects with specific architectural patterns
- Organizations with coding standards
- Open source projects with contribution guidelines
- Any project where consistency matters

## How to Set It Up

### 1. Copy the Template

```bash
# From this repository
cp templates/.CLAUDE-template /path/to/your/project/.CLAUDE

# Or create manually in your project root
touch .CLAUDE
```

### 2. Customize for Your Project

Work through each section and fill in your project's specifics:

**Essential Sections to Complete:**
- [ ] Project Overview (name, description, tech stack)
- [ ] Code Style and Conventions
- [ ] Testing Requirements
- [ ] Architecture Patterns
- [ ] Git Workflow

**Important Sections:**
- [ ] Security Guidelines
- [ ] API and Interface Contracts
- [ ] Common Gotchas
- [ ] Local Development Setup

**Optional but Helpful:**
- [ ] Performance Considerations
- [ ] Dependencies and External Services
- [ ] Documentation standards

### 3. Add to Version Control

```bash
git add .CLAUDE
git commit -m "Add .CLAUDE configuration for AI-assisted development"
git push
```

### 4. Keep It Updated

Update `.CLAUDE` when:
- Coding conventions change
- New patterns are adopted
- Architecture evolves
- Dependencies are added/removed
- Common issues are discovered

## Example: Filled Template

Here's an example for a Next.js project:

```markdown
# .CLAUDE

## Project Overview

**Project Name:** Acme Dashboard
**Description:** Internal analytics dashboard for tracking KPIs
**Tech Stack:** Next.js 14, TypeScript, React, TailwindCSS, Prisma, PostgreSQL

## Code Style and Conventions

### Language/Framework Specifics
- **Language Version:** TypeScript 5.x, Node 20.x
- **Package Manager:** pnpm
- **Build Tool:** Next.js built-in

### Coding Standards
- **Style Guide:** Airbnb TypeScript
- **Linter:** ESLint with our custom config
- **Formatter:** Prettier
- **Line Length:** 100 characters
- **Indentation:** 2 spaces

### Naming Conventions
- **Files:** kebab-case (e.g., user-profile.tsx)
- **Components:** PascalCase (e.g., UserProfile)
- **Variables:** camelCase (e.g., userId)
- **Constants:** UPPER_SNAKE_CASE (e.g., MAX_RETRIES)

### Code Organization Patterns
- Functional React components with hooks
- Server components by default, use 'use client' only when needed
- API routes in app/api/
- Shared utilities in lib/
- Keep components small (<200 lines)

## Testing Requirements

### Test Framework
- **Unit Tests:** Vitest
- **Component Tests:** React Testing Library
- **E2E Tests:** Playwright

### Test Coverage
- **Target Coverage:** 80% for business logic
- **Required Coverage:** All API routes, critical user flows

### Test Patterns
- Test files: *.test.ts or *.test.tsx
- Co-locate tests with source files
- Use describe/it structure
- Mock external services
```

## Using .CLAUDE with Claude Code

### How Claude Code Uses It

When you work in Claude Code, it:
1. Reads the `.CLAUDE` file automatically (if present)
2. Uses it as context for understanding your project
3. Applies conventions when generating code
4. References it when you ask questions

### Prompting with .CLAUDE

**Without .CLAUDE:**
```
"Create a React component for user profile. Use TypeScript, functional 
components with hooks, TailwindCSS for styling, camelCase for variables,
PascalCase for component name, 2-space indentation, Prettier formatting,
include PropTypes, add error handling, and write tests using Jest."
```

**With .CLAUDE:**
```
"Create a React component for user profile"
```

Claude will reference the `.CLAUDE` file for all the conventions!

### Best Practices

**DO:**
- ✅ Reference .CLAUDE in your prompts: "Following our .CLAUDE conventions..."
- ✅ Keep it updated as patterns evolve
- ✅ Be specific in sections that matter most
- ✅ Include examples of preferred patterns
- ✅ Document common gotchas

**DON'T:**
- ❌ Make it too verbose (Claude has token limits)
- ❌ Include information that changes frequently
- ❌ Duplicate information from other docs
- ❌ Leave template sections unfilled (remove instead)
- ❌ Include sensitive information (API keys, etc.)

## For GitHub Organizations

### Organization-Wide Template

Create a `.CLAUDE` template in a shared repository:

```
organization-templates/
  .CLAUDE-nextjs
  .CLAUDE-python-api
  .CLAUDE-react-library
  README.md
```

### Setup Script

Create a script to copy the appropriate template:

```bash
#!/bin/bash
# setup-claude.sh

echo "Select project type:"
echo "1) Next.js application"
echo "2) Python API"
echo "3) React library"
read -p "Choice: " choice

case $choice in
  1) cp ../templates/.CLAUDE-nextjs .CLAUDE ;;
  2) cp ../templates/.CLAUDE-python-api .CLAUDE ;;
  3) cp ../templates/.CLAUDE-react-library .CLAUDE ;;
esac

echo ".CLAUDE file created. Please customize it for your project."
```

### Repository Template

For GitHub repository templates:

1. Include `.CLAUDE` in the template repository
2. Add setup instructions in template's README
3. Mark sections that need customization with `[CUSTOMIZE]`

## Integration with Existing Tools

### With .gitignore

`.CLAUDE` should complement, not replace `.gitignore`:
- `.gitignore` - What Git ignores
- `.claudeignore` - What Claude Code ignores
- `.CLAUDE` - How Claude should work

### With README

Keep them focused:
- `README.md` - For humans (setup, usage, contribution)
- `.CLAUDE` - For AI (conventions, patterns, context)

Some overlap is okay, but README is more comprehensive.

### With CONTRIBUTING.md

For open source:
- `CONTRIBUTING.md` - Process for contributing (PR, issues, etc.)
- `.CLAUDE` - Technical standards and patterns

Reference `.CLAUDE` from `CONTRIBUTING.md`:
```markdown
## Code Standards

We use a `.CLAUDE` file to document our coding standards and conventions.
Please review it before contributing. Claude Code users will have these
standards automatically applied.
```

## Maintenance

### Regular Review

Schedule reviews:
- **Monthly:** Quick check for accuracy
- **Quarterly:** Thorough review and updates
- **After major changes:** Architecture, tech stack, patterns

### Changelog

Track changes at the bottom:

```markdown
## .CLAUDE Changelog

### 2024-12-01
- Updated TypeScript to 5.x
- Added Vitest as test framework
- Removed deprecated Redux patterns

### 2024-10-15
- Initial .CLAUDE file created
```

### Team Collaboration

Make it collaborative:
- Include in code review checklist
- Discuss changes in team meetings
- Accept suggestions from team members
- Document reasons for conventions

## Troubleshooting

### Claude Ignores .CLAUDE

**Possible causes:**
- File not in project root
- File name incorrect (must be exactly `.CLAUDE`)
- File too large (keep under 10KB)
- Conflicting instructions in prompt

**Solutions:**
- Verify file location and name
- Simplify if too large
- Reference explicitly: "Following the .CLAUDE file..."

### Conflicting Patterns

**Issue:** Generated code doesn't match .CLAUDE

**Solutions:**
- Make .CLAUDE more specific
- Provide example code snippets
- Reference .CLAUDE in prompt explicitly
- Check for contradictions within .CLAUDE

### Keeping in Sync

**Issue:** .CLAUDE outdated

**Solutions:**
- Add .CLAUDE review to PR template
- Assign a maintainer
- Include in documentation updates
- Use git hooks to remind

## Examples from Real Projects

### Minimal .CLAUDE (Startup MVP)

```markdown
# .CLAUDE

**Stack:** Next.js 14, TypeScript, Supabase, TailwindCSS

**Key Conventions:**
- Functional components, TypeScript strict mode
- TailwindCSS for all styling
- API routes in app/api/
- Supabase for auth and data

**Must follow:**
- All functions must have type signatures
- Use server components by default
- Error boundaries for all pages
```

### Comprehensive .CLAUDE (Enterprise)

```markdown
# .CLAUDE

[Full template filled out with detailed conventions,
security guidelines, testing requirements, architecture
patterns, deployment procedures, etc.]

**Total:** ~5-7KB of detailed specifications
```

### Open Source .CLAUDE

```markdown
# .CLAUDE

[Standard conventions plus...]

**Contribution Specific:**
- Follow Conventional Commits
- Tests required for all features
- Documentation required for public APIs
- Breaking changes need RFC discussion

**Code Review Focus:**
- Backward compatibility
- Performance impact
- Security implications
- API design
```

## Resources

- [Claude Code Best Practices](../docs/claude-code-best-practices.md)
- [.claudeignore Guide](../docs/claude-code-best-practices.md#claudeignore-file)
- [Template](./.CLAUDE-template)

## Summary

A `.CLAUDE` file is a simple but powerful way to improve AI-assisted development by:
1. Establishing clear conventions
2. Providing project context
3. Ensuring consistency
4. Reducing repetitive prompting

Start simple, iterate, and keep it updated. Your future self (and team) will thank you!
