Claude Code 通关指南

Appearance

2.7 CLAUDE.md 与项目配置 ​

预计耗时：15 分钟

本关任务简报 ​

有没有遇到过这种情况：每次开新对话，都要先跟 Claude 解释"这个项目用的是 TypeScript，回复我用中文，不要乱改我没让你改的地方"？

重复解释背景是因为 Claude 没有跨会话的记忆——每次启动都是一张白纸。CLAUDE.md 就是解决这件事的工具：把你想让 Claude 始终知道的内容写进这个文件，它每次启动都会自动读取，不需要你重复说。

一份好的 CLAUDE.md，是让 Claude 长期高效工作性价比最高的一次投入。

通关奖励：解锁以下技能 ​

  • 📝 知道 CLAUDE.md 是什么以及它的工作原理
  • 📋 能写出一份有效的项目级 CLAUDE.md
  • 🌐 知道全局 CLAUDE.md 适合放什么内容
  • 📂 理解三级文件层次，知道哪层写什么
  • ⚙️ 分清 CLAUDE.md 和 settings.json 各管什么

开始前先检查装备 ​

前置知识说明
1.3 第一次对话 →和 Claude Code 有过基本对话体验，知道什么是"上下文"
1.4 初始化项目 →用过 /init，理解"项目级配置"的概念——CLAUDE.md 是它的核心产出

机制解析 ​

CLAUDE.md 是怎么工作的 ​

Claude Code 在每次启动时，会自动找到并读取 CLAUDE.md，将其内容加入对话上下文的最开始。这意味着：

  • 你写的每一条约定，Claude 在第一次回复前就已经看到了
  • 它不是"备忘录"，是直接影响 Claude 行为的指令
  • 文件更新后，下次启动立即生效

三级文件层次 ​

Claude Code 会同时读取多个位置的 CLAUDE.md，全部叠加拼接进上下文（不是互相覆盖）：

文件位置作用范围是否纳入 Git
~/.claude/CLAUDE.md全局，所有项目通用否（个人配置，不同步）
./CLAUDE.md 或 ./.claude/CLAUDE.md当前项目，团队共享推荐提交
./CLAUDE.local.md当前项目，仅你自己否（应加进 .gitignore）

加载顺序：从全局到项目逐层叠加，越靠后（越接近项目）的内容离 Claude 的"注意力"越近；同一件事多处都写时，以更具体的项目级表述为准。（注意：CLAUDE.md 是拼接，不是覆盖；settings.json 才是上层覆盖下层。）

项目级 CLAUDE.md：告诉 Claude 这个项目是什么 ​

放在项目根目录或 .claude/CLAUDE.md，写当前项目特有的信息。推荐包含这几块：

markdown
# 项目名称

## 项目概述
一两句话说明这个项目是做什么的，面向什么用户。

## 技术栈
- 语言：TypeScript 5.x
- 框架：Next.js 14（App Router）
- 数据库：PostgreSQL + Prisma
- 测试：Vitest + Testing Library

## 开发命令
- 启动开发服务器：`npm run dev`
- 运行测试：`npm test`
- 类型检查：`npm run typecheck`
- 构建：`npm run build`

## 重要约定
- 使用 async/await，不用 .then() 链
- 组件文件用 PascalCase，工具函数用 camelCase
- 不要修改 src/generated/ 下的文件（自动生成，改了会被覆盖）
- PR 提交前必须通过 typecheck 和 lint

## 项目结构
- src/app/ — Next.js App Router 页面
- src/components/ — 共享 UI 组件
- src/lib/ — 工具函数和配置
- prisma/ — 数据库 Schema 和迁移

全局 CLAUDE.md：你跨项目的通用设定 ​

放在 ~/.claude/CLAUDE.md，写在所有项目里都成立的内容。第一次配置时，不需要写很长，先把最关键的几块写清楚就够了：

markdown
## 关于我
[你的名字 / 技术背景]。
我用 Claude Code 主要做 [前端开发 / 数据分析 / 写作等]。

## 沟通方式
- 默认中文回复，代码和命令用英文
- 结论先行，再给理由
- 遇到模糊需求，给最合理的方案，不要反复问我确认
- 发现更好的做法直接说，不用等我问

## 自主边界（这些情况必须先问我）
- 删除文件、目录或 git 历史
- 修改 .env、密钥、token、CI/CD 配置
- git push、git reset --hard、强制推送
- 部署到生产或对外发布内容

## 工程习惯
- 改完主动跑验证，不要只改不验
- 密钥、token 不进代码、不进 commit
- 大改动前先出方案，我确认后再动手
- 不要为了让代码跑通而绕过错误或注释掉校验

判断内容放哪一级 ​

一个简单原则：

  • 换到别的项目里依然成立 → 放全局 ~/.claude/CLAUDE.md
  • 只对当前项目有意义、要和团队共享 → 放项目根目录 CLAUDE.md（或 .claude/CLAUDE.md）
  • 只对你自己生效、不想提交给团队 → 放 CLAUDE.local.md（并加进 .gitignore）

