🤖 多Agent协作开发实践：从零构建面向Agent友好的技术博客网站

一句话总结：8个专职Agent，7个阶段，3.5小时，从需求到交付——完整演示如何用多Agent团队高效构建一个全栈Web应用。

📖 目录

• 一、项目背景
• 二、团队组建与角色分工
• 三、开发流程总览
• 四、Phase A — 需求规格编写
• 五、Phase B — 技术设计
• 六、Phase C — 任务拆解
• 七、Phase D — 编码实现
• 八、Phase E — 单元测试
• 九、Phase F — 代码审查
• 十、Phase G — 功能验证
• 十一、关键经验与踩坑记录
• 十二、复现指南

一、项目背景

1.1 需求描述

开发一个面向Agent友好的技术博客网站，核心特性：

1.2 技术约束

二、团队组建与角色分工

2.1 团队架构

graph TD
    TL[👨‍💼 Team Leader<br/>规划/调度/决策] --> REQ[📋 需求工程师<br/>EARS规格编写]
    TL --> DES[🏗️ 技术设计师<br/>架构与API设计]
    TL --> PLAN[📝 任务规划师<br/>原子任务拆解]
    TL --> BE[🔧 后端工程师<br/>Express+SQLite+JWT]
    TL --> FE[🎨 前端工程师<br/>Vite+WebComponents]
    TL --> IE[🔗 集成工程师<br/>前后端联调]
    TL --> TE[🧪 测试工程师<br/>121个测试用例]
    TL --> CR[👀 代码审查员<br/>25项问题发现]
    TL --> FIX[🛠️ 修复工程师<br/>11项问题修复]
    TL --> VE[✅ 验证工程师<br/>独立功能验证]

    style TL fill:#4A90D9,color:#fff,stroke:#2C5F8A
    style REQ fill:#7B68EE,color:#fff
    style DES fill:#7B68EE,color:#fff
    style PLAN fill:#7B68EE,color:#fff
    style BE fill:#2ECC71,color:#fff
    style FE fill:#2ECC71,color:#fff
    style IE fill:#F39C12,color:#fff
    style TE fill:#E74C3C,color:#fff
    style CR fill:#E74C3C,color:#fff
    style FIX fill:#F39C12,color:#fff
    style VE fill:#9B59B6,color:#fff

2.2 角色职责说明

关键洞察：同一 coding-engineer 类型可复用于不同阶段（后端/前端/集成/修复），通过不同的 prompt 赋予不同职责。

三、开发流程总览

3.1 Spec-Driven Development 流程

flowchart LR
    A["📋 Phase A<br/>需求规格"] --> B["🏗️ Phase B<br/>技术设计"]
    B --> C["📝 Phase C<br/>任务拆解"]
    C --> D1["🔧 Phase D<br/>后端开发"]
    C --> D2["🎨 Phase D<br/>前端开发"]
    D1 --> E["🔗 Phase D<br/>前后端联调"]
    D2 --> E
    E --> F1["🧪 Phase E<br/>单元测试"]
    E --> F2["👀 Phase F<br/>代码审查"]
    F1 --> G["🛠️ 问题修复"]
    F2 --> G
    G --> H["✅ Phase G<br/>功能验证"]

    style A fill:#7B68EE,color:#fff
    style B fill:#7B68EE,color:#fff
    style C fill:#7B68EE,color:#fff
    style D1 fill:#2ECC71,color:#fff
    style D2 fill:#2ECC71,color:#fff
    style E fill:#F39C12,color:#fff
    style F1 fill:#E74C3C,color:#fff
    style F2 fill:#E74C3C,color:#fff
    style G fill:#F39C12,color:#fff
    style H fill:#9B59B6,color:#fff

3.2 阶段耗时统计

四、Phase A — 需求规格编写

4.1 做什么

让需求工程师（team-spec-requirement-agent）基于用户需求，生成EARS格式的需求规格文档。

4.2 怎么做

# 发布任务
publish-task(id=1, content="生成EARS格式需求规格文档")

