---
title: "Claude Code Agent Teams 多代理协作完整实战：30 分钟搭建可交互 MVP"
author: deletexiumu
pubDatetime: 2026-02-23T17:00:00+08:00
featured: false
draft: false
tags:
  - Claude Code
  - AI Agent
  - 教程
  - AI 编程
description: "用 Claude Code Agent Teams 组建 6 人 AI 团队，30 分钟从零构建接入真实数据的可交互 MVP。含两版实战 Prompt、逐阶段截图、踩坑经验总结，读完可直接复现。"
---

做产品最怕一件事：你想的和客户想的不是同一个东西。

用文字描述需求，双方各有各的理解；做 PRD 画原型，没有真实数据流，客户看完说「大概是这个意思吧」；等你花一两周把功能做出来，客户一看：「不是，我要的不是这个。」

问题出在**对齐**上。文字太抽象，PRD 没交互，传统搭 MVP 又太慢。最理想的做法是：**快速搭一个接入真实业务数据的可交互原型，让客户实际操作，确认这就是他要的东西，对齐目标后再正式开干。**

这不仅是对外客户对齐的问题。内部团队也一样——产品经理、设计师、前后端开发对着一份 PRD 各有各的理解，等到联调时才发现分歧，为时已晚。

**如果 30 分钟就能搭出一个接入真实数据的可交互原型呢？** 客户可以直接操作确认需求，内部团队可以基于同一个跑着的东西对齐认知。更重要的是，MVP 中的数据流设计、后端 API 接口、前端组件样式都可以直接复用到正式开发中——不是用完就扔的一次性原型，而是正式项目的起点。

这篇文章展示的就是这个场景：用 Claude Code Agent Teams 组建 6 人 AI 团队，**30 分钟内**从零构建一个「AI 热点日报互动 Dashboard」MVP——接入真实新闻源、跑通完整数据流（抓取→去重→分类→展示），前后端可交互，客户能直接体验。

文中包含两版经过实战验证的 Prompt（严格版 + 宽松版）、逐阶段操作截图、踩坑经验总结。读完可直接复现。

---

## 一、什么是 Agent Teams

> 如果你还不了解 Agent Teams 和 Subagents 的区别，建议先阅读[《从单兵作战到团队协作：Claude Code Agent Team 深度解析》](/posts/claude-code-agent-team/)，那篇文章有详细的架构对比。本文聚焦实战。

**一句话定义**：Agent Teams 允许多个 Claude Code 实例作为一个团队协同工作，拥有共享任务列表、Agent 间消息传递和集中管理能力。

核心架构由四个组件构成：

| 组件 | 作用 |
|------|------|
| **Team Lead** | 创建团队、分配任务、协调工作的主会话 |
| **Teammates** | 独立的 Claude Code 实例，各有自己的上下文窗口 |
| **Task List** | 共享任务列表，支持依赖追踪和自动解锁 |
| **Mailbox** | Agent 间消息系统，支持点对点和广播 |

底层工具包括 `TeamCreate`（创建团队）、`SendMessage`（Agent 间通信）、`TaskCreate/TaskUpdate/TaskList/TaskGet`（任务管理 CRUD）、以及 Plan Approval（队友提交计划，Lead 审批后才能执行）。

**适合什么场景：**
- 多模块并行开发（前端、后端、数据各自独立）
- 研究与审查（多视角并行调查）
- 竞争性假设调试（多个 Agent 测试不同理论，互相反驳）
- 跨层协调（设计、开发、测试各由不同 Agent 负责）

**不适合：**
- 顺序依赖的任务链
- 需要编辑同一文件的工作
- 简单/常规任务（单会话更划算）

---

## 二、环境准备

### 前置条件

1. **Claude Code 已安装**（版本需支持 Agent Teams）
2. **启用实验性功能**——Agent Teams 目前仍是实验性功能，默认关闭

启用方式（二选一）：

```bash
# 方式一：环境变量
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
```

