04｜16 小时 Claude Code：用 `/init` 建立 CLAUDE.md 与项目结构

12 · 项目初始化：用 /init 一键生成 CLAUDE.md

兄弟们，先讲个常见的蠢操作。

刚上手 Claude Code 那阵，接手一个之前同事留下的 Node 后端项目，没跑 /init 就直接开干。第一次问「测试怎么跑」，它去翻了一圈 package.json 才回你；过了二十分钟开个新会话，同样的问题它又从头翻了一遍；下午换个任务，它第三次问「这个项目用的是 npm 还是 pnpm」。

到这一刻就真被它看烦了——不是它笨，是没给它一份「项目说明书」，它每次都得从零摸索一遍。等学会进项目先敲一个 /init，这些重复全没了：它一次性把项目摸清、写成一份 CLAUDE.md 存下来，之后每次会话开局就自带这份上下文，再也不用反复解释。

说白了，/init 就干一件事：把「Claude 每次重新认识你的项目」变成「认识一次，长期记住」。这一篇就讲清楚它怎么用、生成出来长啥样、到底帮你省了什么。

看完这一篇，你会拿到：

• 搞懂 /init 解决的核心痛点：从「每次重新摸索」到「一次生成长期记忆」
• 一套照着敲就行的操作：在项目根目录启动 claude，敲 /init
• 知道它背后做了什么：扫描结构、识别技术栈、生成 CLAUDE.md 草稿
• 看懂生成出来的 CLAUDE.md 大致长什么样、每一块是干嘛的
• 一个关键认知：/init 只是起点，草稿得人工补一刀（怎么补，留给第 18 篇）

01 为什么要有 /init：Claude 的「失忆」问题

先说结论：Claude Code 每次开新会话，都是「失忆」状态——它不记得你上次跟它说过什么。

这不是 bug，是它的设计。官方文档里写得明明白白：

每个 Claude Code 会话都从一个全新的上下文窗口开始。

类比：每天来上班都换一个新实习生。 这实习生本事不小，但有个毛病——今天教会他的事，明天来的是另一个人，全得重教。你跟他讲「我们用 pnpm 不用 npm」「测试在 tests/ 目录」「提交前要跑 lint」，第二天新的一个来了，又得从头讲一遍。

这就是没有 CLAUDE.md 时的真实状态。前面那个 Node 项目踩的坑就是这么来的——不是 Claude 记性差，是它压根没有跨会话的记忆载体。

那怎么办？官方给了两套跨会话传递知识的机制，这一篇只讲第一套：

注意自动记忆有个硬限制：每个会话只加载前 200 行或 25KB，超出部分不进上下文——所以靠自动记忆塞太多东西是靠不住的，CLAUDE.md 才是主力。

CLAUDE.md（项目记忆文件）就是那份写给「每天换人的实习生」看的入职手册——你提前写好放在项目里，Claude 每次开局先读一遍，立刻就「记起」这个项目是怎么回事。

而 /init，就是帮你把这份手册的初稿一键生成出来的命令。

💡 一句话总结：Claude 每次开会话都「失忆」，CLAUDE.md 是它跨会话的记忆载体——/init 帮你把这份记忆的初稿一键写出来。

02 /init 是什么：让 Claude 自己写自己的说明书

/init 是 Claude Code 内置的一个斜杠命令（slash command，输入框里以 / 开头的指令）。

它干的事，用一句话概括：让 Claude 自己扫描你的项目，生成一份专属于这个项目的 CLAUDE.md 草稿。

官方文档对它的描述很精准：

运行 /init 自动生成起始 CLAUDE.md。Claude 分析你的代码库并创建一个包含构建命令、测试指令和它发现的项目约定的文件。

类比：让新员工自己写一份入职手册。 一般入职手册是老员工写好给新人看的。但 /init 反过来——它让这个「新来的」先把整个项目自己读一遍，然后把读到的东西（用什么技术、目录怎么分、命令怎么跑）整理成一份手册。读得对不对，你回头审一眼就知道。

这么设计的好处很实在：项目里的客观事实（技术栈、目录结构、有哪些脚本命令），Claude 自己扫一遍就能扒出来，根本不用你一个字一个字敲。你省下的力气，留着去补那些它扫不出来的东西（比如团队的分支命名规范），就够了。

