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

当多个 AI 智能体实现系统的不同部分时，它们可能会做出相互冲突的技术决策。架构文档通过建立共享标准来防止这种情况。

## 常见冲突类型

### API 风格冲突

没有架构时：
- 智能体 A 使用 REST，路径为 `/users/{id}`
- 智能体 B 使用 GraphQL mutations
- 结果：API 模式不一致，消费者困惑

有架构时：
- ADR 指定："所有客户端-服务器通信使用 GraphQL"
- 所有智能体遵循相同的模式

### 数据库设计冲突

没有架构时：
- 智能体 A 使用 snake_case 列名
- 智能体 B 使用 camelCase 列名
- 结果：模式不一致，查询混乱

有架构时：
- 标准文档指定命名约定
- 所有智能体遵循相同的模式

### 状态管理冲突

没有架构时：
- 智能体 A 使用 Redux 管理全局状态
- 智能体 B 使用 React Context
- 结果：多种状态管理方法，复杂度增加

有架构时：
- ADR 指定状态管理方法
- 所有智能体一致实现

## 架构如何防止冲突

### 1. 通过 ADR 明确决策

每个重要的技术选择都记录以下内容：
- 上下文（为什么这个决策很重要）
- 考虑的选项（有哪些替代方案）
- 决策（我们选择了什么）
- 理由（为什么选择它）
- 后果（接受的权衡）

### 2. FR/NFR 特定指导

架构将每个功能需求映射到技术方法：
- FR-001：用户管理 → GraphQL mutations
- FR-002：移动应用 → 优化查询

### 3. 标准和约定

明确记录以下内容：
- 目录结构
- 命名约定
- 代码组织
- 测试模式

## 架构作为共享上下文

将架构视为所有智能体在实现之前阅读的共享上下文：

```text
PRD："构建什么"
     ↓
架构："如何构建"
     ↓
智能体 A 阅读架构 → 实现 Epic 1
智能体 B 阅读架构 → 实现 Epic 2
智能体 C 阅读架构 → 实现 Epic 3
     ↓
结果：一致的实现
```

## Key ADR Topics

防止冲突的常见决策：

| Topic            | Example Decision                             |
| ---------------- | -------------------------------------------- |
| API Style        | GraphQL vs REST vs gRPC                      |
| Database         | PostgreSQL vs MongoDB                        |
| Auth             | JWT vs Sessions                              |
| State Management | Redux vs Context vs Zustand                  |
| Styling          | CSS Modules vs Tailwind vs Styled Components |
| Testing          | Jest + Playwright vs Vitest + Cypress        |

## 避免的反模式

:::caution[常见错误]
- **隐式决策** — "我们边做边确定 API 风格"会导致不一致
- **过度文档化** — 记录每个次要选择会导致分析瘫痪
- **过时架构** — 文档写一次后从不更新，导致智能体遵循过时的模式
:::

:::tip[正确方法]
- 记录跨越 epic 边界的决策
- 专注于容易产生冲突的领域
- 随着学习更新架构
- 对重大变更使用 `correct-course`
:::

---
## 术语说明

- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
- **ADR**：架构决策记录（Architecture Decision Record）。用于记录重要架构决策及其背景、选项和后果的文档。
- **FR**：功能需求（Functional Requirement）。系统必须具备的功能或行为。
- **NFR**：非功能需求（Non-Functional Requirement）。系统性能、安全性、可扩展性等质量属性。
- **Epic**：史诗。大型功能或用户故事的集合，通常需要多个迭代完成。
- **snake_case**：蛇形命名法。单词之间用下划线连接，所有字母小写的命名风格。
- **camelCase**：驼峰命名法。除第一个单词外，每个单词首字母大写的命名风格。
- **GraphQL mutations**：GraphQL 变更操作。用于修改服务器数据的 GraphQL 操作类型。
- **Redux**：JavaScript 状态管理库。用于管理应用全局状态的可预测状态容器。
- **React Context**：React 上下文 API。用于在组件树中传递数据而无需逐层传递 props。
- **Zustand**：轻量级状态管理库。用于 React 应用的简单状态管理解决方案。
- **CSS Modules**：CSS 模块。将 CSS 作用域限制在组件内的技术。
- **Tailwind**：Tailwind CSS。实用优先的 CSS 框架。
- **Styled Components**：样式化组件。使用 JavaScript 编写样式的 React 库。
- **Jest**：JavaScript 测试框架。用于编写和运行测试的工具。
- **Playwright**：端到端测试框架。用于自动化浏览器测试的工具。
- **Vitest**：Vite 原生测试框架。快速且轻量的单元测试工具。
- **Cypress**：端到端测试框架。用于 Web 应用测试的工具。
- **gRPC**：远程过程调用框架。Google 开发的高性能 RPC 框架。
- **JWT**：JSON Web Token。用于身份验证的开放标准令牌。
- **PRD**：产品需求文档（Product Requirements Document）。描述产品功能、需求和目标的文档。