사람을 위한 규율이 AI에도 작동한다

지난 다섯 편을 통해 flex의 인과 사슬을 따라왔습니다. 컴파일이 아키텍처를 지키고, 이벤트 인프라가 라이브러리로 작동하고, 인가 시스템이 그 레일 위에 올라갑니다. 같은 설계 원칙이 멀티클라우드, Observability, IaC, 배포 파이프라인까지 관통하고, 타임머신과 Rewrite Host 같은 도구가 "전체를 올리지 않고 부분을 검증하는" 이터레이션을 가능하게 했습니다.

이제 이 구조가 예상 밖의 효과를 발휘하는 곳을 이야기합니다. 지난 화에서는 제품으로서의 AI(LLM 플랫폼, RAG, A2A)를 다뤘다면, 이번에는 개발 도구로서의 AI — 코딩 에이전트와의 협업입니다.

빌드가 막는다

AI 코딩 에이전트에게 코드를 작성시킬 때, 가장 큰 과제 중 하나는 "아키텍처를 지키게 하는 것"입니다. 에이전트에게 말로 가이드라인을 줄 수는 있습니다. "이 모듈에서 저 모듈을 직접 참조하면 안 돼", "트랜잭션 경계는 여기까지야". 하지만 자연어 지시는 모호하고, 에이전트가 맥락을 잘못 해석할 여지가 항상 있습니다.

flex의 Gradle 멀티모듈 + Hexagonal 구조에서는 이 문제가 다르게 풀립니다. 에이전트가 허용되지 않은 의존성을 추가하면 빌드가 실패합니다. 이건 말로 하는 피드백이 아니라, 컴파일러가 주는 명확한 피드백입니다. 에이전트 입장에서는 "이건 안 된다"를 추론할 필요 없이, 빌드 결과를 보고 방향을 수정하면 됩니다.

이건 백엔드 코드에서만 일어나는 일이 아닙니다. 지난 화에서 이야기한 flex-terraform의 Pulumi 프로젝트도 동일합니다. Kotlin으로 IaC를 작성하기 때문에, AI 에이전트가 잘못된 서브넷 설정이나 누락된 인터페이스 구현을 생성하면 './gradlew build'가 즉시 잡아냅니다. HCL로 작성된 Terraform에서는 'plan'을 돌려야만 — 그것도 실제 클라우드 credential이 있어야만 — 알 수 있었던 오류입니다. 실제로 flex-terraform Pulumi 프로젝트의 모든 코드 변경은 AI 에이전트(Claude Code)와의 대화로 생성되었습니다.

컴파일 타임에 물리적으로 막아버리는 구조가, AI 에이전트에게는 가장 명확한 가드레일이 됩니다. 1화에서 "사람을 위해" 만든 빌드 규율이, AI 시대에도 그대로 작동하는 것입니다.

구조가 가능하게 한다 — Standalone 조립

Hexagonal 구조의 진짜 위력은 "막는 것"이 아니라 "조립할 수 있게 하는 것"에 있습니다.

flex의 도메인 모듈은 1화에서 이야기한 'flex-skeleton' 템플릿을 기반으로 만들어지기 때문에, Port/Adapter의 경계가 명확합니다. 이 경계가 명확하기 때문에, 특정 도메인만 꺼내서 Adapter를 교체하고 독립 실행 가능한 애플리케이션으로 조립할 수 있습니다. 실제로 flex-flow-backend의 Issue 도메인에는 'standalone-app'이라는 모듈이 있습니다. 이 모듈은 Issue의 API, Service, Infrastructure, Repository 모듈을 조립하되, 프로덕션의 Spring Security + OAuth2 인증 Adapter 대신 단순 헤더 기반의 Standalone Security Adapter를 끼워 넣습니다. Gateway도, 인증 서버도, 다른 도메인도 없이 — Issue 도메인만 독립으로 기동됩니다.

이 standalone 환경 위에 Swagger UI, 시드 데이터, 심지어 Vite + React 프론트엔드와 Playwright E2E 테스트까지 올라갑니다. './gradlew :issue:standalone-app:e2eTestWithServer' 한 줄이면, MySQL TestContainer 위에 Issue 도메인이 뜨고, 프론트엔드가 빌드되고, E2E 시나리오가 자동으로 돌아갑니다.

이 모든 것이 가능한 이유는 Port/Adapter 구조에서 Adapter가 교체 가능하기 때문입니다. 도메인 로직에는 손대지 않고, 외부와의 연결점만 테스트에 적합한 것으로 바꾸면 됩니다. 5화에서 이야기한 타임머신(시간 축 교체)이나 Rewrite Host(공간 축 교체)와 같은 사고방식입니다. Standalone App은 구조 축을 교체하는 것 — 전체 모놀리스 대신 도메인 슬라이스만 조립해서 검증합니다.

Acceptance가 Code Review를 바꾼다

이 standalone 조립이 AI 시대에 특히 중요해지는 이유가 있습니다 — Code Review의 병목을 바꾸기 때문입니다.

