理解 .claude 文件夹：把 Claude Code 调成真正的工程助手

很多人用 Claude Code 时，会注意到项目里出现一个 .claude/ 文件夹，但不一定真的知道它里面每个文件在做什么。

我读完一篇关于 .claude/ 目录结构的整理后，最大的感受是：这不是一个普通配置目录，而是 Claude Code 在项目里的“协作协议”。

你把规则、命令、权限和工作流放进去，Claude 就更像一个理解项目习惯的工程助手，而不是每次都从零开始猜。

先分清两个 .claude

实际上有两个 .claude/。

一个是项目级的：

your-project/.claude/

它适合提交到 git，给团队共享。项目规范、常用命令、权限边界、代码审查流程，都可以放这里。

另一个是个人级的：

~/.claude/

它放你的个人偏好、跨项目命令、个人 skills、会话历史和一些本机状态。简单说，项目级解决“这个项目怎么工作”，个人级解决“我习惯怎么工作”。

CLAUDE.md 是最重要的入口

如果只能配置一个文件，那我会先配置 CLAUDE.md。

它会在 Claude Code 启动时被读取，相当于告诉 Claude：这个项目的构建命令是什么，测试怎么跑，哪些目录不能乱动，错误处理有什么约定，代码风格有哪些非显而易见的规则。

但 CLAUDE.md 不应该越写越长。

我比较认同一个原则：只写那些“不写 Claude 就容易犯错”的内容。格式化规则交给 formatter，简单命名规则交给 lint，已经在文档里讲清楚的东西直接链接即可。

一个好的 CLAUDE.md 更像项目给 Agent 的入职手册，而不是百科全书。

rules、commands、skills 和 agents 各管什么

当 CLAUDE.md 开始变胖，可以把规则拆到：

.claude/rules/

每个文件只负责一个关注点，比如 API 规范、测试规范、前端组件规范。更进一步，还可以做路径级规则：只有 Claude 编辑某些目录时，才加载对应规则。这样能减少无关上下文。

commands/ 则适合放显式工作流。比如：

.claude/commands/review.md

它会变成类似 /project:review 的 slash command。你主动触发它，Claude 按模板做代码审查、修 issue、生成提交说明。

skills/ 更像可复用能力包。commands 通常需要你手动触发，skills 则可以让 Claude 根据任务场景自动判断是否使用。它适合承载更复杂的说明和配套文件。

agents/ 用于专门的子代理。比如 code reviewer、安全审计、性能分析。主会话不必塞进所有细节，可以把一个独立任务交给专门 agent，最后只拿压缩后的结论。

我的理解是：

  • CLAUDE.md 是基础说明。
  • rules/ 是模块化规则。
  • commands/ 是显式按钮。
  • skills/ 是自动能力包。
  • agents/ 是专家分工。

settings.json 是安全边界

.claude/settings.json 管的是 Claude 能做什么、不能做什么。

例如你可以允许：

npm run *
git *
Read
Grep
Glob

也可以禁止：

rm -rf
读取 .env
访问 secrets 目录

我觉得这层非常重要。Agent 真正开始做工程任务后，权限边界不是锦上添花，而是必要的安全网。

团队共享的权限放 settings.json，个人本机偏好可以放 settings.local.json。这样既能统一底线，又不强迫所有人使用同一套个人习惯。

我会怎么开始配置

如果是一个新项目，我不会一上来就把 .claude/ 做得很复杂。

我会这样开始：

  1. 先用 /init 生成一个基础 CLAUDE.md。
  2. 手动删掉废话，只留下构建、测试、目录结构和关键约定。
  3. 加一个 settings.json，至少明确允许常用命令、禁止读取敏感文件。
  4. 加一两个最常用 commands，比如 review 或 fix-issue。
  5. 等规则变多，再拆到 rules/。

skills 和 agents 可以晚一点再做。它们适合稳定、重复、复杂的工作流，不适合一开始为了“看起来高级”而提前堆配置。

最后

我喜欢把 .claude/ 理解成“给 Agent 的项目基础设施”。

配置得越清楚，Claude 就越少猜；Claude 越少猜，我们就越少纠正它。

它真正解决的不是某个技巧问题，而是协作成本问题：怎么让 AI 不只是能回答问题，而是能按照项目的方式持续工作。