---
title: "防止智能体冲突"
description: 架构如何在多个智能体实现系统时防止冲突
sidebar:
  order: 4
---

当多个 AI 智能体并行实现系统时，冲突并不罕见。`architecture` 的作用，就是在 `solutioning` 阶段先统一关键决策，避免到 `epic/story` 实施时才暴露分歧。

## 冲突最常出现在哪些地方

### API 风格冲突

没有架构约束时：
- 智能体 A 使用 REST，路径是 `/users/{id}`
- 智能体 B 使用 GraphQL mutations
- 结果：接口模式不一致，调用方和集成层都变复杂

有架构约束时：
- ADR 明确规定：“客户端与服务端统一使用 GraphQL”
- 所有智能体遵循同一套 API 规则

### 数据库与命名冲突

没有架构约束时：
- 智能体 A 使用 `snake_case` 列名
- 智能体 B 使用 `camelCase` 列名
- 结果：schema 不一致，查询与迁移成本上升

有架构约束时：
- 标准文档统一命名约定和迁移策略
- 所有智能体按同一模式实现

### 状态管理冲突

没有架构约束时：
- 智能体 A 使用 Redux
- 智能体 B 使用 React Context
- 结果：状态层碎片化，维护复杂度增加

有架构约束时：
- ADR 明确状态管理方案
- 不同 `story` 的实现保持一致

## architecture 如何前置消解冲突

### 1. 用 ADR 固化关键决策

每个关键技术选择都至少包含：
- 背景（为什么要做这个决策）
- 备选方案（有哪些选择）
- 最终决策（采用什么）
- 理由（为什么这样选）
- 后果（接受哪些权衡）

### 2. 把 FR/NFR 映射到技术实现

`architecture` 不是抽象原则清单，而是把需求落到可执行方案：
- FR-001（用户管理）→ GraphQL mutations
- FR-002（移动端性能）→ 查询裁剪与缓存策略

### 3. 统一基础约定

至少覆盖以下共识：
- 目录结构
- 命名约定
- 代码组织方式
- 测试策略

## architecture 是所有 epic 的共享上下文

把架构文档看作每个智能体在实施前都要阅读的“公共协议”：

```text
PRD: "做什么"
     ↓
architecture: "如何做"
     ↓
智能体 A 读 architecture → 实现 Epic 1
智能体 B 读 architecture → 实现 Epic 2
智能体 C 读 architecture → 实现 Epic 3
     ↓
结果：实现一致、集成顺畅
```

## 优先写清的 ADR 主题

| 主题 | 示例决策 |
| ---------------- | -------------------------------------------- |
| API 风格 | GraphQL vs REST vs gRPC |
| 数据存储 | PostgreSQL vs MongoDB |
| 认证机制 | JWT vs Session |
| 状态管理 | Redux vs Context vs Zustand |
| 样式方案 | CSS Modules vs Tailwind vs Styled Components |
| 测试体系 | Jest + Playwright vs Vitest + Cypress |

## 常见误区

:::caution[常见错误]
- **隐式决策**：边写边定规则，最终通常会分叉
- **过度文档化**：把每个小选择都写 ADR，造成分析瘫痪
- **架构陈旧**：文档不更新，智能体继续按过时规则实现
:::

:::tip[更稳妥的做法]
- 先记录跨 `epic`、高冲突概率的决策
- 把精力放在“会影响多个 story 的规则”
- 随着项目演进持续更新架构文档
- 出现重大偏移时使用 `bmad-correct-course`
:::

## 继续阅读

- [为什么解决方案阶段很重要](./why-solutioning-matters.md)
- [项目上下文](./project-context.md)
- [工作流地图](../reference/workflow-map.md)