CLAUDE.md 完全指南：让 AI 每次都精准理解你的项目

# E-commerce API

## Stack
- Node.js 22 + Express + TypeScript
- PostgreSQL + Prisma ORM
- Redis for caching

## Commands
- Dev: pnpm dev
- Test: pnpm test
- Lint: pnpm lint
- Build: pnpm build

## Rules
- Use functional style. No classes except Prisma models.
- All API endpoints must have input validation with Zod.
- Never use console.log in production code. Use the logger utility.
- Commit message format: type: description (e.g., feat: add user auth)

# About Me

I'm Alex, a full-stack engineer working primarily with TypeScript and Python.

## Universal Preferences

- Write commit messages in conventional commit format
- Prefer functional programming patterns over OOP
- Keep functions under 40 lines — split if longer
- Use descriptive variable names, never single letters
- When unsure between two approaches, pick the simpler one

# SaaS Dashboard

## Stack
- Next.js 15 (App Router) + TypeScript 5.7
- Tailwind CSS + shadcn/ui
- Zustand for state management
- Prisma + PostgreSQL

## Project Structure
```
src/
├── app/          # Next.js App Router pages
├── components/   # Reusable components
│   ├── ui/       # Base UI components (shadcn)
│   └── features/ # Business logic components
├── lib/          # Utilities and config
├── hooks/        # Custom React hooks
├── stores/       # Zustand stores
├── types/        # TypeScript type definitions
└── services/     # API client layer
```

## Commands
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm vitest
- Lint: pnpm lint

## Coding Standards
- File names: kebab-case (e.g., user-profile.tsx)
- Component names: PascalCase (e.g., UserProfile)
- Functions/variables: camelCase (e.g., getUserById)
- Constants: UPPER_SNAKE_CASE (e.g., MAX_RETRY_COUNT)
- All components must be functional with hooks
- Props must have TypeScript interfaces

## Git Rules
- Commit format: type: description
- Types: feat / fix / refactor / docs / test / chore
- Always run pnpm lint before committing

# Personal Overrides

- I'm working on the payment module this sprint — prioritize that context
- My local PostgreSQL runs on port 5433 (not the default 5432)
- When writing tests, add verbose comments — I'm learning the testing patterns
- Draft comments in English first, I'll review before committing

全局 (~/.claude/CLAUDE.md)
  → 项目 (./CLAUDE.md)
    → 个人 (./CLAUDE.local.md)

/init

# Always handle loading and error states in API calls

# Project Config

@docs/architecture.md
@docs/api-conventions.md
@docs/testing-guide.md
@AGENTS.md

# Developer Profile

I'm [Your Name], a [your role] working with [primary languages].

## Coding Preferences

- Prefer functional programming over OOP
- Variable names must be descriptive — no a, b, temp
- Keep functions under 40 lines
- Code should be self-documenting; minimize comments
- When adding comments, make them explain "why", not "what"

## Workflow

- Run lint before every commit
- Commit frequently in small increments
- No TypeScript errors allowed before committing
- Write tests for any non-trivial business logic

## Things I Dislike

- Over-engineering and unnecessary abstractions
- Design patterns used for the sake of patterns
- Deeply nested callbacks or promises (use async/await)
- Magic numbers — extract to named constants

# [Project Name]

[One-line description of what this project does]

## Stack

- Framework: Next.js 15 (App Router)
- Language: TypeScript 5.7 (strict mode)
- Styling: Tailwind CSS + shadcn/ui
- State: Zustand
- Database: PostgreSQL + Prisma
- Testing: Vitest + Testing Library
- Package manager: pnpm

## Directory Structure

```
src/
├── app/          # Pages and layouts (App Router)
├── components/   # Reusable UI components
├── lib/          # Utilities, helpers, config
├── hooks/        # Custom React hooks
├── stores/       # Zustand state stores
├── types/        # Shared TypeScript types
└── services/     # API client functions
```

## Commands

```bash
pnpm dev          # Start dev server
pnpm build        # Production build
pnpm test         # Run tests
pnpm lint         # Lint check
pnpm db:push      # Push schema to database
pnpm db:migrate   # Run database migrations
```

## Coding Rules

- Use functional components with hooks. No class components.
- Props must have TypeScript interfaces, named [Component]Props.
- File names: kebab-case. Component names: PascalCase.
- All API calls must handle loading and error states.
- No `any` type. Use `unknown` if the type is truly unknowable.
- Sensitive values in .env.local only. Never commit secrets.

