From CCteam-creator-cn
Sets up agent teams for complex multi-agent projects using file-based planning, persistent progress tracking, per-agent directories, and teammate spawning. Triggers on team/swarm/project setup requests.
npx claudepluginhub jessepwj/ccteam-creator --plugin CCteam-creatorThis skill uses the workspace's default tool permissions.
为复杂项目设置多智能体团队,使用持久化文件进行规划和进度追踪。
Sets up multi-agent teams for complex projects with file-based planning, per-agent directories, and teammate spawning. Triggers on team/swarm/start-project requests.
Coordinates Claude Code Agent Teams with shared planning files for parallel work on complex tasks like code review, debugging, and feature development. Requires experimental agent teams enabled.
Spawns and coordinates pre-composed agent teams from teams/ definition files. Resolves agents/skills, verifies entry criteria, preloads skills, and runs peer or sequential workflows for multi-phase tasks.
Share bugs, ideas, or general feedback.
为复杂项目设置多智能体团队,使用持久化文件进行规划和进度追踪。
在开始第 1 步之前,你(team-lead)必须直接读取所有参考文件到自己的上下文中:
Read references/onboarding.md
Read references/templates.md
Read references/roles.md
不要委托给子智能体(Explore、general-purpose 等)去读取。子智能体只会返回摘要,丢失关键细节——你需要完整的模板和入职 prompt 才能正确生成文件和启动智能体。
第 0 步(自动):检查 .plans/ 是否已存在 → 如有,提供恢复选项
开始搭建前,检查当前工作目录是否存在 .plans/ 目录。
如果 .plans/ 存在:
.plans/ 的项目目录——如有多个则列出.plans/<project>/team-snapshot.md 是否存在
b. 如快照存在:读快照头的元数据。对比 skill 源文件时间戳 vs 快照生成时间:
如果 .plans/ 不存在:直接跳到第 1 步。
这一步的目标:让用户充分理解团队是怎么运作的,同时收集用户的真实需求。不要急于创建任何文件或团队。
用自然对话的方式(不要照搬下面的原文,根据上下文灵活表达),向用户解释以下要点:
团队是什么:
适合什么场景:
不适合什么场景:
运作逻辑:
.plans/<项目>/),记录任务、发现和进度在介绍完机制后,通过对话了解:
注意:不要一次性抛出所有问题。根据用户的回答逐步深入,像正常对话一样自然交流。如果用户的需求已经很清晰,可以跳过部分问题。
根据用户需求,推荐合适的角色组合。解释每个角色的作用和为什么推荐它。
以下标准角色为软件开发项目优化。 对于非软件或混合型任务,团队框架是通用的(文件持久化、任务文件夹、阶段门禁、审查协议)——但角色应根据实际工作调整。参见下方"非软件项目适配"。
可用的标准角色(软件开发):
| 角色 | 名称 | 参考智能体 | model | 核心能力 |
|---|---|---|---|---|
| 后端开发 | backend-dev | tdd-guide | sonnet | 写代码 + TDD + 大任务按 task 分文件夹 |
| 前端开发 | frontend-dev | tdd-guide | sonnet | 写代码 + TDD + 大任务按 task 分文件夹 |
| 探索/研究 | researcher | — | sonnet | 代码搜索 + 网页搜索 + 只读不改代码 |
| 联调测试 | e2e-tester | e2e-runner | sonnet | E2E 测试 + 浏览器自动化 + Bug 记录 |
| 代码审查 | reviewer | code-reviewer | sonnet | 只读审查 + 安全/质量/性能深度检查 |
| 管家 | custodian | refactor-cleaner | sonnet | 约束合规 + 文档治理 + 模式→自动化 + 代码清理 |
模型默认值:所有角色默认使用
sonnet。仅在用户要求、不考虑成本、或角色涉及关键/复杂逻辑(如安全敏感审查、复杂业务逻辑)时,才将特定角色升级为opus。不确定时在第 1 步与用户确认。
参见 references/roles.md 了解角色详细定义和能力。
推荐原则:
researcher-1/researcher-2),按方向拆分时按方向命名(researcher-api/researcher-arch)。每个有独立的 .plans/ 目录。无竞态——researcher 对源代码只读非软件项目适配:
以上标准角色是一套经过验证的配置。对于非软件或混合型任务,根据以下原则设计自己的角色:
告知用户以下内容都可以根据需要调整:
Team-lead = 主对话(你自己)。不要生成 team-lead 智能体。
如果用户是在改进现有团队系统而不是从零开始,需要明确判断变更属于:
CCteam-creator 源模板的持久变更判断标准:
CCteam-creator不要在模板变更写回之前就推荐重建活跃团队,除非已选定了阶段边界。
在充分沟通后,使用 AskUserQuestion 让用户最终确认:
chatr、data-pipeline)只有用户确认后,才进入后续的创建步骤。
参见 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 作为索引——链接到各任务专属的发现文件,而不是把所有内容塞进一个巨大的文档。
| 角色 | 文件夹前缀 | 示例 |
|---|---|---|
| backend-dev / frontend-dev | task- | task-auth/、task-payments/ |
| researcher | research- | research-tech-stack/、research-auth-options/ |
| e2e-tester | test- | test-auth-flow/、test-checkout/ |
| reviewer | review- | review-auth-module/、review-payments/ |
| custodian | 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 修复、配置变更)可以直接写在根文件中,不需要任务文件夹。
项目工作目录下的 CLAUDE.md 会被 Claude Code 始终加载到主会话的上下文中。这是让 team-lead 在上下文压缩后仍然保持团队运营知识的核心机制。
在项目工作目录(不是 .plans/ 里面)创建或追加 CLAUDE.md 文件。
参见 references/templates.md 中的 CLAUDE.md 模板。模板必须根据第 2 步确认的实际角色动态填充:
如果项目目录已有 CLAUDE.md,在末尾追加团队运营部分(用清晰的分隔线),不要覆盖已有内容。
没有这个文件,上下文压缩后 team-lead 会丢失:
CLAUDE.md 通过把精简的运营手册永久保留在上下文中来解决这个问题。
在第 3 步中,同时创建 docs/index.md——一个带 section 名和行号范围的详细导航地图。此文件由 custodian 维护,智能体需要查找信息时主动 Read。CLAUDE.md 指向它但不复制其内容(CLAUDE.md 仅在会话启动和 compact 后加载,因此动态导航信息应放在 docs/index.md 中)。
参见 references/templates.md 了解 docs/index.md 模板。
CLAUDE.md 是一份活文档,不是一次性生成物。以下情况需要更新:
## Known Pitfalls)不要在这里放任务级细节——只放能穿越上下文压缩的持久化运营知识。
如果项目有可测试的代码(后端、前端或两者兼有),搭建执行基础设施:
将本 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 项通用检查:
custodian 可以随时间向 golden_rules.py 添加项目特定检查(见 roles.md § 黄金原则维护)。
创建 CI 脚本骨架(scripts/run_ci.py):
golden_rules.check_all() 作为第一步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 } |
TeamCreate(team_name: "<project>").plans/ 路径。通过 TaskUpdate 设置依赖(addBlockedBy)和负责人(owner)。优先 [AFK] 任务;注明输入/输出以减少智能体间信息损耗run_in_background: true参见 references/onboarding.md 了解每个角色的入职 prompt。
生成 team snapshot:所有智能体生成完成后,写 .plans/<project>/team-snapshot.md。包含:
参见 references/templates.md 获取模板。这样下次恢复不用重新读所有 skill 文件。
向用户展示团队成员表和文件位置。
然后引导用户执行 /compact 来释放上下文空间。解释原因:
.plans/ 文件中~/.claude/tasks/,不在项目中)。TaskCreate 描述 = 一句话摘要 + .plans/ 路径。在新会话中恢复项目时,从各智能体的 findings.md 索引重建任务team_name 参数生成新队友加入团队docs/api-contracts.md 和 docs/architecture.md——未文档化的 API 对其他智能体来说不存在docs/invariants.md,然后转化为自动化测试。Reviewer 是第二道防线;自动化测试是第一道[AUTOMATE] 时,team-lead 将其转给 custodian,由 custodian 构建带有智能体可读错误信息的检查脚本并加入 CI。目标:将人工检查转化为自动化执行,让 reviewer 专注更深层的判断docs/,不是这里CCteam-creator 源文件再建议重建Status: complete 即可。不要重命名、移动或加 _archive_ 前缀——索引是导航层,文件夹位置必须稳定,否则交叉引用会断裂planning-with-files 的核心思想是:文件系统 = 磁盘,上下文 = 内存,重要的东西必须写到磁盘上。
团队项目中,这套思想在三个层面运作:
| 层面 | 谁负责 | 文件位置 | 关注什么 |
|---|---|---|---|
| 项目全局 | team-lead | .plans/<project>/task_plan.md | 阶段进度、架构决策、任务分配 |
| 智能体级 | 各 agent 自己 | .plans/<project>/<agent>/ | 自己的任务、发现、工作日志 |
| 任务级 | 各 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 也应遵循"定期自检"原则。建议在以下时机主动检查:
快速扫描(并行读取各 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(目标是什么)
team-lead 的职责不只是派发任务:
.plans/<project>/task_plan.md、decisions.md 和项目 CLAUDE.mdCCteam-creator 的如果这些职责不在主对话中保持,团队可能继续运转,但会逐渐偏离方向。
当发现团队级改进时,team-lead 应分类:
CCteam-creator 源文件模板级变更的典型例子:
推荐操作顺序:
CCteam-creator不要默认"改了模板就立刻重建"。
优先在以下时机重建:
当智能体报告"3次失败,上报 team-lead"时:
## Known Pitfalls(症状、根因、修复、预防)[TEAM-PROTOCOL] 并考虑模板级更新阶段边界健康检查(快速,配合阶段推进一起做):
in_progress 任务应标完成或重新分配?