CLAUDE.md 怎么写才有效？Harness Engineering 实战篇（附模板）

## Commands
- `pnpm test` — run tests (not npm test)
- `pnpm lint` — ESLint + Prettier
- `pnpm typecheck` — strict TypeScript

## Conventions
- All API handlers return Result<T, AppError> type
- Database migrations use reversible format (up + down)
- Commit messages follow Conventional Commits
- Feature branches: feat/description, bug fixes: fix/description

## Architecture Decisions
- No circular imports between modules (enforced by eslint-plugin-import)
- Frontend never imports from backend directly — use shared types package
- All external API calls go through src/lib/api-client.ts

# 差：247 行项目文档
## Project Overview
This is a full-stack e-commerce application built with Next.js 14,
using the App Router pattern with React Server Components...
[再来 200 多行架构描述]

# 差：让 AI "帮我写个 CLAUDE.md"
## Code Quality Standards
- Write clean, maintainable code following industry best practices
- Use meaningful variable names that clearly convey purpose
- Add comprehensive comments for complex logic
- Ensure proper error handling throughout the codebase
- Follow the DRY principle to avoid code duplication

# 差：500+ 行，什么都塞进去
## Database
[40 行数据库惯例]
## Authentication
[30 行认证模式]
## Deployment
[25 行部署流程]
## API Design
[35 行 REST 惯例]
## Testing
[50 行测试策略]
...

CLAUDE.md（始终加载，<60 行）
  → 全局约束
  → 构建/测试命令
  → 关键架构决策

Skills（按需加载）
  → 数据库迁移规则
  → API 设计规范
  → 部署流程
  → 测试惯例

# CLAUDE.md

## Project
- TypeScript monorepo, pnpm workspaces
- React frontend (packages/web), Express backend (packages/api)

## Commands
- `pnpm test` — run all tests
- `pnpm lint` — ESLint + Prettier
- `pnpm typecheck` — TypeScript strict mode

## Critical Rules
- All API responses use Result<T, AppError>
- No direct database queries outside packages/db
- Never modify shared types without running full test suite

# .claude/skills/database-migration.md
---
name: database-migration
description: Rules for creating or modifying database migrations
---

## Migration Rules
- Always create reversible migrations (up + down)
- Use transactions for DDL changes
- Never modify an existing migration file — create a new one
- Test against production schema copy before merging
- Migration files: YYYYMMDDHHMMSS_description.ts

# CLAUDE.md
See @AGENTS.md for shared project conventions.

## Claude-Specific
- Use sub-agents for codebase exploration tasks
- Prefer Sonnet for test generation, Opus for architecture decisions
- Run typecheck hook after every file edit

# CLAUDE.md — 28 行

## Project
- TypeScript monorepo, pnpm workspaces
- Packages: web (React), api (Express), shared (types + utils), db (Prisma)

## Commands
- `pnpm test` — all tests
- `pnpm test --filter=web` — frontend tests only
- `pnpm lint` — ESLint + Prettier
- `pnpm typecheck` — TypeScript strict

## Rules
- Cross-package imports only through package.json exports
- Shared types in packages/shared — never duplicate
- API handlers return Result<T, AppError>
- No circular dependencies (enforced by eslint-plugin-import)

## Testing
- Unit tests next to source: foo.ts → foo.test.ts
- Integration tests in __tests__/ at package root
- Mock external services, never real API calls in tests

## Git
- Conventional commits (feat:, fix:, refactor:, test:, docs:)
- One PR per feature, squash merge to main

# CLAUDE.md — 24 行

## Project
- Python 3.12, FastAPI, SQLAlchemy 2.0, Alembic migrations
- Package manager: uv (not pip)

## Commands
- `uv run pytest` — run tests
- `uv run ruff check .` — linting
- `uv run mypy .` — type checking
- `uv run alembic upgrade head` — apply migrations

## Rules
- All endpoints return ResponseModel[T] wrapper
- Database access only through repository pattern (src/repos/)
- Environment variables via pydantic-settings, never os.getenv
- New endpoints need: handler, schema, test, OpenAPI docstring

## Migrations
- Always reversible (upgrade + downgrade)
- One migration per PR
- Never edit existing migrations

# CLAUDE.md — 22 行

## Project
- React 19, TypeScript, Vite, Tailwind CSS 4
- State: Zustand for global, React Query for server state

## Commands
- `npm run dev` — dev server (port 3000)
- `npm test` — Vitest
- `npm run lint` — ESLint + Prettier
- `npm run typecheck` — tsc --noEmit

## Rules
- Components in src/components/, one component per file
- Custom hooks in src/hooks/, prefixed with use*
- No inline styles — Tailwind classes only
- Server state through React Query, never useEffect + fetch
- All user-facing text through i18n (src/i18n/)

## Testing
- Component tests with Testing Library
- Mock API calls with MSW, never fetch mocking

~/.claude/CLAUDE.md          （用户级，所有项目）
  ↓ 合并
./CLAUDE.md                   （项目根目录）
  ↓ 合并
./packages/web/CLAUDE.md      （子目录，最接近编辑文件的）
  ↓ 合并
./.claude/CLAUDE.local.md     （本地覆盖，不提交到 Git）

检测到重复纠正
  → 添加约束到 CLAUDE.md
  → 验证是否减少了纠正
  → 如果 CLAUDE.md 超过 60 行
    → 把最不关键的规则迁移到 Skills

see @AGENTS.md