01 两个 .claude/ 目录

.claude/ 不是一个目录，是两个，作用域和职责完全不同

1.1 用户级~/.claude/

跟着登录用户走，所有项目共享。放全局偏好——模型默认值、个人快捷指令、跨项目的记忆

典型目录结构：

projects/ 下面那一坨是 Claude Code 自动维护的"账本"，不需要手动碰，但知道它在哪能解决很多奇怪问题——比如想看上次那次会话到底发了什么，直接读 jsonl 就行

1.2 项目级.claude/

放在项目根目录，只在这个项目里生效。是给团队成员或这个仓库定制专属行为的地方

加载优先级：用户级 → 项目级 settings.json → 项目级 settings.local.json

git 提交建议：

一个常见误区：把所有自己的偏好都堆到项目 settings.json 里，结果跟同事发生 git 冲突。个人偏好走 settings.local.json，团队约定才走 settings.json。

02 配置文件

2.1 settings.json

常用顶层 key：model / theme / env / permissions / hooks。重点说 permissions，它的语法变体最多也最容易写错：

加 $schema 后，VS Code、Cursor 这类编辑器会给字段补全和拼写校验——权限规则写错比代码写错更难察觉，写一次就值回票价

几条原则：

• 最小权限：只放行项目实际用到的命令，不要写 "Bash(*)" 一把梭
• 不放行任意代码执行类：python、bash、npm run * 这种，收益小、安全代价大
• 危险命令显式 deny：rm -rf、git push --force、git reset --hard，让 Claude 每次都弹确认

一个常见的安全盲区：Read(./.env) 阻止内置 Read 工具读 .env，但同时放行了 Bash 的话，cat .env 照样能读到——Read/Edit 的 deny 规则只约束内置文件工具，不约束 Bash 子进程。要做严格的路径隔离，需要启用 sandbox

2.2 settings.local.json

跟 settings.json 同结构，用法差异只在一条：它必须进 .gitignore。Claude Code 自动创建它时已经做了这件事，你只要别去掉就行

适合放：本地路径的环境变量、个人调试用的临时权限、个人偏好的 model 切换

2.3 CLAUDE.md

.claude/ 目录之外但跟它密切相关的文件——它会被自动注入到每次对话的 system prompt

项目级 CLAUDE.md 建议按五块来组织（参考京东内部一位同事的归纳）：

• 项目结构：核心目录在哪、源码软链指向哪、自动生成的文件在哪。不告诉 AI 这个，它会反复 find，浪费时间也浪费 token
• 参考项目：本仓库借鉴或对照的其他项目放在哪个本地路径，让 AI 直接对照源码，而不是凭印象生成
• 架构骨架：几句话讲清楚这个项目要干什么、关键模块的职责，让生成的代码符合整体规划
• 编码规则：注释语言、命名风格、空行处理、特定语言的 idioms——AI 在不同模型间风格漂移很大，靠这一节稳住
• 编译与调试：构建命令、运行环境差异（如 Docker 容器内 vs IDE 终端的路径不一致）、是否允许 AI 自动跑编译

不要放：

• 通用工程实践（“写注释”、“加单元测试”——模型已经知道）
• 文件目录树（模型可以自己 ls）
• 会过时的临时状态（“目前我们正在重构 X”）

经验：CLAUDE.md 越短越好用。150 行以内能 hold 住，超过 200 行有效信息会被稀释，遵循度明显下降

还有一条比"写什么"更重要的建议——写"不要做什么"比"要做什么"更重要。模型默认行为已经够好，CLAUDE.md 真正的价值在纠偏：明确禁止用 npm、明确禁止 any 类型、明确禁止改某个配置文件，这类硬约束比"请遵循 SOLID 原则"有用一万倍

03 扩展能力

.claude/ 下真正能改变 Claude Code 行为的几类对象，按使用频率排序：

3.1 commands/ — 自定义 slash 命令

每个文件是一条 /foo 命令：

