Appearance
04 · 项目初始化与 CLAUDE.md
📚 系列导航：上一篇 03 工作原理与 API 配置 讲清了 Claude Code 怎么干活。这一篇解决一个最高频的问题：每次开新会话它都不记得上次的事，怎么让项目规矩「一次写入，长期生效」？
01 问题：Claude 的「失忆」
每个 Claude Code 会话都从全新的上下文窗口开始。你上次交代的「用 pnpm 不用 npm」「测试在 tests/ 目录」「提交前跑 lint」，这次它一概不记得。
CLAUDE.md 就是解决这个问题的——它是 Claude 每次开工必读的「入职手册」，把项目的规矩一次性写进去，之后每次会话都自动遵守。
02 /init：一键生成 CLAUDE.md 草稿
/init 是 Claude Code 内置的斜杠命令，作用：让 Claude 自己扫描项目，把客观事实（技术栈、目录结构、常用命令）整理成 CLAUDE.md 草稿。
操作：
bash
cd /path/to/your-project
claude在输入框敲 /init，回车。Claude 自动扫描项目结构、识别技术栈、落盘 CLAUDE.md。
NOTE
重要：
- 一定要在项目根目录启动
claude再敲/init。 - 项目里已有 CLAUDE.md 时，
/init不会覆盖，只建议改进。 /init生成的是草稿，不是终稿——团队约定、部署流程这些它扫不到的硬约束，必须你人工补。
03 CLAUDE.md 三层级
| 层级 | 放哪 | 管多大范围 | 进不进 git |
|---|---|---|---|
| 用户级 | ~/.claude/CLAUDE.md | 你这台机器上所有项目 | ❌ 不进 |
| 项目级 | ./CLAUDE.md 或 ./.claude/CLAUDE.md | 当前项目 | ✅ 进 |
| 子目录级 | 任意子目录/CLAUDE.md | Claude 读到那个目录时才加载 | ✅ 进 |
| 本地级（变体） | ./CLAUDE.local.md | 当前项目，仅你自己 | ❌ 加进 .gitignore |
加载顺序：从最广到最具体依次加载，拼接不覆盖。越靠近工作目录的指令越晚读，冲突时越占优。
实际分工：个人习惯（如「回复用中文」「改代码前先说思路」）放用户级，团队规矩（技术栈、命令、禁改清单）放项目级，大仓库多模块时用子目录级拆。
04 该写什么 vs 不该写什么
✅ 该写
| 类别 | 说明 | 例子 |
|---|---|---|
| 项目概述 | 一句话说清项目是干嘛的 | 「基于 FastAPI 的订单管理后端」 |
| 技术栈 | 语言、框架、数据库、关键工具 | 「Python 3.11 / PostgreSQL / pytest」 |
| 常用命令 | 测试、构建、检查怎么跑 | uv run pytest、uv run ruff check . |
| 代码约定 | 风格、命名、必须遵守的写法 | 「函数必须有类型注解」「字符串用双引号」 |
| 明确的「不要做」 | 雷区、禁改文件、必须先问的操作 | 「禁改 migrations/ 已有文件」 |
❌ 不该写
- 长篇背景（公司介绍、产品愿景、技术选型历史）
- 过时信息（换了包管理器没更新 CLAUDE.md）
- Claude 看代码能自己推出来的东西（目录结构、ESLint 已定义的代码风格）
- 正确的废话（「写干净的代码」）
好规矩长得像「规则」不是「散文」
| ❌ 模糊散文（没用） | ✅ 具体规则（管用） |
|---|---|
| 代码应该比较整洁 | 函数不超过 50 行，超了必须拆 |
| 尽量写测试 | 每个新增函数必须有对应单元测试 |
| 注意安全 | 用户输入必须先过 sanitize() 再进数据库查询 |
NOTE
200 行红线：全文目标 ≤ 200 行。CLAUDE.md 跟你的对话抢同一个上下文窗口，塞太多废话，重要规矩被淹在噪音里，遵守度反而下降。
05 引用其他文件：@ 语法
text
有关项目概述，请参阅 @README，可用命令见 @package.json。
git 工作流 @docs/git-instructions.mdWARNING
@ 引用不省上下文：@ 引用在启动时展开并加载到上下文中，被引用的文件照样全量进上下文。@ 是用来让结构更清爽，不是用来省 token 的。想省得真删内容。
06 维护：随手补 + 定期精简
会话里想补一条规矩：
text
把「数据库操作必须走 Service 层，别在路由里直接写 SQL」这条加进 CLAUDE.md或敲 /memory 列出所有已加载的记忆文件，自己编辑。
触发精简的时机： 换了包管理器/构建工具、加了或去了重要依赖、发现 CLAUDE.md 又悄悄涨过 200 行。
07 动手：最小项目跑通 /init
bash
mkdir init-demo && cd init-demo
echo '{"name": "init-demo", "scripts": {"test": "echo test ok"}}' > package.json
echo 'console.log("hello from init-demo");' > index.js
claude在输入框敲 /init，等待生成。退出后 cat CLAUDE.md 确认内容。再进 claude 问「这个项目的测试命令是什么？」——它应该直接回答，不用再去翻 package.json。
08 小结
| 知识点 | 关键结论 |
|---|---|
/init | 进新项目第一件事，让 Claude 自动生成 CLAUDE.md 草稿 |
| 三层级 | 用户级(个人) → 项目级(团队) → 子目录级(模块)，拼接加载 |
| 该写什么 | 概述/技术栈/命令/约定/禁区 |
| 不该写什么 | Claude 自己能推出来的、长篇背景、过时信息 |
| 维护 | 会话里直接让 Claude 加，定期精简到 ≤ 200 行 |
NOTE
下一篇：05 界面操作与快捷键：项目规矩写好了，接下来把手放对地方——界面认哪几块、快捷键怎么按才能快一倍。