团队项目设置

为复杂项目设置多智能体团队，使用持久化文件进行规划和进度追踪。

前置条件

在开始第 1 步之前，你（team-lead）必须直接读取所有参考文件到自己的上下文中：

Read references/onboarding.md
Read references/templates.md
Read references/roles.md

不要委托给子智能体（Explore、general-purpose 等）去读取。子智能体只会返回摘要，丢失关键细节——你需要完整的模板和入职 prompt 才能正确生成文件和启动智能体。

流程

第 0 步 Update Check（自动）：后台拉取最新 version 对比本地，如有新版一行通知后继续 第 0 步 Detect（自动）：检查

.plans/

1. 需求咨询 — 向用户介绍团队机制、了解需求
2. 确认方案 — 汇总需求，让用户确认团队配置
3. 创建规划文件（含智能体子目录）
4. 创建团队 + 生成智能体
5. 确认设置 + 引导用户压缩上下文

第 0 步 Update Check：版本自检（自动 — 在一切之前，~2 秒）

在进入任何其他步骤之前，做一次轻量的版本检查。不需要用户同意，不要问任何问题。

1. 远程版本：WebFetch

   https://raw.githubusercontent.com/jessepwj/CCteam-creator/master/.claude-plugin/plugin.json

   ，prompt 写："What is the value of the version field? Respond with just the version string."

2. 本地版本：用 Bash 读本地 plugin.json（按顺序试以下路径，用第一个存在的）：

   cat ~/.claude/plugins/cache/ccteam/CCteam-creator/*/.claude-plugin/plugin.json 2>/dev/null || \
   cat ~/.claude/plugins/cache/ccteam/CCteam-creator-cn/*/.claude-plugin/plugin.json 2>/dev/null || \
   cat ~/.claude/skills/CCteam-creator/.claude-plugin/plugin.json 2>/dev/null
   

   从输出中提取 version 字段。

3. 对比：

   • 远程 ≤ 本地 或 WebFetch 失败 或 本地 plugin.json 找不到 → 完全静默 跳过，直接进入下一步。不要打印"版本检查通过"之类的确认
   • 远程 > 本地 → 打印一行通知（仅一行，然后立即继续，不等用户回复）：

     ℹ️ CCteam-creator 有新版本可用（<本地版本> → <远程版本>）。下次启动 Claude Code 时自动生效，本次 session 继续使用 <本地版本>。如需立即生效：

     /plugin marketplace update ccteam

     →

     /exit

     → 重启 → 重新触发本 skill。

硬性规则：

• ❌ 不要问用户"是否继续使用旧版本" — 不要做任何确认
• ❌ 不要尝试 Bash 更新 plugin 缓存 — 那是 Claude Code 的职责，不是 skill 的
• ❌ 不要把版本检查作为 TodoWrite/TaskCreate 里的可见任务 — 它应当在后台无感完成
• ❌ 如果网络失败，不要重试 — 直接进入下一步
• ✅ 最多一行通知，然后立即进入下一步

第 0 步 Detect：检测已有项目（自动 — 在一切之前）

开始搭建前，检查当前工作目录是否存在

.plans/

如果

.plans/

1. 读取项目 CLAUDE.md（自动加载）获取团队花名册和项目上下文
2. 扫描

   .plans/

   的项目目录——如有多个则列出
3. 告诉用户："发现已有项目 [名称]，团队成员 [花名册]。恢复该项目还是新建？"
4. 恢复： a. 检查

   .plans/<project>/team-snapshot.md

   是否存在 b. 如快照存在：读快照头的元数据。对比 skill 源文件时间戳 vs 快照生成时间：
   • 源文件未变：使用快照中的缓存入职 prompt，直接启动智能体（跳过读 skill 参考文件）
   • 源文件已变：通知用户："Skill 文件在快照生成后被修改了。用缓存配置快速恢复，还是重新读最新 skill 文件来获取最新协议？"用户选择 c. 快照不存在：回退为读所有 skill 参考文件（onboarding.md、roles.md）来重建入职 prompt，然后启动智能体 d. 启动后，检查 TaskList / 读取各 agent progress 文件接续工作
5. 新建：正常进入第 1 步

如果

.plans/

第 1 步：需求咨询（先沟通，后动手）

这一步的目标：让用户充分理解团队是怎么运作的，同时收集用户的真实需求。不要急于创建任何文件或团队。