```json
// 方式二：settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

3. **显示模式选择**：
   - **In-process**（默认）：所有队友运行在主终端内，`Shift+Down` 切换查看
   - **Split panes**：每个队友占独立窗格，需要 tmux 或 iTerm2

### 推荐安装的 MCP 和 Skill

本实战中用到了以下工具，按角色分类：

| 工具名称 | 类型 | 使用角色 | 用途 | 安装方式 |
|---------|------|---------|------|---------|
| Codex MCP | MCP | Architect | 与 Codex 讨论技术方案，AI 辅助架构评审 | `mcp.json` 中配置 `@openai/codex-mcp` |
| cclank-news-aggregator-skill | Skill | Data Engineer | 多源资讯聚合（HN/GitHub/PH/36Kr/V2EX） | `npx skills add cclank-news-aggregator-skill` |
| frontend-design | Skill | Designer | 生成高质量 UI 设计规范和 HTML 原型 | `npx skills add frontend-design` |

Codex MCP 配置示例：

```json
{
  "mcpServers": {
    "codex-mcp": {
      "command": "npx",
      "args": ["-y", "@openai/codex-mcp"]
    }
  }
}
```

### 未安装时的降级方案

| 工具 | 降级方案 |
|-----|---------|
| Codex MCP | Architect 自行输出架构决策，说明选型理由，Team Lead 人工审查 |
| news-aggregator-skill | Data Engineer 改为调用 HackerNews API / GitHub Trending RSS 的抓取脚本 |
| frontend-design skill | Designer 基于提示词直接生成 HTML 原型，风格参考 Linear/Vercel Dashboard |

工具只是锦上添花，没有也不影响核心流程。

---

## 三、Prompt 设计：从「写代码」到「带团队」

Agent Teams 不是随便说一句「帮我写个项目」就能跑好的。你给的 Prompt 本质上是一份**项目管理计划书**——团队组成、开发流程、协作规范、产出要求都要写清楚。

### Prompt 结构拆解

一个完整的 Agent Teams Prompt 包含四个核心模块：

```
1. 团队组成 — 定义每个 Agent 的角色和职责
2. 开发流程 — 阶段门控，哪个阶段完成才能启动下一个
3. 协作规范 — Agent 之间如何沟通、冲突怎么解决
4. 产出要求 — 最终交付物清单
```

### 严格版 vs 宽松版

本实战准备了两版 Prompt，核心差异在于**流程约束的松紧度**：

| 维度 | 严格版 | 宽松版 |
|------|--------|--------|
| 工具依赖 | 明确要求必须使用特定 MCP/Skill | 推荐使用，未安装有降级方案 |
| 阶段门控 | 「不可跳步」，每个阶段都有明确的解锁条件 | 「架构是基础」，但约束语气更柔和 |
| 协作规范 | 用「强制要求」四个字单独分节 | 融入流程描述中 |
| Codex MCP | 「必须调用 Codex MCP 讨论，双方达成共识后才能输出」 | 「推荐调用，若无 Codex MCP 则自行列出选型理由」 |
| 等待策略 | 「Data/Backend 此阶段待命，不得提前开工」 | 同样要求但用 blockquote 提醒而非加粗命令 |
| 冲突解决 | 单独列出冲突解决协议 | 简化为「解决不了再上报 Team Lead」 |

### 选择建议

- **严格版**：首次使用 Agent Teams、团队包含 5+ Agent、项目有明确的接口契约需要遵守时使用。牺牲一些灵活性换取可控性。
- **宽松版**：熟悉 Agent Teams 后使用，或者项目规模较小、允许 Agent 有一定自由度时使用。

本实战使用的是**严格版**。

### 几个关键设计决策

**1. 为什么要「架构先行」？**

没有架构文档约束，每个 Agent 会各自发明数据格式和接口定义，最终对接时一塌糊涂。`ARCHITECTURE.md` 和 `API_SPEC.md` 是团队的「共同语言」。

**2. 为什么要 Architect 调用 Codex MCP？**

让两个 AI 讨论技术方案，会比单个 AI 独断产出更全面的选型分析。Codex 可以对 Architect 的方案提出质疑和改进建议。

**3. 为什么 Phase 3 要做架构审查？**

Agent 不会 100% 遵守架构文档。审查步骤确保在前端开发之前，后端 API 的实际行为与文档一致——否则前端对着错误的接口写代码，返工成本更高。

**4. 为什么强调「主动沟通」？**

Agent 默认不会主动通知其他 Agent。如果不在 Prompt 中明确要求「完成后主动通知下游」，你会看到某个 Agent 傻等另一个早已完成的 Agent。

---

## 四、实战：逐 Phase 详解

> **关于截图的说明**：本次实战中，Team Lead 首次执行时没有严格遵守阶段门控——它一次性启动了所有 6 个 Agent，架构、前后端、数据同时开工。我发现后人工介入，要求在架构完成后先做审查，再继续后续开发。这恰恰说明了为什么 Prompt 中需要明确写出「不可跳步」这样的硬约束。提供的严格版 Prompt 已经针对这个问题做了强化，正常使用应该不会出现这个情况。

### Phase 1：架构先行（Architect + Designer 并行）

按照 Prompt 设计，Team Lead 应该只启动 Architect 和 Designer，其余 Agent 待命。

![Team 启动：6 个 Agent 被创建并开始工作](/blog/claude-code-agent-teams-practical-guide/team-start.png)

**Architect 的工作流程：**

1. 调用 Codex MCP 讨论技术栈选型——FastAPI vs Express、SQLite vs PostgreSQL、去重策略
2. 与 Codex 达成共识后，输出两份核心文档：
   - `ARCHITECTURE.md`：技术栈、目录结构、数据流图、数据库 Schema、去重/分类策略
   - `API_SPEC.md`：7 个 REST API 接口的完整定义（请求参数、响应结构、状态码）

**Designer 同步产出：**

- `design-spec.md`：详细到色值、字号、间距、动画缓动函数的设计规范
- `static/design-preview.html`：可直接在浏览器打开的交互原型

Architect 最终选型结果：

| 层级 | 选型 | 理由 |
|------|------|------|
| 前端 | Next.js 14 + TypeScript + Tailwind | SSR 支持、生态成熟 |
| 后端 | FastAPI (Python 3.11+) | Python NLP 生态、async 原生 |
| 数据库 | SQLite (WAL 模式 + FTS5) | 零运维、日均 50-200 条够用 |
| 去重 | URL 精确 → 标题 Hash → 模糊匹配 | 三级策略，准确率与性能平衡 |
| 分类 | 关键词规则 + LLM 兜底 | 低成本、确定性优先 |

Phase 1 的关键产出是为整个团队建立了**共同契约**。后续所有 Agent 都要参照这两份文档工作。

### Phase 2：并行开发（Data Engineer + Backend Engineer）

架构文档就绪后，Data Engineer 和 Backend Engineer 开始并行开发。

![Agent 自主协调：Agent 之间主动发消息沟通](/blog/claude-code-agent-teams-practical-guide/team-coordinate.png)

**Data Engineer 的工作：**
- 按 `ARCHITECTURE.md` 中的 Schema 设计创建数据库表（news、categories、dedup_log）
- 实现数据采集管道：调用 news-aggregator-skill 聚合多源资讯
- 实现去重引擎：URL 规范化 → 标题 Hash → 模糊匹配
- 完成后**主动发消息给 Backend Engineer**，告知 Schema 结构

**Backend Engineer 的工作：**
- 按 `API_SPEC.md` 实现 7 个 REST API 端点
- 实现分页、筛选、搜索等查询逻辑
- 实现手动刷新触发接口

Agent 自主协调是 Phase 2 的亮点。Data Engineer 完成 Schema 后，不需要 Team Lead 转达，直接发消息给 Backend Engineer 说明表结构和字段含义。这就是 Prompt 中强调「主动沟通」的效果。

### Phase 3：架构审查（Team Lead 主导）

Data Engineer 和 Backend Engineer 完成后，Team Lead 对照 `ARCHITECTURE.md` 和 `API_SPEC.md` 逐项审查实际产出。

![架构审查：Team Lead 对照文档审查，发现 P0 和 P1 两级差异](/blog/claude-code-agent-teams-practical-guide/architecture-review.png)

审查产出了一份 `REVIEW.md`，将差异分为 P0（前端开发前必须修复）和 P1（可后续迭代）：

**P0 差异（阻塞前端）：**

| 接口 | 规范要求 | 实际实现 | 影响 |
|------|----------|----------|------|
| `GET /api/news` | 返回 `pages` 字段 + category 嵌套对象 | 无 `pages`，category 为字符串 | 前端分页、分类展示受影响 |
| `GET /api/stats` | 含 `daily_trend[]`、`sources[]`、`dedup_stats` | 只有 `today_count`、`source_count`、`category_count` | 统计面板无法渲染趋势图 |
| `GET /api/categories` | 含 `slug` 字段 | 只有 `name` + `count` | 前端筛选路由需要 slug |
| `POST /api/news/refresh` | 异步 202 + run_id | 同步阻塞 + subprocess | 前端需要展示加载状态 |

**P1 差异（不阻塞，后续迭代）：**
- Schema 简化（无独立 categories 表、无 dedup 审计字段）——MVP 可接受
- 去重从三级简化为两级——基本能力已有
- 分类从「规则 + LLM」简化为「硬编码映射」——MVP 够用
- 分类体系从架构规范的 8 类简化为 6 类——更简洁实用

**审查决策**：前端可以立即启动开发，Backend Engineer 并行修复 P0 项。这是务实的选择——不追求与架构文档 100% 一致，而是确保前端对接不出问题。

这个阶段充分说明了为什么需要架构审查。即便 Prompt 中写了「不得自行发明字段或接口」，Agent 仍然会做出简化。审查是发现和纠正偏差的最后一道门。

### Phase 4：前端开发

架构审查通过后，Frontend Engineer 同时参考 `design-spec.md`（设计规范）和 `API_SPEC.md`（接口规范）实现前端。

Frontend Engineer 的产出包括：
- Next.js 14 项目结构，TypeScript + Tailwind CSS
- 8 个核心组件：NewsCard、CategoryFilter、SearchBar、StatsPanel、NewsDrawer、DarkModeToggle、RefreshButton、LoadingSkeleton
- SWR 数据请求 hooks（useNews、useStats）
- 响应式布局：桌面三列 → 平板两列 → 手机单列
- 暗黑模式默认开启，支持切换

设计规范中的「Neo-Editorial Tech」风格得到了较好的落地——暗色基调、紫罗兰强调色、数字滚动动画、卡片悬浮效果。

### Phase 5：QA 整合

所有模块完成后，QA Engineer 做最终整合。

![Team 完成：QA Engineer 整合后的最终产出清单](/blog/claude-code-agent-teams-practical-guide/team-complete.png)

QA Engineer 的工作：
1. **结构审查**：检查 import 路径、类型定义一致性、文件引用完整性
2. **修复对接问题**：前后端 API 格式差异、TypeScript 类型与 Python Schema 不匹配
3. **生成部署文件**：
   - `README.md`：快速启动说明
   - `docker-compose.yml`：前后端分离容器编排
   - `.env.example`：环境变量模板
   - `Makefile`：开发快捷命令
4. **输出验收报告**：评估项目可启动状态

---

## 五、最终效果展示

### Dashboard 效果图

![最终页面：暗色主题、三列卡片布局、统计面板、分类筛选](/blog/claude-code-agent-teams-practical-guide/dashboard-final.png)

> 从 Prompt 输入到全部产出完成，总耗时不到 30 分钟。

页面顶部是统计横幅（总资讯数、今日新增、来源数、分类数），中部是三列资讯卡片流，支持分类标签筛选和关键词搜索，右上角暗黑模式切换。

### 项目结构树

```
ai-news-dashboard/
├── docker-compose.yml          # Docker 编排
├── .env.example                # 环境变量模板
├── Makefile                    # 开发快捷命令
├── ARCHITECTURE.md             # 架构设计文档（Architect 产出）
├── API_SPEC.md                 # API 接口文档（Architect 产出）
├── REVIEW.md                   # 架构审查报告（Team Lead 产出）
├── design-spec.md              # UI 设计规范（Designer 产出）
│
├── backend/                    # FastAPI 后端
│   ├── Dockerfile
│   ├── requirements.txt
│   └── app/
│       ├── main.py             # 应用入口 + CORS + 调度器
│       ├── config.py           # pydantic-settings 配置
│       ├── database.py         # SQLite WAL 连接
│       ├── schemas.py          # Pydantic 响应模型
│       └── routers/            # 路由（news/categories/stats/refresh）
│
├── frontend/                   # Next.js 前端
│   └── src/
│       ├── app/                # 页面（layout + page）
│       ├── components/         # 8 个核心组件
│       ├── hooks/              # useNews + useStats
│       └── lib/                # API 客户端 + 类型定义
│
├── scripts/                    # 数据管道
│   ├── schema.sql              # 建表 SQL
│   ├── init_db.py              # 数据库初始化
│   ├── process_news.py         # 采集+去重+分类管道
│   └── generate_mock_data.py   # 模拟数据生成
│
├── static/
│   └── design-preview.html     # 设计原型预览（Designer 产出）
│
└── data/
    └── news.db                 # SQLite 数据库