什么时候该用它？一般有这几个触发时机：

• 接手一个别人留下的项目——你自己都没摸熟，正好让它先扫一遍给你打底
• 自己的项目还没有 CLAUDE.md——一直在裸用，是时候补上了
• clone 下来一个开源项目想改改——先 /init 拿到项目地图，再动手

💡 一句话总结：/init 让 Claude 把项目自己读一遍，把客观事实整理成 CLAUDE.md 草稿——你省下扒事实的力气，专心补它扫不出的东西。

03 怎么跑：进目录、启动、敲命令

操作简单到有点反高潮——启动 claude 后，在输入框里敲 /init 就完事。

第一步：在项目根目录启动 Claude Code。

这一步是关键，一定要 cd 进项目的根目录再启动，不能在桌面或主目录裸启。第 07 篇就强调过：你在哪启动，Claude 就把哪儿当工作区、读哪儿的文件。在主目录跑 /init，它扫的是你一堆乱七八糟的个人文件，扫了个寂寞。

cd /path/to/your-project
claude

第二步：在输入框里敲 /init，回车。

/init

就这样。接下来你什么都不用做，剩下全是 Claude 自己跑——整个过程无需手动操作，它会自行分析、自动输出。

那它在背后到底干了啥？看它跑过很多次，大致是这么个流程：

整件事串成一条线就是：在项目目录里启动 claude → 敲 /init → Claude 扫描项目结构、识别技术栈 → 落盘一份 CLAUDE.md 草稿 → 你再人工微调补全。前四步基本是自动的，最后那步「人工微调」才是把草稿变成好手册的关键，这一篇先点到，第 18 篇专门讲。

官方对这一步的说法是「分析你的代码库」。具体扫的是哪些文件，落到实处大致是这几类（跑下来它基本都会翻）：

• 依赖清单：package.json（Node）、requirements.txt（Python）、pom.xml（Java）这类——用来判断技术栈和能跑的命令
• 现有文档：README 之类——理解项目是干什么的
• 配置文件 + 代码结构：摸清目录怎么分、入口在哪

⚠️ 一个容易忽略的细节：如果项目里已经有 CLAUDE.md，/init 不会粗暴覆盖它。官方文档明确写了——这时它会建议改进而不是覆盖。在一个已经写好 CLAUDE.md 的项目里再敲一次 /init，本来还担心白写了，结果它老老实实列了几条「这里可以补充」的建议，原文一行没动。这点设计相当贴心。

💡 一句话总结：cd 进项目根目录、启动 claude、敲 /init，剩下交给它自动扫——已有 CLAUDE.md 时它只建议改进、不覆盖。

04 生成出来长什么样：CLAUDE.md 草稿拆解

跑完 /init，项目根目录下就多了一个 CLAUDE.md 文件。打开它，你会看到一份结构清晰的 Markdown。

类比：一份标准的项目说明书。 它不是流水账，而是分好块的——项目是干嘛的、用了什么技术、目录怎么分、命令怎么敲、有什么约定。一个新人（包括下一次会话「失忆」后的 Claude）扫一眼这几块，就知道这项目怎么回事了。

生成的内容通常覆盖这么几块（具体字段 Claude 会按你项目实际情况来，下面是个典型样子）：

# 项目名称

## 项目概述
简述这个项目是做什么的、核心功能是什么。

## 技术栈
- Frontend: React + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL

## 目录结构
- `src/components/` - React 组件
- `src/api/`        - API 层
- `tests/`          - 测试文件

## 常用命令
- 启动开发服务器：`pnpm dev`
- 运行测试：`pnpm test`
- 代码检查：`pnpm lint`

## 开发规范
- 使用 TypeScript strict 模式
- 提交前先跑 `pnpm test`

逐块说一下它各自的价值——这正是 Claude 以前要反复问你的那些东西：

看明白没？前面那个 Node 项目里被问烂的「测试怎么跑」「用 npm 还是 pnpm」，全被「常用命令」「技术栈」这两块一次性吃掉了。手册写好往那一放，Claude 开局自己读，这些重复对话直接清零。

