---
title: "에이전트 충돌 방지"
description: 여러 에이전트가 시스템을 구현할 때 아키텍처가 충돌을 방지하는 방법
sidebar:
  order: 4
---

여러 AI 에이전트가 시스템의 서로 다른 부분을 구현하면 충돌하는 기술 결정을 내릴 수 있습니다. 아키텍처 문서화는 공유 표준을 세워 이를 방지합니다.

## 일반적인 충돌 유형

### API 스타일 충돌

아키텍처가 없으면:

- 에이전트 A는 REST와 `/users/{id}`를 사용합니다
- 에이전트 B는 GraphQL 뮤테이션을 사용합니다
- 결과: 일관되지 않은 API 패턴과 혼란스러운 API 사용 경험

아키텍처가 있으면:

- ADR이 명시합니다. "모든 클라이언트-서버 통신에는 GraphQL을 사용"
- 모든 에이전트가 같은 패턴을 따릅니다

### 데이터베이스 설계 충돌

아키텍처가 없으면:

- 에이전트 A는 snake_case 컬럼명을 사용합니다
- 에이전트 B는 camelCase 컬럼명을 사용합니다
- 결과: 일관되지 않은 스키마와 혼란스러운 쿼리

아키텍처가 있으면:

- 표준 문서가 이름 규칙을 명시합니다
- 모든 에이전트가 같은 패턴을 따릅니다

### 상태 관리 충돌

아키텍처가 없으면:

- 에이전트 A는 전역 상태에 Redux를 사용합니다
- 에이전트 B는 React 컨텍스트를 사용합니다
- 결과: 여러 상태 관리 방식과 복잡성

아키텍처가 있으면:

- ADR이 상태 관리 방식을 명시합니다
- 모든 에이전트가 일관되게 구현합니다

## 아키텍처가 충돌을 방지하는 방법

### 1. ADR을 통한 명시적 결정

모든 중요한 기술 선택은 다음과 함께 문서화됩니다.

- 컨텍스트(왜 이 결정이 중요한가)
- 고려한 대안(어떤 선택지가 있는가)
- 결정(무엇을 선택했는가)
- 근거(왜 선택했는가)
- 결과(받아들인 절충)

### 2. FR/NFR별 지침

아키텍처는 각 기능 요구사항을 기술적 접근에 연결합니다.

- FR-001: 사용자 관리 → GraphQL 뮤테이션
- FR-002: 모바일 앱 → 최적화된 쿼리

### 3. 표준과 관례

다음을 명시적으로 문서화합니다.

- 디렉터리 구조
- 이름 규칙
- 코드 구성
- 테스트 패턴

## 공유 컨텍스트로서의 아키텍처

아키텍처를 구현 전 모든 에이전트가 읽는 공유 컨텍스트로 생각하세요.

```text
PRD: "무엇을 만들 것인가"
     ↓
아키텍처: "어떻게 만들 것인가"
     ↓
에이전트 A가 아키텍처를 읽음 → 에픽 1 구현
에이전트 B가 아키텍처를 읽음 → 에픽 2 구현
에이전트 C가 아키텍처를 읽음 → 에픽 3 구현
     ↓
결과: 일관된 구현
```

## 주요 ADR 주제

충돌을 방지하는 일반적인 결정:

| 주제 | 예시 결정 |
| --- | --- |
| API 스타일 | GraphQL vs REST vs gRPC |
| 데이터베이스 | PostgreSQL vs MongoDB |
| 인증 | JWT vs 세션 |
| 상태 관리 | Redux vs 컨텍스트 vs Zustand |
| 스타일링 | CSS Modules vs Tailwind vs Styled Components |
| 테스트 | Jest + Playwright vs Vitest + Cypress |

## 피해야 할 안티패턴

:::caution[흔한 실수]
- **암묵적 결정** - "API 스타일은 하면서 정하자"는 태도는 일관성 부족으로 이어집니다
- **과도한 문서화** - 모든 사소한 선택을 문서화하면 분석 마비가 생깁니다
- **오래된 아키텍처** - 한 번 쓰고 업데이트하지 않은 문서는 에이전트가 오래된 패턴을 따르게 합니다
:::

:::tip[올바른 접근]
- 에픽 경계를 넘는 결정을 문서화하세요
- 충돌이 생기기 쉬운 영역에 집중하세요
- 배운 것을 반영해 아키텍처를 업데이트하세요
- 중요한 변경에는 `bmad-correct-course`를 사용하세요
:::