agents24 agent-teams 插件 /team-feature 命令深度解析：基于文件所有权与依赖管理的多 Agent 并行特性开发

/team-feature 是 agents 仓库 agent-teams 插件中用于"多 Agent 并行开发特性"的核心编排命令：它把一个特性描述拆解为文件所有权互斥的工作流（work stream），通过 blockedBy 依赖关系管理流间协作，并用独立的集成验证阶段保证并行产出的代码能够真正合拢。读完本篇，你将掌握该命令的完整参数语义、七个执行阶段的具体动作、团队角色分工（team-lead / team-implementer），以及与之配套的并行特性开发技能库（文件所有权策略、接口契约、分支与合并策略、任务协调协议），从而在实际的 Claude Code 环境中安全地运行多实现者并行开发工作流。

1. 命令定位与前置条件

/team-feature 的完整定义位于 team-feature.md，其 frontmatter 声明了命令的描述与参数签名：

• description: "Develop features in parallel with multiple agents using file ownership boundaries and dependency management"
• argument-hint: <feature-description> [--team-size N] [--branch feature/name] [--plan-first]

从 插件 README 可以看出，/team-feature 是该插件七条斜杠命令之一，其余命令（/team-spawn、/team-status、/team-shutdown、/team-review、/team-debug、/team-delegate）分别负责团队的生成、监控、关闭、评审、调试与任务委托；/team-feature 则专注于"带文件所有权边界的并行特性开发"这一场景。

1.1 前置检查（Pre-flight Checks）

命令启动时首先执行两项检查（原文档 "Pre-flight Checks" 一节）：

1. 验证实验特性开关：必须设置环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。Agent Teams 是 Claude Code 的实验功能，未开启时命令应中止（这一点与 team-spawn.md 中的预检逻辑一致：未设置时提示用户并停止执行）。
2. 解析 $ARGUMENTS 参数：

参数	含义	默认值
<feature-description>	要构建的特性描述（位置参数）	必填
--team-size N	实现者（implementer）数量	2
--branch	git 分支名	从特性描述自动生成
--plan-first	先拆解并向用户展示计划、获得批准后再生成团队	关闭

安装与配置方式（来自 README）：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

/plugin marketplace add wshobson/agents
/plugin install agent-teams@claude-code-workflows

此外还可在 ~/.claude/settings.json 中配置队友显示模式：

{
  "teammateMode": "tmux"
}

可选模式："tmux"（每个队友一个 tmux 窗格，推荐）、"iterm2"（macOS 专属，每个队友一个 iTerm2 标签页）、"in-process"（同进程运行，默认值）。

一个典型调用（摘自 README 的 Quick Start）：

/team-feature "Add user authentication with OAuth2" --team-size 3 --plan-first

README 的最佳实践明确要求：特性开发务必加 --plan-first，在生成实现者之前先审查拆解方案；并且团队宜小不宜大，2–4 个队友是协调开销与并行收益的平衡点。

2. Phase 1–2：分析与特性拆解

2.1 代码库分析（Phase 1）

命令第一阶段要求先理解特性范围，然后探索代码库，识别四类信息：

• 需要修改的文件（Files that will need modification）
• 需要遵循的既有模式与约定（Existing patterns and conventions）
• 与现有代码的集成点（Integration points）
• 需要同步更新的测试文件（Test files that need updates）

这一阶段实际上是让编排者扮演 team-lead 定义中的"任务分解"能力：把复杂任务拆成独立、可并行的工作单元，并为每个单元定义明确的验收标准、估算相对复杂度以平衡负载、识别共享依赖与集成点。

2.2 拆解为工作流（Phase 2）

拆解规则在原文档中给出四条硬性约束：

1. 每个工作流获得独占的文件所有权——任何文件不得出现在两个流中（no overlapping files）；
2. 定义流之间的接口契约（interface contracts）；
3. 识别流间依赖——用 blockedBy/blocks 关系表达；
4. 跨流平衡工作量。

这些约束与配套技能 parallel-feature-development 中的"基本法则（The Cardinal Rule）"完全对应：One owner per file. 文件不得被分配给多个实现者。

2.3 --plan-first 的拆解展示模板

当指定 --plan-first 时，命令会把拆解结果以固定模板呈现给用户，等待批准后才继续；用户要求修改时则调整拆解。原文档给出的展示格式为：

## Feature Decomposition: {feature}

### Stream 1: {name}
Owner: implementer-1
Files: {list}
Dependencies: none