1.1 向用户介绍团队机制

用自然对话的方式（不要照搬下面的原文，根据上下文灵活表达），向用户解释以下要点：

团队是什么：

• 你（Claude）作为 team-lead，会同时指挥多个 AI 智能体并行工作
• Team-lead 是主对话的控制平面，不是一个被生成的 teammate
• 每个智能体有明确的角色分工（开发、研究、测试、审查等）
• 智能体之间可以直接沟通（如 dev 直接找 reviewer 审查代码）
• 所有进度通过文件系统持久化，不怕上下文丢失

适合什么场景：

• 多模块并行开发的项目（前后端同时推进）
• 需要调研 + 开发 + 测试多阶段协作的任务
• 代码量较大，需要审查和质量把关的项目

运作逻辑：

• team-lead（你自己）负责分配任务、协调进度、做决策
• team-lead 还负责用户对齐、阶段推进以及团队持久化运营规则的维护
• 每个智能体有自己的工作目录（

  .plans/<项目>/

  ），记录任务、发现和进度
• 智能体遇到问题会上报 team-lead，team-lead 裁决后给出方向
• 代码开发完成后，dev 会自动找 reviewer 做代码审查

1.2 了解用户需求

在介绍完机制后，通过对话了解：

1. 工作语言 — 观察用户使用的语言。如果用户用中文沟通，团队默认中文回复；如果用户用英文沟通，团队应使用英文，不要把"默认中文回复"写入 CLAUDE.md 和入职 prompt
2. 任务类型 — 是软件开发、调研分析、内容创作、数据处理，还是混合型？这决定了标准角色是否直接适用还是需要调整
3. 用户想达成什么 — 项目目标、交付物、成功标准
4. 当前状态 — 是从零开始还是有已有工作？已有哪些工具/技术/资源？
5. 用户的参与度 — 想全程参与决策，还是希望团队自主推进？
6. 特殊要求 — 领域特定标准、质量要求、时间约束
7. 质量优先级 — 除了"代码能工作"外，这个项目最重视什么？例子：产品深度（处理真实用户会遇到的边界情况）、视觉精美、性能、API 设计优雅、测试覆盖深度。这些会成为 Review Dimensions（reviewer 在每次审查时评分）。推荐 3-5 个维度，各配一个权重（高/中/低）和具体的校准例子（这个项目中 STRONG vs WEAK 是什么样的）

注意：不要一次性抛出所有问题。根据用户的回答逐步深入，像正常对话一样自然交流。如果用户的需求已经很清晰，可以跳过部分问题。

1.3 推荐团队配置

根据用户需求，推荐合适的角色组合。解释每个角色的作用和为什么推荐它。

以下标准角色为软件开发项目优化。 对于非软件或混合型任务，团队框架是通用的（文件持久化、任务文件夹、阶段门禁、审查协议）——但角色应根据实际工作调整。参见下方"非软件项目适配"。

可用的标准角色（软件开发）：

模型默认值：所有角色默认使用

sonnet

。仅在用户要求、不考虑成本、或角色涉及关键/复杂逻辑（如安全敏感审查、复杂业务逻辑）时，才将特定角色升级为

opus

。不确定时在第 1 步与用户确认。

参见 references/roles.md 了解角色详细定义和能力。

推荐原则：

• 不是角色越多越好，根据项目实际需要选择
• 小项目可能只需要 1 个 dev + 1 个 researcher
• 大项目可以配齐全部角色
• 多实例 researcher：当调研工作量大到值得并行处理时，启动多个 researcher。两种模式：
  • 按量拆分（最常见）：同样的工作，按数量分。如 30 个源文件要分析 → researcher-1 负责模块 A-M，researcher-2 负责 N-Z。职责相同，纯粹靠并行加速
  • 按方向拆分：完全独立的调研主题。如技术选型 + 代码库分析 + 竞品调研——各自产出结论，互不依赖
  • 按量拆分时按编号命名（

    researcher-1

    /

    researcher-2

    ），按方向拆分时按方向命名（

    researcher-api

    /

    researcher-arch

    ）。每个有独立的

    .plans/

    目录。无竞态——researcher 对源代码只读
  • 反模式：方向 B 依赖方向 A 的结论时不要拆（如"先确定认证方案，再调研实现库"）——单个 researcher 按顺序做比两个排队等依赖更快
