CLAUDE.md

# 示例：在 foo/bar/ 中运行 Claude Code
加载顺序：
1. ~/.claude/CLAUDE.md          (用户全局)
2. foo/CLAUDE.md                (祖先)
3. foo/CLAUDE.local.md          (祖先本地覆盖)
4. foo/bar/CLAUDE.md            (当前目录)
5. foo/bar/CLAUDE.local.md      (当前目录本地覆盖)
# 子目录 foo/bar/baz/CLAUDE.md  仅在读取 baz/ 内文件时加载

// .claude/settings.local.json
{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

# Project: [项目名称]

[一两句话描述项目用途和技术栈]

## Tech Stack
- [框架] [版本], [语言] [版本]
- [数据库] via [ORM]
- [测试框架]

## Directory Structure
- `src/app/` — 页面和路由
- `src/lib/` — 共享工具和服务
- `src/components/` — React 组件

## Essential Commands
- `npm run dev` — 启动开发服务器
- `npm run test` — 运行测试套件
- `npm run build` — 生产构建

## Conventions
- [Claude 默认不会遵循的惯例]
- [Claude 默认不会遵循的惯例]

## Architecture Decisions
- [防止错误假设的关键决策]
- [防止错误假设的关键决策]

## Do Not
- [明确的禁止事项]
- [明确的禁止事项]

## Verification
After changes, always run:
1. `npm run lint`
2. `npm run test`
3. `npm run build`

# 差
- 格式化代码要规范
- 测试你的改动
- 保持文件组织

# 好
- 使用 2 空格缩进
- 提交前运行 `npm test`
- API handlers 放在 `src/api/handlers/`

- MUST run tests before committing
- MUST NOT modify migration files
- NEVER force push to main
- ALWAYS validate input with Zod

# 差
- 写测试

# 好
- 添加新 API endpoint 时，MUST 在 tests/api/ 中添加对应测试

cd your-project
claude
/init

# 每几周运行一次
Review my CLAUDE.md file. Identify any instructions that are redundant,
conflicting, or that you would follow correctly without being told.
Suggest what to remove.

# CLAUDE.md (根)

See @README.md for project overview.

## Commands
npm run test

## Detailed guides
- Architecture: @docs/architecture.md
- Database patterns: @docs/database-conventions.md

.claude/
├── CLAUDE.md           # 主项目指令
└── rules/
    ├── code-style.md   # 代码风格指南
    ├── testing.md      # 测试约定
    ├── api-design.md   # API 设计规则
    └── frontend/       # 子目录组织
        └── react-patterns.md

---
paths:
  - "src/api/**/*.ts"
  - "src/middleware/**/*.ts"
---

# API Development Rules

- All endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

my-monorepo/
├── CLAUDE.md              # 共享规则（lint、git、CI）
├── .claude/
│   └── rules/
│       ├── testing.md
│       └── security.md
└── packages/
    ├── web/
    │   ├── CLAUDE.md      # Next.js 专属约定
    │   └── src/
    ├── api/
    │   ├── CLAUDE.md      # Express/Fastify 专属约定
    │   └── src/
    └── shared/
        ├── CLAUDE.md      # 共享库约定
        └── src/

# Monorepo

pnpm workspaces monorepo. Packages in `packages/`.

## Commands
- `pnpm install` — install all dependencies
- `pnpm -r build` — build all packages
- `pnpm -r test` — test all packages

## Rules
- Changes to `packages/shared` require running tests in all consuming packages
- Use workspace protocol for internal dependencies
- Never install dependencies at the root unless they're dev tools

# .gitignore
CLAUDE.local.md
.claude/settings.local.json
.claude/memory/

# CLAUDE.md
@AGENTS.md

## Claude-specific additions
- Use the MCP server at localhost:3000 for database queries
- Run /compact after long refactoring sessions

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 主索引，每次会话加载
├── debugging.md       # 调试模式笔记
├── api-conventions.md # API 设计决策
└── ...                # Claude 创建的其他主题文件

# 在会话中
/memory

# 或设置
{
  "autoMemoryEnabled": false
}

# 或环境变量
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

> Remember that we always use pnpm and never npm

> Add this to CLAUDE.md: always use named exports

## Self-Improvement

When you encounter a bad assumption during a session, suggest a CLAUDE.md correction.

<!-- maintainer: 这条规则在 v3 迁移后需要更新 -->
- Use the new API client for all HTTP calls

# 维护一套共享规则
ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\""
      }
    ]
  }
}

