终极 CLAUDE.md 文件指南:如何把 Claude Code 生产力提升 10 倍

CLAUDE.md 文件是什么?为什么它重要

如果你用 Claude Code 没有 CLAUDE.md 文件,你把它大部分能力放在桌子上没用。

CLAUDE.md 是 Markdown 配置文件,Claude Code 在每次会话开始时自动读取。它告诉 Claude 你的项目架构、编码标准、偏好工具、测试模式和工作流规则。不用每次对话都重复同样指令,你写一次,Claude 每次都遵循。

把它想成雇佣一个对你公司一无所知的承包商 vs 一个读过你整本工程手册的承包商。CLAUDE.md 文件就是那本手册。

为什么 CLAUDE.md 胜过反复提示

光是 token 节省就很可观。如果你每对话在上下文设置上花 500 token,每天有 20 个对话,那就是每天 10,000 token -- 或每天约 $0.15-$0.75,取决于模型。一个月,CLAUDE.md 文件在原始 API 成本上为你省 $4.50-$22.50,同时产生更好结果。

Anthropic 额度 | AWS 额度 | Google Cloud 额度

---

Claude Code 如何读取 CLAUDE.md 文件

Claude Code 按特定优先级顺序查找 CLAUDE.md 文件。理解这个层级对有效组织你的指令至关重要。

文件加载顺序

Claude Code 合并所有适用文件。如果你的全局文件说"用 2 空格缩进",但你的项目文件说"用 4 空格 tab",那个项目的项目文件胜。

什么放哪里

全局 CLAUDE.md(~/.claude/CLAUDE.md)-- 到处都适用的偏好:

# Global Preferences
- Always use TypeScript over JavaScript when possible
- Prefer functional components over class components in React
- Write concise commit messages under 72 characters
- Use ESM imports, never CommonJS require()

项目 CLAUDE.md(项目根)-- 这个代码库专属的一切:

# Project: Acme Dashboard
## Tech Stack
- Next.js 15 with App Router
- TypeScript 5.x strict mode
- Tailwind CSS 4.0
- Prisma ORM with PostgreSQL
- Jest + React Testing Library for tests

## Architecture
- /app — Next.js routes (App Router only, no Pages Router)
- /components — reusable UI components
- /lib — business logic and utilities
- /prisma — database schema and migrations

---

创建你的第一个 CLAUDE.md 文件

以下是开始使用 Claude Code 和正确配置 CLAUDE.md 文件的逐步设置。

步骤 1:安装 Claude Code

npm install -g @anthropic-ai/claude-code

步骤 2:在项目根创建 CLAUDE.md

touch CLAUDE.md

步骤 3:添加基础配置

从这个最小模板开始,按需扩展:

# Project: [Your Project Name]

## Tech Stack
- [Language/Framework]
- [Database]
- [Key libraries]

## Coding Standards
- [Indentation preference]
- [Naming conventions]
- [Import ordering]

## Rules
- Always write tests for new functions
- Never commit directly to main
- Use conventional commit messages

步骤 4:运行 Claude Code

claude

Claude Code 自动检测并加载你的 CLAUDE.md 文件。你会在会话输出中看到确认。

---

CLAUDE.md 模板:入门、高级和团队

模板 1:简单项目(20 行)

最适合个人开发者、副项目和小代码库。

# My App

## Stack
- Python 3.12, FastAPI, SQLAlchemy, PostgreSQL
- pytest for testing

## Rules
- Use type hints on all function signatures
- Write docstrings for public functions
- Keep functions under 30 lines
- Use async/await for all database operations
- Format with black, lint with ruff

## Patterns
- Repository pattern for data access
- Pydantic models for request/response validation
- Dependency injection via FastAPI Depends()

模板 2:高级全栈项目(80+ 行)

适合有多个开发者和复杂架构的生产应用。

# Acme SaaS Platform

## Tech Stack
- Frontend: Next.js 15, TypeScript 5.x, Tailwind CSS 4.0
- Backend: Node.js 22, tRPC, Prisma ORM
- Database: PostgreSQL 16, Redis 7
- Infrastructure: Vercel (frontend), Railway (backend)
- Testing: Vitest, Playwright, MSW

## Architecture
All code follows Clean Architecture principles:
- /packages/web — Next.js frontend (App Router only)
- /packages/api — tRPC backend
- /packages/shared — shared types and utilities
- /packages/db — Prisma schema and client

## Coding Standards
- Strict TypeScript: no any, no ts-ignore
- All components must be functional with hooks
- Server Components by default, "use client" only when needed
- All API routes must have Zod input validation
- Database queries go through repository layer, never raw SQL

## Testing Requirements
- Minimum 80% coverage for new code
- Unit tests for all business logic
- Integration tests for API endpoints
- E2E tests for critical user flows
- Use MSW for API mocking, never mock fetch directly

## Git Workflow
- Conventional commits: feat:, fix:, chore:, docs:
- All PRs require passing CI before merge
- Squash merge to main
- Branch naming: feature/TICKET-123-description

