Ubiquitous Language — 한국어 도메인의 숨은 자산
Eric Evans Domain-Driven Design (2003)의 핵심 명제. 도메인 expert·개발자·코드·문서가 같은 vocabulary를 쓴다. 번역 비용이 bug의 source. overview의 🌐 Domain 축의 root. AI 시대에 vocabulary 단위 information hiding으로 직접 작동. 한국어 학사 용어처럼 고유 정밀도가 높은 도메인에서 가장 강력.
한 줄
도메인 expert가 쓰는 단어가 그대로 코드의 단어, 회의의 단어, 문서의 단어가 되는 design. 번역 layer가 사라지면 misalignment 비용 + verbosity + bug source가 한꺼번에 줄어든다. 한국어 학사 도메인처럼 vocabulary가 정밀하게 박힌 segment에서는 영어로 번역하지 않는 게 오히려 정확. AI 시대에는 "20 words where 1 will do" (Matt) 직접 해결.
⚛️ 철학
원칙의 왜. 더 깊은 root와의 연결.
Evans의 Domain-Driven Design (2003)에서 ubiquitous language는 모델 발견의 핵심 도구로 정의됨:
"Use the model as the backbone of a language. Commit the team to exercising that language relentlessly in all communication within the team and in the code."
— Eric Evans, Domain-Driven Design (2003)
핵심 명제:
도메인 expert·개발자·코드·문서·다이어그램이 모두 같은 vocabulary를 사용한다. vocabulary 일치가 깨지는 자리마다 번역이 발생하고, 번역마다 의미 손실과 bug가 발생한다.
번역 비용을 그림으로:
각 번역 단계에서 의미 손실:
- "수강신청"의 학기·정정 기간·재수강 규칙·정원 제한·시간 충돌 검사·졸업요건 영향 같은 도메인 implications
- 영어로 옮기면 *"course registration"*이 되지만, 학내 학사 시스템 specific 의미가 약함
- 매 번역마다 어떤 implication이 살아 있는지 다시 합의 필요 → 회의·misalignment·bug
Matt의 AI 시대 표현
mattpocock/skills README에서 정확히 같은 명제:
"With a ubiquitous language, conversations among developers and expressions of the code are all derived from the same domain model. I felt the same tension with my agents. Agents are usually dropped into a project and asked to figure out the jargon as they go. So they use 20 words where 1 will do."
→ AI 시대에 UL은 vocabulary 단위 information-hiding|information hiding. 도메인 vocabulary가 secret이 아니라 contract. AI agent가 도메인 단어를 그대로 알면 jargon을 figure out하는 비용이 사라짐.
다른 root와의 연결
- information-hiding — 외부 vocabulary가 새는 것이 leak. UL은 vocabulary 단위 leak 차단
- information-leak-vs-abstraction — 번역 단계가 leak source. UL이 leak을 차단
- simple-not-easy — vocabulary 얽힘 (도메인 단어 ↔ 기술 단어)이 complect의 한 형태. UL이 풀어줌
- strategic-vs-tactical-programming — 어떤 vocabulary를 채택할지가 strategic 결정 (한 번 결정하면 시스템 전체 영향)
- bounded-context — UL이 어디까지 통하는가의 답. UL의 적용 범위 정의
🧱 추상적 작동 구조
UL이 시스템을 어떻게 관통하는가:
핵심: vocabulary가 시스템의 backbone. 모든 layer가 같은 단어를 각자의 형식(자연어 / API / 코드 / SQL / log)으로 표현하지만 core 단어는 동일.
Vocabulary가 만드는 artifact
UL이 정착되면 자연스럽게 따라오는 artifact:
| Artifact | 형태 | 예시 |
|---|---|---|
| Glossary | 도메인 용어집 | 수강신청, 정정, 폐강, 가산점, 정원의 정의 |
| Type definitions | 도메인 타입 | struct SugangSinchung { ... } (한국어 그대로) 또는 struct CourseRegistration |
| Test names | 시나리오를 도메인 언어로 | test_정원_초과시_대기열_등록 |
| ADR (Architecture Decision Record) | 결정의 도메인적 이유 | "정정 기간을 별 module로 분리한 이유" |
| AI agent skills | UL 기반 skill | /수강신청-검증.md, /시간표-충돌-검사.md |
Hickey 명제와의 만남 — vocabulary 단위 complect 제거
도메인 vocabulary ⨯ 기술 vocabulary = complect
→ 두 vocabulary 사이에 *번역 매핑*이 매 layer마다 필요
→ 매 매핑이 secret이 됨 (사람 머릿속에)
→ AI agent fail (secret 모름) + 신참 fail + 변경 비용 폭발
UL: 두 vocabulary를 하나로 통일
→ 매핑 사라짐
→ secret 사라짐 → AI 친화적 + 신참 친화적
→ Hickey의 complect 제거가 vocabulary 단위에서 정확히 작동.
⚠️ 약점/한계
원칙의 적용 한계. 잘못 적용 시 함정.
1. Vocabulary 발견의 비용
UL은 팀이 함께 발견하는 것. 도메인 expert와 깊은 대화가 필요. 시간·관계·기록의 비용이 큼. 빠른 prototyping에 부적합.
해결: Strategic 활동의 일부로 timeboxed. Sprint마다 1-2시간을 vocabulary 발견 회의에 투자. mattpocock/skills의 /grill-with-docs가 이 발견을 AI와 함께 가속.
2. Legacy 시스템과의 충돌
기존 코드의 vocabulary가 잘못된 경우 마이그레이션 비용 큼:
- DB 컬럼 이름 변경 → 모든 query 영향
- API field name 변경 → client 영향
- log·metric 이름 변경 → dashboard 영향
해결: 점진 도입. 새 module부터 UL 적용, legacy는 anti-corruption layer로 격리. 한 번에 다 바꾸지 않음.
3. Vocabulary가 변할 때
도메인 정책 변경 → 단어 의미 변경 (예: 학칙 개정으로 "정정"의 정의가 달라짐). 모든 layer 동기화가 필요해짐.
해결: Vocabulary 변경을 schema migration처럼 다룸. ADR로 변경 이유 기록 + 버전 관리. UL이 살아있는 도구임을 인정.
4. Bounded Context 부재 시 의미 충돌
같은 단어가 다른 도메인 context에서 다른 의미를 가질 수 있음:
- "회원" — 도서관 context vs 학생회 context vs 동아리 context
- "수업" — 학사 context (정규 과목) vs 평생교육원 context (단기 과정)
UL을 시스템 전체에 강제하면 충돌. → bounded-context가 답. UL은 bounded context 안에서만 통일됨.
5. 학습 곡선
신규 팀원이 vocabulary 익히는 시간 필요. 빠른 onboarding 어려움.
해결: Glossary를 첫 onboarding 자료로. AGENTS.md에 도메인 용어집을 처음 부분에. 신참 + AI agent가 같은 자료로 학습.
6. Over-formalization
Vocabulary를 너무 strict하게 강제하면 자연스러운 의사소통 방해. "이 회의에서는 '수강신청'만 쓰세요, '신청'은 금지" 같은 규칙은 비현실적.
해결: Strict는 코드·문서·spec에만, 회의는 자연스럽게. Code review에서 vocabulary deviation 점검.
🔄 대안 흐름
이 원칙이 적용 안 되는 시나리오와 다른 답.
대안 1 — DSL (Domain-Specific Language)
UL을 언어 수준으로 박음. SQL이 DB 도메인의 DSL, Make file이 빌드 도메인의 DSL. 내부 구현 vs 사용자 표현이 언어 자체로 분리.
→ UL의 가장 강한 형태. 비용 큼 (parser·compiler 직접 만들어야), 작은 도메인에 over-spec. 하지만 반복 사용 도메인에서는 가장 강력.
대안 2 — Pidgin / 절충 vocabulary
도메인 + 기술 어휘 혼합. "수강신청 form 제출", "정정 endpoint 호출". 실무 다수가 이 패턴.
→ UL의 현실적 절충. 전 layer 통일 비용 회피, 하지만 번역 비용 일부 잔존. AI 시대에는 AI agent가 pidgin을 figure out하느라 verbosity 증가 — UL이 더 답.
대안 3 — Anemic Domain Model
Vocabulary 일치 거부. 데이터를 그대로 노출. behavior는 service에 별도. CRUD UI에 적합.
→ DDD 진영에서 anti-pattern으로 비판 (Vernon, Fowler). 하지만 도메인이 단순할 때는 over-engineering 회피 측면에서 정당.
대안 4 — English-only standardization
글로벌 팀에서 영어 vocabulary로 통일. 도메인 단어를 영어로 번역 강제. lingua franca가 UL 일치보다 우선.
→ 한국어 도메인에서는 명백한 손실. 한국어 vocabulary의 정밀도 + 글로벌 영어 둘 다는 어려움. 한국 segment의 고유 자산을 영어로 평탄화하면 의미 손실.
대안 5 — No talk, just code
Vocabulary 합의 시간 절감. 코드를 보고 의미 추론. 작은 팀 / 단독 개발자에 적합.
→ Solo project에서는 정당. 하지만 AI agent도 협업 대상이라면 코드만으로 부족 — UL이 AI를 위한 vocabulary 합의가 됨.
💡 인사이트
AI 시대 왜 지금 부활하는가 + 학내 segment 의미.
1. AI agent의 verbosity 문제 직접 해결
mattpocock/skills의 명제 다시:
"Agents use 20 words where 1 will do."
Agent가 도메인 vocabulary를 모르면:
- "course registration form submission for the upcoming semester subject to capacity constraints" (12 words)
Agent가 알면:
- "수강신청" (5 글자)
→ Token 비용 / context 사용 / latency가 모두 직접 감소. 단순 미관이 아니라 경제적 가치. 그리고 misalignment도 감소 — 짧은 단어가 정확한 의미를 운반.
2. AI 시대 information hiding의 vocabulary 단위 표현
information-hiding 명제: secret을 module 안에 격리. UL의 응용:
도메인 vocabulary는 시스템의 secret이 아니라 contract. 외부에 명시적으로 노출.
UL이 정착되면:
- AGENTS.md / glossary가 AI에게 도메인을 한 번에 가르침
- 새 AI session도 vocabulary 학습 시간 0
- AI가 jargon을 figure out하는 실수가 사라짐
→ Information hiding의 vocabulary 측 표현이 UL.
3. 한국어 도메인의 숨은 자산 — 학사 vocabulary
한국어 학사 vocabulary는 고유 정밀도가 매우 높음. 영어로 번역하면 손실:
| 한국어 | 영어 번역 시도 | 손실되는 의미 |
|---|---|---|
| 수강신청 | course registration | 학기·정정 기간·시간충돌·정원·졸업요건 같은 학내 implications |
| 정정 | course change/drop-add | 정정 기간·횟수 제한·환불 규정 |
| 폐강 | course cancellation | 최소 수강인원·교수 사정·대체 안내 |
| 가산점 | bonus points | 우선순위·연차·전공·학년 가중치 |
| 정원 | capacity | 분반·대기열·우선순위 규칙 |
| 재수강 | retaking | 학점 인정·평점 산정·횟수 제한 |
| 학사일정 | academic calendar | 학기·학년·방학·개강·종강 segmentation |
| 전공이수 | major requirement fulfillment | 필수·선택·심화·졸업요건 |
→ 한국어로 두는 것이 정확한 design. 영어로 번역하면 implications가 사라짐. AI agent에게 한국어 vocabulary 그대로 노출하는 게 정합.
4. v1.0 design 직접 적용
| Layer | UL 표현 |
|---|---|
SKILL.md frontmatter | name: 수강신청-검증 (한국어 그대로 또는 sugang-sinchung-verification) |
| AGENTS.md | 첫 부분에 도메인 용어집 (학번, 학과, 과목 코드, 학사일정, 가산점) |
| 학내 통합 모듈 API | 학사일정_조회(), 시간표_충돌_검사() (한국어 함수명 또는 transliteration) |
| Test name | test_정원_초과시_대기열_등록, test_정정_기간_외_변경_불가 |
| Log/metric | dim.수강신청_상태, metric.가산점_평균 |
→ 모든 layer가 한국어 학사 vocabulary 그대로. 번역 layer 0.
5. 학내 vocabulary skill을 marketplace로
학내 sektor에서 가장 직접적인 공유 자산은 vocabulary skill:
/수강신청-glossary.md/학사일정-glossary.md/장학-glossary.md/졸업요건-glossary.md
각 skill이 학내 도메인의 한 vocabulary 영역을 정의. 다른 학생이 자기 도구를 만들 때 이 skill을 import → vocabulary 일관성 자동 확보.
이게 research/stateless-llm-sdk/design-principles|7 원칙의 원칙 3 (Ubiquitous Language per Segment)의 직접 implementation. v1.0 marketplace의 kernel asset이 vocabulary skill.
6. Hickey 명제의 vocabulary 단위 응용
simple-not-easy 노트의 complect (얽힘) 제거가 vocabulary 단위에서:
번역 layer 자체가 complect
→ 도메인 단어가 항상 *기술 단어와 함께* 등장 (얽힘)
→ 둘이 *같이 변해야* 시스템 일관성 유지
UL: 번역 layer 제거
→ 도메인 단어가 *독립적 entity*
→ 변할 때 *vocabulary 자체*가 변하고, 시스템은 자동 따라감
→ Hickey의 simple 추구가 vocabulary 단위에서 번역 layer 제거로 작동.
7. AI 시대 새 협업 mode — 사람-AI dialog의 substrate
전통적 페어 프로그래밍: 두 사람이 같은 vocabulary로 대화. AI 시대 변형:
사람과 AI agent가 같은 도메인 vocabulary로 대화. UL이 그 dialog의 substrate.
학내 학생이 AI에게 "수강신청 검증 함수 만들어줘" — 5 단어로 정확한 의미 전달. AI가 학내 학사 vocabulary skill을 import해 두면 jargon figure out 비용 0. 이게 strategic-vs-tactical-programming|strategic-vs-tactical의 사람-AI substrate가 vocabulary 단위에서 작동하는 모양.
8. 학내 segment에서 vocabulary 학습이 fundamentals 학습
학내 학생이 v1.0이나 비슷한 도구를 처음 만들 때 학습 path:
이 path에서 학생이 vocabulary 정밀도를 의식적으로 사용하기 시작 → DDD 학습이 자연스럽게 시작 → fundamentals 흡수.
→ UL이 fundamentals 학습의 entry point. 추상적 design 원칙보다 내가 매일 쓰는 단어가 입구.
다음에 가야 할 자리
이 노트가 호출한 다른 원칙들 — 자연스러운 다음 노트:
- bounded-context — UL이 어디까지 통하는가. UL의 적용 범위 정의 (Domain 축 두 번째)
- anti-corruption-layer — 외부 시스템과 만나는 자리에서 vocabulary 변환. Domain 축 마무리
- orthogonality — vocabulary 단위 layer 독립성
→ Domain 축은 UL → BC → ACL이 자연스러운 순서. 다음은 bounded-context 권장.
관련
- overview
- information-hiding — vocabulary 단위 information hiding이 UL
- information-leak-vs-abstraction — 번역 layer가 leak source. UL이 leak 차단
- simple-not-easy — vocabulary 얽힘 제거가 complect 제거의 vocabulary 표현
- research/stateless-llm-sdk/design-principles|design-principles — 7 원칙 3번 (Ubiquitous Language per Segment) 직접 source
- sources/key-articles-summary#2. mattpocock/skills — README 핵심|key-articles-summary — Matt의 "20 words where 1 will do" 인용
Sources
직접 source
- Domain-Driven Design: Tackling Complexity in the Heart of Software — Eric Evans (2003). Chapter 2 Communication and the Use of Language가 UL의 원전
- Learning Domain-Driven Design — Vlad Khononov (2021, O'Reilly). 한국어 번역본 《도메인 주도 설계 첫걸음》. UL 가장 접근 쉬운 설명
- Implementing Domain-Driven Design — Vaughn Vernon (2013). 실무 적용
Matt의 AI 시대 응용
- mattpocock/skills GitHub — README의 "20 words where 1 will do" 명제
- aihero.dev — Skills Changelog: Ubiquitous Language → /grill-with-docs — UL 발견을 AI가 돕는 skill 진화
- Vibe Sparking — Matt Pocock Skills Deep Dive — UL skill 외부 분석
무료 자료
- DDD Europe YouTube channel https://www.youtube.com/@ddd_eu — Eric Evans 인터뷰 등
- Eric Evans의 다양한 keynote (DDDx, QCon 등)
관련 노트
- research/stateless-llm-sdk/study-resources-fundamentals|study-resources-fundamentals — 학습 path Step 5 (Khononov DDD)