Domain-Driven Agents: 레거시 코드에서 에이전트가 덜 헤매게 만드는 DDD 맵

TL;DR Highlight

bounded context 맵과 용어집을 repo에 두자 에이전트가 덜 추측하게 됐다

Who Should Read

레거시 코드베이스에 코딩 에이전트를 붙였다가 엉뚱한 이름과 구조로 코드를 짜서 고민인 백엔드 개발자

Core Mechanics

레거시에서 에이전트가 틀리는 이유
- 4년 된 시스템에서 모델이 이미 세 번 쓰인 개념의 네 번째 표기를 만들어낸다.
- 어댑터를 써야 할 곳에서 직접 호출하고, 직접 호출해도 될 곳에 어댑터를 쓴다.
- 시스템이 어디에도 답을 적어두지 않은 질문이라 모델이 추측하고 자주 틀린다.
모델 말고 코드를 준비시키자는 주장
- 저자는 업그레이드할 대상이 모델이 아니라 코드라고 본다.
- 준비 상태는 조금씩 단계적으로 쌓을 수 있다고 한다.
전략은 사람이, 전술은 에이전트가
- 전략 작업은 시스템을 읽고 무엇을 왜 바꿀지 정하는 일이다.
- 전술 작업은 그 결정을 파일에 옮기는 일로, 이쪽이 싸졌다고 한다.
- 저자는 전략 쪽에서 GitHub 이슈를 만들고, 에이전트가 만든 PR을 리뷰한다.
repo마다 .workflow.json과 CONTEXT.md
- .workflow.json의 domain 블록에 프로젝트, bounded context, 용어집 위치, subdomain 유형, 이웃 context와의 edge를 적는다.
- edge에는 to, direction, owner, pattern, shape, note가 들어간다.
- CONTEXT.md는 용어의 정확한 뜻과 일부러 버린 동의어를 담는 살아있는 용어집이다.

Community Reactions

per-entity md 파일로 충분했다는 경험
- Author.ts 옆에 Author.md를 두고 에이전트에게 읽고 쓰는 스킬을 줬다는 댓글이 있었다.
- 350k LOC TypeScript 모놀리스에서 지금까지 쓸 만했고, 에이전트가 쓴 md 수정이 PR에 올라온다고 한다.
폴더별 docs.md가 더 단순하다는 의견
- 폴더마다 docs.md를 두고 변경 때 읽고 갱신하게 했더니 성과가 좋았다는 댓글이 있었다.
- 이 댓글은 별도 포맷이나 manifest 없이도 된다며 원문이 과하게 복잡하다고 봤다.
초기 DDD 경계가 에이전트 개발을 지탱했다는 경험
- 서비스 초기에 bounded context와 ubiquitous language를 잡아 두니 규칙이 복잡해져도 안 어지러웠다는 댓글이 있었다.
- 반면 DDD 없이 쌓인 기존 레거시는 리팩터링조차 못 하고 있다는 고민도 있었다.
그린필드가 더 쉽다는 전제에 반론
- 기존 프로젝트의 오래된 구조와 관례 덕분에 에이전트가 더 잘한다는 반대 경험이 있었다.
- 새 프로젝트에선 단순한 바이브 코딩이 아니면 별로라는 의견이다.
글이 AI가 쓴 느낌이라는 비판
- 첫 문단 말고는 대부분 AI 슬롭 같다며 HN 정책을 묻는 댓글이 있었다.
- AI 시스템에 의존하면 생산성은 오르지만 체계화하기 어렵다는 의견도 있었다.

How to Apply

CONTEXT.md 용어집 하나 만들기
- 에이전트가 자주 틀리는 repo 하나를 골라 루트에 CONTEXT.md를 만든다.
- 핵심 용어의 정확한 뜻과 쓰지 말아야 할 동의어를 적는다.
- 에이전트 작업 전에 이 파일부터 읽으라고 지시한다.
repo 이웃 관계를 edge로 적어 보기
- 호출하는 쪽과 호출받는 쪽 repo를 골라 각각 to, direction, owner를 적는다.
- 용어가 충돌할 때 어느 쪽 모델이 우선인지 owner에 못 박는다.
- 양쪽 선언이 맞는지 직접 대조해 보고 어긋난 곳을 이슈로 만든다.
분석은 이슈로, 구현은 에이전트 PR로 나누기
- 변경이 필요한 곳과 이유를 사람이 분석해 GitHub 이슈로 남긴다.
- 구현은 스킬이나 sub-agent에 맡기고 PR 리뷰에 집중한다.
- 건드리는 코드를 누가 쓰는지 확인한 뒤 머지한다.

Try It

복사해서 바로 해보기

# Claude Code 또는 ChatGPT에 붙여넣기 (원문 방법의 간이 버전: 용어집과 edge 점검)

너는 레거시 코드베이스를 분석하는 도우미다. 아래 코드와 문서를 읽고 CONTEXT.md 초안을 만들어라.

[입력]
- 대상 개념: {{개념 이름 예: job offer status}}
- 관련 코드: {{파일 경로나 코드}}
- 이웃 시스템과의 연동 코드: {{API 클라이언트/어댑터 코드}}

[지시]
1. 같은 개념을 가리키는 표기를 모두 찾아 표로 정리하라.
2. 표 아래에 어떤 표기를 정식으로 쓸지와 버릴 동의어를 제안하라.
3. 이웃 시스템과의 관계를 to, direction, owner, pattern, note로 정리하라. 확신이 없으면 pattern은 unclassified로 두고 note에 이유를 써라.
4. 코드에 근거가 없는 항목은 추측하지 말고 '불명'으로 표시하라.

이어서 해 볼 것: 결과를 CONTEXT.md로 저장하고, 다음 에이전트 작업 때 이 파일부터 읽으라고 지시해 보라.

Terminology

DDD(도메인 주도 설계)비즈니스와 개발이 같은 말을 쓰도록 코드 구조를 도메인 용어에 맞추는 설계 방식이다. 회사 안의 공용 사전을 코드에도 적용하는 셈이다.

Bounded context한 용어가 하나의 뜻으로 통하는 경계다. 같은 단어도 부서마다 뜻이 다르듯 context마다 뜻이 다를 수 있다.

Ubiquitous language기획자와 개발자가 함께 쓰는 공통 용어다. 이 글에서는 모델에게 요구를 전하고 추론을 읽는 통로이기도 하다.

Anticorruption layer(ACL)외부 시스템의 모델이 내 코드로 새어 들어오지 않게 번역해 주는 어댑터 층이다. 통역사 같은 역할이다.

Skill작업이 맞으면 모델이 불러 읽는 절차 마크다운 파일이다. 매번 같은 방식으로 일하게 해주는 체크리스트다.

Sub-agent새 컨텍스트로 좁은 일만 맡아 결과만 보고하는 별도 모델 세션이다. 하도급 담당자처럼 과정 전체가 아니라 결과만 넘긴다.