CLAUDE.md配置文件

用Claude Code时,每次都要解释项目信息、编码规范这些重复内容,很浪费时间。我之前就因为忘记说某个规范,Claude生成的代码完全不符合团队要求,改了半天才弄好。

CLAUDE.md配置文件就是解决这个问题的。

什么是CLAUDE.md

CLAUDE.md就是一个Markdown文件,Claude Code启动时会自动读取。相当于项目的"说明书",告诉Claude:

项目干嘛的
用了什么技术
目录结构
编码规范
常用命令
注意事项

配置文件的层级

Claude Code支持三层配置,优先级从高到低:

企业级 - 公司统一规范
项目级 (./CLAUDE.md) - 团队共享
用户级 (~/.claude/CLAUDE.md) - 个人设置

这样分层的好处:

用户级:个人偏好(语言、编码风格)
项目级:项目规则(技术栈、架构)
企业级:公司规范(安全策略)

为什么CLAUDE.md如此重要

对比:有无CLAUDE.md的差异

没有CLAUDE.md时:

你: 帮我创建一个API路由

Claude: 好的,我来创建一个路由文件。
[创建了basic-route.js]

你: 不对,我们项目用的是TypeScript,而且路由要放在src/routes目录下

Claude: 抱歉,让我重新创建。
[重新创建src/routes/basic-route.ts]

你: 还有,我们团队要求使用函数式组件,需要添加JSDoc注释

Claude: 明白了,我来修改。
[添加注释和调整代码风格]

你: 记得要导出类型定义...

Claude: 好的,我添加类型导出。

有CLAUDE.md后:

你: 帮我创建一个API路由

Claude: 我会按照项目规范创建TypeScript路由文件。
[直接创建src/routes/basic-route.ts,包含:
 - TypeScript类型定义
 - JSDoc注释
 - 函数式组件
 - 类型导出
 - 符合团队编码规范]

✓ 一次到位

CLAUDE.md的核心价值

省时间
- 不用重复解释项目
- 规范自动遵守
- 技术栈已知
代码质量
- 风格统一
- 符合团队规范
- 少返工
开发效率
- 配置一次,长期有效
- 减少沟通
- 一次做对
知识传承
- 新人快速上手
- 最佳实践文档化
- 团队标准统一

创建你的第一个CLAUDE.md

自动生成配置

Claude Code提供了/init命令来自动生成CLAUDE.md文件:

# 在项目根目录启动Claude Code
claude

# 使用init命令
/init

Claude会自动分析你的项目:

扫描package.json、requirements.txt等配置文件
识别项目结构和目录
检测使用的框架和工具
生成定制化的CLAUDE.md

输出示例:

🔍 Analyzing your project...

✓ Detected: Node.js project with TypeScript
✓ Found: React + Next.js framework
✓ Identified: ESLint, Prettier configurations
✓ Discovered: 12 key directories

📝 Generating CLAUDE.md...

✓ CLAUDE.md created successfully!

The file includes:
- Project overview
- Technology stack
- Directory structure
- Common commands
- Coding conventions

手动创建配置

你也可以手动创建CLAUDE.md文件。以下是一个基础模板:

# Project: My Awesome App

## Overview
A modern web application built with React and TypeScript.

## Technology Stack
- Frontend: React 18, TypeScript, Tailwind CSS
- Build: Vite
- Testing: Jest, React Testing Library
- Linting: ESLint, Prettier

## Directory Structure

src/ ├── components/ # Reusable React components ├── pages/ # Page components ├── hooks/ # Custom React hooks ├── utils/ # Utility functions ├── types/ # TypeScript type definitions └── styles/ # Global styles

## Coding Conventions
- Use functional components with hooks
- TypeScript strict mode enabled
- Component files: PascalCase.tsx
- Utility files: camelCase.ts
- CSS modules for component styles

