Layer 1: CLAUDE.md     ← 每次对话自动加载（核心约定）
Layer 2: .claude/rules/ ← 按文件类型/目录触发（场景规则）
Layer 3: 内联指令       ← 在对话中临时指定（一次性指令）

.claude/rules/
├── frontend.md    # 编辑 frontend/ 目录时自动加载
├── api.md         # 编辑 api/ 目录时自动加载
├── testing.md     # 编辑测试文件时自动加载
└── security.md    # 始终加载（安全约束）

"用 Rust 重写这个函数，不要引入新的依赖"
"按 PEP 8 规范格式化，但保留现有的 import 顺序"

# CLAUDE.md — Python Backend Project

## Tech Stack
- Python 3.12+, FastAPI 0.115+, SQLAlchemy 2.0+
- PostgreSQL 16, Redis 7
- Pydantic v2 for validation, Alembic for migrations

## Code Style (MUST FOLLOW)
- Line length: 100 chars max
- Type hints: REQUIRED on all function signatures
- Imports order: stdlib → third-party → local, one import per line
- Variable naming: snake_case, class names: PascalCase
- Docstrings: Google style, required on public functions

## Architecture Constraints
- `/api/v1/` prefix on all routes
- Database queries go through repository layer (never in route handlers)
- All external API calls must have timeout (default 30s) and retry (max 3)
- Environment variables accessed ONLY via `app.core.config.settings`

## Forbidden Patterns (NEVER DO)
- ❌ `print()` in production code → use `logger`
- ❌ Raw SQL strings → use SQLAlchemy ORM
- ❌ `except Exception: pass` → at minimum log the error
- ❌ Hardcoded secrets → use environment variables
- ❌ Synchronous I/O in async routes → use async libraries

## Testing
- Framework: pytest + pytest-asyncio
- Coverage target: ≥80% per module
- Test file naming: `test_{module_name}.py`
- Mock external services with `responses` or `pytest-httpx`

# CLAUDE.md — React Frontend

## Tech Stack
- React 19, TypeScript 5.5+
- State: Zustand (global), React Query (server state)
- Styling: Tailwind CSS 3.4+
- Build: Vite 5, pnpm

## Code Style
- Components: functional ONLY, no class components
- Props: always define interface, use `type` only for unions
- File structure: one component per file, co-locate styles if <50 lines
- Naming: `PascalCase.tsx` for components, `camelCase.ts` for utils
- Exports: named exports preferred over default

## Component Rules
- Every component MUST have a Storybook story (`.stories.tsx`)
- Loading state: always render a skeleton or spinner
- Error state: always render an error boundary fallback
- Empty state: always render a meaningful empty state message
- Accessibility: use semantic HTML, aria labels on interactive elements

## Forbidden
- ❌ `any` type → use `unknown` and narrow
- ❌ Inline styles → use Tailwind classes
- ❌ `useEffect` for derived state → use `useMemo`/`useCallback`
- ❌ Direct DOM manipulation → use React refs

# CLAUDE.md — AI创业内参

## Project Purpose
微信公众号 AI 内容创业，面向 AI 创业者的日报/深度分析。

## Content Rules (MUST FOLLOW)
- 目标读者：AI 创业者，技术背景但非专家
- 文章字数：热点速报 800-1500字，深度分析 2000-4000字
- 必须包含：数据、案例、可操作步骤
- 禁止：空洞的"AI改变一切"，无法验证的"据说""可能"
- 标题风格：数字/对比/悬念，让读者想点开

## Writing Style
- 公众号风格：口语化但不随意，有专业深度但不晦涩
- 段落短（3-5行），多用小标题分割
- 每个章节必须有实质内容，不能是"正确的废话"
- 结尾必须有 CTA（关注/分享/行动建议）

## File Conventions
- 草稿命名：`draft-YYYYMMDD-HHMM-关键词.md`
- 研究输出：`research/outputs/hotspot-scan-YYYYMMDD-HHMM.md`
- 发布脚本：`scripts/submit_*.py`

## Forbidden
- ❌ "今天看到一篇文章说..." 开头
- ❌ 没有具体步骤的"干货"
- ❌ 图片少于 3 张的长文
- ❌ 引用来源不标注 URL

# CLAUDE.md — User Service

## Service Info
- Name: user-service
- Port: 8081
- Protocol: gRPC + REST (grpc-gateway)
- Database: CockroachDB 23.2

## API Design Rules
- REST: follow Google API Design Guide
- gRPC: proto files in `/proto/user/v1/`
- Error codes: use gRPC status codes, map to HTTP properly
- All endpoints MUST have request validation
- Response envelope: `{ "data": ..., "error": ..., "meta": {...} }`

## Performance Constraints
- P99 latency target: <200ms
- Database queries: MUST use prepared statements
- Cache: Redis with 5min TTL default
- Rate limiting: 1000 req/min per API key

## Deployment
- Docker: multi-stage build, final image <200MB
- Health check: `/healthz` returns 200 if DB + Redis are reachable
- Graceful shutdown: 30s timeout, drain connections before exit

# CLAUDE.md — ML Pipeline

## Stack
- Orchestration: Prefect 3.0
- Processing: PySpark 3.5 on Databricks
- Storage: Delta Lake, S3
- Model serving: Triton Inference Server

## Pipeline Rules
- All pipelines MUST be idempotent (safe to re-run)
- Input validation: schema check before processing
- Error handling: dead-letter queue for malformed records
- Monitoring: emit metrics to Prometheus at each stage

## Code Standards
- Spark transformations: use DataFrame API, avoid RDD
- UDFs: prefer Pandas UDF over Python UDF (10x faster)
- Partition: always specify partition column in writes
- Memory: monitor spill, avoid `collect()` on large datasets

## Forbidden
- ❌ Hardcoded S3 paths → use config
- ❌ Full table scans without partition filter
- ❌ `repartition(1)` → causes single-node bottleneck

# .claude/rules/frontend.md
# 仅在编辑 frontend/ 目录下的文件时加载

## Tailwind Rules
- 颜色：使用设计系统的 CSS 变量（`var(--color-primary)`），不硬编码色值
- 响应式：mobile-first，断点 sm(640) md(768) lg(1024)
- 间距：使用 4px 基准（p-1=4px, p-2=8px, p-4=16px...）

## JavaScript Patterns to Avoid
- ❌ `var` → use `const` (or `let` when reassigning)
- ❌ `==` → always use `===`
- ❌ `for (var i=0; ...)` → use `forEach`/`map`/`for...of`
- ❌ Callback hell → use async/await

## Logging Pattern

✅ GOOD:
```python
logger.info("user_login", extra={"user_id": uid, "ip": request.client.host})

print(f"User {uid} logged in")  # no structured logging
logger.info(f"User {uid} logged in from {ip}")  # missing extra fields

### 技巧 4：用优先级标记

```markdown
## Rules by Priority

[P0-MUST] Never commit secrets or API keys
[P0-MUST] Never push to main directly (use feature branches)
[P1-SHOULD] Run `make lint` before committing
[P2-MAY] Add CHANGELOG entry for user-facing changes