### Stream 2: {name}
Owner: implementer-2
Files: {list}
Dependencies: blocked by Stream 1 (needs interface from {file})

### Integration Contract
{shared types/interfaces}

模板中 "Dependencies: blocked by Stream 1 (needs interface from {file})" 一行体现了依赖语义：流 2 之所以等待流 1，不是简单的先后顺序，而是因为它需要流 1 产出的某个文件中的接口——这正是依赖图设计的核心思想。

2.4 文件所有权如何落地：决策框架与所有权策略

命令本身只说"独占文件所有权"，具体怎么分配则由 file-ownership.md 提供的决策框架支撑，共四步：

1. Map All Files：列出该特性需要新建或修改的每一个文件；
2. Identify Natural Clusters：按目录邻近性、功能关系（互相 import 的文件）、层归属（全部 UI / 全部 API 文件）聚簇；
3. Assign Clusters to Owners：每个簇成为一个实现者的所有权边界，要求没有任何文件跨簇、簇内内聚、跨簇依赖最小化；
4. Define Interface Points：在簇交互处定义共享类型定义（归 lead 或指定实现者所有）、API 契约（函数签名、请求/响应形状）、事件契约（事件名与载荷形状）。

该参考文档还给出了按项目类型的所有权划分示例：

React/Next.js 前端

implementer-1: src/components/{feature}/   (UI components)
implementer-2: src/hooks/{feature}/        (custom hooks, state)
implementer-3: src/api/{feature}/          (API client, types)
shared:        src/types/{feature}.ts      (owned by lead)

Express/Fastify 后端

implementer-1: src/routes/{feature}.ts, src/controllers/{feature}.ts
implementer-2: src/services/{feature}.ts, src/validators/{feature}.ts
implementer-3: src/models/{feature}.ts, src/repositories/{feature}.ts
shared:        src/types/{feature}.ts      (owned by lead)

Python Django

implementer-1: {app}/views.py, {app}/urls.py, {app}/forms.py
implementer-2: {app}/models.py, {app}/serializers.py, {app}/managers.py
implementer-3: {app}/tests/
shared:        {app}/types.py              (owned by lead)

技能主文件还补充了三种更抽象的所有权策略（SKILL.md）：

• 按目录：实现者拥有特定目录，适合目录边界清晰的代码库；
• 按模块：拥有逻辑模块（可跨目录），适合面向特性/领域驱动架构；
• 按层：拥有 UI 层 / 业务逻辑层 / 数据层，适合传统 MVC/分层架构。

接口契约的共享文件模式：当实现者需要在边界处协作时，契约文件（如 src/types/auth-contract.ts）由 team-lead 拥有、对实现者只读，双方只 import 而不修改：

// src/types/auth-contract.ts (owned by team-lead, read-only for implementers)
export interface AuthResponse {
  token: string;
  user: UserProfile;
  expiresAt: number;
}

export interface AuthService {
  login(email: string, password: string): Promise<AuthResponse>;
  register(data: RegisterData): Promise<AuthResponse>;
}

这直接呼应了 team-lead.md "File Ownership Rules" 第 4 条：如果一个文件确实需要多个队友改动，该文件归 lead 所有，由 lead 顺序应用变更——/team-feature 的拆解阶段就是在落实这条规则。

3. Phase 3：团队生成（Team Spawn）

原文档 Phase 3 定义了四个动作：

1. 若指定了 --branch，用 Bash 创建并检出分支：

   git checkout -b {branch-name}
   

2. 使用 TeamCreate 工具创建团队，team_name 取 "feature-{timestamp}"，并附 description；

3. 生成一个 team-lead 代理负责协调；

4. 为每个工作流使用 Agent 工具生成一个 team-implementer，参数为：

   • name: implementer-{n}
   • subagent_type: "agent-teams:team-implementer"
   • prompt: 包含拥有的文件清单、接口契约、实现要求

这套生成流程与 team-spawn.md 中 feature 预设的配置一致：feature 预设默认 3 名成员（1 个 team-lead + 2 个 team-implementer），团队名默认 feature-team（而 /team-feature 则用带时间戳的 feature-{timestamp} 以避免重名），显示模式推荐 tmux。预设团队定义 中还给出了该预设的成员任务模板：

Subject: Implement {work stream name}
Description:
  Owned files: {explicit file list}
  Requirements: {specific deliverables}
  Interface contract: {shared types/APIs}
  Acceptance criteria: {verification steps}
  Blocked by: {dependency task IDs if any}

