Claude学院

Claude Code CLAUDE.md 配置文件怎么写？完整模板

CLAUDE.md 是放在项目根目录的纯 Markdown 文件，Claude Code 每次启动会自动把它读进上下文，当作这个项目的"长期记忆"。你在里面写清楚技术栈、构建命令、代码规范和目录约定，Claude 就不必反复问、也不会乱猜。最快的起步方式是在项目目录运行 /init，让它扫描代码库自动生成一份草稿，再按需精修。

CLAUDE.md 放在哪里：四个加载层级

Claude Code 会从多个位置查找并合并配置文件，层级从近到远依次叠加，越靠近当前目录的优先级越高：

  • 项目根目录 ./CLAUDE.md：团队共享，应提交进 Git，是最常用的一份。
  • 子目录 ./packages/api/CLAUDE.md：进入该子目录工作时按需加载，适合 monorepo 的分包约定。
  • 个人本地 ./CLAUDE.local.md：放个人偏好，记得加进 .gitignore，不污染团队配置。
  • 全局 ~/.claude/CLAUDE.md：对你所有项目生效的通用习惯，比如"回答用中文"。

多份文件不是互斥关系，而是合并叠加。把通用习惯放全局，把项目规范放根目录，把私人小动作放 local，这样既共享又不互相干扰。

一份完整的 CLAUDE.md 模板

下面这份模板覆盖了绝大多数项目需要的字段，直接复制到根目录改成你自己的内容即可。注意它就是普通 Markdown，用标题分节，Claude 对结构清晰的文件理解得更好。

# 项目说明

## 项目概览
这是一个基于 Astro 的静态站群 CMS，前端 SSG 输出，后端 Go 控制面，
内容存储在 ClickHouse。核心目标：批量生产高质量 SEO 站点。

## 技术栈
- 语言：TypeScript (前端) / Go 1.22 (后端)
- 框架：Astro 4 + Tailwind CSS
- 数据库：ClickHouse、Redis（缓存）
- 包管理：pnpm（不要用 npm/yarn）

## 常用命令
- 安装依赖：`pnpm install`
- 本地开发：`pnpm dev`（端口 4321）
- 构建：`pnpm build`
- 跑测试：`pnpm test`（基于 Vitest）
- 代码检查：`pnpm lint && pnpm typecheck`

## 代码规范
- 缩进 2 空格，禁用 Tab
- 组件用 PascalCase，工具函数用 camelCase
- 提交前必须通过 lint 和 typecheck
- 不要引入未在 package.json 声明的依赖

## 目录约定
- `src/pages/`：路由页面
- `src/components/`：可复用组件
- `src/lib/`：纯逻辑工具，不依赖 UI
- 测试文件与源码同目录，命名 `*.test.ts`

## 注意事项
- 改完代码要主动运行 typecheck，报错先修再说
- 涉及数据库迁移先问我，不要直接改 schema
- 提交信息用中文，遵循 Conventional Commits

写好 CLAUDE.md 的几条原则

很多人把 CLAUDE.md 写成一篇长文档，反而稀释了关键信息。它的作用是"约束模型行为"，不是给人看的教程，所以：

  1. 短而具体：用祈使句写明确指令，比如"用 pnpm 不要用 npm"，而不是大段背景介绍。每一行都应该是模型能执行的约束。
  2. 命令要可运行：把真实命令原样写进去，Claude 会直接拿去执行，写错命令比不写更糟。
  3. 用 Markdown 结构分节：清晰的标题层级让模型更容易定位信息，这点和写系统提示词的逻辑一致。
  4. 持续迭代：当 Claude 反复犯同一个错，就把纠正写进 CLAUDE.md。你也可以在会话里用 # 开头快速追加一条记忆。

用 @import 引用其他文件

CLAUDE.md 支持用 @路径 语法引入其他文件内容，避免把所有东西堆在一份文件里。例如把详细的代码规范单独抽出来：

## 详细规范
代码风格见 @docs/coding-style.md
API 约定见 @docs/api-conventions.md
@~/.claude/my-personal-rules.md

这样根目录的 CLAUDE.md 保持精简，细节按需引入。引用的文件同样会被读进上下文，注意控制总量，太长会挤占上下文窗口，也会增加 Token 消耗。如果担心成本，可以参考降低 Token 成本的方法。

和子代理、斜杠命令的配合

CLAUDE.md 是项目级的全局上下文，但它不是唯一的扩展手段。当某类任务需要独立的指令集时，更适合用子代理（Subagent）把职责拆开；重复操作则可以做成自定义斜杠命令，比如一个 /deploy 命令封装完整发布流程。CLAUDE.md 负责"模型永远要知道的事"，斜杠命令负责"按需触发的动作"，两者分工明确。如果你刚装好工具还不熟悉，先看常用命令大全会更顺。

常见问题

CLAUDE.md 改了不生效怎么办？

CLAUDE.md 在会话启动时加载，改完后需要重启会话或新开一个会话才会读到最新内容。如果在长会话中临时改动，用 /init 重新生成或 /clear 后重新进入会话。另外确认文件名拼写完全正确（区分大小写为 CLAUDE.md），且位于当前工作目录或其上级。

CLAUDE.md 会消耗 Token 吗？需要担心太长吗？

会。它作为系统上下文的一部分随每次请求发送，越长占用越多。建议把根目录的 CLAUDE.md 控制在精炼范围，细节用 @import 按需引入。具体计费方式以 Anthropic 官网为准，省钱思路可参考相关 Token 成本优化文章。

CLAUDE.md 和 .cursorrules、AGENTS.md 是一回事吗？

作用类似，都是给 AI 编码工具的项目级指令文件，但格式和加载机制由各工具自行定义，互不通用。CLAUDE.md 是 Claude Code 官方约定的文件名，其他工具不会读取它，反之亦然。如果同时用多个工具，需要分别维护对应的配置文件。

← Claude Code