• 路径：<scope>/.claude/commands/<name>.md
• 子目录变成命名空间：commands/git/commit.md → /git:commit
• 文件正文是 prompt 模板
• 可选 YAML frontmatter：description、argument-hint、allowed-tools、model 等
• 模板里可用 $ARGUMENTS 占位用户传入的参数
• !some-shell-command 前缀会先执行 shell 命令，输出内容嵌进 prompt
• @path/to/file 引用文件内容

适合"重复性强、模板化、自己每次说一段长 prompt 嫌烦"的场景，比如 /new-post 思考 标题 直接生成草稿

3.2 agents/ — Subagents

带独立上下文的"子 Claude"：

• 路径：<scope>/.claude/agents/<name>.md
• frontmatter 必填 name、description；可选 tools（工具白名单，缺省继承全部）、model
• 文件正文是这个 agent 的 system prompt
• 主对话可显式 Agent(...) 调用，也可基于 description 自动委派
• 每次调用是全新上下文，主对话只看到 agent 的最终回复

什么时候用：

• 任务读大量文件，但你不想这些 token 占主对话上下文
• 任务有专门的 system prompt（安全审查、性能分析），跟主对话调性不同
• 想并行——一次发出多个 subagent 同时跑

3.3 skills/ — 渐进披露的能力包

看起来跟 subagent 像，机制完全不同：

• 路径：<scope>/.claude/skills/<name>/SKILL.md——注意是目录，可以带脚本、模板、参考资料等附属文件
• SKILL.md frontmatter 至少 name 和 description
• 渐进披露：会话开始时只注入 frontmatter；正文在 description 匹配用户意图时才被读入。这跟 subagent 的"全文进系统提示"完全不同
• 跟 subagent 的本质区别：skill 在主对话上下文里展开执行；subagent 是另起隔离会话

适合定义"按部就班的流程"——比如"发 PR 前的 review 步骤"、“生成某类规范文档”

3.4 rules/ — 把规范拆成可维护的模块

CLAUDE.md 写到几百行就开始失控——信息被稀释，模型遵循度下降。这时把内容迁到 .claude/rules/ 下，一个主题一份 markdown，递归发现，多人维护互不干扰

两种加载模式：

• 无 frontmatter（或没有 paths 字段）：启动时加载，行为类似 CLAUDE.md
• 带 paths frontmatter：只在 Claude 处理匹配路径的文件时触发

例如 .claude/rules/api.md：

API 约定只在改 src/server/api/ 文件时进上下文，前端组件改动不会被无关规则污染

加载顺序：用户级 ~/.claude/rules/ 先加载，项目级 .claude/rules/ 后加载——后者优先，项目规则不会被个人偏好覆盖

和 CLAUDE.md 的分工：

• CLAUDE.md：项目级"必备命令 + 关键约定 + 容易踩的坑"，控制在 200 行内
• rules/：按主题拆分的模块化规范，按需触发

模型遵循度的差距来自信息密度——一份 200 行的 CLAUDE.md 加上若干 paths 触发的 rules，比一份 1000 行什么都塞的 CLAUDE.md 靠谱得多

3.5 plugins/ — 能力打包

把 commands / agents / skills / hooks 打成一组分发的形式。本身不在 .claude/<dir> 下展开，而是通过 settings 的 enabledPlugins 字段启用、或经由 plugin marketplace 安装。适合给团队下发一套配套能力，避免每个仓库都重新拷贝

3.6 output-styles/ — 主对话人格

<scope>/.claude/output-styles/<name>.md 定义一份替换主对话 system prompt 的"风格"。通过 /output-style 命令切换。适合在不同场景间切人格——比如代码评审模式 vs 教学讲解模式。日常用得不多，了解为主

04 自动状态

这一节讲的是你不需要手动维护、但应该知道存在的部分

4.1 projects/

~/.claude/projects/<sanitized-cwd>/ 下每个 *.jsonl 是一次会话的完整 transcript。每行一个 JSON，记录了所有 user/assistant/tool 消息