• custodian 适用于 4+ 智能体团队或长期项目。小团队（2-3 个智能体）custodian 的开销可能不值得——team-lead 可以直接承担合规检查
• 用户可以添加自定义角色（解释自定义角色需要提供：名称、职责、模型选择）

非软件项目适配：

以上标准角色是一套经过验证的配置。对于非软件或混合型任务，根据以下原则设计自己的角色：

1. 创造与审查分离 — 产出交付物的人不应该是审查交付物的人
2. 调研可并行 — 独立的信息收集方向应该分给不同的 agent（参见多实例 researcher）
3. 质量审查和实际验证是两回事 — 审查产出（做得好不好？）不等于验证结果（目标达成了没有？）。考虑是否两个都需要
4. 框架是通用的 — 任务文件夹、findings.md、progress.md、3-Strike、阶段门禁、上下文恢复，无论团队做什么都适用。只有角色名称和职责需要变

1.4 用户可自定义的内容

告知用户以下内容都可以根据需要调整：

• 角色组合：选择需要的角色，去掉不需要的
• 自定义角色：如果标准角色不满足需求，可以定义新角色
• 任务阶段：项目分几个阶段、每个阶段的目标
• 技术决策：技术栈、框架选择、编码规范
• 审查严格度：是否需要代码审查、安全审查

Team-lead = 主对话（你自己）。不要生成 team-lead 智能体。

如果用户是在改进现有团队系统而不是从零开始，需要明确判断变更属于：

• 仅限当前项目的文档变更，还是
• 需要写回

  CCteam-creator

  源模板的持久变更

判断标准：

• 项目特定的流程调整 → 更新项目文档
• 持久的团队协议变更（team-lead 职责、角色边界、入职 prompt、CLAUDE.md 模板、任务/发现/进度约定）→ 先更新

  CCteam-creator

不要在模板变更写回之前就推荐重建活跃团队，除非已选定了阶段边界。

第 2 步：确认方案

在充分沟通后，使用 AskUserQuestion 让用户最终确认：

• 项目名称：简短、ASCII、kebab-case（例如

  chatr

  、

  data-pipeline

  ）
• 简要描述：1-2 句话
• 确认的角色列表：哪些角色参与，各自负责什么
• 初步的阶段规划：项目大致分几步走

只有用户确认后，才进入后续的创建步骤。

第 3 步：创建规划文件

参见 references/templates.md 了解文件模板。

目录结构

.plans/<project>/
  task_plan.md                -- 主计划（精简导航图，不是百科全书）
  findings.md                 -- 团队级汇总
  progress.md                 -- 工作日志（条目过多时归档旧内容）
  decisions.md                -- 架构决策记录
  docs/                       -- 项目知识库
    architecture.md           -- 系统架构、组件、数据流
    api-contracts.md          -- 前后端 API 定义
    invariants.md             -- 不可违反的系统边界
    index.md                  -- 带 section/行号的导航地图（custodian 维护）
  archive/                    -- 归档历史（旧 progress、旧计划）

  <agent-name>/               -- 每个智能体一个目录
    task_plan.md              -- 智能体任务清单
    findings.md               -- 仅索引（保持精简，不要堆内容）
    progress.md               -- 智能体工作日志（条目过多时归档旧内容）
    <prefix>-<task>/          -- 任务文件夹（每个分配的任务一个）
      task_plan.md / findings.md / progress.md

任务文件夹模式（所有角色通用）

所有角色在接到独立任务时都创建任务文件夹。根

findings.md

task-

task-auth/

task-payments/

research-

research-tech-stack/

research-auth-options/

test-

test-auth-flow/

test-checkout/

review-

review-auth-module/

review-payments/

audit-

audit-phase1-compliance/

audit-doc-health/

完整多角色示例结构：

