Playbook

# Build & Test
- Run `npm test -- --run` for unit tests (not the full suite)
- TypeCheck with `npx tsc --noEmit` after code changes
- This project uses pnpm, not npm

# Guidelines
- Write clean, maintainable code
- Follow best practices
- Be careful with edge cases

# Personal Preferences
- I prefer concise explanations over verbose ones
- When committing, use conventional commit format
- I use vim keybindings -- reference vim commands when suggesting editor actions
- Default to TypeScript strict mode

# Project: MyApp API
 
## Build & Test
- `pnpm install` to set up dependencies
- `pnpm test` runs vitest (prefer single test files for speed)
- `pnpm typecheck` runs tsc --noEmit
 
## Architecture
- Express API in src/api/, React frontend in src/web/
- Database: PostgreSQL with Drizzle ORM
- All API routes require auth middleware (see src/middleware/auth.ts)
 
## Conventions
- Use barrel exports (index.ts) for each module directory
- Error responses follow RFC 7807 Problem Details format
- Date fields use ISO 8601 strings, never timestamps

# My Local Setup
- My dev database is at localhost:5433 (non-standard port)
- Use SANDBOX_API_KEY=sk-test-xxx for local testing
- I'm currently working on the billing module refactor

# API Package
- This package uses Express 5 (not Express 4 like the legacy service)
- All handlers must return typed Response<T> objects
- Integration tests require REDIS_URL environment variable

monorepo/
├── CLAUDE.md                    # Global: workspace structure, shared conventions
├── CLAUDE.local.md              # Personal: your active focus area
├── .claude/
│   ├── settings.json            # Hooks, permissions
│   └── rules/
│       ├── code-style.md        # Unconditional: loaded every session
│       ├── testing.md           # Unconditional: testing conventions
│       └── api-design.md        # Path-scoped: only for src/api/**
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md            # Frontend-specific (lazy loaded)
│   ├── api/
│   │   └── CLAUDE.md            # API-specific (lazy loaded)
│   └── shared/
│       └── CLAUDE.md            # Shared library rules (lazy loaded)

{
  "claudeMdExcludes": [
    "**/packages/ios-app/CLAUDE.md",
    "**/packages/legacy-service/.claude/rules/**"
  ]
}

app/
├── CLAUDE.md                    # Shared: build commands, deploy process, env vars
├── .claude/
│   └── rules/
│       ├── frontend.md          # paths: ["src/components/**", "src/pages/**"]
│       ├── backend.md           # paths: ["src/api/**", "src/services/**"]
│       └── database.md          # paths: ["src/db/**", "migrations/**"]

---
paths:
  - "src/components/**"
  - "src/pages/**"
  - "src/hooks/**"
---
 
# Frontend Rules
- Use React Server Components by default; add 'use client' only when needed
- All components export via named exports (no default exports)
- CSS modules for component-scoped styles, Tailwind for layout utilities
- Test components with @testing-library/react, not enzyme

---
paths:
  - "src/db/**"
  - "migrations/**"
  - "prisma/**"
---
 
# Database Rules
- All migrations must be reversible (include both up and down)
- Use parameterized queries exclusively — no string interpolation in SQL
- Foreign keys require explicit ON DELETE behavior

my-library/
├── CLAUDE.md                    # API design principles, semver policy, test requirements
├── .claude/
│   └── rules/
│       └── public-api.md        # paths: ["src/index.ts", "src/public/**"]

# my-library
 
## Build & Test
- `pnpm build` compiles to ESM + CJS via tsup
- `pnpm test` runs vitest (run single files for speed)
- `pnpm typecheck` runs tsc --noEmit
 
## Semver Policy
- Breaking changes require a major version bump and CHANGELOG entry
- All public API changes must update JSDoc annotations
 
IMPORTANT: Exported types in src/public/ are part of the public API.
Changing function signatures, removing exports, or renaming types is a breaking change.

See @README.md for project overview and @package.json for available scripts.
 
# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

{
  "allowedImportPaths": [
    "docs/git-instructions.md",
    "~/.claude/shared-instructions.md"
  ]
}

# Architecture docs are in docs/architecture.md -- read when working on structural changes.

# CLAUDE.md
@AGENTS.md
 
## Claude Code Specific
Use plan mode for changes under `src/billing/`.

# .claude/rules/code-style.md (no paths: frontmatter = unconditional)
 
- Use named exports for all modules
- Prefer `interface` over `type` for object shapes
- Error messages must include the operation that failed and the reason

---
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
  - "**/*.spec.ts"
---
 
# Testing Conventions
- Use `describe` blocks grouped by method/feature
- Prefer `it.each` for parameterized tests
- Mock external services at the module boundary, not inside tests
- Test file must be co-located with the module it tests

# Project Name
 
## Build & Test
- `<install command>` for dependencies
- `<test command>` for unit tests (prefer single file runs)
- `<typecheck command>` for type checking
 
## Architecture
- [2-3 lines: where code lives, what framework, key patterns]
 
## Conventions
- [3-5 lines: things Claude would get wrong without being told]
 
IMPORTANT: [The one rule that causes the most damage when violated]