CLAUDE.md 完全指南：把Claude Code调教成你的专属编程搭档

小凡同志
4 阅读7分钟

CLAUDE.md 完全指南：把Claude Code调教成你的专属编程搭档

每次打开Claude Code，它都像个失忆的新同事。昨天刚告诉它"我们项目用pnpm"，今天又开始给你写npm install。

问题出在哪？你没给它写"员工手册"。

这个手册就是CLAUDE.md。写好了，Claude Code就是一个懂你项目规范、记得住你偏好的编程搭档。写不好，它每次都在猜。

这篇文章把CLAUDE.md的配置体系拆开讲，从基础到进阶，看完直接能用。

先搞清楚：CLAUDE.md到底是什么

CLAUDE.md是一个Markdown文件，放在项目里，Claude Code每次启动都会读它。

你可以把它理解成给AI写的README。里面写什么，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

放在Home目录下，只对你自己生效，所有项目通用。

写什么：你的个人偏好，不适合提交到项目仓库的东西。

# 个人偏好

- 回复用中文
- commit message用英文，遵循Conventional Commits
- 优先用函数式写法，少用class
- 解释代码时简洁直接，不要啰嗦

3. 组织级：系统目录

macOS放在 /Library/Application Support/ClaudeCode/CLAUDE.md，Linux放在 /etc/claude-code/CLAUDE.md。

由IT/DevOps统一部署，所有人强制生效，不能被个人设置覆盖。

适合写：公司安全规范、合规要求、统一编码标准。

优先级从高到低：项目级 > 个人级 > 组织级。 如果项目CLAUDE.md说"用2空格"，个人CLAUDE.md说"用4空格"，最终按项目的来。

写好CLAUDE.md的4个原则

很多人写CLAUDE.md效果不好，不是功能的问题，是写法的问题。

原则一：具体，不要模糊

# ❌ 模糊
- 代码要写得好看
- 测试要充分

# ✅ 具体
- 使用2空格缩进，单行不超过100字符
- 每个公共函数至少一个单元测试，覆盖正常路径和一个边界情况

Claude Code不会"理解"你的审美，它需要明确的规则。

原则二：控制长度，200行以内

CLAUDE.md的内容会占用上下文窗口。写太长，两个问题：

  1. 消耗token，留给实际对话的空间变少
  2. 规则太多，Claude Code反而容易"忘记"某些条目

官方建议：单个CLAUDE.md控制在200行以内。超了就拆分。

原则三：用Markdown结构化

Claude Code扫描CLAUDE.md的方式跟人读文档一样——有标题、有层级的内容更容易被"记住"。

# ✅ 结构清晰
## 构建命令
- 开发：pnpm dev
- 测试：pnpm test

## 代码规范
- 组件用PascalCase
- 工具函数用camelCase

# ❌ 一坨文字
我们项目用pnpm，开发用pnpm dev，测试用pnpm test，组件用PascalCase命名，工具函数用camelCase...

原则四：避免规则冲突

如果项目CLAUDE.md说"用双引号"，某个子目录的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

每个 .md 文件就是一组规则，文件名就是主题。

更强大的是路径匹配。规则可以只在处理特定文件时生效：

---
paths:
  - "src/api/**/*.ts"
---

# API开发规范

- 所有接口必须做入参校验
- 使用统一的错误响应格式
- 添加OpenAPI注释

这条规则只有在Claude Code处理 src/api/ 下的TypeScript文件时才会加载。处理前端组件时不会看到它，不浪费上下文。

常用的路径匹配模式：

模式匹配
**/*.ts所有TS文件
src/components/*.tsx组件目录下的TSX
**/*.test.ts所有测试文件
src/**/*.{ts,tsx}src下所有TS和TSX

用 @import 引用外部文件

CLAUDE.md支持用 @ 语法引入其他文件：

项目概览见 @README.md，可用脚本见 @package.json。

# 补充说明
- Git工作流 @docs/git-workflow.md

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

一个实用技巧：在项目CLAUDE.md里引用个人配置，这样个人偏好不用提交到仓库：

# 个人配置（不提交）
- @~/.claude/my-project-prefs.md

Auto Memory：让Claude Code自己记笔记

除了你手写的CLAUDE.md，Claude Code还有一套自动记忆系统。

它会在协作过程中自己记录有用的信息：构建命令、调试技巧、你的偏好。这些笔记存在 ~/.claude/projects/<项目>/memory/ 目录下。

跟CLAUDE.md的区别：

CLAUDE.mdAuto Memory
谁写的你Claude Code自己
内容规则和指令学到的经验
作用域项目/个人/组织当前项目

两者互补。你定规矩，它记经验。

输入 /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（dev环境）/ 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/ - 全局类型定义

## 代码规范
- 包管理：用 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.md的本质就一句话：把你脑子里的项目规范，写成Claude Code能读懂的文档。

你写得越具体，Claude Code表现越稳定。你写得越模糊，它就越爱猜。

建议从 /init 开始，生成一份基础版本，然后每次发现Claude Code"不听话"的时候，就把对应的规则补上去。用几天就能攒出一份好用的CLAUDE.md。

这东西一旦配好，换项目、换电脑都能带着走。值得花时间搞一搞。

avatar
文章
阅读
粉丝