ubiquitous-language

ubiquitous-language skill 개요

ubiquitous-language skill은 도메인에 관한 뒤섞인 논의를 정리해, 표준 용어·정의·피해야 할 별칭이 포함된 구조화된 DDD 스타일 용어집으로 바꿔줍니다. 핵심 역할은 막연하게 “용어집을 작성하는 것”이 아닙니다. 같은 개념을 두고 제품, 엔지니어링, 기술 문서 팀이 서로 겹치거나 일관되지 않은 표현을 쓰고 있을 때, ubiquitous-language skill은 팀의 언어를 표준화하는 데 초점이 있습니다.

ubiquitous-language가 특히 잘 맞는 용도

대화 안에 이미 도메인 관련 표현이 어느 정도 쌓여 있고, 그것을 재사용 가능한 형태로 정리해야 할 때 ubiquitous-language skill이 가장 잘 맞습니다. 특히 다음과 같은 경우에 유용합니다.

• domain-driven design 작업
• API 및 제품 용어 정리
• 내부 플랫폼 네이밍 정렬
• 온보딩 문서
• 콘텐츠 모델링
• 문서 전반에서 하나의 표준 용어를 일관되게 써야 하는 ubiquitous-language for Technical Writing

실제로 해결하는 핵심 과제

대부분의 사용자는 보통 아래 문제 중 하나를 해결하려고 합니다.

• “같은 것을 두고 이름을 여러 개로 쓰고 있다.”
• “하나의 용어가 문맥마다 다른 뜻으로 쓰인다.”
• “문서, 제품 UI, 엔지니어링 논의의 언어가 점점 어긋나고 있다.”
• “빈 페이지에서 시작하는 게 아니라, 이미 있는 대화를 바탕으로 1차 도메인 용어집이 필요하다.”

이 skill은 현재 대화를 훑어보며 모호하거나 중복되는 용어를 찾아내고, 기준이 되는 canonical term을 제안한 뒤, 결과를 UBIQUITOUS_LANGUAGE.md에 작성합니다.

일반 프롬프트와 다른 점

일반 프롬프트로도 용어집 작성은 요청할 수 있습니다. 하지만 ubiquitous-language 워크플로는 더 구체적이어서, 실제 도입 판단에 훨씬 도움이 됩니다.

• 모호성, 동의어, 과적재된 용어를 찾습니다
• 단순 추출이 아니라 canonical naming으로 밀어붙입니다
• 재사용 가능한 markdown 산출물을 만듭니다
• 검토와 수정이 쉬운 예측 가능한 표 형식을 따릅니다

그래서 단순한 “우리 도메인 용어를 요약해줘”보다, 용어를 굳히고 정제하는 데 더 적합합니다.

출력 결과는 어떤 형태인가

이 skill은 UBIQUITOUS_LANGUAGE.md를 생성하며, 예를 들어 주문 생애주기나 사람/역할 같은 주제별 섹션 아래에 다음 항목을 담은 표를 만듭니다.

• canonical term
• definition
• aliases to avoid

이 형식은 특히 리뷰에 강합니다. 어디에서 의견이 갈리는지가 빠르게 드러나기 때문입니다.

이 skill이 잘 맞지 않는 경우

다음 상황이라면 이 skill은 우선순위가 아닙니다.

• 대화 안에 아직 도메인 자료가 충분히 쌓이지 않았을 때
• 전체 ontology, data model, 또는 event storming 결과물이 필요할 때
• 목표가 도메인 명확화가 아니라 브랜드 네이밍일 때
• 아직 도메인이 너무 가설적이라 canonical term을 정하기 이른 때

이럴 때는 먼저 예시와 논의를 더 모은 뒤, 나중에 이 skill을 실행하는 편이 낫습니다.

ubiquitous-language skill 사용 방법

ubiquitous-language 설치 맥락

mattpocock/skills 기반 skills ecosystem을 사용 중이라면, 평소 쓰는 skill loader를 통해 ubiquitous-language skill을 설치하면 됩니다. 흔한 패턴은 아래와 같습니다.

