docs: 审校 Agent 文档术语与架构描述准确性(docs/agent)#231
Merged
claude-code-best merged 1 commit intoclaude-code-best:mainfrom Apr 10, 2026
Merged
docs: 审校 Agent 文档术语与架构描述准确性(docs/agent)#231claude-code-best merged 1 commit intoclaude-code-best:mainfrom
claude-code-best merged 1 commit intoclaude-code-best:mainfrom
Conversation
基于源码验证和官方文档对照，修正三份 Agent 文档的内容准确性： coordinator-and-swarm.mdx: - 对齐官方术语：Leader→Team Lead, teammate→Teammate, 引入 Mailbox 消息系统 - 修正 Swarm 门控为 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1（原文"默认启用"不准确） - 拓扑描述改为"星型+P2P混合"（官方有 Team Lead 角色，非纯网状） - 新增架构组件表、Mailbox 消息系统、Hook 事件(TeammateIdle/TaskCreated/TaskCompleted)、限制说明 - 新增持久化存储路径(~/.claude/teams/, ~/.claude/tasks/) - 移除虚构的"高水位标记"（claimTask 仅使用文件锁） - 修正 Scratchpad 描述（Workers 获得，非 Coordinator 拥有） - 修复引号不匹配 sub-agents.mdx: - 修正为三路径路由（命名 Agent / Fork / GP 回退），原文仅两种 - 补充 isForkSubagentEnabled() 三前提（feature flag + 非Coordinator + 非非交互式） - 新增模型解析优先级（4级链 + inherit 运行时解析） - 新增内置 Agent 表（Explore/Plan/GP/statusline-setup/claude-code-guide） - 新增 Hook 事件表（frontmatter + settings.json 双级别） - 补充异步生命周期完整链路（finalizeAgentTool → getWorktreeResult） - 补充 transcript 存储路径和结果格式细节 worktree-isolation.mdx: - 区分 createWorktreeForSession vs createAgentWorktree 两种函数 - 修正清理机制为 cleanupWorktreeIfNeeded（非 ExitWorktreeTool 手动操作） - 补充 usedSparsePaths 字段
Contributor
📝 WalkthroughWalkthroughDocumentation updates across three agent-related guides. "Agent Swarms" is renamed to "Agent Teams (Swarm)" with expanded component descriptions (Team Lead, Teammate, Mailbox, hooks). Sub-agents documentation clarifies execution paths (named agent, fork, general-purpose), lifecycle handling, and MCP dependencies. Worktree isolation documentation shifts from ExitWorktreeTool to automated cleanup flow with schema updates. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/agent/coordinator-and-swarm.mdx`:
- Line 13: Update the gate description to list the full set of enablement checks
used by src/utils/agentSwarmsEnabled.ts: include the feature flag
feature('COORDINATOR_MODE'), the CLI switch (the command-line/feature toggle
that can enable coordinator mode), the environment variables
CLAUDE_CODE_COORDINATOR_MODE and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, and the
explicit disable/negation conditions checked by that utility; rephrase the line
so it does not imply env vars are the only entrypoint but instead summarizes all
positive and negative checks performed by agentSwarmsEnabled.ts.
In `@docs/agent/sub-agents.mdx`:
- Around line 50-52: The doc incorrectly states that isForkSubagentEnabled()
requires "not being in Coordinator mode"; update the docs so the function is
described as only checking the FORK_SUBAGENT feature flag and
interactive-session status (matching src/tools/AgentTool/forkSubagent.ts), and
move the Coordinator-mode restriction into a note that it is enforced at the
routing layer (not inside isForkSubagentEnabled()); also clarify that omitting
subagent_type falls back to General-purpose Agent rather than triggering a Fork.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 6529cb59-9995-40b4-aed0-82b77ee63a13
📒 Files selected for processing (3)
docs/agent/coordinator-and-swarm.mdxdocs/agent/sub-agents.mdxdocs/agent/worktree-isolation.mdx
| | **角色** | 明确分工：Coordinator 编排、Worker 执行 | 模糊：每个 Agent 自主认领任务 | | ||
| | **通信** | `SendMessage` 定向通信 + `<task-notification>` | 任务文件系统 + 邮箱广播 | | ||
| | **适用** | 需要集中决策的复杂任务 | 并行度高的独立子任务 | | ||
| | **门控** | `feature('COORDINATOR_MODE')` + `CLAUDE_CODE_COORDINATOR_MODE=1` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 环境变量 | |
Contributor
There was a problem hiding this comment.
补充完整门控条件，避免把启用方式写窄。
当前只写环境变量会让读者误以为这是唯一入口。建议把 CLI 开关与禁用条件一起写上，避免和 src/utils/agentSwarmsEnabled.ts 的实际判定范围脱节。
✏️ 建议文案修正
-| **门控** | `feature('COORDINATOR_MODE')` + `CLAUDE_CODE_COORDINATOR_MODE=1` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 环境变量 |
+| **门控** | `feature('COORDINATOR_MODE')` + `CLAUDE_CODE_COORDINATOR_MODE=1` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 或 `--agent-teams`；且受 RAW/legacy SDK 模式约束 |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| | **门控** | `feature('COORDINATOR_MODE')` + `CLAUDE_CODE_COORDINATOR_MODE=1` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 环境变量 | | |
| | **门控** | `feature('COORDINATOR_MODE')` + `CLAUDE_CODE_COORDINATOR_MODE=1` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 或 `--agent-teams`；且受 RAW/legacy SDK 模式约束 | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/agent/coordinator-and-swarm.mdx` at line 13, Update the gate description
to list the full set of enablement checks used by
src/utils/agentSwarmsEnabled.ts: include the feature flag
feature('COORDINATOR_MODE'), the CLI switch (the command-line/feature toggle
that can enable coordinator mode), the environment variables
CLAUDE_CODE_COORDINATOR_MODE and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, and the
explicit disable/negation conditions checked by that utility; rephrase the line
so it does not imply env vars are the only entrypoint but instead summarizes all
positive and negative checks performed by agentSwarmsEnabled.ts.
Comment on lines
+50
to
+52
| <Note> | ||
| Fork 实验的门控函数 `isForkSubagentEnabled()` 需要同时满足三个前提：`FORK_SUBAGENT` feature flag 已启用、当前不在 Coordinator 模式中、且不是非交互式会话。任一条件不满足时，省略 `subagent_type` 会静默降级为 General-purpose Agent，而非触发 Fork。 | ||
| </Note> |
Contributor
There was a problem hiding this comment.
isForkSubagentEnabled() 的函数语义被写错位了。
这里把“非 Coordinator 模式”也写成了该函数的内部前提；但按 src/tools/AgentTool/forkSubagent.ts，该函数本身只覆盖 feature flag 与非非交互式会话。建议把 Coordinator 约束改成“路由层条件”，避免误导读源码的人。
✏️ 建议文案修正
-Fork 实验的门控函数 `isForkSubagentEnabled()` 需要同时满足三个前提：`FORK_SUBAGENT` feature flag 已启用、当前不在 Coordinator 模式中、且不是非交互式会话。任一条件不满足时，省略 `subagent_type` 会静默降级为 General-purpose Agent，而非触发 Fork。
+Fork 路由需要同时满足三个前提：`FORK_SUBAGENT` feature flag 已启用、当前不在 Coordinator 模式中、且不是非交互式会话。
+其中 `isForkSubagentEnabled()` 本身负责前两类中的前者与“非非交互式”检查；Coordinator 模式限制在 `AgentTool.call()` 的路由决策层处理。任一条件不满足时，省略 `subagent_type` 会静默降级为 General-purpose Agent，而非触发 Fork。📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| <Note> | |
| Fork 实验的门控函数 `isForkSubagentEnabled()` 需要同时满足三个前提：`FORK_SUBAGENT` feature flag 已启用、当前不在 Coordinator 模式中、且不是非交互式会话。任一条件不满足时，省略 `subagent_type` 会静默降级为 General-purpose Agent，而非触发 Fork。 | |
| </Note> | |
| <Note> | |
| Fork 路由需要同时满足三个前提：`FORK_SUBAGENT` feature flag 已启用、当前不在 Coordinator 模式中、且不是非交互式会话。 | |
| 其中 `isForkSubagentEnabled()` 本身负责前两类中的前者与"非非交互式"检查；Coordinator 模式限制在 `AgentTool.call()` 的路由决策层处理。任一条件不满足时，省略 `subagent_type` 会静默降级为 General-purpose Agent，而非触发 Fork。 | |
| </Note> |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/agent/sub-agents.mdx` around lines 50 - 52, The doc incorrectly states
that isForkSubagentEnabled() requires "not being in Coordinator mode"; update
the docs so the function is described as only checking the FORK_SUBAGENT feature
flag and interactive-session status (matching
src/tools/AgentTool/forkSubagent.ts), and move the Coordinator-mode restriction
into a note that it is enforced at the routing layer (not inside
isForkSubagentEnabled()); also clarify that omitting subagent_type falls back to
General-purpose Agent rather than triggering a Fork.
zhangqiang1003
pushed a commit
to zhangqiang1003/claude-code
that referenced
this pull request
Apr 10, 2026
基于源码验证和官方文档对照，修正三份 Agent 文档的内容准确性： coordinator-and-swarm.mdx: - 对齐官方术语：Leader→Team Lead, teammate→Teammate, 引入 Mailbox 消息系统 - 修正 Swarm 门控为 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1（原文"默认启用"不准确） - 拓扑描述改为"星型+P2P混合"（官方有 Team Lead 角色，非纯网状） - 新增架构组件表、Mailbox 消息系统、Hook 事件(TeammateIdle/TaskCreated/TaskCompleted)、限制说明 - 新增持久化存储路径(~/.claude/teams/, ~/.claude/tasks/) - 移除虚构的"高水位标记"（claimTask 仅使用文件锁） - 修正 Scratchpad 描述（Workers 获得，非 Coordinator 拥有） - 修复引号不匹配 sub-agents.mdx: - 修正为三路径路由（命名 Agent / Fork / GP 回退），原文仅两种 - 补充 isForkSubagentEnabled() 三前提（feature flag + 非Coordinator + 非非交互式） - 新增模型解析优先级（4级链 + inherit 运行时解析） - 新增内置 Agent 表（Explore/Plan/GP/statusline-setup/claude-code-guide） - 新增 Hook 事件表（frontmatter + settings.json 双级别） - 补充异步生命周期完整链路（finalizeAgentTool → getWorktreeResult） - 补充 transcript 存储路径和结果格式细节 worktree-isolation.mdx: - 区分 createWorktreeForSession vs createAgentWorktree 两种函数 - 修正清理机制为 cleanupWorktreeIfNeeded（非 ExitWorktreeTool 手动操作） - 补充 usedSparsePaths 字段
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
基于源码验证和官方文档对照，修正三份 Agent 文档的内容准确性：
Changes
coordinator-and-swarm.mdx
Leader→Team Lead、teammate→Teammate、引入Mailbox消息系统、Swarm→Agent TeamsCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1（原文"默认启用"不准确）事件（TeammateIdle/TaskCreated/TaskCompleted）、限制说明、持久化存储路径
sub-agents.mdx
isForkSubagentEnabled()三前提条件说明worktree-isolation.mdx
createWorktreeForSessionvscreateAgentWorktree两种函数及差异cleanupWorktreeIfNeeded（非 ExitWorktreeTool 手动操作）Test plan
bun run docs:dev确认文档渲染正常Summary by CodeRabbit