도메인 주도 에이전트, 레거시 코드의 AI 준비도를 묻다

문제는 모델이 아니라 코드가 답하지 못하는 질문이다

Domain-Driven Agents는 LLM 코딩 도입 논의에서 자주 빠지는 지점을 찌른다. 새 프로젝트나 작은 저장소에서는 모델이 빠르게 성과를 내지만, 오래된 레거시 코드베이스에 들어가면 품질이 급격히 떨어진다는 것이다. 이유는 단순한 컨텍스트 길이가 아니다. 같은 비즈니스 개념이 여러 이름으로 흩어져 있고, 어댑터가 필요한 곳과 직접 호출이 맞는 곳이 문서화되지 않았으며, 코드가 어떤 단어를 금지하는지 알려주지 않는다.

이 글은 그 해법으로 도메인 주도 설계의 언어를 다시 꺼낸다. 보편 언어, bounded context, context map은 인간 개발자를 위한 설계 도구였지만, 이제는 코딩 에이전트가 추측하지 않도록 만드는 입력 계약이 된다. Eric Evans의 DDD reference가 오래전 말한 경계와 언어 문제가 AI 도구에서 다시 운영 이슈가 된 셈이다.

에이전트는 모르는 것을 발명한다

LLM은 빈칸을 싫어한다. 코드베이스가 어느 컨텍스트가 용어를 소유하는지 말하지 않으면 모델은 그럴듯한 새 이름을 만든다. 기존 타입이 있는데 새 타입을 만들고, 읽기 경로에는 변환 계층이 필요한데 쓰기 경로처럼 그대로 통과시키기도 한다. 사람 개발자도 같은 실수를 하지만, 에이전트는 속도가 빠르기 때문에 같은 혼란을 더 넓게 퍼뜨린다.

agent.md, 코딩 에이전트 품질의 새 계약서는 저장소가 에이전트에게 작업 규칙을 제공해야 한다고 봤다. Domain-Driven Agents의 주장은 그 규칙을 비즈니스 의미까지 확장한다.

문맥 지도는 문서가 아니라 빌드 산출물이어야 한다

글쓴이는 각 저장소에 .workflow.json과 CONTEXT.md를 둔다고 설명한다. 전자는 프로젝트, 컨텍스트, 이웃 컨텍스트, 관계 패턴을 담고, 후자는 컨텍스트별 용어집을 담는다. 전체 context map은 사람이 직접 쓰는 문서가 아니라 여러 저장소의 선언을 읽어 생성하는 산출물이다. 이 점이 중요하다. 에이전트가 읽을 문서가 사람이 손으로 갱신하는 위키라면 오래 가지 못한다.

Context Mapper 같은 도구가 보여주듯 컨텍스트 경계는 모델링 대상이 될 수 있다. 하지만 AI 개발 환경에서는 모델링의 목적이 예쁜 다이어그램보다 자동 점검이다. 한쪽 저장소만 경계를 선언했는지, supplier와 consumer 패턴이 맞지 않는지, 같은 관계를 서로 다르게 부르는지 기계적으로 찾아야 한다. Huzzah, 프롬프트를 파일로 남기는 코딩 실험과도 맞닿는 흐름이다. 프롬프트와 의사결정은 채팅창에 흩어지지 않고 저장소 안에 남아야 한다.

한국 개발 조직에는 리팩터링의 우선순위가 바뀐다

많은 팀이 AI 코딩 도구 도입을 라이선스 구매나 IDE 플러그인 설치로 생각한다. 하지만 레거시 제품에서는 준비 작업이 더 중요하다. 먼저 핵심 도메인 용어를 정리하고, 컨텍스트 소유권을 분명히 하며, 외부 시스템과의 변환 지점을 문서화해야 한다. 이것은 대형 리팩터링이 아니라 작은 정책 파일과 용어집에서 시작할 수 있다.

한국 조직의 현실적인 첫 단계는 세 가지다. 첫째, 가장 자주 고장나는 업무 흐름 하나를 골라 용어집을 만든다. 둘째, 같은 의미로 쓰이는 한글, 영어, 약어를 모아 표준어와 금지어를 정한다. 셋째, 에이전트가 수정해도 되는 경로와 리뷰가 필요한 경로를 파일로 남긴다. AI가 없앤 것은 개발자 중산층이 아니라 피드백 한계다는 피드백 루프가 생산성을 좌우한다고 봤다. DDD 문서는 그 피드백을 빠르게 만드는 장치다.

경쟁 구도는 도구보다 준비도다

GitHub Copilot, Cursor, Claude Code, Codex 같은 도구 경쟁은 계속된다. 그러나 레거시 코드에서 차이를 만드는 것은 모델 이름보다 저장소의 설명력이다. GitHub Copilot 문서도 컨텍스트 품질과 저장소 지식의 중요성을 계속 강조한다. 도구는 바뀌어도 컨텍스트의 소유권은 팀에 남는다.

결국 에이전트 친화적인 코드베이스는 사람에게도 좋은 코드베이스다. 용어가 정리되고 경계가 분명하며, 정책이 파일로 남아 있고, 검증이 자동화되어 있으면 신입 개발자도 빠르게 들어온다. AI 도입의 숨은 이익은 단순 자동화가 아니라 조직이 미뤄둔 의미 정리 비용을 드러내는 것이다.

자주 묻는 질문

Q1: DDD를 전사적으로 도입해야 하나요?

A: 아니다. 에이전트가 자주 만지는 한 제품 영역부터 용어집과 경계 문서로 시작하는 편이 현실적이다.

Q2: 문서가 또 낡지 않을까요?

A: 낡을 수 있다. 그래서 사람이 직접 그리는 문서보다 저장소 선언에서 생성되는 context map이 더 낫다.

Q3: 코딩 에이전트 프롬프트와 무엇이 다른가요?

A: 프롬프트는 실행 시점의 지시이고, DDD 문서는 코드베이스가 장기적으로 보존하는 의미 계약이다.

Q4: 작은 스타트업에도 필요한가요?

A: 제품 용어가 빠르게 바뀌는 팀일수록 필요하다. 초기에 정리하면 레거시가 되기 전 비용이 작다.

Q5: 첫 산출물은 무엇이 좋나요?

A: 핵심 명사 20개, 금지 동의어, 소유 컨텍스트, 외부 시스템과의 변환 규칙을 담은 CONTEXT.md가 좋다.