Claude Code 团队协作配置指南：.claude/ 文件夹权限、上下文与技能实战

1. 为什么 .claude/ 文件夹值得单独拿出来讲

很多人第一次接触 Claude Code，注意力全在“怎么装”“怎么让它跑起来”上，等真正用顺手了才发现，真正决定它好不好用的，不是模型本身，而是项目根目录下那个不起眼的.claude/文件夹。这个文件夹里藏着团队协作的全部密码：谁能改哪些文件、哪些命令需要二次确认、项目上下文怎么自动加载、常用技能怎么复用。换句话说，.claude/配置得好，Claude Code 就是一个懂你项目规矩的靠谱队友；配置得随意，它就是一个随时可能越界、每次都要重新解释一遍背景的陌生人。

我见过太多团队在初期把.claude/当成临时目录，随手丢几个文件进去，结果到了多人协作阶段，权限混乱、上下文冲突、技能重复定义的问题集中爆发。这篇文章不打算复述官方文档里能查到的字段说明，而是从实际项目落地的角度，把.claude/文件夹的目录结构、核心配置文件、团队协作策略和常见坑点一次讲清楚。无论你是刚装好 Claude Code 的个人开发者，还是正在推动团队统一 AI 编码规范的负责人，都能从下面这些内容里找到可以直接抄作业的配置方案。

需要先说明一点：.claude/的具体字段和行为会随版本迭代调整，本文基于当前主流版本的常见实践展开，涉及具体参数时我会说明其设计意图，你在实际使用时以本地版本的实际行为为准。

2. .claude/ 文件夹的目录结构与各文件职责

2.1 一个典型的 .claude/ 目录长什么样

先看一个我在多个项目中反复验证过的目录结构，这是团队协作场景下比较完整的一套：

项目根目录/ ├── .claude/ │ ├── settings.json # 项目级配置，团队共享 │ ├── settings.local.json # 个人本地覆盖，加入 .gitignore │ ├── CLAUDE.md # 项目上下文说明，自动加载 │ ├── commands/ # 自定义斜杠命令 │ │ ├── review.md │ │ └── deploy-check.md │ ├── skills/ # 可复用技能定义 │ │ ├── api-conventions/ │ │ │ └── SKILL.md │ │ └── db-migration/ │ │ └── SKILL.md │ └── agents/ # 子代理定义（如启用） │ └── test-runner.md ├── CLAUDE.md # 也可放在根目录，效果类似 └── .gitignore

这个结构里，settings.json和CLAUDE.md是必选项，commands/、skills/、agents/属于按需扩展。很多人会问：为什么CLAUDE.md既可以放根目录也可以放.claude/里？这其实是历史演进留下的灵活性，早期版本习惯放根目录，后来为了集中管理推荐放进.claude/。两种位置都会被读取，但同时存在时要注意优先级，避免上下文重复注入。

2.2 settings.json 与 settings.local.json 的分工

这是团队协作里最容易搞混的一对文件。核心原则只有一条：settings.json进版本库，settings.local.json不进版本库。

settings.json承载的是团队共识，比如：

• 允许 Claude Code 执行哪些命令类别
• 哪些路径禁止读写
• 默认使用的模型和思考预算
• 环境变量注入规则

settings.local.json承载的是个人偏好，比如：

• 我本地想用更激进的自动执行策略
• 我自己的 API 端点或代理配置
• 只对我有效的临时白名单

这样设计的好处是，团队规范和个人习惯互不干扰。新人拉下代码后，settings.json直接生效，不需要口头传达“我们团队不让它碰生产配置”；而老手想临时放宽限制，改自己的 local 文件即可，不会污染别人的环境。

注意：settings.local.json一定要写进.gitignore。我见过不止一个团队因为忘了这一步，把某个人的本地调试配置提交上去，导致全组的权限策略被意外覆盖。

2.3 CLAUDE.md 到底该写什么

CLAUDE.md是 Claude Code 每次会话启动时自动读取的上下文文件，相当于你给这位队友的一份“项目入职手册”。写得好，它能少问一半的废话；写得烂，等于没写。

我的经验是，CLAUDE.md应该聚焦三类信息：

1. 项目是什么：技术栈、目录约定、核心模块职责。用三五句话讲清楚，不要写成架构文档。
2. 规矩是什么：代码风格、提交信息格式、测试要求、禁止事项。
3. 常用操作怎么跑：构建、测试、lint、本地启动的命令。

反面教材是把CLAUDE.md写成 README 的复制粘贴，或者塞进大量与编码无关的业务背景。上下文窗口是有限资源，每一行都要问自己：这行字能不能减少一次来回沟通？

