모든 제품에는 언어가 있습니다.

프로그래밍 언어가 아닙니다. 도메인 언어 (Domain Language)입니다. 이 특정 제품, 이 특정 비즈니스, 이 특정 문제 공간의 맥락에서 특정한 의미를 갖는 구체적인 단어들 말입니다.

이커머스 (e-commerce) 플랫폼에서 '고객 (Customer)'은 '사용자 (User)'와 같지 않습니다. '주문 (Order)'은 '장바구니 (Cart)'와 같지 않습니다. '리스팅 (Listing)'은 '제품 (Product)'과 같지 않습니다. 이러한 구분은 중요합니다. 이는 비즈니스 도메인 (Business Domain)의 실제 차이를 반영합니다. 적절한 위치에 적절한 단어를 사용하는 것은 코드를 읽기 쉽게 만듭니다. 잘못된 단어, 혹은 동일한 개념에 대해 다섯 가지의 서로 다른 단어를 사용하는 것은 누군가 코드를 읽을 때마다 번역을 필요로 하는 코드를 만듭니다.

여러분의 팀은 이 언어를 알고 있습니다. 여러분은 수개월 또는 수년 동안 이를 구축해 왔습니다. 이 언어는 대화 속에, 풀 리퀘스트 (Pull Request) 댓글 속에, 제품 관리자 (Product Manager)가 기능을 설명할 때 사용하는 명칭 속에 살아 있습니다. 이것은 여러분의 팀을 효율적으로 만드는 공유된 어휘입니다.

여러분의 AI는 이 중 그 어떤 것도 알지 못합니다. 그리고 매 세션마다 AI는 자신만의 언어를 만들어냅니다.

도메인 언어 드리프트 (Domain Language Drift)가 실제로 나타나는 모습

이는 미묘하게 시작되어 시간이 지나면서 축적됩니다.

처음 몇 달 동안 AI는 합리적인 명명 규칙을 사용하는 컴포넌트 (Components)와 훅 (Hooks)을 생성합니다. 명백히 잘못된 것은 없습니다. AI가 선택한 단어들은 일반적인 React 어휘이며, 그것들이 설명하는 대상에 대해 충분히 잘 작동합니다.

하지만 표면 아래에서는 도메인 언어가 파편화되고 있습니다. 여러분의 팀이 '고객 (Customer)'이라고 부르는 개념이 어떤 컴포넌트에서는 '사용자 (User)'로, 다른 곳에서는 '클라이언트 (Client)'로, AI가 코드베이스의 다른 부분을 보고 있을 때 생성한 곳에서는 '구매자 (Buyer)'로 나타납니다. 여러분의 팀이 '주문 (Order)'이라고 부르는 개념이 어떤 훅에서는 '구매 (Purchase)'로, 다른 훅에서는 '트랜잭션 (Transaction)'으로, 세 번째 훅에서는 '체크아웃 (Checkout)'으로 나타납니다.

이 중 어느 것도 개별적으로는 틀리지 않습니다. 'User'는 합리적인 단어입니다. 'Client'도 마찬가지입니다. 'Buyer'도 그렇습니다. 하지만 이들은 같은 단어가 아니며, 여러분의 도메인에서는 같은 의미를 갖지 않습니다. AI는 아무도 알려주지 않았기 때문에 그 차이를 알지 못합니다.

6개월 이상의 세션이 지나면, 코드베이스는 하나의 언어로 말하는 것을 멈춥니다. 다섯 개의 언어로 말하게 됩니다. 이번 주의 기능을 위한 AI의 언어, 3개월 전 AI의 언어, AI가 워크플로(workflow)에 들어오기 전 시니어 개발자가 작성했던 언어, 지난 스프린트(sprint)에서 신입 개발자가 추가한 언어, 그리고 비즈니스 대화에는 존재하지만 AI가 따를 수 있는 형태로 한 번도 기록된 적 없는 실제 도메인 언어(domain language)가 그것입니다.

새로운 개발자가 합류하여 코드를 읽으며 코드베이스를 이해하려고 시도합니다. 그들은 어떤 곳에서는 Customer를 발견하고 다른 곳에서는 User를 발견하며, 이들이 같은 것인지 다른 것인지 구분할 수 없습니다. 그들은 질문을 해야만 합니다. 정답은 그것들이 같은 것이라는 사실입니다. AI는 단지 알지 못했을 뿐입니다.

도메인 언어가 명명 규칙(naming conventions)보다 중요한 이유

명명 규칙(naming conventions)은 형식(form)에 관한 것입니다. 컴포넌트(components)를 위한 PascalCase, 함수(functions)를 위한 camelCase, 이벤트 핸들러(event handlers)를 위한 handleX 등. 이것들은 단어가 어떻게 쓰이는지에 대한 규칙입니다.

도메인 언어(domain language)는 의미(meaning)에 관한 것입니다. Customer 대 User, Order 대 Purchase, Listing 대 Product. 이것들은 어떤 단어가 어떤 개념을 담을지에 대한 결정입니다.

