Customization

your-project/
├── CLAUDE.md                    # Main project context
└── .claude/
    ├── settings.json            # Permissions (shared with team)
    ├── settings.local.json      # Personal settings (gitignored)
    ├── rules/                   # Coding standards
    │   ├── code-style.md
    │   ├── components.md
    │   └── ...
    └── commands/                # Custom slash commands
        ├── new-feature.md
        ├── new-page.md
        └── ...

# My SaaS App

## Commands
- `pnpm dev` - Start development server
- `pnpm test` - Run tests (add this if you set up testing)
- `pnpm storybook` - Component playground (if you add Storybook)

## Architecture
[Update as you add new directories and patterns]

## Conventions
[Add your team's specific conventions]

## Domain Knowledge
[Add business logic explanations Claude should know]

## Domain Knowledge

### User Roles
- `owner` - Full access, can delete team
- `admin` - Can manage members, billing
- `member` - Can view and edit content
- `viewer` - Read-only access

### Subscription Tiers
- Free: 1 project, 100MB storage
- Starter: 5 projects, 1GB storage
- Pro: Unlimited projects, 10GB storage

### Key Business Rules
- Users can only belong to one team at a time
- Projects are soft-deleted (30-day retention)
- File uploads limited by plan storage quota

<!-- .claude/commands/test.md -->

Run the test suite for this project.

Steps:
1. Run `pnpm test` to execute all tests
2. If tests fail, analyze the error output
3. Suggest fixes for failing tests
4. Re-run tests after fixes

Focus on:
- Unit tests in `__tests__/` directories
- Integration tests in `tests/`
- Check test coverage if available

> /test

<!-- .claude/commands/review.md -->

Review the recent changes for code quality and potential issues.

Check for:
1. TypeScript errors or `any` usage
2. Missing error handling
3. Security issues (SQL injection, XSS)
4. Performance concerns (N+1 queries, unnecessary re-renders)
5. Missing validation on API inputs
6. Proper authentication checks
7. Consistent naming and code style

Provide actionable feedback with specific line numbers.

<!-- .claude/commands/document.md -->

Generate or update documentation for the specified code.

Ask me:
1. What file or function should be documented?
2. Is this for API docs, inline comments, or README?

Then:
- Add JSDoc comments for functions
- Update README if needed
- Add usage examples
- Document parameters and return types

<!-- .claude/rules/testing.md -->

# Testing

## Test File Location
- Unit tests: `__tests__/[filename].test.ts`
- Integration tests: `tests/[feature].test.ts`
- E2E tests: `e2e/[flow].spec.ts`

## Test Structure
\`\`\`typescript
describe("FeatureName", () => {
  beforeEach(() => {
    // Setup
  });

  it("should do something specific", () => {
    // Arrange
    // Act
    // Assert
  });
});
\`\`\`

## Mocking
- Use `vi.mock()` for module mocks
- Use `vi.spyOn()` for function spies
- Mock external services (Stripe, Resend) in tests

<!-- .claude/rules/team-conventions.md -->

# Team Conventions

## PR Guidelines
- Branch names: `feature/description` or `fix/description`
- Commit messages: Start with verb (Add, Fix, Update, Remove)

## Code Review
- All PRs need 1 approval
- No direct commits to main

## Environment
- Development: localhost:3000
- Staging: staging.ourapp.com
- Production: ourapp.com

{
  "permissions": {
    "allow": [
      "Bash(pnpm dev)",
      "Bash(pnpm build)",
      "Bash(pnpm lint)",
      "Bash(pnpm test)",
      "Bash(pnpm db:*)",
      "Bash(pnpm email)",
      "Bash(git status)",
      "Bash(git diff)"
    ],
    "deny": [
      "Read(**/.env*)",
      "Read(**/node_modules/**)",
      "Read(**/*.pem)",
      "Read(**/*secret*)"
    ]
  }
}

{
  "permissions": {
    "allow": [
      "Bash(git commit -m *)",
      "Bash(git push)"
    ]
  }
}

## Recent Changes
- Added team management feature (see db/team.ts, app/api/teams/)
- Switched from REST to tRPC for type-safe APIs
- Added Playwright for E2E testing

.claude/rules/
├── code-style.md      # General TypeScript/React
├── database.md        # Drizzle ORM patterns
├── api.md             # Route handlers
├── auth.md            # Authentication
├── stripe.md          # Payments
├── testing.md         # Test patterns (your addition)
└── team.md            # Team-specific conventions

<!-- Good: Clear steps and expectations -->
Create a new API endpoint.

Ask me:
1. Endpoint path (e.g., /api/projects)
2. HTTP methods needed
3. Authentication requirements

Then create the route handler with:
- Zod validation for request body
- Proper auth checks
- Error handling
- TypeScript types

<!-- Less good: Vague instructions -->
Make an API route.

# Commit shared configuration
git add CLAUDE.md .claude/settings.json .claude/rules/ .claude/commands/
git commit -m "Update Claude Code configuration"