## Git Conventions

- Commit format: `type: short description`
- Types: feat | fix | refactor | docs | test | chore
- Branch naming: feature/description or fix/description
- Always run `pnpm lint` before committing
- New features require unit tests

## Important Notes

- This is a multi-tenant SaaS app. All database queries MUST filter by tenantId.
- Never import from `node_modules` directly — use the re-exports in `lib/`.
- Rate limiting is handled by middleware. Do not add rate limiting in individual routes.

# [Project Name]

[One-line description]

## Stack

- Python 3.12 + FastAPI
- SQLAlchemy 2.0 + Alembic for migrations
- PostgreSQL 16
- Redis for caching and task queue
- Celery for background tasks
- Poetry for dependency management

## Project Structure

```
src/
├── api/           # FastAPI route handlers
│   └── v1/        # Versioned endpoints
├── core/          # App config, security, dependencies
├── models/        # SQLAlchemy models
├── schemas/       # Pydantic request/response schemas
├── services/      # Business logic layer
├── tasks/         # Celery background tasks
└── utils/         # Helper functions
tests/
├── unit/          # Unit tests
├── integration/   # Integration tests
└── conftest.py    # Shared fixtures
```

## Commands

```bash
poetry install              # Install dependencies
poetry run uvicorn src.main:app --reload  # Dev server
poetry run pytest           # Run all tests
poetry run pytest -x -v     # Run tests, stop on first failure
poetry run alembic upgrade head  # Apply migrations
poetry run black .          # Format code
poetry run ruff check .     # Lint
```

## Coding Rules

- Follow PEP 8. Use Black for formatting (line length 88).
- All functions must have type hints.
- Docstrings use Google style.
- Use Pydantic for all request/response validation.
- Service layer handles business logic. Routes are thin — validate, call service, return response.
- All database operations go through the repository pattern in services/.

## Testing Rules

- Every endpoint needs at least one happy-path and one error-path test.
- Use pytest fixtures for database setup/teardown.
- Mock external API calls. Never make real HTTP requests in tests.

| Layer | Technology | Version |
|-------|-----------|---------|
| Frontend | React + TypeScript | 19.x / 5.7 |
| Backend | FastAPI + SQLAlchemy | 0.115 / 2.0 |
| Database | PostgreSQL | 16 |
| Cache | Redis | 7.x |

- Frontend: React 19 + TypeScript 5.7 + Vite 6
- Backend: FastAPI 0.115 + SQLAlchemy 2.0 + PostgreSQL 16 + Redis 7

See @AGENTS.md

# 所有内容写在 AGENTS.md，为 Claude Code 创建符号链接
ln -s AGENTS.md CLAUDE.md

# Claude-Specific Config

See @AGENTS.md

## Claude-Only Rules
- Use /compact when context gets long
- Prefer Sonnet for routine tasks, switch to Opus for architecture decisions
- When writing Skills, follow the pattern in .claude/skills/

# Project Config

## Architecture
@docs/architecture.md

## API Conventions
@docs/api-conventions.md

## Testing Guide
@docs/testing-guide.md

- IMPORTANT: All database queries MUST filter by tenantId. No exceptions.
- NEVER commit .env files or API keys to Git.
- YOU MUST run the test suite before creating any pull request.

my-monorepo/
├── CLAUDE.md              # 共享规则（Git 规范、CI）
├── frontend/
│   ├── CLAUDE.md          # React/TypeScript 规则
│   └── src/
├── backend/
│   ├── CLAUDE.md          # Python/FastAPI 规则
│   └── src/
└── infra/
    ├── CLAUDE.md          # Terraform/AWS 规则
    └── modules/

## Code Review Standards
- All new code must have unit tests
- No console.log in production code
- No hardcoded configuration values
- Functions must have JSDoc comments

---
name: code-review
description: Review code changes against project standards
---

# Code Review Skill

1. Read git diff for staged changes
2. Check each file against the Code Review Standards in CLAUDE.md
3. List violations with file, line, and suggested fix
4. Summarize: total issues found, severity breakdown

## Automated Checks
- Pre-commit hooks run ESLint and Prettier automatically
- Post-save hooks run the test suite for changed files
- See .claude/settings.json for hook configuration