```

### 技术栈总结

| 层级 | 技术 | 说明 |
|------|------|------|
| 前端框架 | Next.js 14 + TypeScript | SSR/SSG，App Router |
| 样式 | Tailwind CSS | 响应式，暗黑模式 |
| 数据请求 | SWR | 缓存、重验证 |
| 后端框架 | FastAPI (Python 3.11+) | async REST API |
| 数据库 | SQLite WAL + FTS5 | 零运维，全文搜索 |
| 去重引擎 | URL 精确 + Hash + difflib | 三级策略 |
| 分类引擎 | 关键词规则映射 | MVP 版本 |
| 定时任务 | APScheduler | 每日抓取 |
| 部署 | Docker Compose | 前后端分离容器 |

---

## 六、经验总结

### Agent Teams 的优势

**并行效率**：Phase 1 中 Architect 和 Designer 并行，Phase 2 中 Data Engineer 和 Backend Engineer 并行。原本串行需要 5 个阶段的工作，实际只需要 3 轮等待。

**专注上下文**：每个 Agent 只看自己相关的代码和文档。Backend Engineer 不需要关心前端组件，Data Engineer 不需要关心 UI 设计。窄上下文带来更高质量的推理。

**自主协调**：Agent 之间直接发消息沟通，不需要 Team Lead 逐条转达。Data Engineer 完成 Schema 直接告诉 Backend Engineer，Backend Engineer API 变更直接通知 Frontend Engineer。

### 局限性

**Token 成本高**：6 个 Agent 的团队大约消耗单会话 4-6 倍的 Token。本项目全程消耗约 20M+ Token（包含规划和执行）。简单项目用单会话更划算。

**文件冲突**：多个 Agent 同时修改同一文件会出问题。Prompt 设计时要确保每个 Agent 负责不同的文件集。本项目通过目录隔离（backend/、frontend/、scripts/）避免了这个问题。

**无法恢复**：`/resume` 和 `/rewind` 无法恢复运行中的队友。如果中途出错，只能重新开始或手动修复。

**Agent 不完美遵守指令**：即便 Prompt 写了「不得自行发明接口」，Backend Engineer 还是简化了部分 API 响应。所以架构审查（Phase 3）不能省。

### Prompt 设计的 5 个关键 Tips

**1. 角色定义要具体**

不要只写「Backend Engineer」。写清楚它要读哪些文档（API_SPEC.md）、产出什么文件（routers/、schemas.py）、不能做什么（不得自行发明未定义的接口）。

**2. 阶段门控要明确**

写清楚每个阶段的前置条件和解锁逻辑。「Phase 2 在架构完成后解锁」比「然后开始 Phase 2」更有效。

**3. 主动沟通要写进规范**

Agent 默认不会主动通知其他 Agent。必须在 Prompt 中明确要求：
- 完成任务后主动通知下游 Agent
- schema 变更通知 Backend Engineer
- API 变更通知 Frontend Engineer

**4. 产出格式要固定**

指定输出文件名（ARCHITECTURE.md、API_SPEC.md），不要让 Agent 自己起名。这样其他 Agent 可以准确引用。

**5. 完成汇报三步走**

每个 Agent 完成任务后要做三件事：TaskUpdate 标记 completed → 发消息给 Team Lead → 通知下游 Agent。不写这个规范，你会发现任务完成了但没人知道。

### 常见踩坑

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| Agent 空转等待 | 上游完成但没通知下游 | Prompt 中强制要求主动沟通 |
| API 前后端不一致 | Agent 没严格遵守 API_SPEC | 加入架构审查阶段（Phase 3） |
| 多 Agent 改同一文件 | 职责划分不清 | 用目录隔离每个 Agent 的工作区 |
| Team Lead 自己写代码 | Lead 角色没约束 | 使用 Delegate 模式（Shift+Tab） |
| 关闭团队很慢 | 队友需完成当前请求才关闭 | 正常现象，耐心等待 |
| 任务状态滞后 | Agent 忘记调用 TaskUpdate | Prompt 中写死「完成汇报三步走」 |

---

## 七、资源下载

### 完整 Prompt（两版）

<details>
<summary>严格版 Prompt（点击展开）</summary>

```
你现在是 Claude Code Agent Teams 的 Team Lead。
我们要从零构建一个「AI 热点日报互动 Dashboard」。