둘 다 중요합니다. 하지만 이들은 서로 다른 문제를 해결합니다. 명명 규칙은 형식의 일관성을 해결합니다. 도메인 언어는 의미의 일관성을 해결합니다. 그리고 의미의 일관성이야말로 비즈니스를 이해하는 사람에게 코드베이스를 읽기 쉽게 만드는 핵심입니다.

명명 규칙은 완벽하지만 도메인 언어가 파편화된 코드베이스는 기술적으로는 일관적이지만 의미론적(semantically)으로는 혼란스럽습니다. 단어의 대소문자가 어떻게 표기되는지는 알 수 있습니다. 하지만 구매를 완료한 사람을 설명할 때 어떤 단어를 사용해야 하는지는 알 수 없습니다.

도메인 언어의 파편화는 명명 규칙 위반보다 알아차리기 더 어렵습니다. 왜냐하면 자동화된 체크(automated checks)를 트리거하지 않기 때문입니다. 어떤 린터(linter)도 Customer와 User가 혼용되고 있다는 사실을 잡아내지 못합니다. 컴포넌트가 User 객체를 전달받아 내부적으로 이를 Customer라고 부를 때 TypeScript 에러도 발생하지 않습니다. 코드는 컴파일되고, 테스트는 통과합니다. 언어는 파편화되어 있지만 아무도 모릅니다.

AI가 만들어낸 언어가 어디에서 오는가

AI는 도메인 개념(domain concepts)에 이름을 붙일 때 무작위로 선택하는 것이 아닙니다.

AI는 현재 세션에서 보이는 컨텍스트(context)에 기반하여 국소적으로 타당한(locally reasonable) 선택을 하고 있는 것입니다. 작업 중인 파일에서 User를 사용하고 있다면 User를 사용합니다. 인접한 훅(hook)이 Customer를 사용하고 있다면 이를 바꿀 수도 있습니다. 프롬프트(prompt)에서 구매자(buyer)를 언급한다면 Buyer를 사용할 수도 있습니다. 컨텍스트에서 아무것도 추론할 수 없다면, 사용 가능한 가장 일반적인 용어로 돌아갑니다.

각각의 개별적인 선택은 방어 가능합니다. 하지만 그 합계는 혼돈입니다.

이것이 문제의 핵심입니다. AI는 이름을 짓는 데 서툰 것이 아닙니다. AI는 한 세션 내에서 국소적으로 일관된(locally consistent) 명명에는 매우 뛰어납니다. 문제는 서로 다른 컨텍스트를 가진 서로 다른 세션들 사이에서, 각기 다른 국소적으로 타당한 선택을 내림으로써, 의미론적으로 전역적 불일치(globally inconsistent)를 일으키는 코드베이스를 만들어낸다는 점입니다.

도메인 언어(Domain language)는 정의상 AI가 컨텍스트만으로 도출할 수 있는 것이 아닙니다. 컨텍스트는 주변에 어떤 React 패턴이 보이는지는 알려줍니다. 하지만 이 제품의 이 비즈니스 도메인에서 Customer는 최소 한 번의 구매를 완료한 사람을 의미하고, User는 계정을 가진 모든 사람을 의미한다는 사실은 알려주지 않습니다. 그 구분은 비즈니스 내에 존재합니다. AI가 무언가를 생성하기 전에 AI가 사용할 수 있는 형태로 기록된 적이 없었던 것입니다.

도메인 언어 문서 구축하기

해결책은 복잡하지 않습니다. 단지 거의 어떤 팀도 하지 않는 작업일 뿐인데, 그 이유는 이것이 개발 작업처럼 느껴지지 않기 때문입니다.

도메인 언어 문서란 제품의 개념들과, 코드베이스에서 이를 표현하기 위해 사용하는 구체적인 단어들의 목록입니다. 비즈니스 용어집(business glossary)이 아닙니다. 사용자에게 노출되는 용어도 아닙니다. 코드베이스 전반에 걸쳐 컴포넌트 이름(component names), 훅 이름(hook names), 타입 정의(type definitions), 그리고 변수 이름(variable names)에 나타나야 하는 구체적인 기술 용어들입니다.

단순화된 이커머스(e-commerce) 컨텍스트를 위한 도메인 언어 문서의 예시는 다음과 같습니다:

이 프로젝트를 위한 도메인 언어 규칙:

인물 개념(Person concepts):
...

의미 있는 시간 동안 운영되어 온 프로젝트라면 이 문서를 만드는 데 오랜 시간이 걸리지 않습니다. 도메인 언어 (Domain language)는 이미 존재하기 때문입니다. 그것은 대화, 풀 리퀘스트 (Pull request) 댓글, 그리고 제품 관리자 (Product manager)들이 사용하는 명칭 속에 살아 있습니다. 이를 문서화하는 것은 대부분 이미 암묵적으로 존재하던 것을 명시적으로 만드는 과정일 뿐입니다.