# Project: invoice-api

FastAPI REST API for invoice management. Python 3.12, PostgreSQL 16.

## Commands
uv run pytest tests/ -x                    # run tests (stop on first failure)
uv run pytest tests/integration/ -x -k db  # integration tests (needs local PG)
uv run ruff check --fix .                  # lint and auto-fix
uv run mypy src/                           # type check

## Architecture
- src/api/       -> route handlers (one file per resource)
- src/models/    -> SQLAlchemy models (alembic for migrations)
- src/services/  -> business logic (handlers call services, never query DB directly)
- src/core/      -> config, security, dependencies

## Rules
- MUST run `uv run pytest tests/ -x` and confirm all pass before committing
- MUST NOT modify migration files -- generate new ones with `alembic revision --autogenerate`
- All endpoints require authentication except those in src/api/public.py
- Use `Annotated[T, Depends(...)]` for dependency injection, not default arguments

## Gotchas
- The `invoice_number` field is generated server-side. Never accept it from client input.
- PostgreSQL BIGINT IDs -- do not use `int` in Python models with upper bound check

# TaskFlow SaaS

Multi-tenant project management SaaS. Users: SMBs (5-200 employees).
Billing: per-seat subscription via Stripe. Data isolation: separate schema per tenant.

## Tech Stack
Frontend: Next.js 14 (App Router only), React 18, Tailwind CSS + shadcn/ui, Zustand
Backend: Next.js API Routes, Prisma ORM + PostgreSQL (Neon), NextAuth.js v5

## Architecture Rules
- All API routes MUST validate input with Zod schemas
- Always check tenant ownership before DB operations
- Use Server Actions for form mutations, not client-side fetch
- Data fetching happens in Server Components, never in useEffect

## Security Constraints
- Never expose tenant IDs in client-side code or URLs
- All user input must be sanitized before database insertion
- Secrets must use environment variables -- never hardcoded

## Coding Conventions
- TypeScript strict mode -- no `any` types allowed
- File names: kebab-case. Component names: PascalCase
- Custom hooks prefixed with "use" (e.g., useTaskList)
- Error handling: always use try/catch in async functions

## Do Not
- Do not use the Pages Router or getServerSideProps
- Do not use Redux -- we use Zustand
- Do not write raw SQL -- always use Prisma
- Do not create client components unnecessarily

## Testing
- Unit tests: Vitest. Integration tests: Playwright
- All utility functions must have tests before merging
- Test files live next to the file they test (*.test.ts)

## Commands
- `pnpm dev` -- start dev server (port 3000)
- `pnpm test` -- run Vitest
- `pnpm build` -- production build

# Monorepo: DataPulse Platform

pnpm workspaces monorepo. Packages in `packages/`.

## Global Commands
- `pnpm install` -- install all dependencies
- `pnpm -r build` -- build all packages
- `pnpm -r test` -- test all packages

## Global Rules
- Changes to `packages/shared` require running tests in all consuming packages
- Use workspace protocol for internal dependencies: `"@company/shared": "workspace:*"`
- Never install dependencies at the root unless they're dev tools

## Verification
After changes, always run:
1. `pnpm lint`
2. `pnpm -r test`
3. `pnpm -r build`

@packages/web/CLAUDE.md
@packages/api/CLAUDE.md
@packages/shared/CLAUDE.md