## 项目背景
资讯获取：通过 cclank-news-aggregator-skill 获取全网 AI/科技相关资讯，只需当天资讯，自动剔除重复内容。

---

## 团队组成（6 个专业 Agent）

1. **Architect** — 系统设计师
2. **Designer** — UI/UX 设计师（必须使用 frontend-design skill）
3. **Data Engineer** — 数据管道工程师
4. **Backend Engineer** — 后端 API 工程师
5. **Frontend Engineer** — 前端界面工程师
6. **QA Engineer** — 质量保障与项目整合

---

## 开发流程（严格按阶段推进，不可跳步）

### Phase 1：架构先行（阻塞后续所有开发）
- Architect 负责：设计技术栈、目录结构、数据流、API 规范、环境变量清单
- **必须**调用 Codex MCP 与 Codex 讨论方案，双方达成共识后才能输出 ARCHITECTURE.md 和 API_SPEC.md
- Designer 可以同步进行 UI 设计（不依赖架构）

### Phase 2：并行开发（架构完成后解锁）
- Data Engineer 按 ARCHITECTURE.md 实现数据库 schema 和数据管道
- Backend Engineer 按 API_SPEC.md 实现 REST API
- **架构是约束**，Data/Backend 实现必须与架构文档一致，不得自行发明字段或接口