# 启动需求工程师
background-task(
    agent_name="需求工程师",
    subagent_type="team-spec-requirement-agent",
    prompt="""
    你是需求规格工程师，负责生成EARS格式的需求规格文档。
    
    ## 项目描述
    开发一个面向Agent友好的技术博客网站...
    
    ## 你的任务
    1. 在 .codeartsdoer/specs/agent-blog/ 目录下创建 spec.md
    2. 使用EARS格式编写完整的需求规格文档
    """,
    assign_task_id=[1]
)

4.3 产出结构

需求规格文档包含以下章节：

spec.md
├── 1. 组件定位（核心职责、输入、输出、边界）
├── 2. 领域术语表
├── 3. 角色与边界
├── 4. DFX约束（性能、安全、可用性、可维护性）
├── 5. 核心能力
│   ├── 5.1 Agent注册（EARS: 当...时，系统应...）
│   ├── 5.2 Agent登录
│   ├── 5.3 文章发布
│   ├── 5.4 AI审核与评分
│   ├── 5.5 首页文章展示
│   ├── 5.6 Agent文章爬取
│   └── 5.7 文章管理
└── 6. 数据约束

4.4 关键经验

💡 EARS格式的价值：每个需求都有明确的触发条件、系统行为和验收标准，后续设计和测试可直接映射。例如：

当Agent提交注册请求时，系统应校验用户名（3-30字符，仅字母数字下划线）、
密码（≥6字符）、Agent标识（非空），校验通过后创建用户并返回JWT Token。
验收标准：[AC1] 合法输入返回200+Token [AC2] 重复用户名返回409...

五、Phase B — 技术设计

5.1 做什么

让技术设计师（team-spec-design-agent）基于需求规格，生成完整的技术设计文档。

5.2 怎么做

# 等待Phase A完成后
background-task(
    agent_name="技术设计师",
    subagent_type="team-spec-design-agent",
    prompt="""
    你是技术设计师，负责生成技术设计文档。
    
    ## 技术约束（必须严格遵守）
    - 前端：Vite + Web Components + 纯H5
    - 后端：Node.js + Express
    - 数据库：SQLite
    
    ## 你的任务
    1. 阅读 spec.md 需求规格文档
    2. 创建 design.md 技术设计文档
    3. 包含：系统架构、技术选型、目录结构、数据模型、API设计、组件设计...
    """
)

5.3 产出亮点 — API设计

技术设计中最关键的部分是 API接口规范，它直接决定了前后端能否正确对接：

POST /api/v1/auth/register     → 注册
POST /api/v1/auth/login        → 登录
GET  /api/v1/articles           → 公开文章列表（Agent爬取）
GET  /api/v1/articles/:id       → 文章详情（Agent爬取）
POST /api/v1/articles           → 发布文章（需认证）
GET  /api/v1/articles/mine      → 我的文章（需认证）
DELETE /api/v1/articles/:id     → 删除文章（需认证）
PUT  /api/v1/articles/:id/resubmit → 重新提交（需认证）

5.4 产出亮点 — 数据模型

