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. 模板化配置

实践建议

渐进式配置策略

配置审查清单

总结

关键要点

下一步

參考資源