值得注意的两个细节来自 team-spawn.md 的经验性约束，/team-feature 的生成阶段同样适用：

• 不要用角色名 team-lead 作为生成成员的名字——团队创建过程可能保留角色类名称，应使用唯一的成员名；
• 始终使用 Agent 工具实际返回的名字（或 ~/.claude/teams/{team-name}/config.json 中列出的名字）称呼队友，不要使用 UUID 或角色别名。若名字因冲突被加后缀（如 implementer-1 变成 implementer-1-2），后续所有消息和任务都要使用加后缀的名字。

3.1 实现者的行为契约：team-implementer

被生成的 team-implementer 并非空壳，team-implementer.md 为其定义了严格的文件所有权协议：

1. 只修改分配给你的文件——以任务描述中的显式文件清单为准；
2. 绝不触碰共享文件——需要改动共享文件时，发消息给 team-lead；
3. 新文件只能创建在自己的所有权边界内；
4. 接口契约不可变——未经 team-lead 批准不得修改已商定的接口；
5. 拿不准就问——触碰任何不在所有权清单中的文件前先向 lead 确认。

实现者内部还有一套五阶段工作流（理解任务 → 规划实现 → 构建 → 验证 → 汇报），其中"汇报"阶段要求通过 TaskUpdate 把任务标记为已完成、向 lead 发送变更摘要、标注对其他队友的集成关切，并立即上报阻塞而不是自行绕开。这些行为规范解释了为什么 /team-feature 只需在 prompt 中传入"拥有的文件 + 接口契约 + 实现要求"三要素，即可让并行实现者按边界自律。

4. Phase 4：任务创建与依赖编排

原文档 Phase 4 定义了三步任务装配：

1. 对每个工作流调用 TaskCreate：
   • Subject: "{stream name}"
   • Description: 拥有文件、需求、接口契约、验收标准
2. 用 TaskUpdate 为依赖流设置 blockedBy 关系
3. 用 TaskUpdate 把任务分配给实现者（设置 owner）

blockedBy/blocks 的用法与 task-coordination-strategies 技能 中的示例一一对应：

TaskCreate: { subject: "Build API endpoints" }         → Task #1
TaskCreate: { subject: "Build frontend components" }    → Task #2
TaskCreate: { subject: "Integration testing" }          → Task #3
TaskUpdate: { taskId: "3", addBlockedBy: ["1", "2"] }  → #3 waits for #1 and #2

该技能给出的依赖图设计原则同样适用于 /team-feature 的拆解阶段：

1. 最小化链深——宁可宽而浅，不要深而窄；
2. 识别关键路径——最长链决定最小完成时间；
3. 谨慎使用 blockedBy——只添加真正必要的依赖；
4. 避免循环依赖——A 阻塞 B 又阻塞 A 即死锁。

dependency-graphs.md 进一步给出了五种模式及反模式，可直接作为 Phase 2 拆解时的选型参考：

模式	并行度	适用场景
全独立	最大（所有任务并行）	任务操作完全分离的文件/模块；集成任务 blockedBy 全部
顺序链	无	每个任务依赖前一个的输出（尽量避免）
钻石（共享基础）	B、C 在 A 完成后并行	B、C 都需要 A 的产出（如共享类型）
Fork-Join（分阶段并行）	阶段内并行	天然有依赖阶段的流程（build → test → deploy）
流水线	两条并行链	从同一起点分出的两条独立特性链

反模式包括：循环依赖（死锁，修复方法是把共享依赖抽成独立任务）、不必要的依赖（移除 blockedBy 让其独立运行）、星型瓶颈（A 过慢拖累全部下游，应尽量把 A 的工作并行化）。

任务描述本身的写法也有规范——SKILL.md 要求每个任务包含六要素：目标、拥有文件、需求、接口契约、验收标准、范围边界，并给出了完整模板：

## Objective
Build the user authentication API endpoints.

## Owned Files
- src/api/auth.ts
- src/api/middleware/auth-middleware.ts
- src/types/auth.ts (shared — read only, do not modify)

## Requirements
- POST /api/login — accepts email/password, returns JWT
- POST /api/register — creates new user, returns JWT
- GET /api/me — returns current user profile (requires auth)

## Interface Contract
- Import User type from src/types/auth.ts (owned by implementer-1)
- Export AuthResponse type for frontend consumption

## Acceptance Criteria
- All endpoints return proper HTTP status codes
- JWT tokens expire after 24 hours
- Passwords are hashed with bcrypt

## Out of Scope
- OAuth/social login
- Password reset flow
- Rate limiting

