停止与上下文限制的斗争：Multi-Agent Systems 如何解决我的开发混乱（第一部分）

Source: Dev.to

（请提供需要翻译的正文内容，我才能为您完成简体中文翻译。）

Source: …

第 1 部分 共 3 | 阅读时间：10 分钟

TL;DR： 单一 AI 代理会因上下文过载和质量不一致而受限。多代理系统通过在具备明确边界和显式交接合同的专门代理之间分配工作来解决这些问题。本文解释原因并介绍该架构。

单一 AI 代理的问题

“我见过无数开发团队在 AI 辅助开发上撞到同一堵墙。他们一开始很兴奋，使用 Claude 或 GPT 来构建功能。随后现实就出现了。”

当使用 一个 AI 代理进行开发时：

真实案例 – 让单一代理 “构建用户资料页”，会得到：

• 通用的 React 组件（未遵循你的设计系统）
• 与后端模式不匹配的 API 端点
• 绕过仓库层的数据库查询
• 与你的认证策略不一致的安全检查

代理并不是不好——它只是 做得太多。

如果我们拥有一支专家团队呢？

优秀的软件团队都有专职专家。你不会让 UX 设计师去写数据库迁移，也不会让后端工程师去设计用户流程。
多代理系统 将同样的原则应用到 AI 开发中。

一个设计良好的多代理系统能够提供：

• ✅ 明确的关注点分离 – 每个代理都是领域专家
• ✅ 质量一致 – 专家比通才产出更好的工作
• ✅ 显式合同 – 交接强制在边界处保持清晰
• ✅ 架构治理 – 协调代理确保整体一致性
• ✅ 可扩展的复杂度 – 随需求增长可添加更多代理

完整模型

┌─────────────────────────────────────────────────────┐
│  Layer 1: Orchestration (brain‑agent)                │
│  • Slices work into small chunks                     │
│  • Routes to appropriate specialists                 │
│  • Enforces architectural decisions (ADRs)           │
│  • Validates integration between agents              │
└─────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────┐
│  Layer 2: Specialist Agents                          │
│  • ux‑agent: User experience & interaction flows      │
│  • react‑agent: UI components & client state          │
│  • next‑agent: Routing & server/client boundaries    │
│  • backend‑agent: APIs, validation & persistence     │
│  • [Your custom agents as needed…]                  │
└─────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────┐
│  Layer 3: Shared Foundation                          │
│  • conventions.md: Generic dev principles (KISS)   │
│  • project‑rules/: YOUR architecture patterns        │
│  • ADR registry: Documented decisions               │
└─────────────────────────────────────────────────────┘

把 brain‑agent 看作你的技术负责人。它：

1. 接收用户请求并将其拆分为可交付的小块（每块 1‑2 小时）
2. 将每个小块路由到合适的专家
3. 通过 ADRs（Architecture Decision Records）强制执行架构决策
4. 确保所有组件能够正确集成

示例工作流

用户： “构建用户个人资料页面”

brain‑agent:
  SLC‑001 → ux‑agent:      Design profile layout and states
  SLC‑002 → react‑agent:   Build ProfilePage component
  SLC‑003 → backend‑agent: Create GET /api/users/:id endpoint
  SLC‑004 → next‑agent:    Wire route and data fetching

专家职责

一致性之所

conventions.md – 通用原则（适用于任何地方）

KISS (Keep It Simple)
SOLID principles
YAGNI (You Aren't Gonna Need It)
Small, incremental work
Explicit contracts over assumptions

project‑rules/ – 您的特定模式

01-architecture.md   – Your chosen architecture (feature‑first? clean architecture?)
02-tech-stack.md      – Frameworks, libraries, naming conventions
03-security.md        – Auth strategy, multi‑tenancy rules
…etc.

ADR 注册表 – 已记录的决策

• 我们为何选择此模式？
• 我们考虑了哪些替代方案？
• 有哪些权衡？

切片 vs. 按层次

糟糕（层切片）

Week 1: Build all database models
Week 2: Build all API endpoints
Week 3: Build all UI components
Week 4: Integration (surprise! nothing works together)

优秀（特性切片）

SLC‑001 (2 hours): Complete user login
  – Model + API + UI + Integration = ✅ Working feature

SLC‑002 (2 hours): Complete profile view
  – Model + API + UI + Integration = ✅ Working feature

每个切片是：

• XS: 1‑2 小时（单个组件/端点）
• S: 0.5‑1 天（完整特性并集成）
• 完全集成 或 明确标记为未完成

交接合同示例

### HANDOFF
**From:** backend‑agent  
**To:**   react‑agent  
**Slice‑ID:** SLC‑042  

**Public contract**
- **Endpoint:** POST /api/users
- **Request:** `{ name: string, email: string }`
- **Response:** `{ id: string, name: string, email: string }`
- **Errors:**  
  - 400 – validation  
  - 409 – duplicate  
  - 500 – server  

**Edge cases handled**
- Duplicate email → 409 with message  
- Invalid email format → 400 with field errors  
- Missing required field → 400 with field errors

测试用例

1. POST valid data → expect 201
2. POST duplicate email → expect 409
3. POST invalid email → expect 400

问题

• 治理过度 = 官僚主义
• 治理不足 = 混乱

Solution

Architecture Decision Records (ADRs) – 仅用于结构性决策。

何时需要 ADR（工作块直到批准）

• 影响 > 2 个特性 的更改
• 引入 新的架构模式
• 修改 共享契约
• 任何 安全影响

何时不需要 ADR（代理直接进行）

• 本地实现细节
• 单一特性更改
• 遵循已有模式

这种做法让你在快速推进的同时避免架构灾难。

示例工作流

之前（单一代理）

Me: "Add user authentication"

Agent:
  • Generates generic JWT setup
  • Creates basic auth middleware
  • Makes questionable security choices
  • No integration with existing patterns

结果:

• 6 小时调试
• 3 小时重构

之后（多代理）

Me: "Add user authentication"

brain‑agent 检查是否需要架构决策 →
“这会影响多个功能。创建 ADR 以供批准。”

ADR‑003: 身份验证策略

• NextAuth.js v5 使用会话策略
• 用于路由保护的中间件
• 遵循 rules/03-security.md 中的现有模式

用户: 批准

brain‑agent 创建切片 ID 并分配任务：

结果: 每个切片耗时 1–2 小时，完整集成，遵循模式。

好处

适用性

• ✅ 您正在构建非平凡的应用程序（不仅仅是登陆页面）
• ❌ 您正在构建一个简单的原型

即将推出：第 2 部分 – 构建您的第一个多代理系统

• 文件结构和组织
• 如何编写代理规范
• 创建您的大脑代理
• 设置约定和项目规则
• 实际实现示例

敬请期待第 2 部分。

5‑分钟练习

1. 挑选一个功能 在你当前的项目中。
2. 写下来 哪些 agent 负责哪些部分。
3. 定义它们之间的合约。

示例：用户资料编辑

合约

• 请求: { name?: string, bio?: string }
• 响应: 更新后的用户对象
• 错误: 400（验证错误），401（未授权），404（未找到）

注意边界变得多么清晰！

关于本系列

GitHub 模板:

---

有问题或想法吗？ 在评论中留下——我很想听听你在 AI 辅助开发中的经验。

最后更新：2025‑12‑28