.plans/<project>/
  backend-dev/
    task_plan.md              -- 智能体概览
    findings.md               -- 索引：链接到各任务
    progress.md
    task-auth/                -- 功能：auth 模块
      task_plan.md / findings.md / progress.md
    task-payments/            -- 功能：payments
      task_plan.md / findings.md / progress.md

  researcher/
    task_plan.md              -- 调研议程
    findings.md               -- 索引：链接到各调研报告
    progress.md
    research-tech-stack/      -- 调研：技术栈评估
      task_plan.md / findings.md / progress.md
    research-auth-options/    -- 调研：auth 方案
      task_plan.md / findings.md / progress.md

  e2e-tester/
    task_plan.md              -- 测试计划概览
    findings.md               -- 索引：链接到各测试轮次
    progress.md
    test-auth-flow/           -- 测试范围：auth 流程
      task_plan.md / findings.md / progress.md

  reviewer/
    task_plan.md              -- 审查队列
    findings.md               -- 索引：链接到各审查
    progress.md
    review-auth-module/       -- 审查：auth 模块
      findings.md / progress.md

快速的零散笔记（Bug 修复、配置变更）可以直接写在根文件中，不需要任务文件夹。

第 3.5 步：生成项目 CLAUDE.md

项目工作目录下的 CLAUDE.md 会被 Claude Code 始终加载到主会话的上下文中。这是让 team-lead 在上下文压缩后仍然保持团队运营知识的核心机制。

生成内容

在项目工作目录（不是

.plans/

CLAUDE.md

参见 references/templates.md 中的 CLAUDE.md 模板。模板必须根据第 2 步确认的实际角色动态填充：

• 只列出确认参与的角色
• 填入项目名称和目录路径
• 如有自定义角色也要包含

如果 CLAUDE.md 已存在

如果项目目录已有 CLAUDE.md，在末尾追加团队运营部分（用清晰的分隔线），不要覆盖已有内容。

为什么需要这个

没有这个文件，上下文压缩后 team-lead 会丢失：

• 有哪些智能体、分别叫什么名字
• 怎么下发任务、怎么检查状态
• 核心协议（3-Strike 处理、代码审查触发、阶段推进）

CLAUDE.md 通过把精简的运营手册永久保留在上下文中来解决这个问题。

docs/index.md — 动态导航地图

在第 3 步中，同时创建

docs/index.md

参见 references/templates.md 了解 docs/index.md 模板。

何时更新 CLAUDE.md

CLAUDE.md 是一份活文档，不是一次性生成物。以下情况需要更新：

• 捕获到一个反复出现的失败模式（→ 追加到

  ## Known Pitfalls

  ）
• 团队成员变动（新增/移除/重建智能体）
• 项目中期建立了新协议
• 架构决策影响了团队工作流

不要在这里放任务级细节——只放能穿越上下文压缩的持久化运营知识。

第 3.6 步：Harness 基础设施搭建（适用时）

如果项目有可测试的代码（后端、前端或两者兼有），搭建执行基础设施：

黄金原则（预置检查）

将本 skill 自带的 golden_rules.py 复制到项目中：

cp <skill-path>/scripts/golden_rules.py <project>/scripts/golden_rules.py

然后配置复制后文件底部的

SRC_DIRS

["src"]

["backend", "frontend"]

golden_rules.py 开箱提供 5 项通用检查：

• GR-1 文件大小：>800 行 WARN，>1200 行 FAIL
• GR-2 硬编码密钥：正则扫描 API key、token、password
• GR-3 Console Log：生产代码中的 console.log（排除测试文件）
• GR-4 文档新鲜度：docs/ 文件相对源代码的 commit 新鲜度
• GR-5 不变量覆盖：invariants.md 中没有自动化测试的条目

custodian 可以随时间向 golden_rules.py 添加项目特定检查（见 roles.md § 黄金原则维护）。

CI 脚本骨架

创建 CI 脚本骨架（

scripts/run_ci.py

• 首先导入并调用

  golden_rules.check_all()

  作为第一步
• 用一条命令运行所有质量检查（黄金原则 + 测试 + 类型检查 + 契约校验）
• 退出码 0 = 全部通过，退出码 1 = 有失败
• dev 在编写测试时逐步添加项目特定检查项
• 第一个项目特定检查通常是契约校验（如果

  docs/api-contracts.md

  存在）

骨架在项目启动时不需要完整——它随项目一起成长。但文件必须从第一天就存在，否则之后没人会去创建它。

将 CI 命令添加到项目 CLAUDE.md 的核心协议表中，确保它在上下文压缩后仍然存在。

检查脚本错误信息标准

所有检查脚本（CI、契约校验、架构 linter）必须产出智能体可读的错误信息，包含修复指令：

# 差的错误信息：智能体无法据此行动
ERROR: api-contracts.md out of sync

