Claude Code 团队协作怎么配:共享 settings.json、CLAUDE.md 与插件规范

搜「claude code 团队 协作」?按官方文档整理研发团队统一落地清单:哪些文件该提交进 Git(.claude/settings.json、CLAUDE.md、.mcp.json、子代理与插件市场)、哪些放进 .gitignore,以及权限合并与账号合规要点。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 Team / 企业 账号

结论先说

  1. 团队协作的核心是把「公共契约进 Git」和「私人偏好进 .gitignore」彻底分开。
  2. 必须提交进 Git 的五样东西:项目 CLAUDE.md(及 .claude/rules/)、.claude/settings.json、.mcp.json、以及 .claude/agents/ 与 .claude/skills/。
  3. 必须留在本地不提交的两样东西:.claude/settings.local.json 和 CLAUDE.local.md,专门给成员覆盖个人习惯。
  4. 共享权限的生效前提:项目 .claude/settings.json 里的 deny 和 ask 规则拉下代码立刻生效,但 allow 自动放行规则要等每位同事在本机首次打开并点击「信任此文件夹」后才启用。
  5. 跨多个仓库复用扩展时,搭一个团队内部 Git 插件市场,配合 extraKnownMarketplaces 和 enabledPlugins 让新成员开箱即装。

Claude Code 团队仓库文件分工表

图:本站根据 Claude Code 官方文档:Settings 与《Memory》整理的示意图

本文根据 Claude Code 官方文档《Settings files and precedence》《How Claude remembers your project》《Discover and install plugins》《Connect Claude Code to tools via MCP》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Anthropic 官方网站。

适用于谁

  • 搜「claude code 团队 协作」,想让组里五六个程序员拉下同一个 Git 仓库就能共用一套代码规范、常用权限和检查钩子的技术负责人;
  • 团队成员手滑把自己的个人本地配置提交进了主分支,把同事的终端配色或路径搞乱过的人;
  • 想给全组统一分发内部自定义斜杠命令(Skills)、专职子代理和项目 MCP 服务的人。

一、仓库目录怎么摆:公共提交层与个人隔离层

新项目初始化团队配置时,先把仓库结构按官方约定划清楚(全局用户级文件的分工另见 全局 CLAUDE.md 怎么配 与 settings.json 配置详解):

text
your-repo/
├── CLAUDE.md                     # 提交:精简的构建/测试命令与架构红线(建议 ≤200 行)
├── CLAUDE.local.md               # 忽略:成员自己的沙盒测试账号或临时备忘
├── .mcp.json                     # 提交:项目共用的 MCP 服务(用环境变量引密钥)
└── .claude/
    ├── settings.json             # 提交:团队统一权限、Hooks、推荐插件与署名规则
    ├── settings.local.json       # 忽略:成员个人在弹窗点「不再询问」攒下的本地规则
    ├── rules/                    # 提交:按前端/后端目录 paths 拆分的细则文档
    ├── agents/                   # 提交:团队共用的测试员、审查员子代理
    └── skills/                   # 提交:团队统一发版说明、建表迁移等技能

记得在仓库 .gitignore 补上两行,防止同事误提交私人文件:

gitignore
CLAUDE.local.md
.claude/settings.local.json

二、一份可直接抄进仓库的团队 .claude/settings.json

团队统一接入 Claude Code 四步法

图:本站根据 Claude Code 官方文档:Settings 整理的示意图

把下面这份模板放进 .claude/settings.json 提交到主分支,就能一次性帮全组配好常用命令免确认、禁止读取敏感 .env、拦截带副作用的 git push、挂载内部插件市场,并统一用项目内的相对路径跑检查钩子:

json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-cmd.sh"
          }
        ]
      }
    ]
  },
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "api-conventions@team-tools": true
  }
}

写团队配置时要特别避开三个常见坑:

  1. 钩子路径一律用 ${CLAUDE_PROJECT_DIR},千万别写死某个人电脑上的 /Users/zhangsan/... 绝对路径;如果组里既有 macOS 又有 Windows 同事,钩子脚本优先用仓库自带的 node 或 python 脚本保证跨系统能跑。
  2. 列表是合并而不是覆盖:如果某位同事在自己的用户级或 settings.local.json 里对某条命令写了 deny,哪怕团队 settings.json 写了 allow,最终仍按 deny 拒绝——官方规定 deny 永远最先判定。
  3. 跨仓库插件市场与 .mcp.json 不要硬编码密钥:.mcp.json 里需要令牌时用环境变量占位符(配法见 Claude Code MCP 配置教程);多仓库共用的规范和技能打包成内部插件仓库(流程见 自己写插件并发布到 marketplace),比在十个仓库里复制粘贴好维护得多。

三、团队账号与席位合规(别共用同一个个人号)