注意 "Owned Files" 中显式标注 shared — read only, do not modify 的写法——把"只读共享契约"直接编码进任务描述，正是 Phase 2 "每个流获得独占文件所有权"约束在执行层的落点。

5. Phase 5：监控与协调

原文档 Phase 5 定义了 lead 的三项持续职责：

1. 监控 TaskList 掌握进度；
2. 随实现者完成任务：检查集成问题、解除依赖任务阻塞、必要时重新平衡负载；
3. 处理集成点协调：当某个实现者完成接口时，通知依赖它的实现者。

其中"解除阻塞"与"重新平衡"的细节在 task-coordination-strategies 的"Workload Monitoring"一节给出了判断信号表：

信号	含义	动作
某队友空闲而他人忙碌	分配不均	重新分配待办任务
某队友卡在一个任务上	可能有阻塞	主动询问、提供帮助
所有任务都被阻塞	依赖问题	优先解决关键路径
某队友任务量是他人 3 倍	过载	拆分任务或重新分配

重新平衡的步骤为：TaskList 评估现状 → 识别空闲/过载队友 → TaskUpdate 改派 → SendMessage 通知受影响队友 → 观察吞吐改善。

"接口完成时通知依赖方"则对应 team-communication-protocols 技能 中的消息类型选择规则：点对点通知使用 message（默认选择），broadcast 只保留给"影响所有人的关键阻塞、共享资源重大变更"这类场景——因为一次广播会发送 N 条独立消息（N 为团队规模），消耗与团队大小成正比的 API 资源。该技能还列出了若干反模式，对 Phase 5 的协调质量直接相关：

反模式	问题	正确做法
用广播发例行更新	浪费资源、噪音	点对点发给受影响队友
发送 JSON 状态消息	消息系统不为结构化数据设计	用 TaskUpdate 更新任务状态
集成点不沟通	队友基于过期接口开发	你的接口就绪时发消息
用消息微观管理	压垮队友、拖慢工作	只在里程碑检查
用 UUID 称呼队友	难读、易错	永远用队友名字
无视空闲队友	浪费产能	分配新工作或关闭

6. Phase 6：集成验证

原文档规定所有任务完成后执行四步：

1. 用 Bash 验证代码可编译/可构建——运行合适的构建命令；
2. 用 Bash 运行测试——运行合适的测试命令；
3. 发现问题则创建修复任务并指派给合适的实现者（复用 Phase 4 的任务机制做增量修复，而不是另起炉灶）；
4. 向用户汇报集成状态。

这一步的验证项可以与 merge-strategies.md 的"Integration Verification Checklist"对齐，形成更完整的六项检查：

1. 构建检查：代码能否无错误编译/打包？
2. 类型检查：TypeScript/类型标注是否通过？
3. Lint 检查：是否通过 lint 规则？
4. 单元测试：是否全部通过？
5. 集成测试：跨组件测试是否通过？
6. 接口验证：所有接口契约是否与其实现一致？

冲突处理上，同一参考文档给出四条裁决原则，可作为验证阶段发现不一致时的处置依据：契约优先（代码不符合接口契约则代码是错的）、lead 仲裁（lead 决定保留哪个实现）、测试裁决（通过测试的实现是正确的）、手工合并（复杂冲突由 lead 手动处理）。

另外，parallel-feature-development SKILL.md 的 Troubleshooting 一节预判了并行特性开发中最常见的几类问题，对 Phase 6 排障很有参考价值：

• 实现者互相等待共享代码：把共享部分抽成 lead 拥有的独立契约文件，实现者只 import 不修改；
• 所有权清晰仍出现合并冲突：多半是有文件被分给了两个代理，或被双方修改了 index.ts、__init__.py 这类自动导入一切的桶文件——为所有 barrel/index 文件指定唯一 owner，或由 lead 最后合并；
• 一方提前完成但集成被阻塞：用"暂存接口"——先写下游依赖的 stub/mock，集成时再替换为真实实现；
• 特性拆解中途发现拆错了：停止新工作，由 lead 重新分配文件并 broadcast 通知；已写的部分沉没成本可以接受，带着错误的拆分继续更糟；
• 一个实现者写的测试跑不过另一个实现的代码：接口契约漂移了——拥有 API 的一方在未通知测试方的情况下改了签名；应强制"契约文件修改前必须 broadcast"。

7. Phase 7：清理与收尾汇报

原文档 Phase 7 定义了收尾三步，汇报模板为：

## Feature Complete: {feature}

