도메인 주도 프론트엔드 구조는 AI 개발 효율을 높일 수 있을까

프론트엔드 구조를 도메인 중심으로 바꾸면 사람이 코드를 이해하기는 편해질 수 있습니다. 그렇다면 AI 에이전트도 더 적은 비용과 토큰으로 작업할 수 있을까요?

처음에는 그럴 것이라고 예상했습니다. 기능과 가까운 파일이 같은 폴더에 있으면 탐색 범위가 줄어들 것처럼 보였기 때문입니다. 하지만 동일한 코드베이스를 대상으로 구조와 AGENTS.md를 나누어 측정해 보니, 이 직관을 그대로 일반화하기는 어려웠습니다.

이 글은 관찰한 결과를 정리한 실험 기록입니다. 구조가 사람에게 주는 장점과 AI의 탐색 비용은 같은 문제가 아닐 수 있다는 점을 중심으로 살펴보겠습니다.

실험 설정

대상은 925개 파일, 65,004 LOC 규모의 프론트엔드 코드베이스였습니다. 비교 대상의 구현 코드는 경로와 import를 제외하면 byte-identical하게 유지했습니다. 즉 기능 차이가 아니라 파일 배치와 작업 지침이 AI 작업에 미치는 영향을 보려는 목적이었습니다.

첫 번째 실험에서는 다음 두 조건을 함께 바꿨습니다.

기술 레이어 구조에서는 역할별 폴더가 최상위에 있었습니다.

actions/
components/
hooks/
stores/
utils/

도메인 구조에서는 기능별 코드와 공용 코드를 다음처럼 나누었습니다.

domains/auth/
domains/community/
domains/assessment/
shared/ui/
shared/lib/
shared/layout/
shared/types/

작업군은 작은 문구 변경부터 횡단 리팩터링까지 포함했습니다.

1. 문구 변경
2. 공통 컴포넌트 variant 추가
3. 날짜 formatter 추가
4. toast variant 추가
5. 공용 form validator 연결
6. 로그아웃 확인 모달
7. 리포트 공유
8. 인증 form validation 통합
9. 도메인을 가로지르는 공용 button 추가
10. 큰 컴포넌트 리팩터링

측정 지표에는 input/output 토큰, 실제 API 비용, turn 수, 완료 여부, type-check 오류, 코드 품질을 포함했습니다.

여기서 중요한 주의점이 있습니다. 첫 번째 실험은 구조와 AGENTS.md가 함께 바뀐 실험입니다. 결과를 구조만의 효과라고 단정할 수 없습니다.

후속 실험에서는 이 점을 분리했습니다. 기술 레이어 구조는 동일하게 두고, AGENTS.md의 배치 방식만 바꿨습니다. 따라서 첫 번째 실험은 구조와 지침의 결합 효과를, 후속 실험은 지침 배치의 차이를 관찰한 결과입니다.

첫 번째 결과: 도메인 구조가 더 저렴하지는 않았다

첫 번째 비교에서 도메인 구조는 평균 비용이 11.3% 증가했고, 토큰은 13.6% 증가했습니다. 6개 작업 중 5개가 더 많은 비용을 사용했습니다.

특히 리팩터링 작업에서는 비용이 24.6%, 토큰이 34.5% 증가했습니다.

품질은 두 구조가 실질적으로 같았습니다. 도메인 구조가 품질에서 이긴 작업은 0개였습니다. 이 결과만 놓고 보면, 이번 비교에서 도메인 구조는 품질을 높이면서 비용을 절감하는 선택은 아니었습니다.

도메인 구조
  비용   +11.3%
  토큰   +13.6%
  품질   실질적으로 동일

이 수치는 도메인 구조가 나쁘다는 결론이 아닙니다. 다만 AI 토큰 절감만을 근거로 마이그레이션을 정당화하기에는 충분하지 않다는 관찰입니다.

왜 폴더가 가까워도 탐색이 줄지 않았을까

AI 에이전트는 사람처럼 폴더 트리를 훑으며 작업을 시작한다고 생각하기 쉽습니다. 실제 작업에서는 심볼과 텍스트를 검색해 진입점을 찾는 경우가 많습니다.

컴포넌트 이름 검색
  ↓
관련 훅, 타입, 테스트, 호출부 확인
  ↓
변경 범위 검증

즉 AI에게 중요한 것은 파일이 어느 폴더에 있는가만이 아닙니다. 특정 심볼이 어디에 선언되고, 어디에서 사용되며, 어떤 규칙과 연결되는지가 더 직접적인 탐색 단서가 될 수 있습니다.

도메인 구조는 다음과 같은 검증 비용을 추가할 수 있습니다.

1. 깊어진 중첩을 따라 실제 진입점을 확인해야 합니다.
2. barrel export를 거쳐 원본 심볼의 위치를 확인해야 합니다.
3. alias import가 가리키는 실제 경로를 해석해야 합니다.
4. 하나의 도메인에 국한되지 않는 작업은 여러 도메인과 shared 코드를 계속 가로질러야 합니다.

특히 리팩터링은 한 도메인 안에서 끝나는 일이 적습니다. 공통 타입, UI, 상태, API 경계처럼 횡단 관심사를 함께 확인해야 합니다. 폴더가 기능별로 잘 나뉘어도, 작업의 영향 범위가 도메인 경계를 넘으면 탐색과 검증은 다시 넓어집니다.

이번 실험의 비용 증가는 이런 요소와 일관된 방향을 보였습니다. 다만 측정된 결과만으로 어느 한 요소가 원인이라고 확정할 수는 없습니다.

처음의 큰 개선값을 다시 측정한 이유

