#Backend

[AI가 읽을 수 있는 코드베이스 1/5] 프롬프트보다 구조가 먼저다

Summary

자연어 가이드의 한계를 넘어서는 '빌드 가드레일'과 AI 접근성(A-축) 프레임워크 제안

AI 에이전트가 단순히 코드를 짜는 것을 넘어 팀의 아키텍처 규칙을 준수하게 만드는 실전 전략을 다룹니다. 프롬프트보다 강력한 물리적 제약 사항인 빌드 시스템을 통해 AI가 스스로 학습하고 교정할 수 있는 환경을 구축하는 방법을 제시합니다.

AI 코딩 도구를 도입했지만 코드 퀄리티 저하가 고민인 엔지니어링 팀에게 추천합니다. 특히 헥사고날 아키텍처나 멀티 모듈 구조를 검토 중인 팀에게 실질적인 가이드가 될 것입니다.

AI 코딩 에이전트를 도입할 때 단순히 자연어 가이드라인(CLAUDE.md 등)이나 프롬프트 엔지니어링에만 의존할 경우, 해석의 모호성이나 컨텍스트 윈도우의 한계로 인해 모듈 경계가 무너지거나 아키텍처 규칙이 위반되는 문제가 발생한다.

자연어 지시의 한계를 극복하기 위해 Gradle 멀티 모듈과 헥사고날 아키텍처를 활용한 '빌드 가드레일'을 구축하여, 잘못된 의존성 추가 시 컴파일 단계에서 즉각적인 피드백을 주는 폐쇄 루프(Closed-loop) 시스템을 도입했다.

에이전트가 잘못된 의존성을 추가했을 때 컴파일 에러를 통해 스스로 방향을 수정하게 함으로써, 사람이 리뷰 단계에서 발견했을 때보다 훨씬 빠른 '빠른 실패(Fast Failure)'를 유도하고 아키텍처 일관성을 유지하는 성과를 거두었다.

Trade-off

빌드 실패와 수정을 반복하는 루프가 발생하여 기계적 연산 비용이 증가할 수 있으나, 사람이 직접 리뷰하고 수정하는 과정에서 발생하는 컨텍스트 스위칭 비용보다는 경제적인 것으로 판단된다.

Concept · 01

코드 작성 규칙이나 아키텍처 제약 사항을 컴파일러나 빌드 시스템(Gradle 등) 단계에서 물리적으로 강제하여 위반 시 즉시 실패하게 만드는 메커니즘이다.

Concept · 02

인간이 읽기 좋은 코드를 넘어 AI 에이전트가 코드베이스의 구조를 이해하고, 일관된 패턴으로 코드를 수정하거나 생성하기 용이한 정도를 나타내는 지표다.

Concept · 03

비즈니스 로직을 중심에 두고 외부 인프라(DB, UI 등)를 포트와 어댑터를 통해 분리하여 의존성 방향을 내부로 향하게 하는 소프트웨어 설계 방식이다.

Continue reading · same source