至于这个文件该放哪——官方给的位置是项目根目录的 ./CLAUDE.md（或者 ./.claude/CLAUDE.md）。/init 默认就帮你放对地方了，你不用操心路径。更细的层级关系（用户级、项目级怎么叠加），留到第 18 篇展开。

💡 一句话总结：生成的 CLAUDE.md 分「概述 / 技术栈 / 目录 / 命令 / 规范」几块，每一块都精准对掉一类以前反复问的重复——文件放哪 /init 帮你搞定。

05 关键认知：/init 是起点，不是终点

这是这一篇最想让你记住的一句话：/init 生成的是草稿，不是终稿。

为什么必须人工补一刀？因为有些东西，Claude 扫遍整个代码库也扫不出来——它们根本不在代码里，只在你和团队脑子里。

举几个 Claude 自己绝对推断不出来的例子：

• 分支命名规范：你们约定 feature/xxx、fix/xxx，这写在哪个文件里？没有。Claude 扫不到。
• 部署流程：合并到 main 自动触发部署、还是要手动点一下？项目代码里看不出来。
• Code Review 要求：「PR 必须两人 approve」「核心模块改动先在 Plan Mode 出方案」——这是团队的隐性约定。
• 业务背景：为什么这块要这么设计、哪个模块碰了容易出事——这些「为什么」藏在你脑子里。

正确的姿势是迭代优化，而非一次写死。

前面那个 Node 项目就是反面教材的对照组：/init 完就以为万事大吉，没补。结果它生成的「常用命令」里漏了一条自己写的部署脚本（因为那脚本藏在 scripts/ 里没在 package.json 暴露），Claude 自然没扫到。手动往 CLAUDE.md 里加一行「部署用 ./scripts/deploy.sh」，这才算补全。所以正确的习惯是固定的：/init 跑完，立刻通读一遍，把它扫不出的硬约束手动补进去。

所以正确的姿势是这样的对比：

记住这个分工就行：/init 负责把客观事实快速扒出来打底（这块它强），你负责把主观约定和业务背景补进去（这块只有你知道）。两边配合，才是一份真正好用的 CLAUDE.md。

至于「怎么把这份草稿改成一份精炼又好用的手册」——比如层级怎么设计、怎么用引用拆分、怎么长期维护——那是第 18 篇「CLAUDE.md 使用指南」的活儿。这一篇你只要做到「有了它」，下一步才谈「写好它」。

💡 一句话总结：/init 只把客观事实扒出来打底，团队约定、部署流程这些它扫不到的硬货，必须你人工补——草稿审完才算数。

06 动手：给一个最小项目跑通 /init

光说不练假把式。下面用一个两三个文件的最小项目，带你把 /init 完整跑一遍，验证它确实生成了 CLAUDE.md。不依赖任何复杂环境，照着敲就行。

第一步：建一个最小项目（Mac / Linux）

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

Windows PowerShell 用户：mkdir init-demo、cd init-demo 照敲，package.json 和 index.js 这两个文件用记事本新建、把上面单引号里的内容贴进去存好即可。

预期：init-demo 文件夹里有 package.json 和 index.js 两个文件。敲 ls（Windows 用 dir）能看到它俩。

第二步：在项目目录里启动 Claude Code

claude

预期：出现欢迎屏幕，底部有输入框。确认终端当前就在 init-demo 目录下。

第三步：跑 /init

在输入框里敲：

/init

预期：Claude 开始滚屏——你会看到它在读 package.json、index.js，分析项目，然后写文件。跑完它会告诉你 CLAUDE.md 已生成。因为这项目只有两个文件，整个过程很快，几秒到十几秒。

第四步：确认 CLAUDE.md 生成了

退出 Claude（敲 exit 或按 Ctrl+D），回终端看：

cat CLAUDE.md

（Windows PowerShell 用 type CLAUDE.md）

预期：终端打印出一份 Markdown，里面至少能看到项目名 init-demo、技术栈是 Node.js / JavaScript、以及那条 test 命令（echo test ok）被识别成了「运行测试」。看到这些 = /init 跑通了，它确实把你这个小项目读懂并记了下来。

