에이전트 충돌 방지
여러 AI 에이전트가 시스템의 서로 다른 부분을 구현하면 충돌하는 기술 결정을 내릴 수 있습니다. 아키텍처 문서화는 공유 표준을 세워 이를 방지합니다.
일반적인 충돌 유형
섹션 제목: “일반적인 충돌 유형”API 스타일 충돌
섹션 제목: “API 스타일 충돌”아키텍처가 없으면:
- 에이전트 A는 REST와
/users/{id}를 사용합니다 - 에이전트 B는 GraphQL 뮤테이션을 사용합니다
- 결과: 일관되지 않은 API 패턴과 API 사용자의 혼란
아키텍처가 있으면:
- ADR이 명시합니다. “모든 클라이언트-서버 통신에는 GraphQL을 사용”
- 모든 에이전트가 같은 패턴을 따릅니다
데이터베이스 설계 충돌
섹션 제목: “데이터베이스 설계 충돌”아키텍처가 없으면:
- 에이전트 A는 snake_case 컬럼명을 사용합니다
- 에이전트 B는 camelCase 컬럼명을 사용합니다
- 결과: 일관되지 않은 스키마와 혼란스러운 쿼리
아키텍처가 있으면:
- 표준 문서가 명명 규칙을 명시합니다
- 모든 에이전트가 같은 패턴을 따릅니다
상태 관리 충돌
섹션 제목: “상태 관리 충돌”아키텍처가 없으면:
- 에이전트 A는 전역 상태에 Redux를 사용합니다
- 에이전트 B는 React 컨텍스트를 사용합니다
- 결과: 상태 관리 방식이 여러 개로 나뉘어 복잡해짐
아키텍처가 있으면:
- ADR이 상태 관리 방식을 명시합니다
- 모든 에이전트가 일관되게 구현합니다
아키텍처가 충돌을 방지하는 방법
섹션 제목: “아키텍처가 충돌을 방지하는 방법”1. ADR을 통한 명시적 결정
섹션 제목: “1. ADR을 통한 명시적 결정”모든 중요한 기술 선택에는 다음 내용을 함께 기록합니다.
- 컨텍스트(왜 이 결정이 중요한가)
- 고려한 대안(어떤 선택지가 있는가)
- 결정(무엇을 선택했는가)
- 근거(왜 선택했는가)
- 결과(받아들인 절충)
2. FR/NFR별 지침
섹션 제목: “2. FR/NFR별 지침”아키텍처는 각 기능 요구사항을 기술적 접근에 연결합니다.
- FR-001: 사용자 관리 → GraphQL 뮤테이션
- FR-002: 모바일 앱 → 최적화된 쿼리
3. 표준과 관례
섹션 제목: “3. 표준과 관례”다음을 명시적으로 문서화합니다.
- 디렉터리 구조
- 명명 규칙
- 코드 구성
- 테스트 패턴
공유 컨텍스트로서의 아키텍처
섹션 제목: “공유 컨텍스트로서의 아키텍처”아키텍처를 구현 전 모든 에이전트가 읽는 공유 컨텍스트로 생각하세요.
PRD: "무엇을 만들 것인가" ↓아키텍처: "어떻게 만들 것인가" ↓에이전트 A가 아키텍처를 읽음 → 에픽 1 구현에이전트 B가 아키텍처를 읽음 → 에픽 2 구현에이전트 C가 아키텍처를 읽음 → 에픽 3 구현 ↓결과: 일관된 구현주요 ADR 주제
섹션 제목: “주요 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 |