3. 团队配置的核心：权限、上下文与技能三件套

3.1 权限配置：让自动化与安全共存

Claude Code 的权限系统是团队落地时最需要认真对待的部分。默认情况下，它对文件写入、命令执行这类有副作用的操作会请求确认。个人用没问题，但团队批量使用时，频繁确认会严重拖慢节奏。合理的做法是分层放权。

一个我常用的settings.json权限片段大致长这样（字段名以实际版本为准，这里展示的是设计思路）：

{ "permissions": { "allow": [ "Read", "Glob", "Grep", "Bash(npm run test:*)", "Bash(npm run lint:*)", "Bash(git status)", "Bash(git diff:*)" ], "deny": [ "Read(./.env)", "Read(./secrets/**)", "Bash(rm -rf:*)", "Bash(git push:*)" ] } }

这里的逻辑值得拆开讲。allow列表里放的是只读或幂等的操作：读文件、搜索、跑测试、跑 lint、看 git 状态。这些操作即使出错也不会造成破坏，放开确认能极大提升流畅度。deny列表里放的是不可逆或高风险的操作：读密钥文件、递归删除、直接推送远端。这些必须拦住，哪怕多确认几次也值得。

中间地带怎么办？比如git commit。我的建议是允许 commit 但禁止 push，让 Claude Code 帮你整理提交，但最终推送由人把关。这个边界在多数团队里都能接受。

3.2 上下文注入：CLAUDE.md 的进阶写法

基础版CLAUDE.md讲完项目概况就够了，但团队协作场景下，可以做得更精细。一个技巧是用分层引用：主CLAUDE.md只放全局约定，各子目录放自己的CLAUDE.md补充局部规则。

比如前端目录下的CLAUDE.md可以写：

本目录为前端代码，遵循以下额外约定： - 组件一律使用函数式写法，禁止 class 组件 - 样式统一走 CSS Modules，不引入新的样式库 - 新增依赖前必须先说明理由

这样当 Claude Code 在前端目录工作时，会自动叠加这层规则，不需要在主文件里堆砌所有细节。这种分层思路和很多构建工具的配置继承是一个道理，越靠近具体代码的规则越具体。

另一个实用技巧是用 CLAUDE.md 固化“踩过的坑”。每次 Claude Code 犯了同类错误，就把纠正规则写进去。比如它总爱用某个已废弃的 API，你就在文件里明确写“禁止使用 X，改用 Y”。日积月累，这份文件就成了团队 AI 协作的经验沉淀。

3.3 Skills：把重复劳动变成一键调用

Skills 是.claude/体系里最被低估的部分。简单说，它把一段固定的工作流程封装成一个可复用的技能，需要时直接调用，不用每次重新描述。

一个 Skill 的最小结构就是一个目录加一个SKILL.md：

.claude/skills/api-conventions/ └── SKILL.md

SKILL.md里通常包含技能名称、触发条件、执行步骤和注意事项。比如一个“新增 API 接口”的技能，可以规定：先检查现有路由命名风格、再生成 handler 骨架、再补测试、最后更新接口文档。这样团队里任何人让 Claude Code 加接口，产出的结构都是一致的。

Skills 的价值在团队规模上来之后特别明显。它把“老员工脑子里的隐性规范”变成了“新人和 AI 都能读取的显性流程”。我建议每个团队至少沉淀三类 Skill：代码规范类、发布流程类、排错诊断类。

4. 从零搭建一套可用的团队配置：完整实操链路

4.1 第一步：初始化目录与基础文件

假设你接手一个已有项目，要给它配上 Claude Code 的团队配置。第一步是建目录：

mkdir -p .claude/commands .claude/skills touch .claude/settings.json .claude/CLAUDE.md echo ".claude/settings.local.json" >> .gitignore

这里有个细节：settings.local.json不需要手动创建，Claude Code 在需要时会自己生成，你只要保证它被 git 忽略即可。提前创建空文件反而可能引起混淆。

4.2 第二步：写第一版 settings.json

不要一上来就追求完整，先跑通最小可用版本。我的建议是先只配allow和deny两个列表，把最常用的只读命令放开，把最危险的命令拦住。跑一周后根据实际被拦截的记录再调整。

调整的依据来自哪里？Claude Code 在请求确认时会显示它想执行什么。你留意一下哪些确认是高频且安全的，把它们加进allow；哪些是它不该尝试的，加进deny。这种“先观察后收紧”的方式，比一开始就拍脑袋写一大堆规则要靠谱得多。