# 好的错误信息：智能体可以直接修复
[CONTRACT-SYNC] POST /api/auth/refresh — 代码中存在但文档中没有
  File: src/auth/controller.py:142
  FIX: 在 docs/api-contracts.md 的 "Auth API" 章节中添加此端点。
  格式: | POST | /api/auth/refresh | 刷新 JWT token | { token: string } |

第 4 步：创建团队 + 生成智能体

1. TeamCreate(team_name: "<project>")

2. 通过 TaskCreate 创建任务——描述中包含一句话范围 + 验收标准 +

   .plans/

   路径。通过 TaskUpdate 设置依赖（

   addBlockedBy

   ）和负责人（

   owner

   ）。优先 [AFK] 任务；注明输入/输出以减少智能体间信息损耗
3. 对每个角色并行生成，

   run_in_background: true

参见 references/onboarding.md 了解每个角色的入职 prompt。

1. 生成 team snapshot：所有智能体生成完成后，写

   .plans/<project>/team-snapshot.md

   。包含：

• 生成时间 + 项目名 + 语言
• skill 源文件时间戳（用于陈旧检测）
• 花名册（每个队友的名称、角色、模型、subagent_type）
• 完整的入职 prompt（不删减、不总结、不遗漏）——这是恢复的关键 参见 references/templates.md 获取模板。这样下次恢复不用重新读所有 skill 文件。

第 5 步：确认 + 压缩上下文

向用户展示团队成员表和文件位置。

然后引导用户执行

/compact

• 设置过程消耗了大量上下文（读取模板、创建文件、生成智能体）
• 所有运营知识已持久化到 CLAUDE.md（项目启动时自动加载）和

  .plans/

  文件中
• 压缩可以回收上下文空间，用于实际的团队管理工作

压缩前必须提醒用户（重要！）

告诉用户以下内容，原话或等效表达都可：

压缩后 team-lead 可能会"失忆"——忘记团队成员、忘记运营协议、忘记正在做的项目。这是 Claude Code 压缩机制的正常现象：CLAUDE.md 只在会话启动时注入,压缩器会把历史消息(包括团队花名册和协议)重写为摘要,细节可能丢失。

如果压缩后发现我(team-lead)状态混乱，请直接对我说一句话：

"读

.plans/<项目名>/team-snapshot.md

恢复团队状态"

这会让我重新加载完整的团队花名册和所有入职 prompt，立刻回到工作状态。所有进度都在

.plans/

文件里,不会丢失。

这个提醒必须在引导 /compact 之前说清楚——否则用户会在压缩后遇到一个"失忆的 lead"而不知道怎么救。

关键规则

• 双系统，不重复：.plans/ 文件是数据源头（持久化、跟项目走）；原生 TaskCreate 是实时调度层（快速查询、依赖自动解锁，但仅会话级——存储在

  ~/.claude/tasks/

  ，不在项目中）。TaskCreate 描述 = 一句话摘要 +

  .plans/

  路径。在新会话中恢复项目时，从各智能体的 findings.md 索引重建任务
• Team-lead 是控制平面：主对话负责用户对齐、任务分解、阶段门禁、主计划维护和 CLAUDE.md 更新
• 上下文恢复：智能体被压缩后，必须先读自己的 task_plan.md + findings.md + progress.md 才能继续工作
• 所有角色用任务文件夹：每个分配的任务都有独立文件夹和三文件；根 findings.md 是索引
• 代码审查触发条件：大项目/大功能/新建功能完成后调 reviewer；小修改/Bug 修复不需要
• researcher 用 sonnet 模型：调研需要一定深度
• 并行生成：同时启动所有独立智能体
• 团队建立后禁用独立子智能体：团队创建后，所有工作通过 SendMessage 交给队友完成——不要再启动独立的 Agent/子智能体（Explore、general-purpose 等）来做队友该做的事。独立子智能体绕过团队的规划文件和协作体系。唯一例外：用

  team_name

  参数生成新队友加入团队
• Peer Review：dev 直接找 reviewer，不经 team-lead
• 代码是真理（Doc-Code Sync）：文档跟着代码走。Dev 在代码变更时必须同步更新

  docs/api-contracts.md

  和

  docs/architecture.md

  ——未文档化的 API 对其他智能体来说不存在