第五步（可选）：验证它「记住」了

重新进 claude，问一句：

这个项目的测试命令是什么？

预期：它会直接告诉你测试命令，而不用再去翻 package.json——因为答案已经写在它开局就读过的 CLAUDE.md 里了。这一下，你就亲眼看到「失忆」被治好了。

⚠️ 小提醒：真实项目里 /init 扫的文件多、生成内容也丰富得多，跑起来会比这个 demo 慢一些，耐心等它扫完即可；扫完别忘了第 05 节说的——通读一遍，把它扫不出的硬约束补进去。

💡 一句话总结：建个两文件的最小项目、claude 里敲 /init、退出后 cat CLAUDE.md，亲眼看它把项目读懂——再问一句测试命令，验证「失忆」被治好了。

07 小结

这一篇就讲透了一个动作：进新项目第一件事，敲 /init，让 Claude 自己把项目说明书的初稿写出来。

把核心要点串一遍：

你现在应该能： 进任何一个项目，在根目录启动 claude 后敲 /init，让它自动生成一份 CLAUDE.md，看懂生成内容里每一块是什么，并且明白这只是起点——客观事实它帮你打底，主观约定要你亲手补。从此 Claude 不再「每天换个失忆的新人」，而是开局就读过你项目说明书的老手。

下一篇 13「项目结构」——你跑完 /init，CLAUDE.md 里那份「目录结构」是 Claude 扫出来的。但一个项目除了 CLAUDE.md，还有 .claude/ 目录、settings.json、自定义命令、MCP 配置等一堆「Claude Code 专属文件」各司其职。它们分别放什么、长什么样？下一篇带你把这套项目结构一次理清。

13 · 项目结构：Claude Code 在你项目里都放了什么

都说 .claude 那个文件夹「不用管，它自己会处理」，但说句实话，搞懂它你才算真正会用 Claude Code。

为什么这么讲？因为这套工具几乎所有「高级玩法」——自定义命令、权限控制、子代理、技能——落到磁盘上，全是 .claude/ 里的几个文件和目录。你不懂它的结构，遇到「为什么我配的权限没生效」「队友拉了代码却没有我的命令」这类问题，就只能干瞪眼。

我刚上手那阵子就干过一件蠢事：图省事，把一个含数据库密码的配置直接写进了 .claude/settings.json，跟着 git push 一起推上去了。等我反应过来的时候，密钥已经躺在仓库历史里了——最后只能改密码、重写历史，折腾了大半个小时。后来我才搞明白，这种东西本该放 settings.local.json，那个文件 Claude Code 默认就帮你 gitignore 了。一个文件放错地方，差别就这么大。

这一篇不教你每个文件怎么深配（那些留给后面专篇），只干一件事：给你画一张全景地图，让你看一眼某个文件就知道「它是干啥的、放哪、归项目还是归我、要不要提交」。

看完这一篇，你会拿到：

• 一张 .claude/ 目录的全景图：每个文件 / 子目录各管什么
• 「项目级」和「用户级」两套配置的根本区别（跟着项目走 vs 跟着你走）
• 一张速查表：哪些该提交 git、哪些必须进 .gitignore
• 一个一眼就能上手的动手环节，亲眼看清这两层目录长什么样

01 先理解一件事：Claude Code 有「两个家」

先给结论：Claude Code 的配置分两摊放——一摊跟着项目走，一摊跟着你走。看懂这条，后面全顺。

类比：公司的「项目档案柜」和你自己的「工位抽屉」。 项目档案柜（项目级）放的是这个项目所有人都要看的东西——项目规范、谁能动哪些操作，新人来了照着柜子里的资料就能上手。你的工位抽屉（用户级）放的是你个人的习惯——你顺手的快捷方式、你私人的偏好，换个项目这些还跟着你。

落到磁盘上就是两个位置：

这里有两个术语先点一下：

项目级（Project scope）：配置存在仓库里，进 git，全队共享。你改了规则提交上去，队友拉下来就同步生效。

用户级（User scope）：配置存在你电脑的主目录 ~/.claude/，只对你生效、永远不进任何仓库。你换到公司任何一个项目，这套都跟着你。