配置可以共享,登录凭据不能共享。Anthropic 官方条款明确禁止多人共用同一个消费者账号或 API 密钥(官方条款拆解见 Claude Code 能共享账号吗:官方条款与 Team 席位):

  • 企业或固定研发组应开通官方 Claude Team / Enterprise 席位,或在企业云平台(Anthropic Console、Bedrock、Vertex AI)为每位工程师签发独立密钥,并可通过系统目录部署不可被个人覆盖的 managed-settings.json;
  • 小团队成员各自维护独立个人订阅时,可在本站查看 Claude Code 订阅充值说明 或高额度的 Claude Max 充值说明。

常见问题

问:新同事拉下代码后说共享的 settings.json 好像没读到,怎么核实?

答:让他在会话里输入 /status,查看 Setting sources 一行是否列出了 Project settings;如果文件里有语法错误(比如不小心写了 // 注释或多了一个末尾逗号),运行 claude doctor 就能定位具体哪一行报错。

问:项目里的 CLAUDE.md 越写越长,每个人每次提问都变费额度怎么办?

答:官方建议单份 CLAUDE.md 控制在 200 行以内。把只在特定模块才用得到的规则拆进 .claude/rules/ 目录,并在文件头加上 paths 前置字段,这样只有改到对应目录的文件时才会按需加载。

问:云端版(claude.ai/code)能读到我们提交进仓库的 .claude/settings.json 吗?

答:可以。官方说明云端会话从克隆你的 Git 仓库起步,提交在仓库里的 CLAUDE.md 和 .claude/settings.json 同样会被读取。

相关教程

参考资料

  • Claude Code 官方文档:Settings files and precedence — https://code.claude.com/docs/en/settings
  • Claude Code 官方文档:How Claude remembers your project — https://code.claude.com/docs/en/memory
  • Claude Code 官方文档:Discover and install plugins — https://code.claude.com/docs/en/discover-plugins
  • Claude Code 官方文档:Connect Claude Code to tools via MCP — https://code.claude.com/docs/en/mcp

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  5. 05

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  6. 06

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    MCP 收费吗:开源协议免费边界、第三方 API 账单与隐形 Token 开销说明

    搜「mcp 收费 吗」的人常担心装多了插件会被扣费。MCP(模型上下文协议)本身和官方 SDK 采用 MIT 协议完全免费;实际使用中可能产生费用的只有两处:挂载过多工具占用的大模型上下文 Token,以及部分外部商业数据源自带的 API 套餐。

    Claude其他 AI 工具0
  2. 02

    MCP 协议最新版本更新了什么:无状态架构、OAuth 2.1、结构化输出与异步 Tasks 详解

    搜「mcp 重大 更新」「mcp 协议 更新」想补齐规范演进脉络?本文对照 modelcontextprotocol.io 官方规范更新日志,梳理从 Streamable HTTP 到无状态优先架构、OAuth 2.1 资源服务器、Elicitation 交互补参与异步 Tasks 扩展的核心变化。

    Claude其他 AI 工具0
  3. 03

    A2A 和 MCP 有什么区别:工具连接协议与智能体通信协议的边界和配合

    很多人问「有了 MCP 为什么还要出 A2A,两者是不是二选一的竞争关系」。两份官方规范都明确写明它们是上下互补关系:MCP 负责给单个智能体挂载工具与数据源,A2A 负责让多个独立黑盒智能体跨团队、跨框架互相派单协作。

    Claude其他 AI 工具0
  4. 04

    LangGraph 怎么使用 MCP:用 langchain-mcp-adapters 接入本地与远程工具

    想让自建的 LangGraph 状态图直接调用现成的 MCP 服务器,官方标准方案是安装 langchain-mcp-adapters 并使用 MultiServerMCPClient。本文讲清 stdio 与 streamable_http 两种配置写法、异步图运行及按节点分工具技巧。

    Claude其他 AI 工具0
  5. 05

    LangGraph 入门教程:Python 安装、核心概念与跑通第一个状态图智能体

    面向搜「python 安装 langgraph」和「langgraph 中文 文档」的初学者:本文按 LangChain 官方最新 Graph API 规范,讲清安装步骤、State/Node/Edge 四大概念,并从零写出第一个带工具调用循环的 StateGraph。

    Claude其他 AI 工具0
  6. 06

    Claude Agent SDK 子代理怎么写:AgentDefinition 配置、权限收敛与 Python/TS 示例

    在 Python 或 TypeScript 里用 Claude Agent SDK 编排多角色协作,核心是配置 ClaudeAgentOptions 的 agents 字段与 AgentDefinition。本文讲清必开的 Agent 委派权限、工具收敛、模型分级与完整代码示例。

    Claude0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~