常见误区：把构建命令、目录结构、某条接口约定写进全局配置——这些换个项目完全不适用，应该放项目级。

用 @ 导入其他文件 ​

CLAUDE.md 里可以用 @路径 把别的文件"拉进来"一起加载，避免把内容抄一遍：

markdown
项目说明见 @README.md，可用脚本见 @package.json。

# 开发规范
- Git 流程见 @docs/git-workflow.md

启动时这些被引用的文件会和 CLAUDE.md 一起进上下文。相对路径是相对该 CLAUDE.md 文件所在位置解析的，且支持递归导入（最多 4 层）。

适合复用已有的 README、规范文档，而不是重复粘贴。但被导入的文件同样占上下文，别导入太大的文件。

长度建议 ​

精简比完整更重要

CLAUDE.md 不是越长越好。信息越集中，Claude 越容易在实际工作中持续遵守。

全局 CLAUDE.md 控制在 80 行左右，不要超过 200 行。项目级可以稍长，但如果超过 300 行，建议考虑是否有些内容其实更适合放进记忆系统（见 2.8 →）。

快速生成初始模板 ​

不知道从哪里开始？让 Claude 帮你：

text
> /init

/init 会分析当前项目目录，自动生成一份 CLAUDE.md 草稿，你在此基础上修改比从零写更快。

不要放进去的内容 ​

敏感信息

API Key、密码、数据库连接字符串等敏感信息绝对不能写进 CLAUDE.md，尤其是会被 Git 提交的项目根目录版本。

另一个配置文件：settings.json ​

CLAUDE.md 是写给 Claude"看"的自然语言指令；还有一个 settings.json 是结构化的"开关面板"，管的是 Claude 能做什么、怎么跑——权限规则、Hooks、默认模型、环境变量等。两者的差异对比：

CLAUDE.mdsettings.json
写什么自然语言的约定和说明结构化的配置项（JSON）
管什么影响 Claude 的"判断和风格"权限、Hooks、模型、环境变量等"硬规则"
典型内容技术栈、规范、自主边界permissions / hooks / model / env

放在哪（和 CLAUDE.md 层次逻辑相同）：

  • 用户级：~/.claude/settings.json（对你所有项目生效）
  • 项目级：.claude/settings.json（随项目提交、团队共享）
  • 个人本地：.claude/settings.local.json（应 gitignore，不提交）

你在 2.4 权限系统 配 permissions、2.9 Hooks 系统 配 hooks，都是在这个文件里进行操作。完整可配字段在 工具箱 · E. 配置选项速查 →

开始闯关 ​

目标：创建或完善你的全局 CLAUDE.md。

第 1 步：查看当前全局配置

text
/memory

或者直接打开文件：

bash
code ~/.claude/CLAUDE.md

如果文件不存在，用文本编辑器创建它。

第 2 步：参考上面的模板，写入这 4 块内容

  • 关于我（你是谁）
  • 沟通方式（你希望 Claude 怎么回应你）
  • 自主边界（什么情况必须先问你）
  • 工程习惯（做事的通用原则）

不需要写很长，每块 3-5 条就够。

第 3 步：验证生效

保存后重新启动 Claude Code，然后问它：

text
你知道关于我的哪些信息？

Claude 应该能列出你在 CLAUDE.md 里写的内容。

通关检定 ​

  • [ ] 知道 CLAUDE.md 的三级层次及各自的作用范围
  • [ ] 全局 ~/.claude/CLAUDE.md 里已经有基础配置（沟通方式 + 自主边界）
  • [ ] 能用 /init 为一个项目生成初始模板
  • [ ] 知道什么内容不适合放进 CLAUDE.md（敏感信息、特别项目化的内容）
  • [ ] 重启后验证，Claude 能读到你写的内容

全部点亮就算通关 ✓

卡关了？翻车指南在这 ​

写了 CLAUDE.md，但 Claude 好像没有遵守里面的约定

踩坑清单：① 确认文件路径正确（全局是 ~/.claude/CLAUDE.md，不是项目根目录）；② 文件是否保存了；③ 重启 Claude Code 后才生效，不会在当前会话中途加载；④ 内容是否太长，导致 Claude 在实际对话中没有足够关注到。

/init 生成的内容不准确

/init 会读取项目文件做分析，如果项目文件不多或结构不清晰，生成质量会一般。把它当草稿，手动补充和修正里面不准确的部分。

不知道项目级和全局哪个配置在生效

两者同时生效并叠加，项目级会覆盖全局里相同的配置项。如果有冲突，以项目级为准。用 /memory 命令可以查看当前生效的全部内容。

下一关 ​

2.8 内存与记忆系统 →

CLAUDE.md 需要你手动维护，记忆系统是 Claude 主动积累的动态知识——这一关告诉你两者如何配合，让 Claude 越用越懂你。

面向公开用户维护，内容基于 Claude Code 官方文档与真实使用经验整理

© 2026 Claude Code 通关指南