## Common Commands
```bash
npm run dev      # Start development server
npm run build    # Build for production
npm test         # Run tests
npm run lint     # Lint code

## CLAUDE.md的语法和结构

### 基本语法

CLAUDE.md使用标准Markdown语法,Claude可以理解所有Markdown元素:

```markdown
# 一级标题 - 项目名称
## 二级标题 - 主要章节
### 三级标题 - 子章节

**粗体** - 重要信息
*斜体* - 强调内容
`代码` - 命令或代码片段

- 无序列表
1. 有序列表

[链接](url)

```代码块```

实战配置示例

示例1: React + TypeScript前端项目

# E-commerce Frontend

## Project Overview
Modern e-commerce platform frontend built with React, TypeScript, and Next.js.
Focus on performance, accessibility, and user experience.

## Technology Stack
- **Framework**: Next.js 14 (App Router)
- **Language**: TypeScript 5.0+ (strict mode)
- **Styling**: Tailwind CSS + CSS Modules
- **State Management**: Zustand
- **Data Fetching**: TanStack Query (React Query)
- **Forms**: React Hook Form + Zod validation
- **Testing**: Vitest + React Testing Library
- **E2E Testing**: Playwright

## Architecture Patterns
- **Component Structure**: Atomic Design (atoms, molecules, organisms, templates, pages)
- **State**: Server state (React Query) + Client state (Zustand)
- **Routing**: File-based routing with Next.js App Router
- **API**: RESTful API with fetch wrapper

## Directory Structure

src/ ├── app/ # Next.js app directory │ ├── (auth)/ # Auth route group │ ├── (shop)/ # Shop route group │ └── api/ # API routes ├── components/ │ ├── atoms/ # Basic components (Button, Input) │ ├── molecules/ # Composite components (SearchBar) │ ├── organisms/ # Complex components (Header, ProductCard) │ └── templates/ # Page templates ├── hooks/ # Custom React hooks ├── lib/ # Utilities and configurations ├── stores/ # Zustand stores ├── types/ # TypeScript type definitions └── styles/ # Global styles

## Coding Conventions

### Component Guidelines
- **MUST** use functional components with TypeScript
- **MUST** define prop types with TypeScript interfaces
- **MUST** use named exports for components
- **PREFER** composition over inheritance
- **PREFER** custom hooks for reusable logic

Example:
```typescript
interface ButtonProps {
  variant: 'primary' | 'secondary';
  children: React.ReactNode;
  onClick?: () => void;
}

export function Button({ variant, children, onClick }: ButtonProps) {
  return (
    <button className={styles[variant]} onClick={onClick}>
      {children}
    </button>
  );
}

Naming Conventions

Components: PascalCase (e.g., ProductCard.tsx)
Hooks: camelCase with 'use' prefix (e.g., useCart.ts)
Utils: camelCase (e.g., formatPrice.ts)
Types: PascalCase with 'Type' or 'Interface' (e.g., UserType.ts)
CSS Modules: camelCase (e.g., productCard.module.css)

Import Order

// 1. React and Next.js
import { useState } from 'react';
import Link from 'next/link';

// 2. External libraries
import { useQuery } from '@tanstack/react-query';
import clsx from 'clsx';

// 3. Internal modules
import { Button } from '@/components/atoms';
import { useCart } from '@/hooks';

// 4. Types
import type { Product } from '@/types';

// 5. Styles
import styles from './ProductCard.module.css';

State Management Rules

Server state: Use React Query (no caching in Zustand)
Client state: Use Zustand for global UI state
Local state: Use useState for component-specific state
Form state: Use React Hook Form

Common Commands

# Development
npm run dev              # Start dev server (http://localhost:3000)
npm run build           # Production build
npm run start           # Start production server

# Testing
npm run test            # Run unit tests
npm run test:watch      # Watch mode
npm run test:e2e        # Run Playwright E2E tests
npm run test:coverage   # Generate coverage report

# Code Quality
npm run lint            # ESLint
npm run format          # Prettier
npm run type-check      # TypeScript check

API Integration

Base URL: Set in .env.local as NEXT_PUBLIC_API_URL
Authentication: JWT token in Authorization header
Error Handling: Use custom ApiError class
Request Wrapper: Use lib/api.ts fetch wrapper

Example:

import { api } from '@/lib/api';

// GET request
const products = await api.get<Product[]>('/products');

// POST request with auth
const order = await api.post<Order>('/orders', orderData, {
  auth: true
});

Testing Requirements

Unit Tests: All utilities and hooks MUST have tests
Component Tests: Complex components SHOULD have tests
E2E Tests: Critical user flows MUST have E2E tests
Coverage: Aim for >80% code coverage

Performance Guidelines

Use Next.js Image component for all images
Lazy load components below the fold
Implement virtual scrolling for long lists
Use React.memo() for expensive components
Avoid unnecessary re-renders

All interactive elements MUST be keyboard accessible
ARIA labels for icon buttons
Semantic HTML elements
Color contrast ratio >= 4.5:1
Support screen readers

Common Pitfalls to Avoid

⚠️ DO NOT use any type in TypeScript ⚠️ DO NOT fetch data in components (use React Query) ⚠️ DO NOT use inline styles (use Tailwind or CSS modules) ⚠️ DO NOT commit .env.local file ⚠️ DO NOT skip TypeScript errors to "fix" issues

Useful Resources

### 示例2: Node.js + Express后端项目

```markdown
# E-commerce Backend API