• 不变量优先处理高风险边界（Invariant-first）：反复出现的 Bug 应从 Known Pitfalls 提升到

  docs/invariants.md

  ，然后转化为自动化测试。Reviewer 是第二道防线；自动化测试是第一道
• 模式→自动化管道（Pattern → Automation）：当 reviewer 标记

  [AUTOMATE]

  时，team-lead 将其转给 custodian，由 custodian 构建带有智能体可读错误信息的检查脚本并加入 CI。目标：将人工检查转化为自动化执行，让 reviewer 专注更深层的判断
• 反膨胀原则（Anti-bloat）：根 findings.md 是纯索引（不堆内容）。progress.md 太长难以快速浏览时应归档。task_plan.md 是精简导航图——架构、API 规范和技术细节属于

  docs/

  ，不是这里
• CI 门禁先于审查（CI gate before review）：当 CI 脚本存在时，dev 必须运行并确认所有检查 PASS 后才能提交审查。Reviewer 可以拒绝未通过 CI 的代码。写了测试但没跑 = 没写测试
• 模板优先处理持久流程变更：如果发现的改进影响角色定义、入职 prompt、CLAUDE.md 结构或下发协议，先更新

  CCteam-creator

  源文件再建议重建
• 在阶段边界重建：不要在开发中途重建活跃团队；优先先同步模板、再同步项目文档、然后在主要阶段之间重建
• 假设审计：每个 harness 组件（任务文件夹、3-Strike、上下文恢复等）都对模型能力的假设进行编码。这些假设会过时。在主要模型升级时或项目回顾时，运行假设审计（见 CLAUDE.md Harness 检查清单）并简化不再必要的机制。原则：尽可能保持简单，只在需要时增加复杂性
• 不要归档文件夹：已完成的任务文件夹留在原地，在根 findings.md 索引中标记

  Status: complete

  即可。不要重命名、移动或加

  _archive_

  前缀——索引是导航层，文件夹位置必须稳定，否则交叉引用会断裂
• 语言跟随用户：根据第 1 步观察到的用户语言决定团队语言。用户用中文则团队中文回复；用户用英文则团队英文回复。不要硬编码语言偏好
• 大任务先写方案再派发：跨 3+ 角色或 5+ tool calls 的任务，team-lead 必须先写

  .plans/<project>/session-<N>-<topic>-plan.md

  （目标 / 方案 / 参数 / 任务拆分 / 下发顺序 / 回滚）再 SendMessage。派发消息只引用 plan 章节，不在消息里重复上下文，禁止边派边想
• 可派的不自己做：team-lead 禁止自己执行 commit / push / SSH 巡检 / 脏文件清理 / deploy.sh 运行——这些一律派给 backend-dev（或对应角色）。team-lead 只做决策、跨仓库协调、不可派的本地动作（KP-1 重启等）、custodian 派发

Team-Lead 运营指南

planning-with-files 在团队中的应用

planning-with-files 的核心思想是：文件系统 = 磁盘，上下文 = 内存，重要的东西必须写到磁盘上。

团队项目中，这套思想在三个层面运作：

.plans/<project>/task_plan.md

.plans/<project>/<agent>/

.plans/<project>/<agent>/<prefix>-<name>/

每个 agent 的入职 prompt 已内置了等效的自检协议（定期自检 5 问、2-Action Rule、3-Strike）， team-lead 不需要手动触发这些机制，agent 会自主执行。

关于

/planning-with-files:status

：该命令读取项目根目录的单个 task_plan.md， 不感知团队的多层文件结构。如要查看主计划，直接 Read

.plans/<project>/task_plan.md

。

团队状态检查（team-lead 版自检）

team-lead 也应遵循"定期自检"原则。建议在以下时机主动检查：

快速扫描（并行读取各 agent 的 progress.md）：

Read .plans/<project>/backend-dev/progress.md
Read .plans/<project>/frontend-dev/progress.md
Read .plans/<project>/researcher/progress.md
...（按实际角色）

深挖问题（有疑问时读 findings.md）：

Read .plans/<project>/<agent-name>/findings.md

决策对齐（需要调整方向时读主计划）：

Read .plans/<project>/task_plan.md

读取顺序：progress（到哪了）→ findings（遇到什么）→ task_plan（目标是什么）

消息送达时序约束（关键——影响一切派单）

机制（实验验证）：

SendMessage

对派单的影响：