npx skills add mattpocock/skills --skill ubiquitous-language

환경에 따라 skills를 다른 방식으로 로드한다면 그 방법을 쓰면 됩니다. 핵심 조건은 에이전트가 ubiquitous-language skill 정의에 접근할 수 있고, 작업 디렉터리에 UBIQUITOUS_LANGUAGE.md를 쓸 수 있어야 한다는 점입니다.

사용 전에 먼저 읽어야 할 파일

먼저 확인할 파일은 다음입니다.

• SKILL.md

이 저장소 경로는 드물게도 매우 단순합니다. 주요 사용 로직이 이 한 파일에 들어 있으므로, 도입 여부를 판단하기 전에 보조 스크립트나 깊은 참조 파일까지 뒤질 필요가 없습니다.

이 skill이 실제로 필요로 하는 입력

이 skill은 현재 대화에 다음 요소가 이미 들어 있을 때 가장 잘 작동합니다.

• 도메인 명사: order, invoice, account, shipment
• 프로세스 동사: approve, fulfill, cancel
• 역할명: customer, operator, reviewer
• 혼란스러운 사용 사례: “we sometimes say subscription, sometimes contract”
• 경계에 대한 맥락: 제품 영역, 대상 사용자, 시스템, 비즈니스 프로세스

이런 재료가 없으면 결과가 얇아지거나 지나치게 추측성으로 흐르기 쉽습니다.

ubiquitous-language를 제대로 트리거하는 방법

약한 요청은 이런 식입니다.

• “Make a glossary.”

더 강한 요청은 아래와 같습니다.

• “Use the ubiquitous-language skill on this discussion. Extract domain terms, identify synonyms and overloaded words, propose canonical terms, and write UBIQUITOUS_LANGUAGE.md. Group terms by business area.”

이렇게 말해야 에이전트가 단순히 즉석에서 용어집을 꾸며내는 것이 아니라, 의도된 skill 흐름대로 작업하게 됩니다.

막연한 목표를 품질 높은 프롬프트로 바꾸기

좋은 ubiquitous-language usage 프롬프트는 보통 네 가지를 포함합니다.

1. 도메인
2. 원본 자료
3. 충돌이나 문제 지점
4. 기대하는 출력 형태

예시:

“Use the ubiquitous-language skill for our order-management domain. Based on the conversation so far, extract core terms, flag where we use the same word for different concepts, and propose canonical terms with aliases to avoid. Separate customer-facing terms from internal operational terms where needed. Save the result to UBIQUITOUS_LANGUAGE.md.”

실무에서 추천하는 워크플로

안정적으로 쓰려면 아래 흐름이 좋습니다.

1. 먼저 도메인을 자연스럽게 논의한다
2. 대화 중 용어가 실제로 충돌하게 둔다
3. ubiquitous-language를 실행한다
4. 제안된 canonical term을 검토한다
5. 비즈니스적으로 잘못된 부분을 수정한다
6. 승인된 용어집을 문서, API, UI 카피, 이슈 템플릿에 반영한다

이 skill은 논의가 어느 정도 진행된 뒤에 가장 큰 가치를 냅니다. 시작 전에 돌리는 도구는 아닙니다.

출력 품질을 높이는 실전 팁

더 나은 결과를 얻으려면 아래를 챙기세요.

• 추상적인 범주보다 구체적 예시를 넣기
• 용어 충돌을 명시적으로 언급하기
• 어떤 독자가 가장 중요한지 밝히기: engineers, users, support, writers
• 해당 용어가 내부 전용인지 대외 공개용인지 표시하기
• 모든 것을 한 라벨로 뭉개지 말고 의미 있는 구분을 유지하라고 요청하기

이런 정보는 잘못된 동의어 병합을 줄여 주기 때문에, 용어집 품질에 직접적인 영향을 줍니다.