일단 언어가 존재하게 되면, 이는 AI가 매 세션 시작 전에 전달받는 규칙의 일부가 됩니다. 어휘가 정의되었기 때문에 AI는 더 이상 자신만의 어휘를 만들어내지 않습니다. 'Customer'는 'Customer'가 나타나야 할 곳에 나타나고, 'User'는 'User'가 나타나야 할 곳에 나타납니다. 규칙이 존재하기 때문에 그 구분이 유지됩니다.

시간이 흐름에 따라 코드베이스에서 변하는 것

도메인 언어의 일관성 (Consistency)은 도메인 언어의 파편화 (Fragmentation)가 발생하는 것과 동일한 방식으로 복리로 작용합니다. 하지만 이는 올바른 방향으로 작용합니다.

AI가 올바른 도메인 용어를 일관되게 사용하면, 새로운 컴포넌트 (Component)들은 구조적뿐만 아니라 의미론적 (Semantically)으로도 기존 컴포넌트와 유사해 보입니다. 지난주에 작성된 새로운 기능을 읽는 개발자는 사용된 단어들이 다른 모든 곳에서 사용되는 것과 동일하기 때문에, 그것이 무엇에 대해 이야기하고 있는지 즉시 이해할 수 있습니다.

코드베이스를 읽는 데 드는 인지적 부하 (Cognitive overhead)가 줄어듭니다. 코드가 더 단순해졌기 때문이 아니라, 언어가 일관되게 변했기 때문입니다. 개발자는 시스템의 서로 다른 부분을 읽을 때 'User', 'Customer', 'Client' 사이를 번역하며 머릿속으로 변환할 필요가 없습니다. 각 개념에 대해 하나의 단어를 마주하게 되며, 그 단어가 무엇을 의미하는지 즉시 알게 됩니다.

온보딩 (Onboarding)이 가속화됩니다. 새로운 개발자는 문서화를 통해 도메인 언어를 한 번 학습하면, 이후 AI가 생성하는 모든 컴포넌트와 훅 (Hook)을 포함하여 코드베이스의 모든 곳에서 일관되게 적용된 언어를 보게 됩니다.

검색이 신뢰할 수 있게 됩니다. 'Orders'와 관련된 모든 것을 찾는 개발자는 'Order'를 검색하여 찾아낼 수 있습니다. 'Purchase', 'Transaction', 'Checkout', 'Fulfillment' 등을 추가로 검색하며 모든 변형을 다 찾아냈기를 바랄 필요가 없습니다.

코드베이스는 마치 공통된 언어를 공유하는 팀이 작성한 것처럼 읽히기 시작합니다. 규칙이 그렇게 되도록 보장하기 때문입니다. AI가 코드의 상당 부분을 구축하는 데 관여했을 때조차 말입니다.

당신의 제품이 이미 보유하고 있는 언어

당신의 제품은 이미 도메인 언어 (domain language)를 가지고 있습니다. 당신의 팀은 이미 그것을 알고 있습니다.

문제는 언어가 존재하지 않는다는 것이 아닙니다. 문제는 AI가 무언가를 생성하기 전에, AI가 따를 수 있는 형태로 그 언어가 명문화된 적이 없다는 점입니다.

AI가 당신의 도메인 내 개념에 대해 잘못된 단어를 사용할 때마다, 그것은 실수를 하는 것이 아닙니다. 그것은 당신이 남겨둔 공백을 채우고 있는 것입니다. 당신이 원했던 단어가 규칙에 없었기 때문에, AI는 자신이 가진 맥락에서 가장 합리적으로 보이는 단어를 사용한 것입니다.

도메인 언어를 기록하세요. 매 세션마다 AI에게 그것을 전달하세요. 그리고 단 하나만 있어야 할 코드베이스에서 동일한 개념에 대해 다섯 개의 단어를 찾아내는 일을 멈추세요.

프롬프트 (prompt)는 중요하지 않습니다. 규칙 (rules)이 중요합니다.

당신의 React 프로젝트에는 언어가 있습니다. 그것은 당신의 팀이 수행한 작업과 사물들을 무엇이라 불러야 하는지에 대해 나누었던 대화들을 통해 시간이 흐르며 발전해 왔습니다.

당신의 AI는 매 세션마다 다른 언어를 말합니다. 그것이 당신의 언어를 말할 수 없어서가 아닙니다. 당신이 당신의 언어가 무엇인지 알려준 적이 없기 때문입니다.

기록하세요. 일관되게 적용하세요. 그리고 코드베이스가 마침내 다섯 개의 언어가 아닌, 단 하나의 언어로 말하게 하세요.

당신의 React 프로젝트의 도메인 언어가 파편화된 곳을 찾고 싶습니까?

저는 바로 그 지점을 정확히 식별할 수 있도록 도와주는 무료 24가지 체크리스트를 만들었습니다. 제품이 이미 보유한 언어를 따르는 대신 AI가 어휘를 임의로 만들어내고 있는 구조적 공백들을 찾아낼 수 있습니다.

→ React AI Clean Code Checklist 받기 — 무료

→ Avery Code React AI Engineering System