举个常见的用法：把「回复用中文」「commit 信息用什么前缀」这类纯个人偏好，放在用户级的 ~/.claude/CLAUDE.md 里——这样打开任何项目，Claude 都按你的习惯来。而「这个项目用 pnpm 不用 npm」这种项目事实，写进项目级的 ./CLAUDE.md，提交上去让全队共享。个人习惯和项目规范，从一开始就分两个地方放，后面省心。

💡 一句话总结：Claude Code 有「两个家」——项目里的 ./.claude/（跟项目走、进 git、团队共享）和主目录的 ~/.claude/（跟你走、不进 git、只对你生效）。

02 打开项目级 .claude/：里面都有啥

现在把项目里那个 ./.claude/ 文件夹翻开看看。一个用起来的项目，结构大概长这样：

your-project/
├── CLAUDE.md                ← 项目说明书（也可放 .claude/CLAUDE.md）
├── CLAUDE.local.md          ← 你的个人项目偏好（进 .gitignore）
├── .mcp.json                ← 团队共享的 MCP 服务器配置（进 git）
└── .claude/
    ├── settings.json        ← 团队共享配置：权限、hooks、模型默认值
    ├── settings.local.json  ← 你的个人配置覆盖（自动 gitignore）
    ├── commands/            ← 自定义斜杠命令，每个 .md 一条 /命令
    ├── rules/               ← 模块化的项目规则（CLAUDE.md 拆出来的）
    ├── skills/              ← 技能：可被 /调用 或 Claude 自动调用的工作流
    └── agents/              ← 子代理：各有独立上下文的专项助手

逐个说它们是干什么的，本篇只点到「是什么、归谁管」，深用法各有专篇：

CLAUDE.md —— 项目说明书。 Claude 每次进项目第一个读的文件。项目是什么、怎么跑、有什么约定，都写这儿。它和 .claude/settings.json 有个本质区别：CLAUDE.md 是给 Claude 看的「指导」（它读了尽量照做，但不是硬约束），settings.json 是Claude Code 强制执行的「配置」。

官方提了个细节：CLAUDE.md 放项目根目录，或者放 .claude/CLAUDE.md 都行——后者能让项目根目录干净点。

CLAUDE.local.md —— 你的个人项目偏好。 叠在 CLAUDE.md 之上、只与你本人相关的指令，比如「我本地数据库是 5433 端口」。要手动加进 .gitignore（跑 /init 时选个人选项会帮你加）。

settings.json —— 团队共享的配置中心。 控制 Claude 能不能执行某些操作（权限）、在哪些时机跑你的脚本（hooks），还能设这个项目默认用哪个模型。进 git，是团队的安全基线。

settings.local.json —— 你的个人配置覆盖。 和上面同样的 JSON 格式，但只对你生效、不提交。你想临时放开个权限、又不想影响队友，就写这儿。Claude Code 第一次写这个文件时，会自动帮你配 git 忽略它——这就是开头那个「本该用上、却被漏掉」的文件。

这里有个细节官方点了名：它把忽略规则加到的是你全局的 ~/.config/git/ignore（不是项目里的 .gitignore），所以你翻项目的 .gitignore 是找不到这行的。想让全队都忽略它，得自己再往项目 .gitignore 里补一行。

commands/ —— 自定义斜杠命令。 目录里每个 .md 文件，就变成一条 /文件名 命令。把你反复输入的那段指令存成文件，下次敲 / 就能调。官方已将 commands/ 和 skills/ 统一为同一底层机制，新建命令推荐用 skills/（支持打包附属文件），commands/ 继续兼容但不再是推荐路径。

rules/ —— 模块化的项目规则。 当 CLAUDE.md 写太长（官方建议控制在 200 行内），就把规则按主题拆成 rules/ 下的多个文件，比如 testing.md、api-design.md。

skills/ —— 技能。 每个技能是一个子目录，里面有个 SKILL.md。它既能你手动 /技能名 调用，也能让 Claude 根据任务自动判断该不该用。

agents/ —— 子代理。 每个 .md 定义一个有独立上下文窗口的专项助手，主对话脏不到它。适合并行干活或隔离任务。