## Security Rules
- NEVER hardcode secrets or API keys
- Always use environment variables for config
- Sanitize all user input
- Use parameterized queries (Prisma handles this)
- NEVER expose internal error details to clients

模板 3:团队配置(通过 Git 共享)

适合想要所有成员保持一致 Claude Code 行为的团队。

# Team Engineering Standards — Acme Corp

## Overview
This file ensures Claude Code follows our team's engineering
standards. Committed to Git so all engineers get identical behavior.

## Code Review Checklist (Claude must follow before suggesting code)
1. Does this change have tests?
2. Are error cases handled?
3. Is the function documented?
4. Does it follow our naming conventions?
5. Are there any security implications?

## Naming Conventions
- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase with use prefix (useAuth.ts)
- Utils: camelCase (formatDate.ts)
- Constants: SCREAMING_SNAKE (MAX_RETRIES)
- Database tables: snake_case (user_profiles)
- API routes: kebab-case (/api/user-settings)

## Forbidden Patterns
- DO NOT use console.log in production code (use our logger)
- DO NOT use any TypeScript escape hatches (any, @ts-ignore)
- DO NOT install new dependencies without justification
- DO NOT modify database schema without migration file
- DO NOT use default exports (use named exports only)

## Preferred Libraries (do not suggest alternatives)
- State management: Zustand (not Redux)
- Forms: React Hook Form + Zod (not Formik)
- HTTP client: native fetch (not Axios)
- Date handling: date-fns (not Moment.js)
- Animation: Framer Motion (not React Spring)

---

对比:CLAUDE.md vs .cursorrules vs .github/copilot-instructions.md

如果你在评估 AI 编码工具,理解每个如何处理配置至关重要。

Claude Code 的关键差异化是 CLAUDE.md 周围的生态 -- hooks、自定义命令、MCP 服务器和多 agent 支持把它从配置文件变成完整的自动化框架。

---

Hooks:自动化你的 Claude Code 工作流

Hooks 在 .claude/settings.json 中配置,不在 CLAUDE.md 本身。它们在 Claude Code 事件之前或之后自动运行 shell 命令。

Hook 配置结构

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "echo 'File about to be modified'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH"
      }
    ],
    "PreCommit": [
      {
        "command": "npm run lint && npm run test:changed"
      }
    ]
  }
}

最实用的 Hook 模式

实用 Hook 示例

每次文件编辑后自动格式化:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

为变更文件跑测试:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "npx vitest run --reporter=verbose --changed"
      }
    ]
  }
}

---

自定义斜杠命令

斜杠命令让你创建可复用的提示模板,用一个 / 命令触发。

如何创建斜杠命令

1. 在你的项目中创建 .claude/commands/ 目录
2. 添加 Markdown 文件 -- 每个文件成为一个命令
3. 用 $ARGUMENTS 作为动态输入占位符

示例:.claude/commands/review.md

Review the following code for:
1. Security vulnerabilities
2. Performance issues
3. Missing error handling
4. Test coverage gaps

Code to review: $ARGUMENTS

Provide a severity rating (low/medium/high/critical) for each finding.

Claude Code 中的用法:

/project:review src/auth/login.ts

有用的斜杠命令想法

---

MCP 服务器:扩展 Claude Code 能力

MCP(Model Context Protocol)服务器把 Claude Code 连接到外部工具和服务。正确配置时,Claude Code 可以查询数据库、浏览网页、管理文件、与 GitHub 交互等等 -- 全部从你的编码会话内。

如何配置 MCP 服务器

MCP 服务器在 .claude/settings.json 中设置:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost:5432/mydb"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

最流行的开发者 MCP 服务器

在 CLAUDE.md 中引用 MCP

你的 CLAUDE.md 可以指示 Claude Code 何时以及如何使用连接的 MCP 服务器:

## Available Tools
- Use the postgres MCP to check schema before writing migrations
- Use the github MCP to create PRs after completing feature branches
- Use the memory MCP to track progress on multi-step tasks

---

爆红的 27-Agent 设置:Google 工程师如何自动化 80% 工作

2026 年初,一位 Google 工程师的 Twitter 帖子爆红,描述他如何设置 27 个专门的 Claude Code agent 来处理工作流的不同部分。每个 agent 有自己的 CLAUDE.md,带窄、聚焦的指令。

核心洞察

不是用一个通用 Claude Code 会话试图做所有事,他把工作分解为专门化角色。每个 agent 有:

• 一份带领域专属知识的专属 CLAUDE.md
• 受限的工具访问(只用得到的)
• 关于应该和不应该碰什么的清晰边界
• 特定的输出格式和质量标准

示例 Agent 拆分

如何复刻这个设置

你不需要 27 个 agent 才能从这个模式中受益。从 3-5 个专门配置开始:

1. 按角色创建独立 CLAUDE.md 文件:

.claude/agents/frontend.md
.claude/agents/backend.md
.claude/agents/testing.md

2. 用特定配置启动 Claude Code:

# Use different profiles by combining global + agent-specific context
claude --profile frontend

3. 定义清晰的交接点:

你的主 CLAUDE.md 可以引用何时切换 agent:

## Agent Workflow
- Frontend changes: use the frontend agent profile
- API changes: use the backend agent profile
- After any code change: run the test agent
- Before merging: run the review agent

为什么这能工作

27-agent 方法有效是因为 AI 生产力的一条基本原则:窄上下文产生比宽上下文更好的输出。 加载 400 行关于前端、后端、DevOps、测试和文档指令的 Claude Code 会话,在任何单一任务上的表现都比加载 50 行高度相关指令的会话差。

---

常见 CLAUDE.md 错误(以及如何修复)

错误 1:太模糊

不好:

Write good code that follows best practices.

好:

- Use TypeScript strict mode, no implicit any
- All functions must have JSDoc comments
- Error handling: wrap async operations in try/catch
- Max function length: 30 lines

错误 2:指令过载

放 500+ 行指令会让 Claude Code 把重要规则降低优先级。保持 CLAUDE.md 聚焦。

错误 3:不版本控制 CLAUDE.md

你的 CLAUDE.md 应该提交到 Git。这确保:

• 团队一致性
• 变更历史和问责
• 如果指令导致问题易于回滚
• 指令变更的 PR 评审

错误 4:忽略安全部分

总是在你的 CLAUDE.md 中包含安全规则:

## Security (CRITICAL — never ignore)
- NEVER hardcode API keys, tokens, or passwords
- NEVER commit .env files
- ALWAYS use parameterized database queries
- ALWAYS validate and sanitize user input
- NEVER expose stack traces or internal errors to users

错误 5:忘记提及技术栈

Claude Code 能从代码推断你的栈,但显式声明防止错误假设:

## Stack (authoritative — do not infer differently)
- Runtime: Node.js 22 (NOT Deno, NOT Bun)
- Framework: Next.js 15 App Router (NOT Pages Router)
- ORM: Prisma (NOT Drizzle, NOT TypeORM)
- Package manager: pnpm (NOT npm, NOT yarn)

---

Claude Code 最佳实践:高级用户技巧

技巧 1:使用条件指令

## Environment-Specific Rules
- In development: use verbose logging, skip minification
- In production: no console.log, enable all optimizations
- In CI: run full test suite, fail on any warning

技巧 2:定义输出格式

## When I ask for a code review, respond with:
1. **Summary** (1-2 sentences)
2. **Issues found** (bulleted, severity-tagged)
3. **Suggested fixes** (with code snippets)
4. **Overall grade** (A/B/C/D/F)

技巧 3:为依赖设置边界

## Dependency Rules
- NEVER install packages with fewer than 1,000 weekly downloads
- NEVER install packages with known CVEs
- Prefer built-in Node.js APIs over third-party packages
- Always check bundle size impact before adding frontend deps

技巧 4:为长项目使用记忆文件

## Memory
- Track all completed features in .claude/memory/features.md
- Log all architecture decisions in .claude/memory/decisions.md
- Update progress after each session

技巧 5:与你的 CI/CD 集成

你的 CLAUDE.md 能指示 Claude Code 尊重你的 CI 流水线:

## Before pushing any code:
1. Run `pnpm lint` — fix all errors
2. Run `pnpm test` — all tests must pass
3. Run `pnpm build` — build must succeed
4. Check bundle size — must not exceed 250KB

---

Claude Code 多少钱?(以及如何获取额度)

Claude Code 使用 API 额度,意味着你的成本取决于使用的模型和喂入多少上下文。

Claude Code 成本拆解

一次典型重度 Claude Code 日使用 500K-2M token,根据模型选择花 $2-$30。一个配置良好的 CLAUDE.md 通过消除重复上下文降低 token 使用。

为 Claude Code 获取免费额度

为你的 Claude Code 使用提供资金的最佳方式是通过额度计划:

跨所有计划总可叠加额度:高达 $230,000+。

Anthropic 额度 | AWS 额度 | Google Cloud 额度 | Azure 额度

一个 CLAUDE.md 文件加 $5,000-$25,000 初创额度给你 3-6 个月的密集 Claude Code 开发,零成本。浏览ClaimAICredits上所有可用额度计划找出你符合的。

---

快速参考:CLAUDE.md 备忘单

---

今天就开始

CLAUDE.md 文件是 AI 辅助开发中你能设置的最高杠杆配置。从本指南的简单模板开始,提交到你的仓库,根据你工作流中有效的内容迭代。

从 Claude Code 中获得最大价值的工程师不是写更好的提示 -- 而是写更好的 CLAUDE.md 文件。爆红的 27-agent 设置证明:经过深思的配置每次都打败暴力提示。

如果 Claude Code 的 API 成本阻碍你尝试多 agent 工作流等高级设置,探索通过 ClaimAICredits 可用的免费额度计划。叠加来自 Anthropic、AWS 和 Google Cloud 的额度可以给你数月免费开发时间来完善你的 CLAUDE.md 配置。