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应该聚焦三类信息项目是什么技术栈、目录约定、核心模块职责。用三五句话讲清楚不要写成架构文档。规矩是什么代码风格、提交信息格式、测试要求、禁止事项。常用操作怎么跑构建、测试、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.mdSKILL.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我推荐按这个顺序先写“项目一句话简介”和“技术栈”再写“目录结构说明”只写关键目录然后写“开发命令”构建、测试、lint 各一条最后写“代码规范”和“禁止事项”写完先自己读一遍问自己一个刚入职的工程师看这份文件能不能在不问人的情况下跑起项目如果能这份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末尾留一个“最近更新”区块记录每次修改的原因和日期。这样过几个月回头看能快速想起当初为什么加某条规则避免误删。这个习惯看起来不起眼但在多人协作的项目里能省下大量“这条规则是谁加的、能不能删”的沟通成本。
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应该聚焦三类信息项目是什么技术栈、目录约定、核心模块职责。用三五句话讲清楚不要写成架构文档。规矩是什么代码风格、提交信息格式、测试要求、禁止事项。常用操作怎么跑构建、测试、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.mdSKILL.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我推荐按这个顺序先写“项目一句话简介”和“技术栈”再写“目录结构说明”只写关键目录然后写“开发命令”构建、测试、lint 各一条最后写“代码规范”和“禁止事项”写完先自己读一遍问自己一个刚入职的工程师看这份文件能不能在不问人的情况下跑起项目如果能这份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末尾留一个“最近更新”区块记录每次修改的原因和日期。这样过几个月回头看能快速想起当初为什么加某条规则避免误删。这个习惯看起来不起眼但在多人协作的项目里能省下大量“这条规则是谁加的、能不能删”的沟通成本。