3.8 KiB
3.8 KiB
| title | description | sidebar | ||
|---|---|---|---|---|
| 에이전트 충돌 방지 | 여러 에이전트가 시스템을 구현할 때 아키텍처가 충돌을 방지하는 방법 |
|
여러 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. 표준과 관례
다음을 명시적으로 문서화합니다.
- 디렉터리 구조
- 이름 규칙
- 코드 구성
- 테스트 패턴
공유 컨텍스트로서의 아키텍처
아키텍처를 구현 전 모든 에이전트가 읽는 공유 컨텍스트로 생각하세요.
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를 사용하세요 :::