Claude Code 完全使用指南 打造你的专属编程助手

CLAUDE.md 完全指南：将 Claude Code 打造成你的专属编程助手

你是否经常遇到这样的困扰？每次启动 Claude Code，它都像一位没有记忆的新手。昨天刚明确告知项目使用 pnpm，今天它却又开始生成 npm install 的代码。

问题的根源在哪里？其实非常简单——你缺少一份清晰的“AI 工作手册”。

这份手册就是 CLAUDE.md。配置得当，Claude Code 将成为深刻理解你项目规范、牢记你个人偏好的智能编程伙伴。配置不当，它只能不断猜测你的意图，工作效率自然难以提升。

本文将深入解析 CLAUDE.md 的完整配置体系，从基础概念到高级技巧，助你快速掌握并应用于实际开发。

核心概念：CLAUDE.md 究竟是什么？

简而言之，CLAUDE.md 是一个放置在项目根目录的 Markdown 文件，Claude Code 在每次启动时都会自动读取其内容。

你可以将其理解为专门为 AI 编写的项目说明书。文件中定义的规则，就是 Claude Code 必须遵守的工作准则。例如：项目使用的包管理器、代码风格规范、测试执行命令、各目录的功能说明等。

它并非复杂的 JSON 或 YAML 配置文件，而是一个使用自然语言编写的 Markdown 文件，上手门槛极低。

最高效的启动方式是什么？在 Claude Code 中直接输入 /init 命令，它将自动分析你的项目结构，生成一份基础版的 CLAUDE.md。你只需在此基础上进行修改和补充，即可快速完成配置。

三层配置体系：项目级、个人级与组织级

CLAUDE.md 支持多层级部署，形成从个人到组织的完整覆盖。

1. 项目级配置：./CLAUDE.md

位于项目根目录，随 Git 版本管理，实现团队共享。

应包含哪些内容？项目技术架构、统一编码规范、构建部署命令、团队协作约定——所有需要团队成员共同遵守的规则。

# 项目开发规范
## 核心技术栈
- 前端框架：React 18 + TypeScript
- 包管理器：pnpm（禁止使用 npm 或 yarn）
- 测试框架：Vitest

## 常用脚本命令
- 启动开发服务器：pnpm dev
- 运行单元测试：pnpm test
- 执行生产构建：pnpm build

## 目录结构说明
- src/api/ - API 接口层
- src/components/ - 公共组件库
- src/pages/ - 页面级组件
- src/utils/ - 通用工具函数

## 代码风格约定
- 组件名称采用 PascalCase 命名法
- 工具函数采用 camelCase 命名法
- 常量定义使用 UPPER_SNAKE_CASE
- 统一使用 2 个空格进行缩进

此文件提交至代码仓库后，团队所有成员在使用 Claude Code 时都会自动加载，确保协作一致性。

2. 个人级配置：~/.claude/CLAUDE.md

位于用户主目录，仅对当前用户生效，适用于所有项目。

适合存放个人开发偏好，例如习惯的交流语言、特定的提交信息格式等不适合纳入团队规范的内容。

# 个人开发偏好设置
- 交互回复使用中文
- 提交信息遵循 Conventional Commits 规范
- 优先采用函数式编程风格，减少类（class）的使用
- 代码解释力求简洁明了，避免冗长描述

3. 组织级配置：系统全局目录

macOS 系统路径为 /Library/Application Support/ClaudeCode/CLAUDE.md，Linux 系统路径为 /etc/claude-code/CLAUDE.md。

此层级由 IT 或 DevOps 团队统一部署，对所有用户强制生效，且不可被个人设置覆盖。

适合定义公司级别的安全策略、合规性要求及统一的编码基础标准。例如：“所有 API 密钥必须从环境变量读取”、“严格禁止使用 eval() 函数”等强制性规定。

三层配置的优先级从高到低依次为：项目级 > 个人级 > 组织级。举例说明，若项目级 CLAUDE.md 规定“使用 2 空格缩进”，而个人级配置为“使用 4 空格”，最终 Claude Code 将遵循项目级规则。

编写高效 CLAUDE.md 的四大核心原则

许多开发者配置了 CLAUDE.md 但效果不佳，问题往往不在于功能，而在于编写方式。遵循以下四个原则，可显著提升配置效果。