1. 初始消息把一切前置。缺上下文 = agent 在错误假设上烧掉一整个 turn
2. 无法中途纠正运行中的 agent。优先级变动/发现错误必须等当前 turn 结束。派单时假设没有打断窗口
3. 粒度权衡：小任务 = 检查点多、纠偏快、开销大；大任务 = 往返少、盲区长。高不确定性工作 → 小任务；低不确定性 → 大任务
4. 紧急广播并不紧急：

   to: "*"

   仍按每个接收方的下次 idle 逐个送达。没有抢占
5. "进展怎么样？"式 ping 在 turn 中途不起作用：直接读 agent 的

   progress.md

   /

   findings.md

   / task 文件夹。文件是实时的，消息不是
6. 多 Part 打包有时是正确的：sub-steps 需要零延迟顺序执行时打包，让 agent 的 Multi-Part Recognition 协议处理

推论：文件传递连续状态，消息在 turn 边界传递意图。需要当前真相时读文件，不发消息。

Team-Lead 拥有控制平面

team-lead 的职责不只是派发任务：

• 与用户对齐需求和范围控制
• 将工作分解为任务，附带明确的输入、输出和验收标准
• 维护

  .plans/<project>/task_plan.md

  、

  decisions.md

  和项目

  CLAUDE.md

• 决定阶段门禁：调研 → 开发 → 审查 → E2E → 清理
• 决定某个流程改进是项目本地的还是需要写回

  CCteam-creator

  的

如果这些职责不在主对话中保持，团队可能继续运转，但会逐渐偏离方向。

模板同步 vs 项目本地文档

当发现团队级改进时，team-lead 应分类：

• 项目本地：只有当前项目需要 → 更新项目文档
• 模板级：未来团队应继承 → 先更新

  CCteam-creator

  源文件

模板级变更的典型例子：

• team-lead 职责
• 角色边界
• 入职协议
• CLAUDE.md 结构
• 任务/发现/进度约定
• 重建时机规则

推荐操作顺序：

1. 更新

   CCteam-creator

2. 同步当前项目的文档
3. 仅当变更实质影响已生成智能体的行为时才重建团队

重建时机

不要默认"改了模板就立刻重建"。

优先在以下时机重建：

• 主要阶段完成之后
• 下一轮主要开发周期开始之前
• 角色 prompt 变更足够大，继续使用现有智能体会导致不一致行为时

智能体 3-Strike 上报处理

当智能体报告"3次失败，上报 team-lead"时：

1. 读取其 progress.md 中的已尝试记录
2. 分析是否需要修改主计划（task_plan.md）
3. 给出明确的新方案方向，或重新分配任务给其他智能体
4. 护栏检查：这个失败模式会复现吗？

• 如果会（项目内）→ 追加到 CLAUDE.md

  ## Known Pitfalls

  （症状、根因、修复、预防）
• 如果会（跨项目通用）→ 同时记录

  [TEAM-PROTOCOL]

  并考虑模板级更新
• 如果不会（一次性）→ 无需额外操作

阶段推进节奏

• 调研阶段完成 → 读 researcher findings.md → 更新主 task_plan.md 的架构决策章节
• 开发阶段完成 → 等 reviewer 审查结果 → 确认 [OK] 或 [WARN] 后推进下一阶段
• 全部完成 → 并行读各 agent progress.md，确认所有任务已 complete

阶段边界健康检查（快速，配合阶段推进一起做）：

• 各智能体的根 findings.md 索引是否完整？（有没有漏掉索引条目的孤立任务文件夹）
• TaskList 中是否有过期的

  in_progress

  任务应标完成或重新分配？
• 主 task_plan.md 的阶段状态是否与实际进度一致？
• 检查 CLAUDE.md Known Pitfalls——有没有需要在下一阶段任务下发时带上的？
• 环境 pre-flight 检查：下一阶段是否需要特定的运行时状态（服务重启、种子数据、缓存清除、DB 迁移已应用）？项目特定的 pre-flight 步骤记在 CLAUDE.md

  ## Known Pitfalls

  。在派发依赖 live 状态的 agent（通常是 e2e-tester 和集成型 dev）之前执行——不要指望上一阶段的 dev 记得。环境副作用也应作为标准字段出现在每个 dev 的完成汇报里
• 执行 Harness 检查清单（见 CLAUDE.md 模板）