서론

최근 저는 결제 및 알림 피드 시스템의 데이터를 모델링하는 작업을 수행했습니다. 이 시스템에는 고객, 프로젝트, 더블 엔트리 원장(double-entry ledger), PIX 지급액, WhatsApp 전송 아웃박스 등이 포함됩니다. 잘못된 컬럼 하나가 누락되는 불변성(invariant)을 깨뜨릴 수 있는 도메인입니다. 돈이 사라진 후에야 아무도 알아차리지 못하는 종류의 문제입니다.

평소라면 draw.io를 열고 상자들을 끌어다 놓고 선으로 연결했을 것입니다. 하지만 이번에는 텍스트 기반 다이어그램 언어인 Mermaid를 사용하여 전체 작업을 진행했습니다. 그리고 AI 어시스턴트(제 경우 Claude)와 디자인을 계속 주고받으며 작업했는데, 명확히 하자면 사이트가 아니라 제 IDE에서 작성한 것입니다.

그 선택은 제가 예상했던 것보다 훨씬 중요하게 작용했습니다. 다이어그램이 더 이상 '디자인의 그림'에 머무르지 않고 '그 자체인 디자인'이 되었습니다. AI가 읽고, 비평하고, 외과적인 정밀함으로 편집할 수 있는 무언가이자, 제가 살아있는 명세(living spec)로서 코드 옆에 커밋할 수 있는 것이 된 것입니다.

제가 배운 점을 구체적인 사례로 소개합니다.

erDiagram
    CUSTOMER ||--o{ PAYMENT : has
    PROJECT  ||--o{ PAYMENT : receives
...

사례 1: 단일 컬럼에 대한 정밀 수정

이것이 저를 설득한 결정적인 차이점입니다.

draw.io에서는 컬럼이 '상자 안에, 모양 안에, 캔버스 안에' 존재합니다. 만약 AI에게 하나의 필드를 고치게 하고 싶다면,

특정한 종류의 수정 작업이 극적으로 쉬워졌습니다:

• 컬럼 의미론 (Column semantics). 인라인 주석("signed; +credit / -debit", "= SUM(entries)")은 의도를 담고 있습니다. AI는 이를 활용하여 설계 자체를 검증했습니다. 예를 들어, 캐시된 balance 컬럼이 이를 유도하는 원장 항목(ledger entries)과 일치하는지 확인하는 식입니다.

PNG 파일로는 이러한 대화를 결코 나눌 수 없습니다.

사례 2: 다이어그램이 저장소(repo) 및 버전 관리 시스템 내에서 명세서(spec) 역할을 하는 경우

다이어그램이 일반 텍스트이기 때문에, 프로젝트 내에 존재합니다:

docs/design/EntityRelation.md

이는 텍스트가 무료로 제공하는 모든 이점을 가능하게 합니다:

• 차이점(diff) 확인이 가능합니다. BANK_ACCOUNT 테이블이나 새로운 status 열거형(enum) 값을 추가하는 풀 리퀘스트(pull request)는 이를 구현하는 마이그레이션(migration) 바로 옆에서 읽기 쉬운 diff 형태로 나타납니다. 반면 draw.io의 .drawio 바이너리 덩어리는 노이즈로 가득한 diff로 나타납니다.
• 신뢰할 수 있는 단일 원천(Source of truth)이 됩니다. 저는 Mermaid 파일을 계약(contract)으로 취급합니다. Flyway 마이그레이션과 JPA 엔티티(entities)는 이 파일과 일치해야 합니다. 설계와 실제 구현이 어긋날 때, 다이어그램을 기준으로 조정합니다. 이로써 설계 문서와 스키마(schema) 간의 불일치가 사라집니다.
• 단순한 모양이 아닌 불변성(invariants)을 인코딩합니다. 상자(box)만으로는 표현할 수 없는 규칙들을 다이어그램에 직접 주석으로 남겼습니다:

  %% 불변성(Invariant): LEDGER_TRANSACTION당, SUM(LEDGER_ENTRY.amount) = 0.
  %% 돈은 계좌 간에만 이동하며, 생성되거나 파괴되지 않는다.

이 두 줄은 아마도 전체 시스템에서 가장 중요한 부분일 것이며, 다이어그램과 함께 존재합니다. 즉, 사람이 읽을 수 있을 뿐만 아니라 나중에 원장(ledger) 구현을 돕는 AI도 읽을 수 있습니다.

웹사이트 위의 그림은 '내보내기(export)'해야 하는 산출물입니다. 하지만 Mermaid 파일은 코드처럼 '소유'하고, 버전 관리하며, 리뷰할 수 있는 산출물입니다.

사례 3: AI는 이미지보다 "코드로서의 다이어그램(diagram-as-code)"을 통해 더 잘 추론합니다

이 부분은 제가 과소평가했던 지점입니다.

AI에게 다이어그램 이미지를 건네주면, AI는 시각 정보 처리 (vision)를 수행해야 합니다. 레이블을 OCR(광학 문자 인식)하고, 어떤 선이 어떤 박스에 연결되는지 추측하며, 아주 작은 까마귀 발 모양 (crow's-foot) 기호로부터 카디널리티 (cardinality)를 추론해야 합니다. 이 과정은 정보 손실이 발생하고 느리며, 조용히 오류를 범하곤 합니다.

반면, AI에게 Mermaid를 건네주는 것은 **AI가 이미 네이티브하게 이해하고 있는 구조화된 텍스트 (structured text)**를 건네주는 것과 같습니다. 관계들은 모호하지 않은 토큰 (tokens)으로 표현됩니다:

erDiagram
    INSTITUTION ||--o{ BANK_ACCOUNT : "pays out to"
    INSTITUTION ||--o{ ACCOUNT : "owns (wallet)"
...

||--o{는 그 자체로

• 수정 작업이 정밀합니다 (surgical): 하나의 컬럼이 모델이 직접 편집할 수 있는 한 줄의 텍스트가 됩니다. 직접 찾아가서 다시 타이핑해야 하는 셀(cell)이 아닙니다.
• 다이어그램이 명세서(spec)가 됩니다: 다이어그램이 저장소(repo)에 존재하며, 리뷰 시 차이점(diff)을 확인할 수 있고, 스키마(schema)가 반드시 준수해야 하는 불변량(invariants)을 담게 됩니다.
• AI가 네이티브하게 추론합니다: Mermaid는 픽셀(pixels)이 아닌 구조화된 텍스트(structured text)이므로, 대화의 수준이 "이 줄이 무엇을 의미하나요?"에서 "이것이 올바른 모델인가요?"로 격상됩니다.

다이어그램은 더 이상 _내 의도를 그린 그림_이 아니라, _기계와 인간 모두 읽을 수 있는 의도의 기술(statement)_이 되었습니다. 나의 AI 페어(AI pair)가 토큰(token) 단위로 읽고, 이의를 제기하며, 함께 편집할 수 있는 형태가 된 것입니다. 저에게 있어 이것이 바로 핵심입니다.

AI 어시스턴트와 함께 도메인을 모델링하고 있다면, 먼저 Mermaid로 ER 다이어그램을 작성해 보세요. 마이그레이션(migrations) 파일 옆에 함께 커밋(commit)하세요. 모델이 그림을 설명하게 하지 말고 텍스트를 편집하게 하세요. 첫 번째 수정 작업에서 바로 그 차이를 느끼게 될 것입니다.