## Project Overview
RESTful API backend for e-commerce platform built with Node.js, Express, and PostgreSQL.
Focuses on scalability, security, and maintainability.

## Technology Stack
- **Runtime**: Node.js 20 LTS
- **Framework**: Express 4.x
- **Language**: TypeScript 5.0+
- **Database**: PostgreSQL 15 + Prisma ORM
- **Validation**: Zod
- **Authentication**: JWT + bcrypt
- **Testing**: Jest + Supertest
- **Documentation**: Swagger/OpenAPI 3.0

## Architecture
- **Pattern**: Layered Architecture (Controller → Service → Repository)
- **Authentication**: JWT-based with refresh tokens
- **Authorization**: Role-based access control (RBAC)
- **Error Handling**: Centralized error handler middleware
- **Logging**: Winston with rotation

## Directory Structure

src/ ├── config/ # Configuration files ├── controllers/ # Request handlers ├── services/ # Business logic ├── repositories/ # Database access layer ├── models/ # Prisma models ├── middlewares/ # Express middlewares ├── routes/ # API routes ├── utils/ # Utility functions ├── types/ # TypeScript types ├── validators/ # Zod schemas └── tests/ # Test files

## Coding Conventions

### Layered Architecture
```typescript
// Controller - Handle HTTP request/response
export const createProduct: RequestHandler = async (req, res, next) => {
  try {
    const data = ProductCreateSchema.parse(req.body);
    const product = await productService.create(data);
    res.status(201).json({ success: true, data: product });
  } catch (error) {
    next(error);
  }
};

// Service - Business logic
export const productService = {
  async create(data: ProductCreateInput) {
    // Validate business rules
    await this.validateProductData(data);
    // Call repository
    return await productRepository.create(data);
  }
};

// Repository - Database operations
export const productRepository = {
  async create(data: ProductCreateInput) {
    return await prisma.product.create({ data });
  }
};

API Response Format

All API responses MUST follow this structure:

// Success Response
{
  "success": true,
  "data": { ... },
  "message": "Optional success message"
}

// Error Response
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": { ... } // Optional
  }
}

Naming Conventions

Files: kebab-case (e.g., user-controller.ts)
Classes: PascalCase (e.g., UserService)
Functions: camelCase (e.g., getUserById)
Constants: UPPER_SNAKE_CASE (e.g., MAX_LOGIN_ATTEMPTS)
Database tables: snake_case (e.g., user_sessions)

Environment Variables

Required variables in .env:

# Server
NODE_ENV=development
PORT=3000

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# JWT
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=15m
REFRESH_TOKEN_EXPIRES_IN=7d

# Redis (for sessions)
REDIS_URL=redis://localhost:6379

Common Commands

# Development
npm run dev             # Start dev server with nodemon
npm run build          # Build TypeScript
npm run start          # Start production server

# Database
npx prisma migrate dev  # Create migration
npx prisma generate     # Generate Prisma Client
npx prisma studio      # Open Prisma Studio

# Testing
npm test               # Run all tests
npm run test:watch     # Watch mode
npm run test:coverage  # Coverage report

# Code Quality
npm run lint           # ESLint
npm run format         # Prettier
npm run type-check     # TypeScript check

API Design Guidelines

RESTful Conventions

GET    /api/v1/products           # List products
GET    /api/v1/products/:id       # Get single product
POST   /api/v1/products           # Create product
PATCH  /api/v1/products/:id       # Update product
DELETE /api/v1/products/:id       # Delete product

Request Validation

MUST use Zod for all request validation:

import { z } from 'zod';

const ProductCreateSchema = z.object({
  name: z.string().min(1).max(200),
  price: z.number().positive(),
  description: z.string().optional(),
  categoryId: z.string().uuid()
});

// In controller
const data = ProductCreateSchema.parse(req.body);

Security Requirements

MUST validate all user inputs
MUST use parameterized queries (Prisma handles this)
MUST hash passwords with bcrypt (min 10 rounds)
MUST sanitize error messages (no stack traces in production)
MUST implement rate limiting on authentication endpoints
MUST use HTTPS in production
MUST set secure HTTP headers (use helmet.js)

Error Handling Pattern

// Custom error classes
export class AppError extends Error {
  constructor(
    public statusCode: number,
    public code: string,
    message: string
  ) {
    super(message);
  }
}

// Usage
throw new AppError(404, 'PRODUCT_NOT_FOUND', 'Product not found');

// Global error handler middleware
export const errorHandler: ErrorRequestHandler = (err, req, res, next) => {
  if (err instanceof AppError) {
    return res.status(err.statusCode).json({
      success: false,
      error: {
        code: err.code,
        message: err.message
      }
    });
  }
  // Handle other errors...
};

Testing Strategy

Unit Tests: Services and utilities (>90% coverage)
Integration Tests: API endpoints with test database
E2E Tests: Critical flows (auth, checkout, etc.)

Example:

describe('POST /api/v1/products', () => {
  it('should create a product', async () => {
    const response = await request(app)
      .post('/api/v1/products')
      .set('Authorization', `Bearer ${authToken}`)
      .send({
        name: 'Test Product',
        price: 99.99,
        categoryId: testCategoryId
      })
      .expect(201);

    expect(response.body.success).toBe(true);
    expect(response.body.data.name).toBe('Test Product');
  });
});

Common Pitfalls

⚠️ DO NOT expose internal error details to clients ⚠️ DO NOT store sensitive data in logs ⚠️ DO NOT use SELECT * queries (specify fields in Prisma) ⚠️ DO NOT skip request validation ⚠️ DO NOT commit .env files ⚠️ DO NOT use any type in TypeScript

### 示例3: Python + Django全栈项目

```markdown
# Django Blog Platform

