Cursor Composer에게 "이 모듈 전체를 리팩토링해줘"라고 프롬프트를 입력하는 순간, 당신의 헥사고날 아키텍처는 위험에 처한다. dev.to에 공개된 사례 분석에 따르면, 멀티파일 편집을 수행하는 AI 코딩 에이전트는 단 하나의 프롬프트로 도메인 레이어가 인프라스트럭처를 직접 참조하는 구조를 만들어낼 수 있다. 30초면 충분하다. 정작 문제는 AI의 능력 부족이 아니라 AI가 아키텍처 의도를 '읽을 수 있는 형태'로 제공하지 않은 개발자 측의 설계 공백이다.
많은 팀이 이 문제를 PR 리뷰로 막으려 한다. 하지만 AI 에이전트가 빠른 속도로 코드를 쏟아내는 상황에서 "domain이 infrastructure를 import하고 있네요"를 사람이 매번 잡아내는 건 구조적으로 불가능하다. Notion에 아키텍처 가이드라인을 정성껏 써두는 방식도 마찬가지다. 아무도 읽지 않는 문서는 AI에게도, 사람에게도 가드레일이 되지 못한다. 결국 순환 의존성을 손으로 풀며 몇 시간을 보내는 패턴이 반복된다.
해법의 핵심은 아키텍처를 코드로 박제하는 것이다. ArchUnit 같은 아키텍처 테스트 라이브러리를 활용하면 패키지 경계를 JUnit 테스트처럼 명시적으로 정의할 수 있다. domain 레이어가 infrastructure에 의존하면 빌드가 깨지는 규칙을 코드 한 줄로 선언하는 것이다. 이렇게 만든 규칙을 .cursorrules에 포함시키면 Claude 3.7 Sonnet 기반의 Cursor는 멀티파일 편집을 시도하기 전에 이미 경계를 인식한다. CI/CD 파이프라인에 아키텍처 테스트를 포함시키면 AI가 경계를 위반하는 순간 빌드가 즉시 실패하고, 에이전트 스스로 수정을 반복하게 된다.
이 접근법의 진짜 가치는 '아키텍처를 shift-left한다'는 점에 있다. 기능을 만들라고 프롬프트를 입력하기 전에 아키텍처 규칙을 먼저 작성하는 것, 즉 AI가 실행하는 컨텍스트 자체에 구조적 제약을 심어두는 방식이다. 위반은 유닛 테스트 실패와 동일하게 취급한다—빨간불이 켜지면 무조건 멈춘다. 예외는 없다.
Tailwind CSS 4의 설계 철학도 같은 맥락에서 읽힌다. dev.to의 시니어 CSS 개발자 분석에 따르면, 유틸리티 클래스가 '인라인 스타일처럼 지저분해 보인다'는 비판은 컴포넌트 기반 아키텍처의 핵심을 놓친 시각이다. .card-variant-3-updated 같은 전역 클래스가 5,000줄짜리 스타일시트 속에 쌓이는 패턴은 AI가 코드를 대량 생성하는 환경에서 더욱 빠르게 폭발한다. 반면 Tailwind의 유틸리티 클래스는 스타일을 컴포넌트 단위로 격리시켜, 컴포넌트를 삭제하면 스타일도 함께 사라지는 구조를 만든다. 아키텍처 경계와 스타일 경계, 모두 '격리'라는 같은 원칙 위에 서 있다.
TestFlight 배포 파이프라인에 프리플라이트 게이트를 추가한 iOS 개발자의 사례도 같은 원칙을 다른 레이어에서 구현한다. 핵심은 빌드 번호 스탬프처럼 리포지터리를 변경하는 작업이 품질 검사 이후에 실행되도록 순서를 재배치한 것이다. Claude API를 활용한 AI 기능이 백엔드 엣지 펑션을 통해 동작하더라도, 그 경계의 순수 로직은 Deno 테스트로 격리해 검증한다. "모델은 확률적일 수 있다. 하지만 그 주변 시스템은 그래서는 안 된다"는 문장이 이 모든 접근의 공통 철학을 압축한다.
AI 에이전트가 코드를 생성하는 속도는 앞으로 더 빨라질 것이다. 하지만 속도가 빨라질수록, 잘못된 방향으로 향하는 속도도 함께 빨라진다. 아키텍처 거버넌스의 무게중심은 이제 코드 리뷰 시점이 아니라 에이전트가 실행되는 컨텍스트 설계 시점으로 이동해야 한다. 실행 가능한 아키텍처 테스트, 컨텍스트 파일에 심어둔 경계 규칙, CI에 박힌 품질 게이트—이 세 가지가 AI 에이전트를 통제하는 실질적인 구조다. 화려한 프롬프트 엔지니어링보다 지루한 가드레일 설계가 팀의 코드베이스를 지킨다.