4.3 第三步：写 CLAUDE.md 的实操顺序

写CLAUDE.md我推荐按这个顺序：

1. 先写“项目一句话简介”和“技术栈”
2. 再写“目录结构说明”，只写关键目录
3. 然后写“开发命令”，构建、测试、lint 各一条
4. 最后写“代码规范”和“禁止事项”

写完先自己读一遍，问自己：一个刚入职的工程师看这份文件，能不能在不问人的情况下跑起项目？如果能，这份CLAUDE.md就合格了。

4.4 第四步：沉淀第一个 Skill

选一个团队里最重复的任务做成 Skill。多数团队的第一个 Skill 都是“代码审查”或“提交信息生成”。以提交信息为例，SKILL.md可以规定格式为type(scope): description，并给出几个正例反例。这样 Claude Code 生成的提交信息就能和团队历史保持一致。

4.5 第五步：验证与迭代

配置写完不是终点。找一两个真实任务让 Claude Code 跑一遍，观察它在哪些环节卡壳、哪些规则没生效。常见问题是CLAUDE.md里的规则写得太抽象，比如“代码要整洁”，这种它没法执行。要改成可判断的具体规则，比如“函数不超过 50 行”“禁止使用 any 类型”。

5. 踩坑实录：那些配置里容易翻车的地方

5.1 上下文冲突：多个 CLAUDE.md 打架

前面提到分层CLAUDE.md很好用，但有个坑：如果主文件和子目录文件的规则矛盾，Claude Code 的行为会变得不可预测。比如主文件说“统一用双引号”，子目录说“统一用单引号”，它可能随机选一个。

解决办法是建立优先级约定：子目录规则覆盖主文件规则，但子目录不得与主文件的核心禁令冲突。核心禁令（如安全相关）只在主文件定义，子目录只能补充不能推翻。

5.2 权限过宽：一次误操作删掉半个仓库

这是我听过最惨的案例。某团队为了图省事，在allow里加了宽泛的Bash权限，结果 Claude Code 在执行清理任务时跑了一条范围过大的删除命令。虽然最终从 git 恢复了，但浪费了大半天。

教训很直接：永远不要给Bash全量放行。要用前缀匹配精确到具体命令，比如Bash(npm run test:*)而不是Bash(npm:*)，更不是Bash。前缀匹配的粒度越细，误伤面越小。

5.3 settings.local.json 被提交

前面强调过，但值得再说一遍。判断方法很简单：git status里如果出现settings.local.json，说明.gitignore没配好。补救办法是把它从版本库移除并补上忽略规则，同时检查历史提交里有没有泄露个人配置。

5.4 Skill 定义太泛导致误触发

Skill 的触发条件如果写得太宽，比如“处理任何代码相关任务”，它会在不相关的场景被调用，反而添乱。好的触发条件应该是具体的，比如“当用户要求新增 REST 接口时”。宁可窄一点，需要时手动调用，也不要宽到到处乱触发。

5.5 版本升级后配置失效

.claude/的字段会随版本变化。我遇到过升级后某个权限字段被重命名，导致原有规则静默失效的情况。建议在CLAUDE.md里记一笔当前配置对应的版本，升级后对照变更日志检查一遍关键字段。

6. 让配置真正服务团队：几条实战心得

配置这件事，最怕的是“为了配置而配置”。我见过团队花大力气写了几百行settings.json，结果没人维护，半年后字段全过期。真正有效的做法是让配置跟着项目一起演进。

第一条心得是从最小可用开始。先配权限和CLAUDE.md，跑顺了再加 Skills 和 agents。一次性堆太多，出问题时很难定位是哪块配置引起的。

第二条是把配置纳入代码审查。.claude/下的文件既然进了版本库，就应该像代码一样被 review。权限放宽、规则修改这类变更，最好有第二个人看过再合并。

第三条是定期清理。每季度回顾一次CLAUDE.md和 Skills，删掉过时的规则，合并重复的技能。配置文件和代码一样，会腐化，需要维护。

第四条是区分“团队共识”和“个人偏好”的边界要清晰。凡是影响他人的规则进settings.json，凡是只影响自己的进settings.local.json。这条边界模糊了，协作就会出问题。

最后分享一个我自己的小习惯：在CLAUDE.md末尾留一个“最近更新”区块，记录每次修改的原因和日期。这样过几个月回头看，能快速想起当初为什么加某条规则，避免误删。这个习惯看起来不起眼，但在多人协作的项目里，能省下大量“这条规则是谁加的、能不能删”的沟通成本。