## Project Overview
Full-stack blog platform built with Django and Django REST Framework.

## Technology Stack
- **Framework**: Django 4.2 LTS
- **API**: Django REST Framework 3.14
- **Database**: PostgreSQL 15
- **Caching**: Redis
- **Task Queue**: Celery
- **Testing**: pytest + pytest-django

## Project Structure

project/ ├── apps/ │ ├── accounts/ # User management │ ├── blog/ # Blog posts │ ├── comments/ # Comments system │ └── api/ # API endpoints ├── config/ # Django settings ├── static/ # Static files ├── media/ # User uploads └── tests/ # Test files

## Coding Conventions

### Python Style
- Follow PEP 8 style guide
- Use Black for formatting (line length: 88)
- Use type hints for all functions
- Docstrings for all classes and public methods

Example:
```python
from typing import Optional
from django.db import models

class Post(models.Model):
    """Blog post model."""

    title: models.CharField = models.CharField(max_length=200)
    content: models.TextField = models.TextField()
    author: models.ForeignKey = models.ForeignKey(
        "accounts.User",
        on_delete=models.CASCADE,
        related_name="posts"
    )

    def get_excerpt(self, length: int = 100) -> str:
        """Return post excerpt."""
        if len(self.content) <= length:
            return self.content
        return f"{self.content[:length]}..."

Django Conventions

App names: plural (e.g., accounts, posts)
Model names: singular (e.g., User, Post)
View classes: end with View or ViewSet
URL names: app_name + action (e.g., blog_post_list)

Common Commands

# Development
python manage.py runserver      # Start dev server
python manage.py makemigrations # Create migrations
python manage.py migrate        # Apply migrations

# Testing
pytest                          # Run tests
pytest --cov                    # With coverage
pytest -k test_name            # Run specific test

# Shell
python manage.py shell_plus     # Enhanced shell

API Design

Use DRF ViewSets for CRUD operations
Implement pagination (PageNumberPagination)
Use serializers for validation
Version APIs (e.g., /api/v1/)

Testing Requirements

All views MUST have tests
Models MUST have tests for custom methods
API endpoints MUST have integration tests
Aim for >85% code coverage

## 编码规范配置详解

### 格式化规范

```markdown
## Code Formatting