기술 문서 작성자는 무엇을 다르게 해야 하나

ubiquitous-language for Technical Writing에 쓸 때는 다음과 같은 제약을 함께 넣는 것이 좋습니다.

• 독자에게 익숙한 선호 어휘
• 금지할 내부 jargon
• UI label 제약
• API term 제약
• 문서가 제품 언어를 그대로 따라야 하는지, 아니면 정규화해야 하는지

예시:

“Use the ubiquitous-language skill, but optimize for external documentation. Prefer terms users will recognize, keep internal code names in aliases to avoid, and note any term that should not appear in public docs.”

이렇게 해야 결과물이 에디토리얼 관점에서 바로 활용 가능해집니다.

기대되는 출력 파일과 검토 방식

생성되는 파일은 UBIQUITOUS_LANGUAGE.md입니다. 리뷰할 때는 아래 질문으로 점검하세요.

• 이 skill이 서로 다른 개념을 실수로 합쳐 버리지는 않았나?
• 모호한 용어를 경고 없이 그대로 남겨두지는 않았나?
• “aliases to avoid”가 실제 사용 맥락에서 타당한가?
• 정의가 단순한 문구 취향이 아니라 실제 시스템 동작을 반영하고 있는가?

첫 결과물은 최종 진실이라기보다, 의사결정을 위한 초안으로 보는 편이 맞습니다.

ubiquitous-language skill FAQ

ubiquitous-language는 초보자도 쓰기 쉬운가?

네. 도메인에 대한 대화가 이미 어느 정도 있다면 초보자도 충분히 활용할 수 있습니다. 깊은 DDD 전문성이 없어도 괜찮습니다. 출력은 읽기 쉬운 markdown이고, 표 형식이라 의견 충돌도 눈에 잘 띕니다. 다만 초보자가 자주 놓치는 점은, 결과 품질이 원본 대화의 구체성에 크게 좌우된다는 사실입니다.

그냥 용어집을 직접 요청하는 것보다 왜 더 나은가?

ubiquitous-language skill은 범위가 더 좁은 대신, 용어 정렬 목적에는 더 안정적입니다. 모호성, 동의어, 과적재된 용어를 감지하고, 그다음 canonical choice를 강제하도록 설계되어 있습니다. 일반적인 glossary 프롬프트는 용어를 나열만 하고 충돌을 해결하지 못하는 경우가 많습니다.

DDD 팀에게만 도움이 되나?

아닙니다. DDD 어휘를 프레임으로 삼고 있을 뿐, 실제로는 용어 표류가 마찰을 만드는 어디에서든 유용합니다. 예를 들면 기술 문서, API, 지원 운영, 제품 설계, 내부 툴링 같은 영역입니다. 특히 여러 팀이 같은 워크플로를 서로 다른 표현으로 설명하고 있을 때 효과가 큽니다.

언제 ubiquitous-language 설치를 우선하지 말아야 하나?

주요 요구가 아래 중 하나라면 ubiquitous-language install을 우선할 필요는 없습니다.

• 제품명 브레인스토밍
• 최종 사용자 문서를 처음부터 생성하기
• 데이터베이스 스키마 설계
• 모든 비즈니스 규칙을 상세히 맵핑하기

이 skill은 전체 도메인 모델링이 아니라, 언어를 정규화하는 용도입니다.

짧은 대화만으로도 작동하나?

작동은 하지만 결과는 약해집니다. 이 skill은 현재 대화에서 내용을 추출하므로, 입력이 빈약하면 정의가 일반론적으로 흐르고 의미 있는 충돌 탐지도 줄어듭니다. 짧은 대화밖에 없다면, 먼저 예시·엣지 케이스·경합하는 용어를 더 보강하는 것이 좋습니다.

문서화 워크플로에도 맞나?

그렇습니다. 출력 파일은 버전 관리하기 쉽고, pull request에서 리뷰하기도 편하며, 스타일 가이드·아키텍처 문서·온보딩 자료·API 레퍼런스에 재사용하기 좋습니다. 그래서 용어 결정이 코드와 문서 옆에 함께 살아 있길 원하는 팀에게 ubiquitous-language usage는 실무적으로 잘 맞습니다.