### Phase 3：架构审查（Data/Backend 完成后，Team Lead 主导）
- Team Lead 对照 ARCHITECTURE.md 逐项审查 Data/Backend 产出
- 发现偏差必须打回返工，明确列出差异清单
- 审查通过后才能启动 Frontend Engineer

### Phase 4：前端开发（架构审查通过 + 设计完成后解锁）
- Frontend Engineer 同时参考 design-spec.md 和 API_SPEC.md 实现
- 若后端 API 有变更，Backend Engineer 必须主动通知 Frontend Engineer

### Phase 5：QA 整合（所有模块完成后）
- QA Engineer 做结构审查、修复 import 错误和类型不匹配
- 生成 README.md、docker-compose.yml、.env.example
- 评估项目是否可启动，输出完整验收报告

---

## Agent 协作规范（强制要求）

**主动沟通原则**：
- 任何 Agent 完成任务后，必须主动发消息通知依赖自己产出的其他 Agent
- 发现问题或需要其他 Agent 配合时，直接发消息沟通，不要等 Team Lead 转达
- Backend Engineer 完成 API 变更后，必须立即通知 Frontend Engineer
- Data Engineer 更新 schema 后，必须立即通知 Backend Engineer

**依赖关系沟通**：
- 每个 Agent 开始工作前，先检查依赖方是否已完成，如未完成主动询问进度
- 如果等待依赖超时，向 Team Lead 报告，不要空转