.mcp.json —— 团队共享的 MCP 服务器配置。 放在项目根目录，和 .claude/ 并列。MCP（Model Context Protocol）服务器可以在两个地方配：这里的 .mcp.json 是进 git 给全队共享的，比如团队都要用的数据库工具或内部 API；而个人的 MCP 配置（比如只你自己在用的工具）存在 ~/.claude.json 里，不会进任何仓库。两者的区别就是：项目共享 vs 个人私用。

💡 一句话总结：项目级 .claude/ 里，CLAUDE.md / rules/ 是给 Claude 看的「指导」，settings.json 是 Claude Code「强制执行」的配置，commands/ skills/ agents/ 是你给它装的「扩展」。

03 同样的目录，~/.claude/ 里也有一套

这是最容易绕晕新手、但其实最简单的一点：上面那些目录名，在用户级的 ~/.claude/ 里几乎原样再有一份。

commands/、rules/、skills/、agents/、CLAUDE.md、settings.json——这些在项目里有，在 ~/.claude/ 里也有。区别只有一个：

（用户级 ~/.claude/ 还有几个项目级没有的独有目录——themes/、keybindings.json、output-styles/、workflows/ 等，留给后续专篇逐一介绍。）

放在 ~/.claude/ 下的，对你所有项目生效；放在项目 ./.claude/ 下的，只对那一个项目生效。

举两个用法你就懂了：

• 一个 /commit-zh 命令（生成中文 commit 信息），放在 ~/.claude/commands/ 里——这样在任何项目都能用，不用每个项目重配一遍。
• 但「部署到公司测试环境」这种命令，明显只跟那一个项目有关，就放进项目的 .claude/commands/，提交上去给全队用。

除了这些「双胞胎」目录，~/ 主目录下还有两个只在用户级出现、而且你基本不用手动碰的文件，认个脸就行：

这里多说一句自动记忆（auto memory）：它和 CLAUDE.md 是两套东西。CLAUDE.md 是你写给 Claude 的指令；自动记忆是 Claude 自己写给自己的笔记（比如它摸清了你的构建命令、踩过的坑），存在 ~/.claude/projects/<项目>/memory/ 下，跨会话复用。这俩别搞混：一个你写、一个它写。

💡 一句话总结：commands/ skills/ 这些目录项目级和用户级各有一套，区别只是「管一个项目」还是「管你所有项目」；~/.claude.json 和 ~/.claude/projects/ 是用户级专属、你基本不用手动碰。

04 哪些进 git，哪些千万别提交

这一节最实用，开头那个泄露密钥的坑就栽在这。先给铁律：带「local」的、含密钥的，一律不进 git。

为什么有的提交有的不提交？逻辑很简单——团队要共享的就提交，只跟你或你这台机器有关的就别提交。

类比：项目档案柜的东西要登记入库（进 git），你工位抽屉里的私人物品不用上交。

把项目里常见的文件按「该不该提交」分个类，照着这张表办就不会错：

几个实用的提醒：

settings.local.json 不用你操心 gitignore。 官方明确写了：Claude Code 在创建这个文件时，会自动配置 git 忽略它。你想本地临时放开个权限，写这儿最稳。

CLAUDE.local.md 要你自己加 .gitignore。 它和 settings.local.json 不一样，不会自动忽略——跑 /init 选「个人」选项时会帮你加，否则记得手动加一行。

密钥永远别硬写进任何配置文件。 官方推荐的做法是在配置里用环境变量引用，比如写 ${GITHUB_TOKEN} 而不是把 token 明文贴进去——Claude Code 启动时从你的 shell 环境读，token 根本不落到文件里。这条建议雷打不动地执行。

💡 一句话总结：团队共享的（CLAUDE.md、settings.json、commands/ 等）进 git；带「local」的和任何含密钥的绝不提交——settings.local.json 系统自动帮你忽略，CLAUDE.local.md 要你手动加。

05 配置冲突了听谁的：优先级一张图讲清

你可能已经想到一个问题：用户级 settings.json 和项目级 settings.json 都设了同一项，到底听谁的？

官方给的优先级顺序是这样的（从高到低）：

Managed（组织托管，最高，谁都盖不住）
  ↓