什么时候它有用：

• 想分析自己最常用什么命令（参见我之前那篇 fewer-permission-prompts 的例子）
• 想看上次某个 bug 是怎么 debug 出来的
• 想给同事演示"那次操作的全过程"——直接发 jsonl

4.2 memory/

自动记忆系统住在 ~/.claude/projects/<sanitized-cwd>/memory/。结构是：

• MEMORY.md：索引文件（每条一行，自动加载到上下文）
• <slug>.md：每个独立记忆一个文件，有 frontmatter

它存的是跨会话需要保留的、且不能从代码或 git 推出的事实——你的角色背景、反复纠正过的偏好、项目里的非显性约定

不该存的：代码片段、文件路径、git 历史、临时状态

05 最小配置

如果你刚开始整理自己的 .claude/，从下面这套起步就够：

commands/ agents/ skills/ rules/ 都不是必备，等你发现自己反复在做某件事时再加。过早配置等于过早优化

5.1 完整工作流示例

配好 commands 之后，日常迭代会变成这样的链条：

每一步都是可被打断、可被回滚的小动作。比直接说"帮我搞定这个 feature 并提交"靠谱得多，因为模型在每一步都拿到了你这一刻明确的意图，不会"自作主张"地连贯执行十几个不该连贯执行的动作

这是 .claude/ 配置的最大价值——把含混的"AI 帮我写代码"拆成一连串明确的、可观察的、可控制的步骤

06 实践经验

.claude/ 配好了不等于用得好。下面这几条，是踩过的坑里能转化为 rule / hook / prompt 习惯的：

6.1 先注释再删代码

让 AI 重构时，rule 里默认要求用注释替代删除，删除由工程师确认后再做。AI 一旦"自信地"删错文件，回滚成本远高于多看一眼注释行

6.2 环境差异写进 rule

如果开发、编译、测试环境路径不一致（典型：Docker 容器内 /code/... 对 IDE 终端 /data/home/.../code/...），把这个映射写进 CLAUDE.md。贴一段编译错误时 AI 能自动换算到 IDE 路径，不用人工对照

6.3 用脚本而不是裸命令

rule 里告诉 AI 跑测试用 scripts/test.sh，而不是让它每次自己拼 pytest --cov=...。脚本化的好处是统一入口，AI 一看就知道系统怎么跑，失败时也好定位是流程问题还是代码问题

6.4 明确"何时可以编译"

大型项目编译几分钟到几十分钟，让 AI 写一点编译一次会拖死节奏。rule 里写明：只有显式说"编译"时才执行——日常生成代码先攒着，攒完一组任务再统一编译

6.5 单测是反偷懒的杠杆

AI 写实现代码很快，写单测时却最爱 mock 一切——主分支根本没被覆盖。两条配套习惯：rule 里要求优先覆盖核心调用链，少 mock；review 单测时优先看断言充不充分，而不是看是否通过

6.6 让 AI 自证

AI 给的方案和代码不一定对。怀疑某处不对劲又说不清时，直接问"这里是不是不优雅？“或"再 review 一下这份设计”。模型被反问时往往会主动承认问题，比你自己挑错快。这条不需要写进 rule，写进自己的 prompt 习惯就行

07 结语

.claude/ 的所有这些文件、目录、配置项，本质上都是在做同一件事：把你和 agent 之间反复重复的对话固化下来

第一次让它做某件事时，多说几句无所谓；第二次还要重复同样的话，就该想想是不是该写成一条 rule、一个 command、一份 skill。用 Claude Code 这类 agent 的核心实践原理就一句话：使用过程中不断增加配置调教 agent

不要追求一次性配齐完美的 .claude/，那是过早优化，等你发现自己反复在做某件事时再加。让配置跟着真实使用一起长大，每一条新增的规则背后都该有一次"我又重复说了"的不耐烦——那才是它该被沉淀下来的信号