erDiagram
    USERS {
        string id PK
        string username UK
        string password_hash
        string agent_id
        int login_fail_count
        datetime locked_until
        datetime created_at
    }
    
    ARTICLES {
        string id PK
        string author_id FK
        string title
        text content
        string tags
        string status
        int score
        datetime published_at
        datetime updated_at
        int retry_count
        datetime review_submitted_at
    }
    
    REVIEW_RECORDS {
        string id PK
        string article_id FK
        int score
        string result
        text review_comment
        datetime reviewed_at
    }
    
    AUDIT_LOGS {
        string id PK
        string user_id
        string action
        text detail
        datetime created_at
    }
    
    USERS ||--o{ ARTICLES : "author_id"
    ARTICLES ||--o{ REVIEW_RECORDS : "article_id"

5.5 关键经验

💡 设计先行，避免返工：技术设计文档中明确定义了API路径、请求参数、响应格式、状态码、错误码，后续前后端工程师并行开发时，只需遵循同一份API规范即可，极大减少了集成问题。

六、Phase C — 任务拆解

6.1 做什么

让任务规划师（team-spec-task-agent）将技术设计拆解为可执行的原子任务。

6.2 拆解原则

6.3 产出示例

### 任务2.1: 用户数据访问层
- 描述: 实现user-repository.js，包含createUser, findByUsername, findById等方法
- 涉及文件: server/repositories/user-repository.js
- 依赖: 任务1.3（数据库初始化）
- 验收标准:
  - [x] createUser插入用户并返回完整用户对象
  - [x] findByUsername按用户名查询返回用户或null
  - [x] 所有查询使用参数化查询防止SQL注入

七、Phase D — 编码实现

7.1 并行开发策略

这是整个流程中最关键的并行化环节。前后端工程师同时启动，基于同一份API规范独立开发：

sequenceDiagram
    participant TL as Team Leader
    participant BE as 后端工程师
    participant FE as 前端工程师
    participant IE as 集成工程师

    TL->>BE: 分配后端开发任务
    TL->>FE: 分配前端开发任务
    
    Note over BE,FE: 并行开发（基于同一份API规范）
    
    BE->>BE: Express + SQLite + JWT
    BE->>BE: 24个服务端文件
    FE->>FE: Vite + Web Components
    FE->>FE: 15个客户端文件
    
    BE-->>TL: 后端完成
    FE-->>TL: 前端完成
    
    TL->>IE: 启动集成工程师
    IE->>IE: 验证API对接
    IE->>IE: 修复4个集成问题
    IE-->>TL: 联调完成

7.2 后端开发产出

server/
├── index.js                    # Express入口（CORS、路由、优雅关闭）
├── config.js                   # 配置管理（环境变量、JWT、速率限制参数）
├── database/
│   ├── connection.js           # SQLite连接（WAL模式、外键约束）
│   └── init.js                 # 建表脚本（4张表+索引）
├── repositories/               # 数据访问层
│   ├── user-repository.js      # 用户CRUD
│   ├── article-repository.js   # 文章CRUD（分页、排序、标签筛选）
│   ├── review-repository.js    # 审核记录CRUD
│   └── audit-log-repository.js # 审计日志
├── services/                   # 业务逻辑层
│   ├── user-service.js         # 注册/登录（bcrypt、账户锁定）
│   ├── article-service.js      # 文章发布/查询/删除/重新提交
│   └── review-service.js       # AI审核提交/结果处理
├── controllers/                # 控制器层
│   ├── auth-controller.js      # 认证请求处理
│   └── article-controller.js   # 文章请求处理
├── routes/                     # 路由层
│   ├── auth-router.js          # POST /register, POST /login
│   └── article-router.js       # 6个文章API路由
├── middlewares/                 # 中间件
│   ├── auth-middleware.js       # JWT Token验证
│   ├── rate-limit-middleware.js # 滑动窗口速率限制
│   ├── validate-middleware.js   # 请求参数schema校验
│   └── error-middleware.js      # 统一错误处理
├── schedulers/                 # AI审核调度
│   ├── review-scheduler.js     # 审核调度器（含模拟审核服务）
│   └── review-retry-queue.js   # 指数退避重试队列
└── utils/                      # 工具类
    ├── error-types.js          # 10个错误码 + AppError类
    ├── logger.js               # 结构化日志
    └── validator.js            # 通用校验函数

7.3 前端开发产出

src/
├── main.js                     # 应用入口（注册所有Web Components）
├── router/
│   └── app-router.js           # SPA路由（History API）
├── services/                   # API服务层
│   ├── api-client.js           # HTTP请求封装（fetch + Token注入）
│   ├── auth-service.js         # Token存储 + 注册/登录API
│   └── article-service.js      # 文章相关API
├── components/                 # Web Components
│   ├── blog-header.js          # 顶部导航栏
│   ├── blog-home.js            # 首页文章列表
│   ├── blog-article-detail.js  # 文章详情页
│   ├── blog-article-editor.js  # 文章编辑器（含Markdown预览）
│   ├── blog-auth-form.js       # 注册/登录表单
│   ├── blog-my-articles.js     # 我的文章管理
│   ├── blog-pagination.js      # 分页组件
│   └── blog-markdown-renderer.js # Markdown渲染（marked+hljs+DOMPurify）
└── styles/
    └── global.css              # 全局样式（CSS变量、响应式）

7.4 集成阶段发现的4个问题

7.5 关键经验

💡 并行开发的基石是API规范：只要API路径、请求参数、响应格式在技术设计阶段定义清楚，前后端完全可以并行开发。集成阶段发现的问题主要是"实现细节不匹配"而非"接口设计不匹配"。

⚠️ 第三方库版本兼容性：marked v15 的API变更是一个典型的"静默失败"——代码不报错但功能失效。集成测试是发现此类问题的唯一手段。

八、Phase E — 单元测试

8.1 做什么

让测试工程师（developer-test-generator）为后端API和前端组件编写测试。

8.2 测试架构

graph TB
    subgraph "后端测试 (Jest)"
        AT[auth.test.js<br/>19个测试]
        ART[article.test.js<br/>39个测试]
        RLT[rate-limit.test.js<br/>4个测试]
    end
    
    subgraph "前端测试 (Vitest + happy-dom)"
        AF[blog-auth-form.test.js<br/>13个测试]
        AH[blog-home.test.js<br/>13个测试]
        AP[blog-pagination.test.js<br/>23个测试]
        AR[router.test.js<br/>13个测试]
    end
    
    subgraph "测试辅助"
        TA[test-app.js<br/>无速率限制的测试应用]
        TH[test-helpers.js<br/>数据库清理]
    end
    
    TA --> AT
    TA --> ART
    TH --> TA
    
    style AT fill:#2ECC71,color:#fff
    style ART fill:#2ECC71,color:#fff
    style RLT fill:#2ECC71,color:#fff
    style AF fill:#3498DB,color:#fff
    style AH fill:#3498DB,color:#fff
    style AP fill:#3498DB,color:#fff
    style AR fill:#3498DB,color:#fff

8.3 测试结果

8.4 关键经验

💡 速率限制干扰测试：后端测试中，速率限制器的内存Store在测试文件间共享，导致auth测试被rate-limit测试的请求耗尽配额。解决方案：为auth/article测试创建不含速率限制的测试应用，rate-limit测试使用独立应用。

💡 内存数据库：使用 DB_PATH=:memory: 环境变量让SQLite使用内存模式，测试间互不影响，且不污染生产数据。

九、Phase F — 代码审查

9.1 做什么

让代码审查员（team-code-reviewer）对全部代码进行质量和安全审查。

9.2 审查发现分布

pie title 代码审查发现的问题分布
    "🔴 严重问题" : 5
    "🟡 一般问题" : 11
    "🟢 改进建议" : 9

9.3 5个严重问题详情

9.4 修复后的关键改动

JWT密钥校验（修复前 vs 修复后）：

// ❌ 修复前：可预测的默认密钥
secret: process.env.JWT_SECRET || 'agent-blog-jwt-secret-key-2024-change-me-in-production'

// ✅ 修复后：启动时强制校验
const jwtSecret = process.env.JWT_SECRET;
if (!jwtSecret) {
  console.error('错误：环境变量 JWT_SECRET 未配置，服务器拒绝启动。');
  process.exit(1);
}
if (jwtSecret.length < 32) {
  console.error(`错误：JWT_SECRET 长度不足（当前 ${jwtSecret.length} 字符），要求至少32字符。`);
  process.exit(1);
}

LIKE注入修复：

// ❌ 修复前：用户输入的 % 和 _ 未转义
params.push('%"' + tag + '"%');

// ✅ 修复后：转义LIKE通配符
const escapedTag = tag.replace(/%/g, '\\%').replace(/_/g, '\\_');
params.push('%"' + escapedTag + '"%');
// 并在SQL中添加 ESCAPE '\\' 子句

9.5 关键经验

💡 代码审查不可跳过：5个严重安全问题中，4个是运行时不会报错的"静默风险"（密钥可预测、IP伪造、内存泄漏、LIKE注入），只有通过人工审查才能发现。

💡 安全审查清单：JWT密钥管理、trust proxy配置、SQL注入（含LIKE注入）、XSS防护、密码处理一致性——这5项应作为每个项目的必查项。

十、Phase G — 功能验证

10.1 做什么

让验证工程师（team-result-verifier）独立验证所有功能是否满足需求规格。

10.2 验证方法

graph LR
    A[代码审查] --> B[单元测试<br/>58/58通过]
    B --> C[端到端API测试<br/>54项验证]
    C --> D[对抗性测试<br/>SQL注入/XSS/并发]
    D --> E{最终判定}
    E -->|全部通过| F[✅ VERDICT: PASS]
    
    style F fill:#2ECC71,color:#fff,stroke:#27AE60

10.3 验证结果总览

10.4 关键经验

💡 独立验证的价值：验证工程师不参与开发，从需求规格出发独立构造测试用例，能发现开发者"自测"时忽略的问题（如无效JSON返回500而非400）。

💡 端到端测试 > 单元测试：单元测试验证的是"代码是否按预期工作"，端到端测试验证的是"功能是否满足需求"。两者互补，不可替代。

十一、关键经验与踩坑记录

11.1 ✅ 做对的事

11.2 ⚠️ 踩过的坑

11.3 🎯 流程优化建议

graph TD
    A[当前流程] --> B[优化建议]
    
    B --> B1["集成测试前置<br/>在Phase D中增加API契约测试"]
    B --> B2["增量代码审查<br/>每个工程师完成后立即审查<br/>而非等全部完成"]
    B --> B3["测试与开发并行<br/>测试工程师基于API规范先写测试<br/>开发工程师再实现"]
    B --> B4["CI/CD集成<br/>每次提交自动运行测试<br/>代码审查问题自动检测"]
    
    style B fill:#F39C12,color:#fff

十二、复现指南

12.1 环境准备

# 确保安装了 Node.js >= 20
node --version

# 创建项目目录
mkdir agent-blog && cd agent-blog

12.2 Step-by-Step 复现

Step 1: 初始化项目

作为Team Leader，首先调用 get-team-setup(scene='coding') 获取团队配置指引。

Step 2: Phase A — 需求规格

# 发布任务
publish-task(todos=[{
    "id": 1,
    "content": "生成EARS格式需求规格文档",
    "blocked_by": [],
    "target_files": [".codeartsdoer/specs/agent-blog/spec.md"]
}])

# 启动需求工程师
background-task(
    agent_name="需求工程师",
    subagent_type="team-spec-requirement-agent",
    prompt="""...""",  # 详见第四节
    assign_task_id=[1],
    run_in_background=True
)

# 等待完成
background-output(session_id=..., block=True)

Step 3: Phase B — 技术设计

publish-task(todos=[{
    "id": 2,
    "content": "生成技术设计文档",
    "blocked_by": [1],
    "target_files": [".codeartsdoer/specs/agent-blog/design.md"]
}])

background-task(
    agent_name="技术设计师",
    subagent_type="team-spec-design-agent",
    prompt="""...""",  # 详见第五节
    assign_task_id=[2],
    run_in_background=True
)

Step 4: Phase C — 任务拆解

publish-task(todos=[{
    "id": 3,
    "content": "生成实现任务列表",
    "blocked_by": [2],
    "target_files": [".codeartsdoer/specs/agent-blog/tasks.md"]
}])

background-task(
    agent_name="任务规划师",
    subagent_type="team-spec-task-agent",
    prompt="""...""",
    assign_task_id=[3],
    run_in_background=True
)

Step 5: Phase D — 并行开发（关键！）

# 同时启动前后端工程师
background-task(
    agent_name="后端工程师",
    subagent_type="coding-engineer",
    prompt="""...""",  # 包含完整的API规范和技术约束
    assign_task_id=[4],
    run_in_background=True  # 异步，不等待
)

background-task(
    agent_name="前端工程师",
    subagent_type="coding-engineer",
    prompt="""...""",  # 同一份API规范
    assign_task_id=[5],
    run_in_background=True  # 异步，不等待
)

# 等待两者都完成
wait(timeout=300)

⚠️ 关键：两位工程师的prompt中必须包含同一份API规范，否则集成阶段会大量返工。

Step 6: Phase D — 前后端联调

background-task(
    agent_name="集成工程师",
    subagent_type="coding-engineer",
    prompt="""
    你是集成工程师。前后端由不同工程师并行开发，请验证：
    1. 后端启动正常
    2. 前端启动正常
    3. API接口对接正确
    4. 修复所有集成问题
    """,
    assign_task_id=[6],
    run_in_background=True
)

Step 7: Phase E+F — 测试与审查（并行！）

# 测试和审查可以并行
background-task(
    agent_name="测试工程师",
    subagent_type="developer-test-generator",
    prompt="""...""",
    run_in_background=True
)

background-task(
    agent_name="代码审查员",
    subagent_type="team-code-reviewer",
    prompt="""...""",
    run_in_background=True
)

Step 8: 修复审查问题

background-task(
    agent_name="修复工程师",
    subagent_type="coding-engineer",
    prompt="""
    修复代码审查发现的11个问题：
    1. JWT密钥硬编码 → 启动时强制校验
    2. 速率限制绕过 → 添加trust proxy
    ...
    """,
    run_in_background=True
)

Step 9: Phase G — 功能验证

background-task(
    agent_name="验证工程师",
    subagent_type="team-result-verifier",
    prompt="""
    独立验证所有功能是否满足需求规格。
    给出 VERDICT: PASS / FAIL / PARTIAL
    """,
    run_in_background=True
)

12.3 启动与验证

# 安装依赖
npm install

# 启动后端
node --env-file=.env server/index.js

# 启动前端（另一个终端）
npm run dev

# 运行测试
npm test           # 后端 58 个测试
npx vitest run     # 前端 63 个测试

12.4 核心Prompt模板

以下是最关键的3个Prompt模板，可直接复用：

1. 需求工程师Prompt核心结构：

你是需求规格工程师。
项目描述：[一句话描述]
核心功能：[功能列表]
技术约束：[约束列表]
你的任务：在 [目录] 下创建 spec.md，使用EARS格式编写，包含：
- 组件定位、领域术语、角色边界
- DFX约束（性能/安全/可用性/可维护性）
- 核心能力（每个功能用EARS格式：当...时，系统应...）
- 数据约束

2. 编码工程师Prompt核心结构：

你是[前端/后端]编码工程师。
项目背景：[spec.md和design.md路径]
技术栈（必须严格遵守）：[具体版本和约束]
你需要完成的任务：[按模块列出所有文件和功能]
关键设计要点：[API格式、状态码、认证方式等]
注意事项：[边界条件、兼容性要求等]
完成后请claim任务id=X，并确保 [启动命令] 可以正常运行。

3. 代码审查员Prompt核心结构：

你是代码审查专家。
审查范围：[所有文件路径]
审查要点：
1. 安全性（SQL注入、XSS、JWT、速率限制）
2. 代码质量（结构、命名、错误处理、日志）
3. 设计一致性（与设计文档对比）
4. 性能（查询效率、渲染性能）
5. 可维护性（职责清晰、依赖合理）
输出格式：严重问题/一般问题/改进建议，每项含文件路径、行号、描述、修复建议

附录：项目文件清单

agent-blog/
├── .codeartsdoer/specs/agent-blog/
│   ├── spec.md                 # 需求规格（597行）
│   ├── design.md               # 技术设计（1460行）
│   └── tasks.md                # 任务列表（27个子任务）
│
├── server/                     # 后端（24个文件）
│   ├── index.js                # Express入口
│   ├── config.js               # 配置管理
│   ├── database/               # 数据库层（2个文件）
│   ├── repositories/           # 数据访问层（4个文件）
│   ├── services/               # 业务逻辑层（3个文件）
│   ├── controllers/            # 控制器层（2个文件）
│   ├── routes/                 # 路由层（2个文件）
│   ├── middlewares/            # 中间件（4个文件）
│   ├── schedulers/             # AI审核调度（2个文件）
│   ├── utils/                  # 工具类（3个文件）
│   └── __tests__/              # 后端测试（3个测试套件 + 辅助）
│
├── src/                        # 前端（15个文件）
│   ├── main.js                 # 应用入口
│   ├── router/                 # SPA路由（1个文件）
│   ├── services/               # API服务层（3个文件）
│   ├── components/             # Web Components（8个文件）
│   ├── styles/                 # 全局样式（1个文件）
│   └── __tests__/              # 前端测试（4个测试文件）
│
├── docs/api.html               # API文档
├── VERIFICATION_REPORT.md      # 功能验证报告
├── package.json                # 项目配置
├── vite.config.js              # Vite配置
├── jest.config.js              # Jest配置
└── .env                        # 环境变量

📌 总结：多Agent协作开发的核心不是"让Agent写代码"，而是"让正确的Agent在正确的时间做正确的事"。Spec-Driven Development流程确保了需求→设计→实现→测试→审查→验证的完整闭环，而任务列表和并行调度则最大化了团队效率。希望这个案例能帮助你构建自己的Agent团队！