title: "防止代理冲突" description: 架构如何防止多个代理实施系统时的冲突
当多个 AI 代理实施系统的不同部分时，它们可能会做出相互冲突的技术决策。架构文档通过建立共享标准来防止这种情况。
常见的冲突类型
API 风格冲突
没有架构：
- 代理 A 使用
/users/{id}的 REST - 代理 B 使用 GraphQL 变更
- 结果：不一致的 API 模式，消费者困惑
有架构：
- ADR 指定：“所有客户端-服务器通信使用 GraphQL”
- 所有代理遵循相同的模式
数据库设计冲突
没有架构：
- 代理 A 使用 snake_case 列名
- 代理 B 使用 camelCase 列名
- 结果：不一致的模式，令人困惑的查询
有架构：
- 标准文档指定命名约定
- 所有代理遵循相同的模式
状态管理冲突
没有架构：
- 代理 A 使用 Redux 进行全局状态管理
- 代理 B 使用 React Context
- 结果：多种状态管理方法，复杂性增加
有架构：
- ADR 指定状态管理方法
- 所有代理一致实施
架构如何防止冲突
1. 通过 ADR 进行显式决策
每个重要的技术选择都记录在案：
- 上下文（为什么这个决定很重要）
- 考虑的选项（存在哪些替代方案）
- 决定（我们选择了什么）
- 理由（为什么选择它）
- 后果（接受的权衡）
2. 特定于 FR/NFR 的指导
架构将每个功能需求映射到技术方法：
- FR-001: 用户管理 → GraphQL 变更
- FR-002: 移动应用 → 优化查询
3. 标准和约定
显式文档化：
- 目录结构
- 命名约定
- 代码组织
- 测试模式
架构作为共享上下文
将架构视为所有代理在实施前阅读的共享上下文：
PRD: "构建什么"
↓
Architecture: "如何构建"
↓
Agent A 阅读架构 → 实施 Epic 1
Agent B 阅读架构 → 实施 Epic 2
Agent C 阅读架构 → 实施 Epic 3
↓
Result: 一致的实施关键 ADR 主题
防止冲突的常见决策：
| 主题 | 示例决策 |
|---|---|
| API 风格 | GraphQL vs REST vs gRPC |
| 数据库 | PostgreSQL vs MongoDB |
| 认证 | JWT vs Sessions |
| 状态管理 | Redux vs Context vs Zustand |
| 样式 | CSS Modules vs Tailwind vs Styled Components |
| 测试 | Jest + Playwright vs Vitest + Cypress |
避免的反模式
:::caution[常见错误]
- 隐式决策 — “我们会边做边弄清楚 API 风格”导致不一致
- 过度文档化 — 记录每个微小的选择导致分析瘫痪
- 陈旧架构 — 文档写了一次就不再更新，导致代理遵循过时的模式 :::
:::tip[正确方法]
- 记录跨越 Epic 边界的决策
- 关注容易冲突的领域
- 随学随更新架构
- 对于重大变更使用
correct-course:::