原则一：指令明确具体，避免模糊描述

Claude Code 无法“理解”模糊的审美偏好或笼统期望，它需要清晰、可执行的明确指令。

# ❌ 模糊低效的写法
- 代码风格要优雅美观
- 测试覆盖要全面充分

# ✅ 清晰具体的写法
- 统一使用 2 个空格缩进，单行代码长度不超过 100 个字符
- 每个公共函数至少编写一个单元测试，需覆盖正常执行路径及一个边界情况

指令越具体，AI 的执行准确度越高。

原则二：控制文档长度，建议 200 行以内

CLAUDE.md 的内容会占用 Claude 模型的上下文窗口。文档过长会导致两个明显问题：一是消耗宝贵的 Token 额度，挤占实际对话空间；二是规则条目过多，Claude Code 可能“遗忘”部分内容。

官方建议：单个 CLAUDE.md 文件最好控制在 200 行以内。若规则确实繁多，可考虑拆分管理。

原则三：善用 Markdown 层级结构

Claude Code 解析 CLAUDE.md 的方式类似于人类阅读文档——拥有清晰标题和层级结构的内容更容易被“记忆”和遵循。

# ✅ 结构清晰的写法
## 项目构建命令
- 启动开发环境：pnpm dev
- 执行测试套件：pnpm test

## 代码命名规范
- 组件名称采用 PascalCase
- 工具函数采用 camelCase

# ❌ 结构混乱的写法
我们项目用pnpm，开发用pnpm dev，测试用pnpm test，组件用PascalCase命名，工具函数用camelCase...

清晰的层级能极大提升规则的可读性与 AI 的执行效率。

原则四：避免规则冲突，保持一致性

规则相互矛盾是最棘手的情况。例如，项目级 CLAUDE.md 要求“使用双引号”，而某子目录的规则文件却规定“使用单引号”，这可能导致 Claude Code 困惑甚至随机选择。

解决方案是定期检查 CLAUDE.md 文件，及时删除过时或矛盾的规则，确保所有指令协调一致。

进阶技巧：使用 .claude/rules/ 目录拆分规则

随着项目规模增长，将所有规则塞入单一文件显然不现实。.claude/rules/ 目录应运而生，它允许你按主题将规则拆分到不同的文件中。

your-project/
├── .claude/
│   ├── CLAUDE.md          # 项目核心配置总纲
│   └── rules/             # 按主题拆分的规则目录
│       ├── code-style.md  # 代码风格规范
│       ├── testing.md     # 测试规范
│       ├── security.md    # 安全开发规范
│       └── frontend/
│           └── react-patterns.md # 前端 React 特定模式

每个 .md 文件即为一组独立的规则集，文件名直接体现主题，便于管理。

更强大的是路径匹配功能。你可以让特定规则仅在处理匹配的文件时才生效：

---
paths:
- "src/api/**/*.ts"
---
# API 层开发规范
- 所有接口必须进行入参校验
- 使用统一的错误响应格式
- 必须添加 OpenAPI 注释

上述规则仅在 Claude Code 处理 src/api/ 目录下的 TypeScript 文件时才会被加载。当它处理前端组件时，则完全看不到此规则，从而节省宝贵的上下文空间。

以下是一些常用的路径匹配模式示例：

使用 @import 语法引用外部文件

CLAUDE.md 支持使用 @ 语法引入其他文件的内容，有效避免内容重复和维护多个副本。

项目整体介绍请参考 @README.md，可用脚本命令请查看 @package.json。
# 补充说明
- Git 协作流程详见 @docs/git-workflow.md

被引用的文件会在 Claude Code 启动时自动展开并加载。支持相对路径和绝对路径，最多支持 5 层嵌套引用。

这里有一个实用技巧：你可以在项目级 CLAUDE.md 中引用个人配置文件，这样既能应用个人偏好，又无需将这些私人设置提交至团队仓库。

# 个人开发配置（不提交至版本库）
- @~/.claude/my-project-prefs.md

Auto Memory：让 Claude Code 自动积累经验

除了手动编写的 CLAUDE.md，Claude Code 还具备一套自动记忆系统，可视为它的“学习笔记”。