Files modified: {count}
Streams completed: {count}/{total}
Tests: {pass/fail}

Changes are on branch: {branch-name}

随后：

1. 向所有队友发送 shutdown_request；
2. 调用 TeamDelete 移除团队资源。

这个顺序不是随意的：team-communication-protocols 技能 的"Shutdown Protocol"明确了优雅关闭的完整时序——lead 向每个队友发 shutdown_request → 队友以 shutdown_response 回应（approve: true 则保存状态并退出；approve: false 并附理由则继续工作）→ lead 处理拒绝：查看理由（通常是"还在做任务"）、等其当前任务完成后重试 → 所有队友都关闭后再调用 TeamDelete。该技能特别警告："永远不要强制终止拥有未保存工作的队友。"这也解释了为什么 Phase 7 把 shutdown_request 放在汇报之后、TeamDelete 之前——先给用户交付结论，再逐个优雅下线，最后清理资源。

README 的最佳实践第 5 条同样强调：始终用 /team-shutdown 优雅关闭团队，而不是手动杀进程。

8. 端到端执行链路总览

把七个阶段串起来，/team-feature "..." --team-size 3 --plan-first --branch feature/oauth2 的完整执行链路为：

1. 预检：确认 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 已设置，解析四个参数；
2. 分析：探查代码库，确定待改文件、既有约定、集成点、测试文件；
3. 拆解：生成文件所有权互斥的工作流 + 接口契约 + blockedBy 依赖，向用户展示拆解模板并等待批准；
4. 生成：git checkout -b feature/oauth2 → TeamCreate（feature-{timestamp}）→ 生成 team-lead → 按流生成 implementer-{n}（agent-teams:team-implementer），prompt 携带文件清单/契约/需求；
5. 装配任务：每流一个 TaskCreate，依赖流加 blockedBy，TaskUpdate 设置 owner；
6. 监控：TaskList 轮询进度，完成接口时点对点通知依赖方，失衡时重新平衡；
7. 验证：构建 + 测试 + 契约核对，失败则派修复任务；
8. 收尾：输出 Feature Complete 摘要 → 逐队友 shutdown_request（处理拒绝与重试）→ TeamDelete 清理。

9. 实战建议与适用边界

结合 README 最佳实践 与技能库内容，使用 /team-feature 时的建议：

1. 默认加 --plan-first：在生成实现者之前审查拆解，是成本最低的质量闸门；
2. 文件所有权是第一铁律：同一文件绝不分配给多个实现者；边界处用接口契约衔接；
3. 团队保持小规模：2–4 名队友为宜，更大团队的协调开销会吃掉并行收益（--team-size 默认 2 即出于此考虑）；
4. 定期 /team-status：监控进度与任务分布；负载不均时配合 /team-delegate --rebalance；
5. 用 /team-shutdown 收尾：不要用手动杀进程替代 Phase 7 的优雅关闭序列。

需要说明的适用前提与限制：

• 整个工作流依赖 Claude Code 的实验性 Agent Teams 功能（CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1），以及 TeamCreate/TeamDelete、TaskCreate/TaskUpdate/TaskList、SendMessage、Agent 等工具，这些在 team-lead 与 team-implementer 的 frontmatter tools: 字段中有显式声明；
• 团队配置（成员名、agentId）持久化在 ~/.claude/teams/{team-name}/config.json，队友发现（discovery）依赖该文件；
• 分支策略上，/team-feature 采用单分支策略（所有实现者在同一 feature 分支工作），这与 merge-strategies.md 的归纳一致：单分支无合并开销、要求严格的文件所有权，最适合 2–3 人的小团队；4 人以上或关注点重叠的复杂特性，可考虑子分支策略（feature/auth-login、feature/auth-register 等子分支由 lead 按依赖图顺序合并）。
• 若只需一个更轻量的入口，team-spawn.md 的 feature 预设（/team-spawn feature --name xxx）会先落一个静态团队骨架（1 lead + 2 implementer），而 /team-feature 则是"针对具体特性描述"的全流程编排命令，两者定位互补。

10. 相关资源索引

• 命令定义：team-feature.md
• 插件总览与安装：README.md
• 角色定义：team-lead.md、team-implementer.md、team-reviewer.md、team-debugger.md
• 并行特性开发技能：SKILL.md、file-ownership.md、merge-strategies.md
• 任务协调技能：SKILL.md、dependency-graphs.md
• 通信协议技能：SKILL.md
• 预设团队与生成命令：preset-teams.md、team-spawn.md