Claude Code 原生 Agent 编排配置与使用手册：Subagents + Agent Teams 双平台落地指南

Claude Code 原生 Agent 编排配置与使用手册

适用环境 ：Windows 11（PowerShell / Windows Terminal / VS Code Terminal）与 macOS 13+（Terminal / iTerm2 / VS Code Terminal）；Claude Code CLI

方案：原生 Subagents + Agent Teams + 全局 CLAUDE.md（可选 Hooks / CI）

原则：全局配置一次；按任务动态选择执行方式；无需 OMC；不固定 Agent 数量或角色。

核对日期：2026-10-29。Claude Code 迭代较快，涉及实验性功能和版本特性时，以本文末尾的官方文档为准。

目标与边界
理解三种执行方式
[Windows 与 macOS 环境准备](#Windows 与 macOS 环境准备)
[开启原生 Agent Teams](#开启原生 Agent Teams)
配置全局动态编排规则
Subagents：默认可用与可选角色定义
首次验证与日常使用
[Team 交互、模型与权限](#Team 交互、模型与权限)
完整开发工作流与质量门禁
常见问题与故障排查（双平台）
禁用、回退与维护建议
[配置验收清单（Windows 实测 / macOS 模板）](#配置验收清单（Windows 实测 / macOS 模板）)
官方参考资料

1. 目标与边界

1.1 希望实现什么

在任何项目运行 claude，无需每次粘贴"创建三个 Agent"之类的提示词。
主 Agent 自行评估任务规模，并选择 直接执行 / Subagents / Agent Teams。
Agent 数量、角色、并行范围由具体任务决定，而非永久预设。
有依赖的步骤串行推进，无依赖的步骤按需并行。
代码变更完成后执行适当测试；复杂或高风险变更做独立审查。
减少过度防御、提前抽象、反复验证及无意义拆分。
对 main 合并、破坏性操作保留必要的人工授权或技术门禁。

1.2 这不是一个"强制编排引擎"

组成	负责什么	不保证什么
`settings.json`	开启 Agent Teams、配置显示模式及权限	不保证每条任务都会创建团队
全局 `CLAUDE.md`	跨项目持续提供动态编排策略	不等于每一条都被程序强制执行
Subagents	独立上下文处理专门任务	不自动形成完整团队
Agent Teams	独立 Teammates、消息通信、可用时共享任务列表	不等于持久化的企业级任务调度器
Hooks / CI	用可执行检查阻止不合规的操作或交付	不能代替完整的业务验收设计

重要：Agent Teams 目前仍属于实验性功能。它在交互式 Claude Code CLI 会话中可用；claude -p 非交互模式和 Agent SDK 会话不能按相同方式创建原生 Teammates。

2. 理解三种执行方式

#mermaid-svg-eZ5Zt9d0iEhgApcO{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-eZ5Zt9d0iEhgApcO .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-eZ5Zt9d0iEhgApcO .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-eZ5Zt9d0iEhgApcO .error-icon{fill:#552222;}#mermaid-svg-eZ5Zt9d0iEhgApcO .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-eZ5Zt9d0iEhgApcO .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-eZ5Zt9d0iEhgApcO .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-eZ5Zt9d0iEhgApcO .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-eZ5Zt9d0iEhgApcO .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-eZ5Zt9d0iEhgApcO .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-eZ5Zt9d0iEhgApcO .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-eZ5Zt9d0iEhgApcO .marker{fill:#333333;stroke:#333333;}#mermaid-svg-eZ5Zt9d0iEhgApcO .marker.cross{stroke:#333333;}#mermaid-svg-eZ5Zt9d0iEhgApcO svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-eZ5Zt9d0iEhgApcO p{margin:0;}#mermaid-svg-eZ5Zt9d0iEhgApcO .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-eZ5Zt9d0iEhgApcO .cluster-label text{fill:#333;}#mermaid-svg-eZ5Zt9d0iEhgApcO .cluster-label span{color:#333;}#mermaid-svg-eZ5Zt9d0iEhgApcO .cluster-label span p{background-color:transparent;}#mermaid-svg-eZ5Zt9d0iEhgApcO .label text,#mermaid-svg-eZ5Zt9d0iEhgApcO span{fill:#333;color:#333;}#mermaid-svg-eZ5Zt9d0iEhgApcO .node rect,#mermaid-svg-eZ5Zt9d0iEhgApcO .node circle,#mermaid-svg-eZ5Zt9d0iEhgApcO .node ellipse,#mermaid-svg-eZ5Zt9d0iEhgApcO .node polygon,#mermaid-svg-eZ5Zt9d0iEhgApcO .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-eZ5Zt9d0iEhgApcO .rough-node .label text,#mermaid-svg-eZ5Zt9d0iEhgApcO .node .label text,#mermaid-svg-eZ5Zt9d0iEhgApcO .image-shape .label,#mermaid-svg-eZ5Zt9d0iEhgApcO .icon-shape .label{text-anchor:middle;}#mermaid-svg-eZ5Zt9d0iEhgApcO .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-eZ5Zt9d0iEhgApcO .rough-node .label,#mermaid-svg-eZ5Zt9d0iEhgApcO .node .label,#mermaid-svg-eZ5Zt9d0iEhgApcO .image-shape .label,#mermaid-svg-eZ5Zt9d0iEhgApcO .icon-shape .label{text-align:center;}#mermaid-svg-eZ5Zt9d0iEhgApcO .node.clickable{cursor:pointer;}#mermaid-svg-eZ5Zt9d0iEhgApcO .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-eZ5Zt9d0iEhgApcO .arrowheadPath{fill:#333333;}#mermaid-svg-eZ5Zt9d0iEhgApcO .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-eZ5Zt9d0iEhgApcO .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-eZ5Zt9d0iEhgApcO .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-eZ5Zt9d0iEhgApcO .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-eZ5Zt9d0iEhgApcO .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-eZ5Zt9d0iEhgApcO .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-eZ5Zt9d0iEhgApcO .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-eZ5Zt9d0iEhgApcO .cluster text{fill:#333;}#mermaid-svg-eZ5Zt9d0iEhgApcO .cluster span{color:#333;}#mermaid-svg-eZ5Zt9d0iEhgApcO div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-eZ5Zt9d0iEhgApcO .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-eZ5Zt9d0iEhgApcO rect.text{fill:none;stroke-width:0;}#mermaid-svg-eZ5Zt9d0iEhgApcO .icon-shape,#mermaid-svg-eZ5Zt9d0iEhgApcO .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-eZ5Zt9d0iEhgApcO .icon-shape p,#mermaid-svg-eZ5Zt9d0iEhgApcO .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-eZ5Zt9d0iEhgApcO .icon-shape rect,#mermaid-svg-eZ5Zt9d0iEhgApcO .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-eZ5Zt9d0iEhgApcO .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-eZ5Zt9d0iEhgApcO .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-eZ5Zt9d0iEhgApcO :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 没有
有
不需要
需要
否
是
用户输入普通开发需求
主 Agent 读取全局规则并分析任务
是否有明显的独立委派价值?
Single Agent 直接执行
是否需要多成员直接协作\n或共享任务协调?
Subagents 专项委派
Agent Teams 创建 Teammates
验证与交付
验收通过?
修复并重新验证
汇总修改与测试证据

模式	典型场景	特点	成本
Single Agent	小 Bug、文案、局部组件修改	最少协调、响应直接	通常最低
Subagents	代码探索、专项测试、独立 Review	独立上下文，结果返回调用者；具名 Subagents 也可互发消息	中等
Agent Teams	多模块并行、复杂故障多假设、跨前后端协作	每个 Teammate 是独立会话；消息和共享任务协作	较高

注意容易忽略的一点 ：启用 Agent Teams 后，主 Agent 发起的具名 Subagent 调用，在交互式会话里可能升级为 Teammate。因此三种方式是策略选择，不一定是互不干扰的硬开关。

3. Windows 与 macOS 环境准备

两套系统的机制相同 ：用户级配置都位于 ~/.claude/，区别主要是终端命令、路径表示和多窗格工具。无需在每个项目复制全局配置文件。

3.1 系统要求与终端

对比	Windows 11	macOS
官方支持系统	Windows 10 1809+（本文以 Windows 11 为例）	macOS 13.0+
常用终端	PowerShell、Windows Terminal、VS Code 集成终端	Terminal（默认 zsh）、iTerm2、VS Code 集成终端
用户主目录	`C:\Users\<用户名>`	`/Users/<用户名>`
Claude 配置目录	`$HOME\.claude`	`$HOME/.claude` 或 `~/.claude`
推荐 Teams 显示模式	`in-process`	`in-process`；熟悉 tmux/iTerm2 可用 `auto` 或分屏
是否需要 OMC	不需要	不需要

3.2 Windows 11 安装与版本检查

打开 PowerShell：

powershell 复制代码

claude --version
claude --help

如果尚未安装，可使用官方原生安装命令（在可信的 PowerShell 环境执行）：

powershell 复制代码

irm https://claude.ai/install.ps1 | iex

原生安装后可尝试：

powershell 复制代码

claude doctor
claude update

已有 Homebrew / WinGet / npm 等其他安装方式时，应按照对应包管理器更新，避免多份 claude 可执行文件造成版本混淆。

3.3 macOS 安装与版本检查

打开 Terminal 或 iTerm2，先查看是否已安装：

bash 复制代码

command -v claude
claude --version

如果尚未安装，官方推荐原生安装：

bash 复制代码

curl -fsSL https://claude.ai/install.sh | bash

根据安装器提示重新打开终端或加载 Shell 配置后，验证：

bash 复制代码

claude --version
claude doctor

若使用 Homebrew，也可以选择 Homebrew cask（可选，不要和原生安装重复安装）：

bash 复制代码

brew install --cask claude-code
# 后续通过 Homebrew 更新
brew upgrade claude-code

macOS 原生安装一般使用 ~/.local/bin/claude 启动器；如果提示 command not found: claude，先检查 command -v claude 和终端的 PATH，按官方安装器提示完成路径配置。使用 zsh 时，持久化 Shell 的 PATH 修改通常放在 ~/.zprofile 或 ~/.zshrc，实际以安装器提示为准。

3.4 配置文件路径（Windows / macOS 一一对应）

作用	Windows 11	macOS
全局设置	`C:\Users\<用户名>\.claude\settings.json`	`/Users/<用户名>/.claude/settings.json`
全局编排规则	`C:\Users\<用户名>\.claude\CLAUDE.md`	`/Users/<用户名>/.claude/CLAUDE.md`
全局自定义 Subagents（可选）	`C:\Users\<用户名>\.claude\agents\`	`/Users/<用户名>/.claude/agents/`
项目级设置	`<项目>\.claude\settings.json`	`<项目>/.claude/settings.json`
项目级 Subagents	`<项目>\.claude\agents\`	`<项目>/.claude/agents/`
项目级指令	`<项目>\CLAUDE.md` / `AGENTS.md`	`<项目>/CLAUDE.md` / `AGENTS.md`

Windows 11 检查：

powershell 复制代码

Test-Path "$HOME\.claude\CLAUDE.md"
Test-Path "$HOME\.claude\settings.json"

macOS 检查：

bash 复制代码

ls -la ~/.claude
ls -l ~/.claude/CLAUDE.md ~/.claude/settings.json

若 macOS 首次安装尚未生成目录，可执行：

bash 复制代码

mkdir -p ~/.claude

在当前已经检查过的 Windows 环境中，真实全局文件路径是：

text 复制代码

C:\Users\Administrator\.claude\CLAUDE.md
C:\Users\Administrator\.claude\settings.json

这属于用户当前机器的实测信息，不代表 Mac 上已有相同配置。Mac 用户需要分别按后文步骤创建和验证。

Windows 路径中 C:\Users\Administrator.claude\CLAUDE.md 少了一个 \，与 C:\Users\Administrator\.claude\CLAUDE.md 不相同。

4. 开启原生 Agent Teams

原生 Agent Teams 为实验性能力 ，默认关闭。Windows 和 Mac 使用相同的 JSON 配置项，仅编辑命令不同。Subagents 不需要通过此开关开启。

4.1 永久开启（Windows 11 / PowerShell）

备份并编辑用户级设置文件：

powershell 复制代码

New-Item -ItemType Directory -Force "$HOME\.claude" | Out-Null
if (Test-Path "$HOME\.claude\settings.json") {
  Copy-Item "$HOME\.claude\settings.json" "$HOME\.claude\settings.json.bak"
}
notepad "$HOME\.claude\settings.json"

把以下字段合并到原有 JSON 中（不要覆盖已有 MCP、权限、Hooks 和插件配置）：

json 复制代码

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "in-process"
}

校验用户级配置：

powershell 复制代码

$config = Get-Content "$HOME\.claude\settings.json" -Raw | ConvertFrom-Json
$config.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
$config.teammateMode

预期输出：

text 复制代码

1
in-process

4.2 永久开启（macOS / zsh 或 bash）

先备份，再用 macOS 自带的文本编辑器修改：

bash 复制代码

mkdir -p ~/.claude
if [ -f ~/.claude/settings.json ]; then
  cp ~/.claude/settings.json ~/.claude/settings.json.bak
fi
open -e ~/.claude/settings.json

如果文件尚不存在，先执行 touch ~/.claude/settings.json，再运行 open -e。也可以直接使用 nano ~/.claude/settings.json。

写入或合并与 Windows 相同的 JSON：

json 复制代码

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "in-process"
}

macOS 上验证（安装了 python3 时）：

bash 复制代码

python3 -m json.tool ~/.claude/settings.json >/dev/null && echo "JSON 格式有效"
python3 -c 'import json, pathlib; p=pathlib.Path.home()/".claude/settings.json"; c=json.loads(p.read_text()); print("Agent Teams:", c.get("env",{}).get("CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS")); print("teammateMode:",c.get("teammateMode","in-process (默认)"))'

若未安装 python3，也可使用已安装的 jq：

bash 复制代码

jq -r '.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, (.teammateMode // "in-process")' ~/.claude/settings.json

以上校验命令是可选诊断手段：不要为了开启 Agent Teams 而强制安装 Python 或 jq。可以直接通过 cat ~/.claude/settings.json 检查内容，再在交互式 Claude Code 中执行只读 Team 测试。

4.3 临时开启（不修改文件）

Windows PowerShell：

powershell 复制代码

$env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"
claude

macOS Terminal / iTerm2：

bash 复制代码

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

该命令只影响这一次启动的进程及其子进程。要长期启用，使用前两节的 settings.json。如果项目/组织有更高优先级的设置，实际行为仍需以运行时验证为准。

4.4 显示模式怎么选（重点区别在 macOS）

设置值	Windows 11	macOS	含义
`in-process`	推荐	默认推荐	所有成员在一个终端的 Agent 面板内切换；无需额外依赖
`auto`	通常退回 `in-process`	推荐给已使用 tmux / iTerm2 的人	检测合适的分屏环境，否则回退
`tmux`	仅适合兼容的 Unix/WSL 环境	支持（需 tmux 或相应 iTerm2 集成）	倾向使用独立窗格
`iterm2`	不适用	iTerm2 专用（需要 `it2` CLI）	使用 iTerm2 原生窗格

对于Mac 普通用户，先维持：

json 复制代码

"teammateMode": "in-process"

对于Mac 熟悉 tmux 的开发者，可以改为：

json 复制代码

"teammateMode": "auto"

macOS 安装 tmux（可选）：

bash 复制代码

brew install tmux
# 检查
command -v tmux
tmux -V
# 进入 tmux 会话
tmux new -s claude-team
# 在 tmux 内启动 Claude
claude

也可以只对一次会话指定显示模式：

bash 复制代码

claude --teammate-mode auto

--teammate-mode 属于实验性选项，可能不在 claude --help 中显示。对于 iTerm2 原生多窗格，需要另行安装 it2 CLI（https://github.com/mkusaka/it2）并在 iTerm2 → Settings → General → Magic → Enable Python API 中启用 Python API（具体安装链接与流程以 Claude Code 官方文档指向的 it2 项目为准）。不要以为只安装 iTerm2 就足以启用原生窗格。

重要限制 ：在 VS Code 集成终端里，推荐 in-process；官方文档不支持该终端的 Agent Teams split-pane 显示。Windows Terminal 也不支持 split panes 模式；它们不会因此丧失原生 Agent Teams 编排能力。

5. 配置全局动态编排规则

5.1 为什么不用每个项目重复输入提示词

Claude Code 会加载用户级 ~/.claude/CLAUDE.md，因此全局行为要求只需写入一次。项目可以额外写自己的业务规范，但不必重复全局编排规则。

在 Windows PowerShell 中打开：

powershell 复制代码

notepad "$HOME\.claude\CLAUDE.md"

在 macOS Terminal / iTerm2 中打开：

bash 复制代码

mkdir -p ~/.claude
touch ~/.claude/CLAUDE.md
open -e ~/.claude/CLAUDE.md
# 或使用 nano ~/.claude/CLAUDE.md

两端写入的 Markdown 内容完全一致，不需要分别维护 Windows 版和 Mac 版提示词。

5.2 推荐的全局 `CLAUDE.md`

下面是适合长期使用的最小而完整 版本。当前对话中，Windows 11 端的文件内容已核对无误，可直接保留；Mac 首次配置时可复制相同规则。

markdown 复制代码

# Global Agent Orchestration

## Automatic Orchestration

- Automatically choose between direct execution, Subagents,
  and native Agent Teams based on task complexity.
- Do not require the user to explicitly request delegation.
- Create specialized agents dynamically when beneficial.
- Do not use a fixed number of agents or predefined roles.
- Prefer the simplest execution strategy that meets the goal.
- Use Agent Teams only when direct collaboration or
  substantial parallelism provides clear benefits.
- Avoid unnecessary agents and token consumption.

## Execution

- Analyze requirements and dependencies before implementation.
- Run independent tasks in parallel when beneficial.
- Avoid concurrent modifications to the same files.
- Perform relevant tests after implementation.
- Use independent review for nontrivial or high-risk changes.
- Fix confirmed defects and rerun affected checks.
- Verify acceptance criteria before reporting completion.

## Engineering Principles

- Avoid overengineering and speculative defensive code.
- Validate untrusted input at appropriate boundaries.
- Do not introduce premature abstractions.
- Prefer simple, maintainable implementations.
- Preserve existing project conventions.

## Safety

- Do not merge into main without explicit authorization.
- Do not perform destructive operations without approval.
- Do not claim tests passed unless they actually ran.
- Report unresolved issues and verification limitations.

语义：它指导 Claude 自主选择编排方案；不会自动创建固定的三个角色，也不会保证每次都派生 Agent。

5.3 全局规则与项目规则同时存在

用户级 CLAUDE.md 管理跨项目通用策略。
项目的 AGENTS.md / CLAUDE.md 管理本仓库约定，如框架、命令、接口约定、目录结构。
如果项目文件与全局文件冲突，先检查加载方式和更具体的项目要求；对于重要安全约束，不要仅依靠提示词。
新版 Claude Code 可以直接读取 AGENTS.md，但它是否与项目级 CLAUDE.md 同时加载取决于 Project instructions 设置。
特别地，用户级 ~/.claude/CLAUDE.md 不会阻止单独的项目 AGENTS.md 被加载；而项目级 CLAUDE.md 在默认加载策略下可能取代该层级的 AGENTS.md。

检查实际加载内容：

text 复制代码

/context all
/memory

观察 Memory files 中的真实路径。若希望项目同时加载两种文件，可在 /config 的 Project instructions 里选择 claude-md-and-agents-md（此选项依赖相应版本）。

6. Subagents：默认可用与可选角色定义

6.1 不需要额外开启

Subagents 是 Claude Code 原生功能。没有自定义角色文件时，Claude 仍可使用内置的 Explore、Plan、General-purpose 等 Subagents，根据任务自行委派。

text 复制代码

用户提问 -> 主 Agent 判断 -> 调用 Subagent -> 子 Agent 返回结论 -> 主 Agent 继续

自定义 Agent 是可选项，建议只有当某类任务反复出现、专用权限确有价值时才配置。

6.2 可复用角色：示例只读 Reviewer

如确需所有项目复用一名 Reviewer，可在用户级目录创建：

powershell 复制代码

New-Item -ItemType Directory -Force "$HOME\.claude\agents" | Out-Null
notepad "$HOME\.claude\agents\reviewer.md"

macOS / zsh：

bash 复制代码

mkdir -p ~/.claude/agents
touch ~/.claude/agents/reviewer.md
open -e ~/.claude/agents/reviewer.md
# 或 nano ~/.claude/agents/reviewer.md

内容（两套系统相同）：

markdown 复制代码

---
name: reviewer
description: Independent evidence-based code reviewer; use after nontrivial implementation or high-risk changes.
tools: Read, Grep, Glob
model: inherit
---

You are an independent code reviewer.
- Identify real correctness, security, and regression defects.
- Point to affected code and explain why each finding matters.
- Avoid speculative low-probability issues without evidence.
- Do not modify implementation files.
- Summarize remaining risks and whether the review passes.

说明：

description 是 Claude 判断是否委派的重要依据。
model: inherit 表示选择主 Agent 模型；仍受实际模型供应商及有效配置影响。
tools: Read, Grep, Glob 使此角色没有写文件工具；但这不是对主会话或所有 Teammates 的通用文件系统沙箱。
不建议无需求就同时创建十几个角色，以免占用上下文并增加路由歧义。

6.3 临时角色，不落盘

也可以通过 CLI 的 --agents 参数临时提供 JSON 定义，仅对本次会话生效。Windows PowerShell 示例：

powershell 复制代码

claude --agents @'
{
  "reviewer-temp": {
    "description": "Read-only code reviewer",
    "prompt": "Review correctness and regressions. Return evidence. Do not edit files.",
    "tools": ["Read", "Grep", "Glob"],
    "model": "inherit"
  }
}
'@

macOS / zsh：

bash 复制代码

claude --agents '{
  "reviewer-temp": {
    "description": "Read-only code reviewer",
    "prompt": "Review correctness and regressions. Return evidence. Do not edit files.",
    "tools": ["Read", "Grep", "Glob"],
    "model": "inherit"
  }
}'

这用于一次性试验，不等于"让 Claude 自动生成动态角色"所必需的步骤。你的默认方案不需要这段配置。

6.4 `/agents` 在新版中做什么

text 复制代码

/agents

新版 /agents 可能仅提示通过对话或编辑 .claude/agents/ 来管理自定义角色；较老版本可能显示交互式管理向导。不要以"没有弹出创建界面"判断 Subagents 失效。

7. 首次验证与日常使用

7.1 A 组：验证全局规则已加载

进入任意已信任的项目。

Windows PowerShell：

powershell 复制代码

cd D:\workspace\projects\your-project
claude

macOS Terminal / iTerm2：

bash 复制代码

cd ~/Projects/your-project  # 替换为真实项目目录
claude

在 Claude Code 中执行：

text 复制代码

/context all

预期在 Memory files 下看到真实加载路径，例如：

text 复制代码

C:\Users\Administrator\.claude\CLAUDE.md
AGENTS.md

macOS 示例则可能是：

text 复制代码

/Users/<用户名>/.claude/CLAUDE.md
AGENTS.md

你目前已完成 Windows 端此项检查 ：先前输出显示加载了用户级 CLAUDE.md（约 255 tokens）和一份 AGENTS.md（约 2.9k tokens）。

7.2 B 组：验证开关已写入

Windows PowerShell：

powershell 复制代码

(Get-Content "$HOME\.claude\settings.json" -Raw |
  ConvertFrom-Json).env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

macOS（若安装 jq）：

bash 复制代码

jq -r '.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS' ~/.claude/settings.json

或者使用第 4.2 节的 python3 / cat 检查。

预期输出：

text 复制代码

你目前已完成 Windows 端此项检查 ：PowerShell 命令实际返回 1；macOS 仍需在对应设备上实际检查。

7.3 C 组：验证真正创建 Team（建议先只读）

在交互式 Claude Code 中发送一次验证任务：

请创建一个原生 Agent Team ，不是只调用普通 Subagents。对当前项目分别从架构、测试与安全三个角度并行做只读检查；不要修改文件。让成员交换发现，汇总后结束。

预期观察：

出现 Team Lead 和 Teammates；成员可直接收发消息。
支持任务工具的会话里可看到共享任务列表，按 Ctrl + T 切换。
可以选中某位 Teammate，按 Enter 查看其独立会话。
所有工作完成后由 Lead 汇总结论。

特别说明：Agent 面板中出现多个条目不能单独证明 Team 成立，因为普通 Subagents 也可能出现在面板。应以实际 Team 建立、消息与共享任务行为判断。

7.4 日常使用：不再重复发送编排提示词

例如：

text 复制代码

帮我优化登录模块，确保现有功能不回归。

全局规则会持续指导 Claude：小任务可直接做；涉及专项审查时委派 Subagents；明确能并行合作时才可能创建 Team。Claude 仍可以决定不创建 Team，这是合理的。

8. Team 交互、模型与权限

8.1 常用操作

操作	使用方法
查看成员	主终端输入框下方的 Agent 面板
切换成员	`↑` / `↓` 选择，`Enter` 进入其记录
给成员发消息	进入成员视图后输入消息
停止所选成员	在选中成员时按 `x`
显示共享任务	`Ctrl + T`，前提是该会话具备 Task 工具
查看 Subagent 执行情况	`/tasks`（具体显示会随版本变化）
让成员退出	告诉 Lead 让指定 Teammate shutdown

8.2 模型是不是继承主 Agent

对 Team 而言，模型选取大致按下列优先级：

创建 Teammate 的提示明确指定的模型。
如果来自自定义 Subagent 定义，则使用它的 model；inherit 表示主模型。
CLAUDE_CODE_SUBAGENT_MODEL（当设置且不为 inherit）。
否则使用 Team Lead 当前模型。

因此不指定单独模型时通常跟随主模型；但每个成员在创建时确定模型，主 Agent 之后切换模型，不会自动让已创建成员跟着变。

如你使用自定义模型网关（例如 gpt-6.1-sol），还需确认该网关对独立 Teammates 的实际支持；不能只凭 /context 的主模型名称推断所有成员都成功启动或继承。

8.3 权限与安全边界

Teammates 通常从 Team Lead 继承权限模式（dontAsk 有例外）。
成员的权限提示回到 Lead 会话处理；Teammate 之间的消息不能代替用户授权。
in-process 成员受 Lead 会话有效的允许/拒绝规则约束。
--dangerously-skip-permissions 会扩大 Team 的权限风险，不建议在日常 Windows 或 macOS 开发主机使用。
不要仅通过"请勿修改文件"来约束高风险操作；如必须技术上阻止，使用工具 allowlist、权限规则、Hooks、只读执行环境或仓库保护。

8.4 并发修改与 Worktree

Agent Teams 的成员默认共享同一个工作目录。因此：

并行只读分析最容易安全落地。
并行开发必须先分清模块、文件归属和任务依赖。
不要让两个 Teammates 同时改同一文件。
若需要强隔离，显式设计独立 Git Worktree / 分支、测试及集成步骤；不要认为开启 Team 就自动实现每成员独立 Worktree。
自定义 Subagent 的 isolation: worktree 只适用于它按对应机制作为 Subagent 启动的场景；当具名调用被升级为 Teammate 时，不能指望该字段自动提供隔离。

9. 完整开发工作流与质量门禁

9.1 推荐的阶段关系

#mermaid-svg-c5Ga7aBkRGIJTQph{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-c5Ga7aBkRGIJTQph .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-c5Ga7aBkRGIJTQph .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-c5Ga7aBkRGIJTQph .error-icon{fill:#552222;}#mermaid-svg-c5Ga7aBkRGIJTQph .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-c5Ga7aBkRGIJTQph .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-c5Ga7aBkRGIJTQph .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-c5Ga7aBkRGIJTQph .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-c5Ga7aBkRGIJTQph .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-c5Ga7aBkRGIJTQph .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-c5Ga7aBkRGIJTQph .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-c5Ga7aBkRGIJTQph .marker{fill:#333333;stroke:#333333;}#mermaid-svg-c5Ga7aBkRGIJTQph .marker.cross{stroke:#333333;}#mermaid-svg-c5Ga7aBkRGIJTQph svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-c5Ga7aBkRGIJTQph p{margin:0;}#mermaid-svg-c5Ga7aBkRGIJTQph .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-c5Ga7aBkRGIJTQph .cluster-label text{fill:#333;}#mermaid-svg-c5Ga7aBkRGIJTQph .cluster-label span{color:#333;}#mermaid-svg-c5Ga7aBkRGIJTQph .cluster-label span p{background-color:transparent;}#mermaid-svg-c5Ga7aBkRGIJTQph .label text,#mermaid-svg-c5Ga7aBkRGIJTQph span{fill:#333;color:#333;}#mermaid-svg-c5Ga7aBkRGIJTQph .node rect,#mermaid-svg-c5Ga7aBkRGIJTQph .node circle,#mermaid-svg-c5Ga7aBkRGIJTQph .node ellipse,#mermaid-svg-c5Ga7aBkRGIJTQph .node polygon,#mermaid-svg-c5Ga7aBkRGIJTQph .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-c5Ga7aBkRGIJTQph .rough-node .label text,#mermaid-svg-c5Ga7aBkRGIJTQph .node .label text,#mermaid-svg-c5Ga7aBkRGIJTQph .image-shape .label,#mermaid-svg-c5Ga7aBkRGIJTQph .icon-shape .label{text-anchor:middle;}#mermaid-svg-c5Ga7aBkRGIJTQph .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-c5Ga7aBkRGIJTQph .rough-node .label,#mermaid-svg-c5Ga7aBkRGIJTQph .node .label,#mermaid-svg-c5Ga7aBkRGIJTQph .image-shape .label,#mermaid-svg-c5Ga7aBkRGIJTQph .icon-shape .label{text-align:center;}#mermaid-svg-c5Ga7aBkRGIJTQph .node.clickable{cursor:pointer;}#mermaid-svg-c5Ga7aBkRGIJTQph .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-c5Ga7aBkRGIJTQph .arrowheadPath{fill:#333333;}#mermaid-svg-c5Ga7aBkRGIJTQph .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-c5Ga7aBkRGIJTQph .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-c5Ga7aBkRGIJTQph .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-c5Ga7aBkRGIJTQph .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-c5Ga7aBkRGIJTQph .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-c5Ga7aBkRGIJTQph .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-c5Ga7aBkRGIJTQph .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-c5Ga7aBkRGIJTQph .cluster text{fill:#333;}#mermaid-svg-c5Ga7aBkRGIJTQph .cluster span{color:#333;}#mermaid-svg-c5Ga7aBkRGIJTQph div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-c5Ga7aBkRGIJTQph .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-c5Ga7aBkRGIJTQph rect.text{fill:none;stroke-width:0;}#mermaid-svg-c5Ga7aBkRGIJTQph .icon-shape,#mermaid-svg-c5Ga7aBkRGIJTQph .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-c5Ga7aBkRGIJTQph .icon-shape p,#mermaid-svg-c5Ga7aBkRGIJTQph .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-c5Ga7aBkRGIJTQph .icon-shape rect,#mermaid-svg-c5Ga7aBkRGIJTQph .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-c5Ga7aBkRGIJTQph .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-c5Ga7aBkRGIJTQph .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-c5Ga7aBkRGIJTQph :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 简单
专项
高并行价值
否
是
否
是
需求与验收条件
主 Agent 分析依赖
选择执行方式
单 Agent 开发
Subagents 执行独立任务
Agent Teams 协作
运行相关测试 / Lint / 类型检查
检查结果通过?
修复已确认问题
必要时独立 Review
验收通过?
汇总证据，等待合并授权

原则：不要为了满足图中的视觉分工，强行并行"开发、测试、审查"三个互相依赖的步骤。能提前并行的可以是测试设计、代码探索或不同模块实现，最终测试仍需针对可运行产物。

9.2 CLAUDE.md、Hooks、CI 如何分工

层级	示例	约束强度
`CLAUDE.md`	"复杂变更做独立审查"	指导性
Subagent tools	Reviewer 只允许 Read / Grep / Glob	工具能力限制
`TaskCompleted` / `TeammateIdle` Hooks	在任务完成时执行验证，失败反馈	可执行门禁，需正确实现
CI / 分支保护	未通过测试或未获审核禁止合并	仓库侧强制约束

关于 Hooks ：官方提供 TaskCreated、TaskCompleted、TeammateIdle 等事件。根据具体事件退出码与输出协议，可以阻止任务完成或向 Agent 反馈问题。配置前应先定义真正可执行的验收命令；不要创建只输出"FAIL"的空壳门禁。Windows 环境可使用 PowerShell Hook 脚本；macOS 环境可使用 bash/zsh 脚本（例如 scripts/check-task.sh），确保可执行权限 chmod +x scripts/check-task.sh。Hooks 的命令字段、输入数据与退出码必须遵守当前 Hooks 官方文档（https://code.claude.com/docs/en/hooks）为准。

9.3 为什么不要默认全自动合并 main

Prompt 不是 Git 访问控制。
Team 自身不持有完整的 PR 审批/CI 状态机。
对主分支的保护应由 GitHub/GitLab 分支保护规则和 CI 强制实施。
本文全局规则只允许"在最终验收后请求授权"，不允许未经授权直接合并。

10. 常见问题与故障排查（双平台）

Q1：已经设置为 `1`，但没有创建 Team？

先确认是在交互式 claude 中，而不是 claude -p。然后使用第 7.3 节的明确创建原生 Team测试语句。普通的小任务不创建 Team 属于正常行为。

Q2：明明想要 Subagent，却出现 Teammate？

Agent Teams 开启后，具名的 Subagent 调用可能转为 Teammate。若要暂时恢复普通具名 Subagent 行为，把开关设为 0：

json 复制代码

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

Claude Code 会重新读取用户配置中的环境变量，不一定需要重启；其他更高优先级配置仍可能覆盖该值。

Q3：`/context all` 只显示 Memory 文件，不显示 Team 状态？

正常。/context all 用来排查上下文和指令文件，不负责证明 Team 运行状态。真正验证 Team 要看是否创建了 Teammates、消息与任务协作。

Q4：`AGENTS.md` 已加载，是否还要复制到 `CLAUDE.md`？

不用。当前已加载就不必重复；只有当实际加载策略发生变化或不同项目的规则互相冲突时再调整。注意新版 Claude Code 对项目级 CLAUDE.md 与 AGENTS.md 的优先读取规则。

Q5：为什么成员执行权限提示很多？

Teammates 的权限请求可能集中出现在 Lead 会话。可以针对可信的常用命令配置最小允许规则，但不要直接开启全局无限权限。

Q6：为什么 Team 显示任务完成，实际测试没跑？

任务列表状态不是测试结果。检查终端执行记录和 CI 结果；把最重要的条件加到 Hooks 或仓库侧门禁，而不是只依赖编排提示词。

Q7：多个成员修改同一文件冲突怎么办？

先减少并行写入，按文件/模块划分所有权；必要时采用独立 Worktree。不要通过堆叠无意义锁和重复校验替代合理的任务分工。

Q8：恢复历史会话以后 Teammates 不见了？

当前 Agent Teams 的 in-process 模式不能通过 /resume 完整恢复旧的 Teammates。可让 Lead 基于已有任务结论重新创建成员，关键进展应记录在仓库文档或任务系统中。

Q9：为什么运行成本突然变高？

每个 Teammate 都有独立上下文和模型请求。减少并发成员，避免简单任务组队，优先让专项问题走 Subagent；仅在并行协作有实质收益时使用 Team。

Q10：自定义 Reviewer 无法被发现？

检查文件位置和 YAML frontmatter：第一行必须是 ---，同时要有合法 name 与 description。项目级目录是 .claude/agents/，用户级目录是 ~/.claude/agents/。新版支持监测文件变化，但某些情况下重启会话仍是最直接的排障方式。

Q11：macOS 提示 `claude: command not found`？

先执行 command -v claude。如果使用原生安装，检查 ls -l ~/.local/bin/claude 并参考安装器的 PATH 提示。若用 Homebrew 安装，执行 brew list --cask claude-code 和 brew --prefix 核查；不要同时保留多套安装方式。重新打开终端后运行 claude doctor。

Q12：macOS 的 tmux / iTerm2 无法分屏？

先把 teammateMode 改为 in-process，确认 Team 本身工作正常。
tmux：检查 command -v tmux，确认 tmux -V 能返回版本；优先在 tmux 会话中设置 teammateMode: auto。
iTerm2 原生窗格：需要 it2 CLI 及 Python API 开关；仅安装 iTerm2 不够。
VS Code 集成终端不支持这种 split-pane 显示，应回到 in-process。
macOS tmux 遗留会话可先用 tmux ls 找出目标会话，再针对正确的会话名 执行 tmux kill-session -t <name>；不要直接 tmux kill-server 误伤其他工作。

Q13：macOS 修改了配置，仍没有启用 Team？

先检查 ~/.claude/settings.json 是否为合法 JSON；确认 env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 是字符串 "1"；在新的交互式 claude 会话中执行第 7.3 节只读 Team 测试。注意 CLAUDE.md 内容加载成功不能证明 Teams 实际启用，项目/企业级配置也可能影响行为。

11. 禁用、回退与维护建议

11.1 临时关闭 Agent Teams

将 ~/.claude/settings.json 中：

json 复制代码

"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"

Windows 和 macOS 都是改同一个用户级 settings.json 字段；保存后再进行一次新委派测试。恢复时改回 1。如果本次只是 Shell 临时开启，则关闭对应终端或在 macOS 使用 unset CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS、在 PowerShell 使用 Remove-Item Env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 清理本次会话变量。

11.2 想完全停用动态编排策略

备份或编辑用户级 ~/.claude/CLAUDE.md，删除 Automatic Orchestration 部分即可。不要删除整个 .claude 文件夹，里面可能还有凭据、设置、Skills、会话等。

11.3 日常维护的推荐准则

首先使用原生功能，不因为"可以创建 Team"就强制每次创建。
发现明确、重复的角色需求后，才新增自定义 Subagent。
发现反复发生且可验证的质量问题后，才增加 Hook 或 CI 门禁。
修改全局配置前备份，并用一个只读小任务验证，不直接拿生产项目试错。
团队编排运行情况应以日志与任务输出为证，不能把"Claude 说已经完成"当成通过验收。

12. 配置验收清单（Windows 实测 / macOS 模板）

不要混淆验证状态：下表中的"Windows 已确认"来自用户在本次对话提供的真实命令输出；Mac 版本是补充的完整操作步骤，尚未在用户的 Mac 设备上执行。

检查	Windows 11	macOS	验证方法
全局 `CLAUDE.md` 存在	✅ 已确认	⬜ 待验证	Win `Get-Item`；Mac `ls -l ~/.claude/CLAUDE.md`
全局规则内容正确	✅ 已确认	⬜ 待验证	Win `Get-Content -Raw`；Mac `cat ~/.claude/CLAUDE.md`
全局规则进入上下文	✅ 已确认	⬜ 待验证	Claude Code 内 `/context all`
项目 `AGENTS.md` 已加载	✅ 已确认	依项目	Claude Code 内 `/context all`
Teams 用户级开关为 `"1"`	✅ 已确认	⬜ 待验证	第 4 节的各平台配置检查
Subagents 原生能力	✅ 可用	✅ 可用	不需要额外功能开关
实际成功创建原生 Team	⬜ 尚未验证	⬜ 尚未验证	第 7.3 节的交互式只读测试
Teammate 间消息与共享任务	⬜ 尚未验证	⬜ 尚未验证	成员面板 / `Ctrl + T`
测试、Review 与门禁真实执行	按任务验证	按任务验证	终端日志 / CI 证据

最终完成标准 ：不仅看到配置文件中 1，还要完成一次真实的交互式 Agent Team 创建与协作测试。

13. 官方参考资料

Claude Code --- 官方安装（macOS / Windows）（https://code.claude.com/docs/en/setup）
Claude Code --- 设置文件与优先级（https://code.claude.com/docs/en/settings）
Claude Code --- Agent Teams（https://code.claude.com/docs/en/agent-teams）
Claude Code --- Subagents（https://code.claude.com/docs/en/sub-agents）
Claude Code --- Memory / CLAUDE.md / AGENTS.md（https://code.claude.com/docs/en/memory）
Claude Code --- Hooks（https://code.claude.com/docs/en/hooks）
Claude Code --- Permissions（https://code.claude.com/docs/en/permissions）

一句话结论 ：Windows 和 macOS 都能通过用户级 ~/.claude/settings.json + ~/.claude/CLAUDE.md 一次性配置原生动态编排。Windows 已确认全局规则与 Teams 开关成功配置；Mac 请按第 3--7 节独立执行验证。两端均无需安装 OMC，也无需在每个项目重复配置固定角色。

Claude Code 原生 Agent 编排配置与使用手册：Subagents + Agent Teams 双平台落地指南