122 lines
3.8 KiB
Markdown
122 lines
3.8 KiB
Markdown
---
|
|
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`를 사용하세요
|
|
:::
|