命令行参数（--permission-mode 这类，仅当次会话）
  ↓
Local（settings.local.json）
  ↓
Project（项目 settings.json）
  ↓
User（用户 ~/.claude/settings.json，最低）

记忆口诀：越「具体」、越「靠近当前这次操作」的，优先级越高。 组织管的 > 你这次命令行临时指定的 > 你这个项目本地的 > 项目共享的 > 你全局默认的。

这张图把两棵树并排摆开：左边项目级 ./.claude/（跟着项目走、按需进 git 给团队共享），右边用户级 ~/.claude/（跟着你这个人走、管你所有项目）——记住哪棵树管什么，后面配置往哪放就不会乱。

但这里有个特别容易踩的坑，必须单独拎出来——不是所有设置都遵守「覆盖」逻辑：

这个区别很容易吃亏：我自己就栽过一次——在用户级 settings.json 里 deny 了某个命令，本以为从此全局禁用，结果换到一个项目里它照跑不误，当时我盯着配置看了半天没想通。后来才搞清楚，权限规则是合并的、不是覆盖的，项目级 allow 了，会和用户级的规则叠在一起评估。所以权限别指望靠用户级「一刀切禁掉」，得搞清楚合并规则。

💡 一句话总结：优先级从高到低是 Managed → 命令行 → Local → Project → User；但要分清——model 这类标量是「覆盖」，permissions.allow 这类数组是「合并叠加」。

06 动手：亲眼看清这两层目录

光看图不如自己扒一眼。下面这套命令只读不写，安全得很，照着敲就能把「两个家」看个明白。

第一步：看你主目录的用户级 ~/.claude/

打开终端，敲（Mac / Linux）：

ls -a ~/.claude

Windows PowerShell 用：

dir $HOME\.claude

预期：你会看到 settings.json、projects、可能还有 commands、skills 等——具体有哪些取决于你用 Claude Code 多深。只要列出了东西，就说明用户级这个「家」是存在的、在生效的。

第二步：在一个项目里看项目级 .claude/

随便 cd 进一个你跑过 Claude Code 的项目（没有的话，回上一篇用 /init 建一个），然后：

ls -a .claude

预期：至少能看到 settings.local.json（你之前批过权限的话），可能还有 settings.json。这就是项目级的「档案柜」，和主目录那个是两套。

第三步：验证 settings.local.json 确实被 git 忽略了

在这个项目里（得是个 git 仓库），敲：

git check-ignore .claude/settings.local.json

预期：终端回显出这个文件路径（.claude/settings.local.json），就证明它已经被 git 忽略了——这正是 Claude Code 自动帮你做的。如果什么都没输出，说明它没被忽略，你最好手动把这行加进 .gitignore。

第四步（可选）：瞄一眼项目说明书

cat CLAUDE.md

（Windows PowerShell 用 type CLAUDE.md）

预期：打印出上一篇 /init 生成的内容。这就是 Claude 每次进项目第一个读的文件，现在你知道它躺在哪了。

⚠️ 一个提醒：git check-ignore 只在 git 仓库里有意义。要是这个项目还没 git init，这条命令会报 fatal: not a git repository，先把它变成 git 仓库再试。

💡 一句话总结：ls -a ~/.claude 看用户级、ls -a .claude 看项目级、git check-ignore .claude/settings.local.json 验证忽略——三条只读命令，把「两个家」和「谁被 git 忽略」一次看清。

07 小结

这一篇我们把 Claude Code 在项目里的「家底」摸了一遍。串起来回顾：

你现在应该能： 打开任何一个项目，看一眼 .claude/ 里的某个文件就知道它是干什么的、归项目还是归你、要不要提交；也知道配置冲突时该听谁的。这张全景地图就是后面所有专篇的底图——之后学 settings.json 怎么细配、CLAUDE.md 怎么写好、技能和子代理怎么造，你都能在这张图上找到它的位置。

下一篇 14「交互界面与快捷键」——目录结构这张「静态地图」看明白了，接下来该把 Claude Code 的「操作面板」摸熟了。下一篇带你认全那个界面里每一块、再把最常用的快捷键练成肌肉记忆，让你敲得又快又稳。