### Automatic Formatting
- **Tool**: Prettier
- **Line Length**: 100 characters
- **Indentation**: 2 spaces
- **Semicolons**: Required
- **Trailing Commas**: ES5
- **Quote Style**: Single quotes
- **Arrow Function Parentheses**: Always

Run `npm run format` before committing.

### ESLint Rules
- Extends: `['airbnb', 'plugin:@typescript-eslint/recommended']`
- No console.log in production code
- Prefer const over let
- No unused variables
- Require explicit return types

Git提交规范

## Git Commit Convention

Follow Conventional Commits specification:

```text
[type]([scope]): [subject]

[body]

[footer]

Types

feat: New feature
fix: Bug fix
docs: Documentation only
style: Code style changes
refactor: Code refactoring
test: Adding tests
chore: Maintenance tasks

Examples

feat(auth): add OAuth2 login support

Implement OAuth2 authentication with Google and GitHub providers.
Includes login, logout, and token refresh functionality.

Closes #123

fix(api): resolve race condition in user creation

Add transaction lock to prevent duplicate user accounts
when simultaneous registration attempts occur.

Branch Naming

Feature: feature/short-description
Bug fix: fix/short-description
Hotfix: hotfix/short-description

## 项目特定的提示词模板

你可以在CLAUDE.md中定义常用的提示词模板:

```markdown
## Claude Code Prompt Templates

### Create New Feature
When creating a new feature, follow these steps:
1. Create feature branch: `git checkout -b feature/[name]`
2. Create necessary files in appropriate directories
3. Implement feature following coding conventions
4. Add unit tests (min 80% coverage)
5. Add integration tests if applicable
6. Update documentation
7. Run all tests and linting
8. Create pull request

### Debugging Workflow
When debugging issues:
1. Reproduce the bug with a minimal test case
2. Add logging statements to trace execution
3. Use debugger breakpoints if needed
4. Fix the bug
5. Add regression test
6. Verify fix works
7. Clean up debug code

### Refactoring Checklist
Before refactoring:
- [ ] Write tests for existing behavior
- [ ] Ensure all tests pass
- [ ] Make incremental changes
- [ ] Run tests after each change
- [ ] Update documentation
- [ ] Review performance impact

### Code Review Focus
When reviewing code, check:
- Does it follow project conventions?
- Are there adequate tests?
- Is error handling comprehensive?
- Are edge cases covered?
- Is documentation updated?
- Are there security concerns?

