YAML 기반 Architecture Map 도입으로 AI 생성 코드의 Architectural Drift 해결

Context

AI Agent의 빠른 개발 속도로 인해 코드 리뷰 단계에서 시스템 전체의 구조적 변화를 감지하지 못하는 Architectural Drift 발생. 개별 파일 단위의 Diff 분석으로는 모듈 간 의존성 오염 및 계층 구조 위반을 식별하기 어려운 한계 노출.

Technical Solution

• 코드베이스를 분석하여 모듈, 의존성, 배포 토폴로지를 정의한 YAML 기반 Architecture Map 생성
• Git 기반 버전 관리를 통해 아키텍처 정의서를 코드와 동일한 Single Source of Truth로 유지
• LLM을 활용한 증분 동기화(Incremental Sync) 방식으로 YAML 파일을 최신화하여 토큰 비용 최적화
• Deterministic Script를 이용해 YAML을 Mermaid 다이어그램으로 자동 변환하여 가시성 확보
• GitHub Action을 통한 PR 단계의 아키텍처 Diff 자동 포스팅으로 리뷰어의 의사결정 지원
• ML 기반의 Black-box 탐지가 아닌, 명시적 정의서를 통한 화이트박스 형태의 검증 구조 설계