**冲突解决**：
- Agent 之间如有技术分歧，双方直接沟通协商，协商不成上报 Team Lead 裁决
- 任何对已有文件的修改，必须通知相关 Agent

**完成汇报**：
- 每个 Agent 完成任务后：① 用 TaskUpdate 标记 completed ② 发消息给 Team Lead 汇报 ③ 通知下游 Agent

---

## 最终产出要求
- 完整可部署项目代码（前后端分离）
- README.md（含快速启动说明）
- .env.example（所有环境变量）
- docker-compose.yml（一键启动）
- static/design-preview.html（可浏览器预览的 UI 原型）
- ARCHITECTURE.md + API_SPEC.md（架构和接口文档）

---

## 启动指令
立即创建团队，按 Phase 1 开始，Architect 和 Designer 并行先动。开始！
```

</details>

<details>
<summary>宽松版 Prompt（点击展开）</summary>

```
你现在是 Claude Code Agent Teams 的 Team Lead。
我们要从零构建一个「AI 热点日报互动 Dashboard」。

## 项目背景
每日自动抓取 AI/科技热点资讯，去重分类后展示在交互式 Dashboard 上，面向开发者和 AI 爱好者。

【推荐工具】若已安装以下工具，可显著提升产出质量（未安装也能完成项目）：
- cclank-news-aggregator-skill：多源资讯聚合（HN/GitHub/PH/36Kr/V2EX），若未安装则由 Data Engineer 自行实现抓取脚本
- frontend-design skill：生成高质量 UI 设计规范，若未安装则 Designer 直接输出 HTML 原型
- Codex MCP：辅助 Architect 做技术方案评审，若未安装则 Architect 自行输出并说明选型理由

