레거시에 강한 AI 에이전트 만드는 DDD
새 프로젝트에서는 잘 작동하던 AI 코딩 에이전트가 레거시 코드 앞에서 엉뚱한 결정을 내리는 경우가 많아요. 문제는 모델의 성능보다 코드베이스가 도메인의 의미와 경계를 제대로 설명하지 못한다는 점에 있을 수 있습니다.
1. 레거시 코드에서 AI 에이전트가 흔들리는 이유
복잡한 기존 시스템에서는 같은 개념이 여러 이름으로 표현되고, 설계 의도가 코드에 명확히 남아 있지 않아요. AI는 답을 찾지 못하면 기존 구조와 어울리는 결정을 내리는 대신 가장 그럴듯한 방향을 추측합니다.
예를 들어 ‘채용 제안 상태’ 필드를 추가하라고 요청했을 때, 이미 세 가지 표현이 존재한다면 AI가 네 번째 이름을 만들 수 있어요. 어댑터(Adapter, 시스템 간 데이터 구조를 변환하는 계층)가 필요한 곳에서 직접 호출하거나, 반대로 단순 호출이면 충분한 곳에 불필요한 계층을 추가하기도 합니다.
결국 레거시 프로젝트에서 먼저 개선해야 할 대상은 모델이 아니라 코드가 제공하는 맥락이에요. 시스템이 용어의 의미와 소유권, 컨텍스트의 경계를 답할 수 있도록 준비해야 AI도 일관된 구현을 만들 수 있습니다.
2. 전략적 작업과 전술적 작업의 분리
LLM의 등장으로 리팩터링 비용은 줄었지만, 무엇을 왜 바꿀지 결정하는 비용은 여전히 남아 있어요. 이를 전략적 작업과 전술적 작업으로 구분하면 사람과 AI의 역할을 명확하게 나눌 수 있습니다.
- 전략적 작업: 시스템을 분석하고 변경 범위와 설계 방향을 결정해요. 전체 구조와 비즈니스 목적을 이해해야 하므로 사람이 주도합니다.
- 전술적 작업: 모듈 추출, 여러 패키지의 코드 수정, 테스트 추가처럼 결정된 내용을 파일에 반영해요. 반복 작업에 강한 AI가 맡기 좋은 영역입니다.
사람은 분석 결과를 GitHub Issues로 정리하고, AI는 이를 구현해 PR을 생성해요. 이후 개발자는 테스트 범위와 다른 시스템에 미칠 영향을 검토하며 승인하거나 수정을 요청하는 방식으로 시간을 절약할 수 있습니다.
3. Skills와 Sub-agent로 구현 흐름 표준화
에이전트가 매번 다른 방식으로 작업하지 않게 하려면 반복 가능한 절차와 역할 분리가 필요해요. 원문에서는 이를 Skill과 Sub-agent라는 두 가지 장치로 구성합니다.
Skill은 이슈 처리나 컨텍스트 맵 재생성 절차를 기록한 마크다운 지침이에요. 사용자가 그날 어떤 표현으로 요청하더라도 같은 작업 순서와 검증 기준을 적용할 수 있다는 점이 유용합니다.
Sub-agent는 구현, 보안 검토, 명세 검증처럼 하나의 좁은 역할만 수행하는 별도 모델 세션이에요. 각 에이전트가 독립된 컨텍스트에서 결과만 보고하므로 대화가 불필요한 정보로 복잡해지는 문제도 줄일 수 있습니다.
4. DDD로 에이전트가 이해할 공통 언어 만들기
DDD(Domain-Driven Design, 도메인 중심 설계)는 비즈니스와 코드, AI가 같은 언어를 사용하도록 연결해요. 특히 유비쿼터스 언어와 바운디드 컨텍스트(도메인 모델이 유효한 경계)는 AI가 용어를 임의로 만들지 않도록 도와줍니다.
각 저장소 루트에는 .workflow.json을 두고 프로젝트명, 컨텍스트, 문서 위치, 서브도메인 유형, 인접 컨텍스트와의 관계를 선언해요. 관계에는 호출 방향, 모델의 소유자, 통합 패턴과 예외적인 동작까지 기록합니다.
각 컨텍스트의 CONTEXT.md에는 용어의 정확한 의미와 사용하지 않기로 한 동의어를 관리해요. 예를 들어 백엔드는 Job Offer와 Resume을 소유하고, 프런트엔드는 View Model과 Filter State 같은 화면 용어만 소유한다고 명시할 수 있습니다.
5. 컨텍스트 맵 검증과 다음 단계
각 시스템이 관계를 양쪽에서 선언하면 불일치를 자동으로 발견할 수 있어요. 생성기는 여러 저장소의 도메인 정보를 모아 재생성 가능한 CONTEXT-MAP.md를 만들고, 양쪽 선언이 올바른 조합인지 교차 검증합니다.
검증은 저장소 온보딩, 매니페스트 수정, 다른 컨텍스트가 의존하는 기능 변경 전에 실행할 수 있어요. 불일치가 발견되면 고유 지문을 가진 DDD 이슈를 생성하며, 재검사 시 같은 이슈를 갱신하거나 문제가 해결되면 자동으로 닫습니다.
다음 단계는 각 컨텍스트 내부를 값 객체(Value Object), 애그리거트(Aggregate), 도메인 서비스 같은 DDD 구성 요소로 옮기는 일이에요. AI 도입을 서두르기보다 용어와 소유권, 시스템 경계를 먼저 문서화해 보세요. 작은 컨텍스트 하나부터 정리하는 것만으로도 에이전트의 추측은 줄고, 생성되는 코드와 PR의 품질은 한층 안정될 수 있습니다.