AI 에이전트가 PR을 만들었을 때, 리뷰어의 첫 번째 질문은 "이거 진짜 돌아가?"입니다. 동작 확인에 상당한 인지 부하가 소모됩니다. 코드를 읽고, 머릿속에서 실행 흐름을 따라가고, 엣지 케이스를 상상해야 합니다.

하지만 그 PR에 standalone 환경에서의 E2E 테스트 통과 결과가 붙어 있다면? "돌아가는지"는 이미 증명되어 있습니다. 리뷰어는 "동작 확인" 대신 "설계 판단"에 집중할 수 있습니다. "이 추상화가 이 맥락에서 맞는가?", "이 모듈 경계가 적절한가?", "이 변경이 다른 도메인에 의도치 않은 영향을 주지 않는가?"

flex에서는 이 접근을 "Acceptance 증명 우선"이라 부르고 있습니다. AI가 만든 코드든, 사람이 만든 코드든, PR이 올라올 때 acceptance가 자동으로 증명되면 리뷰의 무게 중심이 달라집니다. "이거 돌아가?"에서 "이 설계가 이 맥락에서 맞아?"로.

이건 AI가 코드를 더 많이 생성하게 되는 시대에서, 엔지니어의 시간을 가장 높은 가치의 판단에 쓰게 해주는 구조적 변화입니다. 수동 동작 확인이 아니라 구조적 acceptance 증명. 이것도 결국 1화의 "문서가 아니라 빌드가 지킨다"와 같은 사고방식입니다.

구조가 점수를 만든다

flex는 내부적으로 코드베이스의 "AI 접근성"을 평가하는 프레임워크를 만들어 사용하고 있습니다. 코드 품질과 AI 접근성을 2축으로 놓고, L1(AI-Hostile)부터 L5(AI-Native)까지 5단계로 평가합니다.

결과는 흥미로웠습니다. flex-marvel-backend는 L4(AI-Partnered, 4.18/5.0) 등급을 받았고, 이는 Twenty CRM을 제외한 대부분의 오픈소스 제품 코드베이스(GitLab, Sentry, Mattermost, Grafana 등)를 상회하는 수치였습니다. 같은 회사 안에서도 차이가 명확했는데, Frontend 코드베이스는 코드 품질 자체는 4.1로 높았지만 AI 접근성이 2.63에 그쳐 L3(AI-Guided) 등급이었습니다.

이 격차의 원인은 코드를 잘 짰느냐가 아니라, 구조가 일관되느냐였습니다. 패턴 일관성, 의존성 방향의 예측 가능성, 모듈 간 조립 가능성. 1화에서 깎아낸 경계가 AI 시대의 경쟁력으로 변환되고 있는 겁니다. 참고로, 현재까지 L5(AI-Native)를 달성한 제품 코드베이스는 업계에 존재하지 않습니다.

경계를 깎은 자리에 남은 것

여섯 편에 걸쳐 이야기한 것을 다시 한번 따라가보겠습니다.

빌드가 아키텍처를 지킵니다. 아키텍처가 이벤트 인프라의 라이브러리화를 가능하게 합니다. 이벤트 인프라가 인가 시스템의 기반을 제공합니다. 같은 설계 원칙이 멀티클라우드, Observability, 인프라 코드, 배포 파이프라인, 개발 도구까지 관통합니다. 그리고 이 모든 것이 AI 에이전트와의 협업에서 가드레일이자 발판이 됩니다.

각각의 결정은 그 시점에서는 눈앞의 문제를 풀기 위한 것이었습니다. "아키텍처를 지키자"고 Gradle 플러그인을 만들 때, 2년 뒤에 AI 에이전트의 가드레일이 될 거라고 예상하지 않았습니다. Outbox 패턴을 라이브러리로 만들 때, 이게 인가 시스템의 인프라가 될 거라고 계획하지 않았습니다. Hexagonal의 Adapter 교체 가능성이, AI가 만든 코드의 acceptance를 증명하는 standalone 환경으로 이어질 줄도요. IaC를 Kotlin + 인터페이스 기반으로 짤 때, AI 에이전트가 인프라 변경을 안전하게 생성하는 도구가 될 줄은 몰랐습니다.

하지만 좋은 아키텍처의 특성이 바로 이겁니다. 오늘의 문제를 제대로 풀면, 내일의 문제를 풀 수 있는 자격이 함께 생긴다는 것.

여기까지의 이야기는 하나의 레포 안에서 일어나는 일이었습니다. flex 백엔드는 50개 이상의 레포, 3500개 이상의 모듈이 서로 의존하는 생태계입니다. 이 구조의 일관성이 레포의 경계를 넘어 전체 생태계 수준에서 작동할 때, 어떤 일이 가능해지는지를 마지막 화에서 이야기합니다.

다음 화에서는,
의존성의 방향을 따라 변화가 레포 간에 자동으로 전파되고, 분산된 구조 전반이 하나의 흐름으로 이어지며 결국 시리즈 전체에서 다뤄온 인과 사슬이 하나의 자동화된 파이프라인으로 수렴하는 과정을 이야기 해보겠습니다.