核心概念 #
CLAUDE.md是Claude Code的核心配置文件，它相当于项目的**”说明书”**，告诉Claude如何理解和处理你的代码库。一个好的CLAUDE.md可以显著提升AI的理解准确性和工作效率。我结合自己的项目来说明如何写一个配置。
其作用如下：
- 上下文设置：为Claude提供项目背景、技术栈、架构信息
- 约束定义：设定开发规范、代码风格、质量标准
- 任务指导：提供明确的执行指令和优先级
- 知识传承：保存项目的重要决策和设计理念
为什么重要？
- 减少沟通成本：避免重复解释项目背景
- 提升准确性：使Claude更好地理解你的意图
- 保持一致性：确保所有修改都符合项目规范，在团队合作中保持代码的一致性
- 加速开发：减少调试和返工时间
工作原理 #
当你在项目目录启动 Claude Code 时，发生的“记忆系统初始化”过程如下图所示。
CLAUDE.md 的内容会每次对话都加载，所以要精简。把“每次都需要”的内容放这里，把“偶尔需要”的内容放到 Skills 或文档里。
Claude Code 支持五个层级的记忆，就像洋葱一样，从外到内，按层级结构组织——高层级的文件优先加载，为底层文件提供基础：
其中每个层级都有其用途及使用场景，如下所示：
| 记忆类型 | 位置 | 用途 | 使用场景 | 共享范围 |
|---|---|---|---|---|
| 企业策略 | macOS:/Library/ApplicationSupport/ClaudeCode/CLAUDE.md Linux: /etc/claude-code/CLAUDE.md Windows: C:\Program Files\ClaudeCode\CLAUDE.md |
组织级指令，由 IT/Devops管理 | 公司编码标准、安全策略、合规要求 | 组织内所有用户 |
| 项目记忆 | ./CLAUDE.md或者./claude/CLAUDE.md（必须提交到git） | 团队共享的项目指令 | 项目架构，编码标准，常用工作流 | 通关版本管理与团队成员共享 |
| 模块记忆 | ./claude/rules/*.md | 模块化的、特定主题的项目指令 | 语言特定指南、测试规范、API标准 | 通关版本管理与团队成员共享 |
| 用户记忆 | ~/.claude/CLAUDE.md | 跨所有项目的个人偏好 | 代码风格偏好、个人工具快捷方式 | 仅自己 |
| 项目本地 | ./CLAUDE.local.md（记得把他加到.gitignore） | 跨所有项目的个人偏好 | 你的沙箱URL、偏好的测试数据 | 仅自己 |
基础结构 #
项目记忆一般来说是整个开发过程中最常用的“说明书”了，一个完整的项目CLAUDE.md文件包含以下几个部分：
## CLAUDE.md
## 项目概述
[project]
## 技术栈
[stack]
## 开发指令
[commands]
## 架构和约束
[architecture]
## 当前任务
[tasks]核心字段 #
项目概述 #
项目概述的作用是描述项目的基本信息和目标，关键信息：
- 项目名称和版本
- 业务目标和价值主张
- 目标用户和使用场景
- 项目状态和进展
示例：
## 项目概述
**项目名称**：Virtual Library - 虚拟文档平台
**当前版本**：v0.0.0
**项目状态**：首次开发，正在开发第一个mvp版本v0.0.1
**业务目标**：为用户提供虚拟文档浏览、下载
**核心价值**：简单易用、数据安全技术栈 #
作用：列出项目使用的技术和工具
关键信息：
- 前端框架和版本
- 后端技术栈
- 数据库和中间件
- 部署和开发工具
示例：
## 技术栈
**后端**：
- Golang v1.24.1 + gin
- gorm + mysql
- logrus + viper
- 腾讯与COS + 万象CI预览
- JWT 身份验证
**工具链**：
- CI/CD：GitHub Actions + Vercel开发指令 #
作用：定义常用的开发命令和脚本
重要性：Claude可以自动执行这些命令，提高工作效率
示例：
make test
make run
make deploy项目架构 #
作用：定义代码组织结构和开发规范
关键信息：
- 目录结构说明
示例：
virtual-library/
├── main.go # 入口文件
├── config.yaml # 配置文件
├── go.mod
├── Makefile
├── internal/ # 业务代码
│ ├── dao/ # 数据访问层（按模块）
│ │ ├── doc.go # 文档相关
│ │ ├── user.go # 用户相关
│ │ └── order.go # 订单相关
│ ├── handler/ # HTTP 处理器（按模块）
│ │ ├── doc.go # 文档相关
│ │ ├── user.go # 用户相关
│ │ ├── admin.go # 管理后台
│ │ ├── payment.go # 支付相关
│ │ ├── upload.go # 文件上传
│ │ └── handler.go # 公共函数
│ ├── middleware/ # 中间件
│ ├── router/ # 路由设置
│ ├── service/ # 业务逻辑（按模块）
│ │ ├── service.go # 主服务
│ │ ├── doc.go # 文档相关
│ │ ├── user.go # 用户相关
│ │ └── order.go # 订单相关
│ └── server/ # HTTP 服务器封装
└── pkg/ # 通用库（可被外部引用）
├── config/ # 配置加载
├── database/ # 数据库连接
└── logger/ # 日志最佳实践 #
1. CLAUDE.md 维护 #
- 定期更新：至少每周review一次
- 版本控制：与Git一起管理，重大更新做标记
- 团队同步：重要更改后及时通知团队成员