---

## 团队组成（6 个专业 Agent）

1. **Architect** — 系统设计师
2. **Designer** — UI/UX 设计师
3. **Data Engineer** — 数据管道工程师
4. **Backend Engineer** — 后端 API 工程师
5. **Frontend Engineer** — 前端界面工程师
6. **QA Engineer** — 质量保障与项目整合

---

## 开发流程（按阶段推进，架构是一切的基础）

### Phase 1：架构先行
Architect 和 Designer 并行启动：
- **Architect**：设计技术栈选型、项目目录结构、数据流、完整 API 接口规范（API_SPEC.md）、环境变量清单，输出 ARCHITECTURE.md
  - 推荐：调用 Codex MCP 讨论关键决策
  - 若无 Codex MCP：自行列出选型及理由，Team Lead 审查
- **Designer**：设计 Dashboard UI，输出 design-spec.md 和可浏览器预览的 static/design-preview.html
  - 推荐：使用 frontend-design skill 确保设计质量
  - 若无该 skill：直接输出完整 HTML 原型（含模拟数据和交互）

> Data Engineer / Backend Engineer 此阶段待命，不得提前开工。

### Phase 2：并行开发（Phase 1 完成后解锁）
- **Data Engineer**：按 ARCHITECTURE.md 实现数据库 schema 和数据采集管道
  - 推荐：使用 cclank-news-aggregator-skill 作为数据来源
  - 若无该 skill：实现调用 HackerNews API / GitHub Trending RSS 的抓取脚本
  - 完成后主动通知 Backend Engineer schema 结构
