你以为 .claude 文件夹只是编辑器顺手生成的“系统垃圾”吗？很多 Claude Code 用户从来没点进去看过，只知道项目根目录里多了个隐藏目录。结果就是：明明有一整套可控的行为面板，却一直放着吃灰。其实 .claude 更像是你和 Claude 之间的“项目契约”，写得越清楚，它越像靠谱队友，而不是随机发挥的实习生。
.claude 文件夹负责约束 Claude 在项目里的行为：它保存你的指令、自定义命令、权限规则，甚至跨会话的记忆。只要搞清楚每个文件的职责和加载顺序，你就能把 Claude Code 调成真正适合你团队的“协作工程师”。
下面会从整体结构讲起，一路拆到具体文件和实用配置，让你知道哪些是每天会用到的，哪些是设好就可以忘掉的基础设施。
两个 .claude 文件夹，而不是一个
很多人只知道项目里有一个 .claude 目录，却不知道本机其实还有一个“影子配置”。如果你只改了其中一个，行为对不上，很容易一头雾水。
项目级 .claude 放在代码仓库里，是团队共享的配置，会跟着 git 一起提交。这里定义的是“我们这个项目应该怎么做事”，包括统一的规则、自定义命令和权限策略。团队成员拉下代码后，默认就继承了这些约定。
另一个目录在你的用户主目录：~/.claude/。这里保存的是个人偏好和本机状态，比如会话历史、自动记忆、个人命令等。它不会进仓库，只影响你自己。
可以简单记：项目
.claude代表“团队共识”，~/.claude代表“我个人的习惯”。两者叠加后，才是 Claude 实际执行的行为。
CLAUDE.md：Claude 的“工作说明书”
每次你在项目里启动 Claude Code，会话一开始读取的就是 CLAUDE.md。它会被直接塞进系统提示里，整场对话都在这份说明书的约束下进行。
换句话说：你在 CLAUDE.md 里写的规则，Claude 会当真。你要求“先写测试再写实现”，它就会优先这么做；你强调“禁止用 console.log 处理错误，统一走自定义日志模块”，它也会反复遵守。有团队反馈，在认真写完 CLAUDE.md 后，代码审查里重复纠正 AI 的次数下降了接近 40%。
项目根目录下的 CLAUDE.md 是最常见的入口。不过你也可以在 ~/.claude/CLAUDE.md 写一份全局偏好，对所有项目生效；甚至在子目录里放局部规则。Claude 会把这些文件合并起来，形成一份综合“人格设定”。
什么内容适合写进 CLAUDE.md
很多人要么把 CLAUDE.md 写成“项目百科全书”，要么只写两句口号，效果都不太好。更实用的做法是只放那些会直接影响 Claude 行为的关键信息。
应写内容
- 构建、测试和代码检查命令（如
npm run test、make build等），方便 Claude 自动调用 - 关键架构决策（例如“使用 Turborepo 管理 monorepo”）
- 不明显的坑点（例如“TypeScript 开启 strict 模式，未使用变量会报错”）
- 导入约定、命名规范、错误处理风格等“风格类规则”
- 主要模块的文件和目录结构，让 Claude 知道代码大致长什么样
不应写内容
- 已经在 linter 或格式化工具里配置好的规则
- 可以通过链接访问的完整文档全文粘贴
- 大段理论性解释，比如“为什么我们选择函数式编程”之类长文
经验上，把 CLAUDE.md 控制在 200 行以内更稳。太长会占用大量上下文，Claude 反而更容易“看不完”而忽略部分指令。有用户测试过：从 400 行精简到 150 行后，Claude 遵守命名规范的成功率明显提升。
下面是一个简洁但实用的示例：
只有大约二十来行，却已经包含了在这个代码库里高效协作所需的关键信息。日常开发中，你不用一遍遍重复解释“我们用什么测试框架”“错误怎么处理”，Claude 会自己遵守。
CLAUDE.local.md：给自己用的“私心配置”
团队规则不可能照顾到每个人的习惯。有时候你想让 Claude 对你“特殊一点”，比如偏好某种测试运行方式，或者希望它默认用特定视图打开文件。
这种情况就用 CLAUDE.local.md。在项目根目录创建这个文件后，Claude 会把它和主 CLAUDE.md 一起读取。区别是：CLAUDE.local.md 会自动被 git 忽略，你的个人偏好不会污染团队配置。
我自己就会在这里写一些“有点主观”的偏好，比如“优先用 TDD 风格写示例”，这样既不强迫同事接受，也能让 Claude 对我更顺手。
rules/：把大说明书拆成可维护模块
当团队和项目一起长大时，CLAUDE.md 很容易膨胀成一份 300 行的“没人敢动的遗迹”。大家都知道它重要，但谁也不想成为那个重构它的人。
rules/ 文件夹就是为了解决这个问题。你可以把一整块的规则拆成多个关注点清晰的小文件。
.claude/rules/ 里的每个 Markdown 文件，都会和 CLAUDE.md 一起加载。你可以按主题拆分，比如：
这样一来，负责 API 规范的人只需要维护 api-conventions.md，测试负责人只改 testing.md。互不踩脚，也更容易 code review。
更有意思的是路径作用域规则。给规则文件加上 YAML frontmatter，就能让它只在特定路径下生效：
当 Claude 编辑 React 组件时，这个规则不会加载；只有处理 src/api/ 或 src/handlers/ 下的文件时才会启用。没有 paths 字段的规则则对所有会话生效。
一个简单判断：当你开始觉得
CLAUDE.md变成“杂物间”时，就该把内容拆到rules/里了。
commands/：把常用操作变成一条斜杠命令
Claude Code 自带了 /help、/compact 之类的斜杠命令，其实你完全可以为团队常用流程再造一批“内置指令”。
commands/ 文件夹就是命令工厂。你放进 .claude/commands/ 的每个 Markdown 文件，都会变成一个可用命令。
比如：
review.md会生成/project:reviewfix-issue.md会生成/project:fix-issue
文件名就是命令名：
比如你创建 .claude/commands/review.md：
当你运行 /project:review 时，Claude 会自动把真实的 git diff 注入提示中。这里的 ! 反引号语法可以执行 shell 命令并嵌入输出，让命令不只是“模板文字”，而是动态工作流。有团队统计过，把常用的“PR 审查流程”做成命令后，每次审查平均节省了 3–5 分钟。
向命令传递参数
命令不只是固定动作，也可以接收参数。用 $ARGUMENTS 占位，就能拿到命令名后面的文本：
执行 /project:fix-issue 234 时，命令会自动把编号为 234 的 issue 内容拉进提示里。你不用再手动复制链接、粘贴描述。
个人命令 vs 项目命令
- 项目命令：放在
.claude/commands/，会随仓库共享，命令前缀通常是/project:* - 个人命令：放在
~/.claude/commands/，跨项目可用，前缀变成/user:command-name
比较实用的个人命令包括：
- 每日站会小助手（自动整理昨天/今天/阻塞项）
- 生成符合团队规范的提交信息
- 一键跑安全扫描并总结结果
我也见过有人做了一个“重构建议”命令，专门在大文件上跑静态分析和重构提示，效果还挺不错的。
skills/：让 Claude 主动调用的复用工作流
命令需要你手动输入 /xxx 才会触发，而技能（skills）更像是 Claude 的“内建本领”。当对话内容匹配某个技能的描述时，它会自动决定要不要调用。
简单对比一下：
每个技能放在一个独立子目录里，目录中至少包含一个 SKILL.md：
SKILL.md 用 YAML frontmatter 描述“什么时候应该用我”：
当你说“帮我审查这个 PR 的安全问题”时，Claude 会根据描述判断：这正好匹配安全审查技能，于是自动调用。你也可以用 /security-review 显式触发。
技能和命令的关键差别在于：技能可以带一整套支持文件。上面例子里的 DETAILED_GUIDE.md 就是和 SKILL.md 同目录的详细安全审查指南。命令是单文件脚本，技能更像一个小型插件包。
个人技能放在 ~/.claude/skills/，可以在所有项目里复用。说实话，这一块目前还没被大多数团队用到位，我也不太确定是不是每个项目都需要，但在安全审计、性能分析这类重复性强的任务上，技能的价值会非常明显。
agents/：为复杂任务准备的专门子代理
有些任务复杂到需要“请一个专家进来”，比如系统级安全审计、架构评审、合规检查等。你可以在 .claude/agents/ 里定义这些专门角色。
每个代理是一个 Markdown 文件，里面写清楚：它的角色设定、能用哪些工具、偏好哪个模型等：
比如 code-reviewer.md 可以长这样：
当 Claude 需要做代码审查时，会在一个独立上下文里启动这个“代码审查员代理”。它会自己读文件、跑工具、整理结论，最后把压缩后的结果反馈给主会话。这样主对话不会被一堆中间日志淹没。
tools 字段用来限制代理能用的工具。比如安全审计员只需要 Read、Grep、Glob，就不该有写文件的权限。这种“最小权限”配置可以显著降低误操作风险，尤其是在生产仓库里。
model 字段则允许你为不同任务选择不同模型：
- Haiku：适合大部分只读探索、批量扫描
- Sonnet / Opus：留给需要高推理能力的关键任务
个人代理可以放在 ~/.claude/agents/，跨项目共享。最近不少团队在做“专门的迁移代理”“专门的性能分析代理”，在大规模重构场景下非常省心。
settings.json：权限与项目级安全网
.claude/settings.json 决定了 Claude 在项目里“能做什么、不能做什么、做之前要不要问你一声”。这部分配置直接关系到安全和信任度。
一个完整示例大概长这样：
关键字段说明：
$schema：启用 VS Code 或 Cursor 的自动补全和校验，强烈建议保留allow：白名单，列出可以直接执行、无需确认的命令和工具deny：黑名单，列出绝对禁止的命令和路径
常见的允许列表包括：
Bash(npm run *)或Bash(make *)，让 Claude 能自由运行项目脚本Bash(git *)，只读 git 命令（如git diff、git status）- 文件操作工具：Read、Write、Edit、Glob、Grep 等
常见的拒绝列表则会包含：
- 破坏性 shell 命令，如
rm -rf、sudo相关操作 - 直接访问网络的命令，如
curl、wget - 敏感文件和目录，如
.env、secrets/下的内容
不在任何一边的命令，Claude 会先问你要不要执行。这种“中间态”设计相当于一个安全缓冲区，你不需要一开始就列出所有可能命令。
你也可以创建 settings.local.json 作为个人覆盖配置，路径是 .claude/settings.local.json。它会自动被 git 忽略，适合存放你自己愿意放宽或收紧的权限，比如在本机允许多跑一些调试脚本。
有团队在引入 Claude Code 时，先从极严的
settings.json开始，逐步放宽。数据显示，这种“渐进式信任”比一上来全开权限更容易让成员安心使用。
全局 ~/.claude/：你的“个人记忆库”
~/.claude/ 这个目录你可能不会天天打开，但知道里面有什么，会帮你在一些“诡异记忆”场景下少踩坑。
~/.claude/CLAUDE.md：对所有 Claude Code 会话生效的全局说明书。适合写个人编码原则、偏好风格、常用约定等~/.claude/projects/：按项目存储会话记录和自动记忆。Claude 会在你工作时自动记下有用信息，比如常用命令、架构模式、踩过的坑，你可以用/memory查看和编辑~/.claude/commands/和~/.claude/skills/：存放个人命令和技能，所有项目共享
有一次我发现 Claude 居然记得一个已经删掉的老脚本路径，追根溯源才发现是自动记忆里还留着旧信息。清理对应项目的 ~/.claude/projects/ 记录后，一切就恢复正常了。
全貌：这些文件如何协同工作
把前面的内容串起来，你会发现 .claude 其实是一套分层的“协作协议”：
CLAUDE.md/CLAUDE.local.md：定义项目和个人的基础规则rules/：把规则拆成可维护模块，按路径精细生效commands/：把高频操作变成一条命令skills/：让 Claude 在合适时机主动调用复杂工作流agents/：为特定复杂任务准备专门角色settings.json：用权限系统兜底安全和可控性
从最近一两年的趋势看，越来越多团队开始把“AI 配置”当成工程基础设施的一部分，而不是临时脚本。.claude 就是这套基础设施的入口。
实用入门配置：从零到可用的 5 步
如果你刚开始用 Claude Code，又不想一上来就搞得太复杂，可以按下面这套流程来：
- 在 Claude Code 中运行
/init，让它通过扫描项目生成一份初始CLAUDE.md，然后手动精简到真正关键的内容 - 添加
.claude/settings.json，根据技术栈设置允许/拒绝规则。至少要允许运行项目脚本，并明确拒绝读取.env等敏感文件 - 为一两个常用工作流创建命令，比如“代码审查”和“修复 issue”
- 随着项目变大、
CLAUDE.md变得拥挤时，把部分规则拆到.claude/rules/里，必要时用路径作用域控制生效范围 - 在
~/.claude/CLAUDE.md写入个人偏好，比如“优先写类型再写实现”“更偏好函数式风格而不是类”
对大约 95% 的项目来说，这套配置已经足够支撑日常开发。skills 和 agents 更适合在你发现有复杂、重复、且对质量要求高的工作流时再引入。
关键洞见：.claude 是“你和 Claude 的契约”
.claude 文件夹本质上是在告诉 Claude：你是谁、这个项目在做什么、哪些事可以做、哪些事绝对不能做。定义得越清晰，你花在“纠正 Claude”的时间就越少，它花在“真正帮你干活”的时间就越多。
CLAUDE.md 是杠杆率最高的那个文件，先把它写好，其他模块都是在这之上的精细化优化。很多团队都是从一份简单但清晰的 CLAUDE.md 开始，后面再慢慢长出 rules、commands、skills 和 agents。
如果你正打算把 Claude 当成长期战力，而不是偶尔问问问题的聊天机器人，那不妨把 .claude 当成项目基础设施的一部分来维护。等到哪天你发现“这套配置已经帮我们省下了无数重复沟通”，大概就会庆幸当初花的那点时间。
这个判断和配置方法在不少团队里都被反复验证有效，值得你先收藏一份，等需要扩展 Claude 能力时再回来对照着一步步加。
常见问题
Q：CLAUDE.md 写太长会有什么具体问题？
A：会话上下文是有限的，CLAUDE.md 过长会占用大量上下文空间，Claude 需要在海量规则中“挑重点”，反而更容易忽略你真正在意的部分。实践中，超过 200 行的说明书往往包含大量重复或低价值信息，既拖慢加载，又降低指令遵循度。建议做法是：保留直接影响行为的规则，把长文档改成链接引用，定期 review CLAUDE.md，把已经固化到代码或工具配置里的内容删掉。
Q：settings.json 里权限放得太宽会有安全风险吗？
A：会有，而且是那种“平时感觉不到，一出事就很严重”的风险。比如误允许了 Bash(*)，Claude 在尝试修复问题时可能执行破坏性命令，删库、改配置都有可能发生。更隐蔽的是读取 .env、secrets/ 这类敏感文件，一旦被错误暴露到日志或外部系统，后果很难挽回。建议从最小权限原则出发：只允许项目脚本和只读 git 命令，明确拒绝危险命令和敏感路径，其余一律先询问再执行。
Q：commands 和 skills 应该优先用哪一个？
A：如果你已经有一套清晰的“我想什么时候触发它”的场景，优先用 commands；如果你希望 Claude 在合适时机自动帮你做事，可以考虑 skills。命令适合高频、可预期的操作，比如“审查当前 diff”“根据 issue 生成修复计划”；技能更适合复杂、上下文驱动的任务，比如“只要用户提到安全审查，就自动启用安全检查流程”。建议先从 2–3 个命令开始，等你摸清团队的高频需求，再把真正值得自动触发的流程抽成技能。
Q：团队成员的 CLAUDE.local.md 会不会互相冲突？
A：不会直接冲突，因为 CLAUDE.local.md 默认不会被提交到仓库，只在本地生效。每个人可以根据自己的习惯微调 Claude 的行为，比如偏好的输出格式、是否更详细地解释步骤等。潜在的问题在于：如果个人配置和团队 CLAUDE.md 差异太大，可能导致“每个人看到的 Claude 行为都不太一样”，沟通时会有落差。建议团队层面把关键规则写清楚，个人配置只做风格和体验层面的微调，不要在核心架构或安全策略上做本地覆盖。
Q：什么时候值得为项目引入 agents 子代理？
A：当某类任务同时满足“复杂度高、步骤固定、对质量要求高、且经常重复出现”这几个特征时，就很适合做成 agent。比如大型项目的代码审查、安全审计、性能分析、依赖升级评估等。直接好处是：你可以为这些任务单独配置系统提示、工具权限和模型选择，既保证安全，又能让 Claude 在专门上下文里深度思考。建议先从一个最痛的场景开始，比如“安全审查总是没人愿意做”，做一个安全审计代理，跑通后再考虑扩展到其他领域。