技术栈和依赖说明

详细的技术栈描述

## Detailed Technology Stack

### Frontend Stack
```typescript
// React Ecosystem
"react": "^18.2.0"              // UI library
"react-dom": "^18.2.0"          // DOM bindings
"react-router-dom": "^6.8.0"   // Routing

// State Management
"zustand": "^4.3.0"            // Lightweight state management
"@tanstack/react-query": "^4.24.0"  // Server state management

// Form Handling
"react-hook-form": "^7.43.0"   // Form state
"zod": "^3.20.0"               // Schema validation

// Styling
"tailwindcss": "^3.2.0"        // Utility-first CSS
"clsx": "^1.2.1"               // Conditional classes

// Development
"vite": "^4.1.0"               // Build tool
"typescript": "^4.9.0"         // Type safety
"eslint": "^8.35.0"            // Linting
"prettier": "^2.8.0"           // Formatting

Backend Stack

{
  "express": "^4.18.0",           // Web framework
  "prisma": "^4.11.0",            // ORM
  "jsonwebtoken": "^9.0.0",       // JWT auth
  "bcrypt": "^5.1.0",             // Password hashing
  "zod": "^3.20.0",               // Validation
  "winston": "^3.8.0",            // Logging
  "helmet": "^7.0.0",             // Security headers
  "cors": "^2.8.5",               // CORS middleware
  "express-rate-limit": "^6.7.0"  // Rate limiting
}

Why These Choices?

Zustand over Redux:

Simpler API and less boilerplate
Better TypeScript support out of the box
Smaller bundle size (1KB vs 3KB gzipped)
Our app doesn't need Redux's advanced features

Prisma over TypeORM:

Better TypeScript integration
Intuitive query API
Powerful migration system
Excellent documentation

Vite over Webpack:

Faster cold starts (10x)
Faster HMR (Hot Module Replacement)
Simpler configuration
Better development experience

## 配置最佳实践

### 1. 保持简洁

CLAUDE.md不用写所有细节。重点记录:
- Claude常需要的信息
- 容易忘的规范
- 项目特有约定
- 常见问题

**不好** (太详细):
```markdown
## TypeScript Configuration
The tsconfig.json file is located in the root directory.
It extends from @tsconfig/node18/tsconfig.json...
(300 more lines of TypeScript documentation)

好 (简洁):

## TypeScript
- Strict mode enabled
- Path aliases: `@/` → `src/`
- No `any` type
- All functions must have return types

2. 使用实例代码

代码示例比文字说明更清晰:

## Component Creation Pattern

When creating a new component:

```typescript
// components/Button/Button.tsx
import styles from './Button.module.css';
import type { ButtonProps } from './Button.types';

export function Button({ variant = 'primary', children, ...props }: ButtonProps) {
  return (
    <button className={styles[variant]} {...props}>
      {children}
    </button>
  );
}

// components/Button/Button.types.ts
export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'ghost';
  children: React.ReactNode;
}

// components/Button/index.ts
export { Button } from './Button';
export type { ButtonProps } from './Button.types';

3. 突出禁止事项

明确告诉Claude不要做什么:

## ⚠️ Critical Don'ts

### Never Do These:
❌ DO NOT use `var` (use `const` or `let`)
❌ DO NOT commit secrets or API keys
❌ DO NOT use `any` type in TypeScript
❌ DO NOT skip error handling
❌ DO NOT ignore TypeScript errors
❌ DO NOT use `!important` in CSS
❌ DO NOT modify node_modules directly

### Database
❌ DO NOT run migrations on production without backup
❌ DO NOT use `SELECT *` in queries
❌ DO NOT store passwords in plain text

### Security
❌ DO NOT expose error stack traces to clients
❌ DO NOT trust user input without validation
❌ DO NOT use `eval()` or `Function()` constructor

4. 包含故障排除

记录常见问题和解决方案:

## Troubleshooting

### Common Issues

**Issue: "Module not found" errors after pulling**
```bash
# Solution: Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Issue: Database connection fails