- **Backend Engineer**：按 API_SPEC.md 实现 REST API，不得自行发明未定义的接口
  - 完成后主动通知 Frontend Engineer 可用的 API 地址和格式

### Phase 3：架构审查（Phase 2 完成后，Team Lead 主导）
- 对照 ARCHITECTURE.md 逐项检查 Data/Backend 产出，记录偏差
- 有偏差打回返工，说明具体差异；审查通过才解锁前端

### Phase 4：前端开发（Phase 3 通过 + Designer 完成后）
- **Frontend Engineer**：参考 design-spec.md 和 API_SPEC.md 实现
- Backend 若有变更，必须主动同步给 Frontend Engineer

### Phase 5：QA 整合（所有模块完成后）
- **QA Engineer**：结构审查、修复 import 错误和字段不一致、生成 README.md / docker-compose.yml / .env.example，输出验收报告

---

## Agent 协作规范

**主动沟通**（最重要）：
- 完成任务后第一时间通知下游 Agent，不要等 Team Lead 转达
- 发现问题直接找相关 Agent 协商，解决不了再上报 Team Lead
- schema 有变更 → 通知 Backend Engineer；API 有变更 → 通知 Frontend Engineer

**完成汇报三步走**：
① TaskUpdate 标记 completed → ② 发消息给 Team Lead → ③ 通知下游 Agent

**等待依赖时**：
- 主动询问对方进度，不要空转
- 等待时间过长向 Team Lead 报告

---

## 最终产出
- 完整可部署代码（前后端分离）
- README.md（快速启动说明）
- .env.example（所有环境变量）
- docker-compose.yml（一键启动）
- static/design-preview.html（UI 原型，可直接浏览器打开）
- ARCHITECTURE.md + API_SPEC.md

---

立即创建团队，Architect 和 Designer 并行先动，开始！
```

</details>

### MCP/Skill 安装清单

| 工具 | 类型 | 安装命令 |
|------|------|---------|
| Codex MCP | MCP | 配置到 `~/.claude/mcp.json`（见上文） |
| news-aggregator-skill | Skill | `npx skills add cclank-news-aggregator-skill` |
| frontend-design | Skill | `npx skills add frontend-design` |

### Demo 源码

文章附件中包含完整的 Demo 项目源码（demo-project.zip），解压即可查看全部代码和文档。

包含内容：
- 完整前后端代码（FastAPI + Next.js）
- 架构文档（ARCHITECTURE.md）、API 规范（API_SPEC.md）
- UI 设计规范（design-spec.md）+ 可预览原型（design-preview.html）
- 架构审查报告（REVIEW.md）
- docker-compose.yml、.env.example、Makefile
- 数据管道脚本（采集、去重、分类、模拟数据生成）
- 预置的 SQLite 数据库（含模拟数据，解压即可运行）

---

**关于 Agent Teams 的当前状态**：截至 2026 年 2 月，Agent Teams 仍是实验性功能。它是目前唯一真正实现多 Agent 对等协作的 AI 编程工具——其他工具（Cursor、Windsurf、GitHub Copilot）要么是单 Agent 增强，要么是功能分工但 Agent 之间无法直接通信。掌握它的 Prompt 设计和流程编排方法，是用好这个工具的关键。

---

## 相关阅读

- [从单兵作战到团队协作：Claude Code Agent Team 深度解析](/posts/claude-code-agent-team/) — Agent Teams 的架构原理、与 Subagents 的详细对比、适用场景分析
- [我如何使用 Claude Code：先计划，再编码](/posts/claude-code-plan-before-code/) — 单会话下的 Plan Mode 最佳实践，与 Agent Teams 的"先规划再执行"理念互补
- [从需求到自动化：Claude Code Skill 工具链完整实战](/posts/claude-code-skill-toolchain/) — 本文用到的 Skill（news-aggregator、frontend-design）的安装和使用方法
- [AI Agent 多模型编排：让 Claude、DeepSeek、Gemini 各干各的活](/posts/ai-agent-multi-model-orchestration/) — 从同模型多 Agent 协作进阶到跨模型编排