在日常协作中，它会自动记录有价值的信息：例如某个复杂的构建命令如何成功执行、某个调试技巧、或你反复纠正的某个偏好。这些笔记存储在 ~/.claude/projects/<项目名>/memory/ 目录下。

Auto Memory 与 CLAUDE.md 的主要区别如下：

两者形成互补关系。你负责制定规则框架，它负责记忆项目实践中的具体经验。

你可以随时输入 /memory 命令查看和编辑所有记忆文件。如果发现记忆有误，直接修改或删除即可。

实战案例：一个真实项目的配置示例

以下是一个真实项目案例。这是一个名为 poi-cloud-operation 的中后台系统，基于 Vue 2 + TypeScript 构建。

poi-cloud-operation/
├── CLAUDE.md          # 项目核心配置总纲
├── .claude/
│   ├── settings.json  # 权限相关配置
│   └── rules/         # 拆分后的规则目录
│       ├── api-rules.md      # API 开发规范（paths: src/api/**, src/services/**）
│       ├── store-rules.md    # Vuex 状态管理规范（paths: src/store/**）
│       └── component-rules.md # 组件开发规范（paths: src/components/**）

项目根目录的 CLAUDE.md 仅包含最核心、全局性的信息：

# poi-cloud-operation 项目配置
技术栈：Vue 2.6 + TypeScript 3.7 + Element UI

## 核心脚本命令
- 启动本地开发服务器：yarn serve
- 启动联调环境：yarn serve-test
- 执行构建：yarn build（开发环境）/ yarn build-pre（预发布）/ yarn build-pro（生产环境）

## 主要技术栈
- 核心框架：Vue 2 + vue-class-component（装饰器写法）
- 状态管理：Vuex
- UI 组件库：Element UI + Poieta UI（内部组件库）
- 图表库：ECharts 4/5 + AntV X6（流程图）
- 构建工具：Vue CLI 4

## 项目目录结构
- src/api/ - API 接口定义层
- src/services/ - 业务逻辑层（复杂数据处理）
- src/store/ - Vuex store，按模块拆分
- src/components/ - 通用组件，采用大驼峰命名法
- src/account/ - 账户管理功能模块
- src/utils/ - 工具函数集
- src/@types/ - 全局 TypeScript 类型定义

## 代码规范细则
- 包管理器：统一使用 yarn，禁止使用 npm
- 换行符：LF（已在 .prettierrc 中配置）
- 代码缩进：2 个空格
- 单行长度：120 个字符（Prettier 已配置）
- 组件写法：使用 class 组件风格，配合 @Component 装饰器
- 类型定义：开启 strict 模式，避免使用 any，接口名称以 I 为前缀（例如 IUserInfo）
- API 调用：统一通过 api/ 目录管理，禁止在 Vue 文件中直接编写 axios 调用

## 重要注意事项
- 项目包含多个环境配置文件（.env.local, .env.dev 等），修改时请确认目标环境
- 使用了内部私有包 @poit/*，执行 install 前请确认 registry 配置正确
- 项目体积较大，开发时内存占用较高，请注意避免内存溢出（OOM）

@README.md

将这套清晰的规则写入 CLAUDE.md 后，Claude Code 在编写代码时便能自动做到：使用 class 组件而非 options API、将 API 请求抽象至 services 层而非直接写在页面中、为类型定义添加 I 前缀、使用 yarn 而非 npm install。

整个配置的核心在于：简洁、具体、结构化。Claude Code 读取后便能明确如何开展工作。

总结

归根结底，CLAUDE.md 的本质可以概括为一句话：将你脑海中的项目规范，转化为 Claude Code 能够理解的明确文档。

你写得越具体、越清晰，Claude Code 的表现就越稳定、越可预测。你写得越模糊、越笼统，它就越倾向于“猜测”，结果自然难以令人满意。

最实用的建议是从 /init 命令开始，生成一份基础配置，然后每当发现 Claude Code 在某项任务上“不听话”时，就将对应的规则补充进去。无需几日，你便能积累出一份高度定制化、极其高效的 CLAUDE.md 配置。

这份配置一旦完善，便成为你的重要开发资产。更换项目或电脑均可随身携带，一劳永逸。投入时间进行配置，绝对物超所值。