# Check PostgreSQL is running
pg_isready

# Verify environment variables
echo $DATABASE_URL

# Reset database
npx prisma migrate reset

Issue: Tests fail with timeout

# Increase Jest timeout in setup file
jest.setTimeout(10000);

Issue: ESLint errors on import order

# Auto-fix with:
npm run lint -- --fix

### 5. 版本控制提醒

```markdown
## Version Control

### Before Committing
- [ ] Run tests: `npm test`
- [ ] Run linting: `npm run lint`
- [ ] Run formatting: `npm run format`
- [ ] Update CHANGELOG.md for significant changes
- [ ] Ensure no console.log statements
- [ ] Check for unused imports

### Pull Request Checklist
- [ ] Branch is up to date with main
- [ ] All tests pass
- [ ] No TypeScript errors
- [ ] Documentation updated
- [ ] Screenshots for UI changes
- [ ] Migration plan for breaking changes

团队共享配置

同步团队CLAUDE.md

项目级CLAUDE.md应该提交到Git仓库:

# Add to git
git add CLAUDE.md
git commit -m "docs: add CLAUDE.md configuration"
git push

团队成员拉取后,Claude Code会自动识别和使用。

团队协作规范

## Team Collaboration

### CLAUDE.md Maintenance
- **Owner**: Tech Lead
- **Update Frequency**: After major architecture changes
- **Review Process**: PR required for significant changes
- **Notification**: Announce updates in team chat

### When to Update CLAUDE.md
✅ New coding conventions adopted
✅ Technology stack changes
✅ New common commands added
✅ Architecture patterns updated
✅ Common pitfalls discovered

### Contribution Guidelines
To suggest changes to CLAUDE.md:
1. Create a branch
2. Update CLAUDE.md
3. Add rationale in PR description
4. Tag @tech-lead for review
5. Announce changes after merge

个人配置与团队配置分离

使用用户级配置(~/.claude/CLAUDE.md)处理个人偏好:

# Personal Claude Code Configuration

## My Preferences
- Always use verbose logging
- Prefer functional programming style
- Add extra comments for complex logic
- Use Chinese for code comments (personal preference)

## My Custom Aliases
When I say "test now", run:
```bash
npm run test:watch

When I say "quick deploy", run:

npm run build && npm run deploy:staging

My Workflow

I prefer to review code before applying changes
Always show me the diff before modifying files
Ask for confirmation before deleting files

## 高级配置技巧

### 1. 条件配置

```markdown
## Environment-Specific Guidelines

### Development Environment
- Use mock data from `src/mocks/`
- Enable verbose logging
- Disable authentication for testing
- Use hot reload

### Staging Environment
- Use staging database
- Enable performance monitoring
- Use real authentication
- Enable error tracking

### Production Environment
- NEVER test experimental features
- NEVER bypass security checks
- Always create backup before deployment
- Monitor error rates closely

2. 动态内容引用

## Dynamic References

### Current Sprint Goals
See: [Sprint Board](link-to-jira)

### Latest Architecture Decisions
See: `docs/architecture/ADR-*.md`

### API Documentation
See: `http://localhost:3000/api-docs` (dev)
See: `https://api.example.com/docs` (prod)

### Design System
See: [Figma](link-to-figma)

3. 模板化配置

创建配置模板供不同项目使用:

# CLAUDE.md Template for Microservices

## Service: [SERVICE_NAME]

## Responsibility
[What this service does]

## Dependencies
### Upstream Services
- [Service A]: [Purpose]

### Downstream Services
- [Service B]: [Purpose]

## API Endpoints

GET /api/v1/[resource] POST /api/v1/[resource] PUT /api/v1/[resource]/:id DELETE /api/v1/[resource]/:id

## Configuration
- Port: [PORT]
- Database: [DATABASE]
- Queue: [QUEUE_NAME]

实践建议

