1. 개요 및 목적
ARCHITECTURE.md는 제품의 청사진(Blueprint)입니다. 시스템이 어떤 구조로 구성되고 각 모듈이 어떻게 상호작용하며 데이터가 흐르는지 정의합니다.
"How should the system work? (시스템 구조와 컴포넌트는 어떻게 구성되고 동작하는가?)"
설계 정의 사항 (Architectural Specifications)
1. 시스템 전체 아키텍처 다이어그램 & 모듈 책임 경계
2. 라우팅 매핑 & 정보 데이터 흐름 (Data Flow)
3. 외부 연동 경계 (External Boundaries & Mocks)
4. 실패 처리 경계 (Failure Boundaries & Recovery)
5. 절대로 침해할 수 없는 아키텍처 불변식 (Invariants)
2. 왜 ARCHITECTURE.md가 결정적인가?
AI 에이전트는 명확한 아키텍처 설계도가 주어지지 않으면, 프로젝트 전체 구조를 고려하지 않고 단순 기능 위주의 파편화된 스파게티 코드를 구현하려는 경향이 있습니다.
ARCHITECTURE.md는 AI가 기존 설계 구조를 유해하지 않고 일관된 패턴으로 시스템을 완성하도록 차단합니다.