초기 단일 측정에서는 도메인 구조가 비용을 56% 줄인 결과가 한 번 나왔습니다. 매우 큰 차이였지만, 단일 결과만으로 결론을 내리지는 않았습니다.

같은 조건을 다섯 번 반복해 보니 도메인 구조의 결과는 평균적으로 +1.8%였습니다. 단순 반복 작업에서도 결과 범위는 -20%부터 +75%까지 넓게 나타났습니다.

이 경험에서 얻은 가장 실용적인 교훈은 반복 측정의 필요성입니다. 한 번의 유리한 결과는 작업 경로, 탐색 순서, 검증 범위의 차이를 반영할 수 있습니다. 구조 선택처럼 비용이 큰 결정을 하려면, 서로 다른 작업 유형과 반복 실행에서 방향이 유지되는지 먼저 확인해야 합니다.

후속 실험: 구조는 그대로, AGENTS.md만 바꾸기

첫 번째 실험에서는 구조와 AGENTS.md가 동시에 바뀌었으므로 두 효과를 분리할 수 없었습니다. 후속 실험에서는 기술 레이어 구조를 동일하게 유지하고, 지침의 위치만 달리했습니다.

비교한 조건은 다음과 같습니다.

지역화한 조건에는 총 17개의 로컬 AGENTS.md 파일이 있었습니다. 이번 관찰에서는 하나의 큰 루트 지침보다, 작업 위치와 가까운 작은 지침 묶음이 더 낮은 비용과 연결됐습니다.

이 결과 역시 모든 프로젝트에 그대로 적용되는 법칙은 아닙니다. 다만 AI가 실제로 작업하는 경로에서 필요한 정보를 짧고 구체적으로 제공하는 편이, 전역 문서 하나에 많은 정보를 모으는 방식보다 유리할 가능성을 보여줍니다.

AGENTS.md에는 무엇을 넣어야 할까

AGENTS.md는 코드의 복사본이 아니라, 코드 검색만으로 바로 알기 어려운 맥락을 보완하는 문서로 다루는 편이 좋았습니다.

원칙은 간단합니다.

grep과 glob으로 즉시 드러나지 않는 정보를 넣는다.

예를 들어 다음 정보는 짧게 적어도 작업의 방향을 잡는 데 도움이 됩니다.

금지 규칙은 대안을 함께 적는 것이 중요합니다. 예를 들어 “이 모듈을 직접 import하지 말 것”만으로는 다음 행동을 결정하기 어렵습니다. 대신 “직접 import하지 말고 이 공개 API를 사용한다”처럼 우회 경로를 함께 알려줘야 합니다.

## 결제 상태 변경

- 시작점: `usePaymentMutation`과 `paymentActions`
- 금지: 화면 컴포넌트에서 API client를 직접 호출하지 않는다.
- 대안: 변경은 `paymentActions`를 통해 수행한다.
- 주의: `PaymentStatus`와 `OrderStatus`는 이름이 비슷하지만 책임이 다르다.

반대로 다음 내용은 대체로 넣지 않는 편이 낫습니다.

1. 전체 디렉터리 트리
2. 전체 파일 목록
3. 함수 시그니처
4. 긴 프로젝트 철학

이 정보는 쉽게 낡거나 검색으로 빠르게 확인할 수 있습니다. 문서가 길어질수록 필요한 지침을 찾는 비용도 함께 늘어납니다.

한계와 적용 범위

이 글의 결과는 하나의 925개 파일, 65,004 LOC 코드베이스와 비교한 작업들에서 나온 관찰입니다. 구현 코드는 경로와 import를 제외하면 동일하게 맞췄지만, 작업 비용은 반복 실행에서도 넓게 변동했습니다.

따라서 다음과 같은 결론은 피해야 합니다.

도메인 구조는 항상 AI에게 불리하다.
로컬 AGENTS.md는 언제나 가장 좋다.
한 번의 비용 측정으로 구조를 결정할 수 있다.

대신 구조 변경을 검토할 때는 실제 팀의 작업을 대표하는 작업군을 만들고, 단순 수정과 횡단 리팩터링을 구분해 여러 번 측정하는 것이 안전합니다. 비용, 토큰, 결과 품질을 함께 보고, 결과가 반복해서 같은 방향을 보이는지 확인해야 합니다.

결론

이번 실험에서 도메인 구조는 AI 작업의 비용이나 토큰을 줄이지 못했습니다. 첫 번째 비교에서는 평균 비용과 토큰이 증가했고, 품질은 실질적으로 같았으며 도메인 구조가 품질에서 이긴 작업은 없었습니다. 초기의 -56% 결과도 반복 측정 뒤에는 평균 +1.8%로 바뀌었습니다.

그렇다고 도메인 중심 구성이 가치 없다는 뜻은 아닙니다. 사람의 책임 구분, 온보딩, 장기 유지보수에는 여전히 도움이 될 수 있습니다. 다만 AI 토큰 절감만을 이유로 구조를 마이그레이션하는 것은 이번 결과로 정당화되지 않았습니다.

제가 내린 결론은 구조를 하나의 목적에만 맞추지 말자는 것입니다. 사람을 위한 코드 구조는 사람의 소유권과 유지보수를 중심으로 설계하고, AI를 위한 지식 구조는 심볼 앵커, 책임 경계, 금지 패턴의 대안, 코드 밖의 함정을 중심으로 설계해야 합니다.

두 구조는 분리해서 최적화하되 서로 충돌하지 않게 맞춰야 합니다. 폴더 구조가 모든 맥락을 전달할 것이라 기대하기보다, 검색으로 보이지 않는 정보를 적절한 위치의 AGENTS.md로 보완하는 편이 더 현실적인 접근이었습니다.

긴 글 읽어주셔서 감사합니다.