渐进式配置策略

第一周: 基础信息
- 项目概述
- 技术栈
- 常用命令
第二周: 编码规范
- 命名约定
- 文件结构
- 代码示例
第三周: 高级配置
- 架构模式
- 最佳实践
- 故障排除
持续优化:
- 记录常见问题
- 添加新的规范
- 移除过时信息

配置审查清单

定期(每月)审查CLAUDE.md:

总结

CLAUDE.md是Claude Code的"大脑",一个配置良好的CLAUDE.md可以:

✅ 提升效率: 减少重复沟通,提高首次正确率 ✅ 保证质量: 统一编码规范,减少代码审查时间 ✅ 知识传承: 新成员快速上手,最佳实践文档化 ✅ 团队协作: 统一团队标准,提高协作效率

关键要点

使用/init命令快速开始,然后根据需要定制
保持简洁,只记录重要和常用的信息
使用代码示例,比文字描述更清晰
明确禁止事项,防止常见错误
定期更新,保持配置与项目同步
分层管理,个人配置与团队配置分离

下一步

立即为你的项目创建CLAUDE.md
查看 Claude Code最佳实践
学习 MCP集成
探索实战案例

参考资源

Sources:

什么是CLAUDE.md​

配置文件的层级​

为什么CLAUDE.md如此重要​

对比:有无CLAUDE.md的差异​

CLAUDE.md的核心价值​

创建你的第一个CLAUDE.md​

自动生成配置​

手动创建配置​

推荐的文档结构​

实战配置示例​

示例1: React + TypeScript前端项目​

Naming Conventions​

Import Order​

State Management Rules​

Common Commands​

API Integration​

Testing Requirements​

Performance Guidelines​

Accessibility (a11y) Requirements​

Common Pitfalls to Avoid​

Useful Resources​

API Response Format​

Naming Conventions​

Environment Variables​

Common Commands​

API Design Guidelines​

RESTful Conventions​

Request Validation​

Security Requirements​

Error Handling Pattern​

Testing Strategy​

Common Pitfalls​

Django Conventions​

Common Commands​

API Design​

Testing Requirements​

Git提交规范​

Types​

Examples​

Branch Naming​

技术栈和依赖说明​

详细的技术栈描述​

Backend Stack​

Why These Choices?​

2. 使用实例代码​

3. 突出禁止事项​

4. 包含故障排除​

团队共享配置​

同步团队CLAUDE.md​

团队协作规范​

个人配置与团队配置分离​

My Workflow​

2. 动态内容引用​

3. 模板化配置​

实践建议​

渐进式配置策略​

配置审查清单​

总结​

关键要点​

下一步​

参考资源​

什么是CLAUDE.md

配置文件的层级

为什么CLAUDE.md如此重要

对比:有无CLAUDE.md的差异

CLAUDE.md的核心价值

创建你的第一个CLAUDE.md

自动生成配置

手动创建配置

推荐的文档结构

实战配置示例

示例1: React + TypeScript前端项目

Naming Conventions

Import Order

State Management Rules

Common Commands

API Integration

Testing Requirements

Performance Guidelines

Accessibility (a11y) Requirements

Common Pitfalls to Avoid

Useful Resources

API Response Format

Naming Conventions

Environment Variables

Common Commands

API Design Guidelines

RESTful Conventions

Request Validation

Security Requirements

Error Handling Pattern

Testing Strategy

Common Pitfalls

Django Conventions

Common Commands

API Design

Testing Requirements

Git提交规范

Types

Examples

Branch Naming

技术栈和依赖说明

详细的技术栈描述

Backend Stack

Why These Choices?

2. 使用实例代码

3. 突出禁止事项

4. 包含故障排除

团队共享配置

同步团队CLAUDE.md

团队协作规范

个人配置与团队配置分离

My Workflow

2. 动态内容引用

3. 模板化配置

实践建议

渐进式配置策略

配置审查清单

总结

关键要点

下一步

参考资源