The CLAUDE.md Vault

# Project Instructions
 
## Stack
- Next.js 15 with App Router, TypeScript strict mode
- Tailwind CSS v4 (config in globals.css, not tailwind.config.js)
- PostgreSQL with Drizzle ORM
- pnpm as package manager
 
## Build and Test
- Build: pnpm build (must pass zero errors before committing)
- Test: pnpm vitest run (prefer single test files, not full suite)
- Lint: pnpm lint
- Typecheck: pnpm tsc --noEmit
 
## Code Style
- Server components by default. Only add "use client" for interactivity.
- Use ES modules (import/export), never require()
- 2-space indentation, single quotes, trailing commas
- Prefer early returns over nested if/else
- Name booleans with is/has/should prefix (isLoading, hasError)
 
## Git
- Conventional commits: feat:, fix:, chore:, docs:
- Never push directly to main
- Run typecheck before committing
 
## Gotchas
- Tailwind v4 has no config file. All theme config is in app/globals.css.
- Environment variables need NEXT_PUBLIC_ prefix for client-side access.

# Project Instructions
 
## Stack
- Python 3.12+ with type hints everywhere
- Click for CLI framework
- pyproject.toml for project config (no setup.py)
- uv for package management
 
## Build and Test
- Install: uv sync
- Test: uv run pytest tests/ -x (stop on first failure)
- Single test: uv run pytest tests/test_foo.py::test_bar -v
- Lint: uv run ruff check . --fix
- Format: uv run ruff format .
- Typecheck: uv run mypy src/
 
## Code Style
- Use pathlib for all file paths, never os.path
- Prefer dataclasses over plain dicts for structured data
- Use logging module, never print() for status output
- All public functions need docstrings (Google style)
- Type hints on all function signatures
 
## Project Layout
- Source code in src/mytool/
- Tests mirror source structure in tests/
- CLI entry point is src/mytool/cli.py
 
## Gotchas
- Tests require TEST_API_KEY env var. Use .env.test for local runs.
- The config parser expects YAML, not JSON. Check conftest.py for fixtures.

# Project Instructions
 
## Stack
- Go 1.22, standard library preferred over third-party deps
- Chi for HTTP routing
- sqlc for database queries (do not write raw SQL strings)
- Docker for local development
 
## Build and Test
- Build: go build ./cmd/api
- Test: go test ./... -race -count=1
- Single package: go test ./internal/auth/ -v -run TestName
- Lint: golangci-lint run
- Generate: go generate ./...
 
## Code Style
- Follow standard Go conventions (gofmt, govet)
- Errors: return errors, do not panic. Wrap with fmt.Errorf("doing X: %w", err)
- Context: pass ctx as first parameter to all functions that do IO
- Naming: use MixedCaps, not underscores. Acronyms stay uppercase (HTTP, ID, URL).
- Tests: table-driven tests preferred. Use t.Helper() in test helpers.
 
## API Conventions
- All endpoints return JSON with {"data": ...} or {"error": ...} envelope
- Use middleware for auth, logging, request ID injection
- Health check endpoint: GET /healthz
 
## Gotchas
- Run go generate before building. sqlc models are generated code.
- Docker compose mounts vendor/ directory. Run go mod vendor after adding deps.

# Project Instructions (Root)
 
## Stack
- Turborepo monorepo with pnpm workspaces
- Packages: apps/web, apps/api, packages/ui, packages/shared
 
## Build and Test
- Build all: pnpm build
- Build one: pnpm --filter @myorg/web build
- Test all: pnpm test
- Test one: pnpm --filter @myorg/api test
 
## Workspace Rules
- Shared types go in packages/shared, never duplicated across apps
- UI components go in packages/ui with Storybook stories
- Each package has its own tsconfig.json extending the root
- Cross-package imports use workspace protocol: "@myorg/shared"
 
## Git
- PRs must pass CI for all affected workspaces
- Changesets required for packages/ui and packages/shared changes
- Branch naming: feat/ticket-123-description, fix/ticket-456-description