ubiquitous-language skill 개선 방법

더 풍부한 도메인 근거를 제공하기

출력 품질을 가장 크게 좌우하는 레버는 원본 자료의 밀도입니다. ubiquitous-language를 실행하기 전에 아래를 포함하세요.

• 실제 사용자에게 보이는 용어
• 내부 shorthand
• 프로세스 단계
• edge case
• 같은 것을 두고 두 사람이 다른 말을 쓴 사례

이 skill은 눈에 보이는 것만 정규화할 수 있습니다.

진짜 동의어와 중요한 구분을 분리하기

흔한 실패 패턴은, 서로 관련은 있지만 다른 두 개념을 하나로 접어 버리는 것입니다. 이를 막으려면 차이를 직접 명시하세요. 예를 들면 다음과 같습니다.

• “Order is the customer request; invoice is the billing artifact.”
• “Account is the legal entity; workspace is the product container.”

이렇게 해야 과도하게 단순화하지 않고 도메인 경계를 유지할 수 있습니다.

어떤 언어가 우선해야 하는지 알려주기

canonical naming에는 판단이 들어갑니다. 선호 기준을 밝히지 않으면, 기술적으로는 맞지만 실제 워크플로에는 맞지 않는 용어를 고를 수 있습니다. 아래 기준을 지정하면 결과가 좋아집니다.

• external vs internal vocabulary
• engineering vs business terminology
• UI labels vs back-office labels
• 호환성을 위해 유지해야 하는 용어

이런 가이드는 생성 후 실제로 쓸 수 있는 용어집을 만드는 데 큰 차이를 냅니다.

모호성이 큰 도메인에는 더 강한 프롬프트 쓰기

도메인 용어가 과하게 겹쳐 있다면, 모호성 분석을 명시적으로 요청하세요. 예시:

“Use the ubiquitous-language skill and be strict about ambiguity. If the same term refers to multiple concepts, split them into separate entries and call out the conflict clearly instead of picking one silently.”

이렇게 하면, 그럴듯한데 틀린 명확성을 만들어내는 위험을 줄일 수 있습니다.

aliases to avoid는 특히 신중히 검토하기

많은 팀이 가장 큰 가치를 얻는 부분이 “aliases to avoid” 열이지만, 동시에 실수 시 혼란도 가장 큰 영역입니다. 금지된 별칭이 아래 조건에 해당하는지 꼭 확인하세요.

• 정말로 오해를 부르는가
• 레거시 문서에서는 아직 필요한가
• 어떤 독자에게는 허용 가능하지만 다른 독자에게는 부적절한가

좋은 2차 검토에서는 canonical term은 유지하되, alias 가이드를 조금 완화하는 경우가 많습니다.

첫 초안 이후 반복하기

좋은 ubiquitous-language guide는 한 번으로 끝나지 않고 반복적으로 다듬습니다.

1. skill을 실행한다
2. 이견이 있는 용어를 표시한다
3. 대화에 보완 예시를 추가한다
4. skill을 다시 실행한다
5. 용어집을 승인한다
6. 문서와 제품 언어 전반에 적용한다

첫 결과물 하나로 모든 네이밍 결정을 끝내려 해서는 안 됩니다.

결과를 문서 시스템으로 확장하기

UBIQUITOUS_LANGUAGE.md가 안정화되었다면, 실제 에디토리얼 작업과 연결해야 ubiquitous-language skill의 가치가 더 커집니다.

• 문서 스타일 가이드에서 링크하기
• PR 리뷰에 활용하기
• heading과 UI reference를 canonical term에 맞추기
• 오래된 문서에서 금지 alias를 점검하기

그래야 이 용어집이 보기 좋은 장식이 아니라, 실제로 작동하는 운영 자산이 됩니다.