Domain Canvas Skill: 화면·업무 개념·ER 다이어그램을 하나의 모델로 연결하기

갱신의 출발점을 하나로 만들기

Domain Canvas Skill은 작업 지침과 Python 생성 스크립트를 묶은 것입니다. 프로젝트 코드와 명세를 조사하고 화면·업무 객체·데이터 구조를 model.json에 정리한 뒤 열람용 HTML을 생성합니다. 독립된 호스팅 서비스가 아니라 프로젝트 안에 설치하는 Claude Code 스킬로 배포됩니다.

핵심은 세 다이어그램을 따로 관리하지 않고 같은 모델을 사용하는 것입니다. model.json을 수정하고 HTML을 다시 생성하면 각 보기가 갱신된 데이터를 읽습니다. 화면의 대응 관계는 bindings, 업무·데이터 관계는 relationships에 기록하므로 서로 관련된 항목의 일관성은 확인해야 합니다.

README: 개요와 배포

같은 대상을 세 가지 질문으로 읽기

도메인은 고객·신청·계약처럼 업무에서 의미를 갖는 대상과 규칙입니다. 개체 관계(ER) 다이어그램은 데이터의 속성과 관계를 표현합니다. 보기를 전환하면 같은 대상을 검토하는 상세 수준이 달라집니다.

Design은 완성된 UI를 자동 설계하지 않습니다. 화면 이미지나 로컬 HTML 프로토타입을 참조할 수 있으며 없으면 임시 미리보기를 표시합니다. Concept은 설명과 관계를, ER은 속성과 키 표시를 보여 줍니다. 현재 ER 보기는 업무 의미만 나타내는 kind: domain 관계선을 제외합니다.

생성 코드: 표시와 검증

부동산 CRM 예제 따라가기

동봉 모델은 고객·매물·신청·계약·서류의 다섯 객체, 세 상세 화면, 다섯 관계를 담습니다. 계약 상세는 계약을 주 대상, 고객과 매물을 맥락 정보, 서류를 관련 목록으로 연결합니다. 하나의 화면이 역할에 따라 여러 객체와 연결될 수 있습니다.

계약 상세에 미제출 서류를 표시하려 한다고 가정해 봅시다. Design에서 서류와의 연결을 확인하고, Concept에서 계약과 서류의 의미를 읽고, ER에서 document.contract_id 같은 속성을 살펴볼 수 있습니다. 이는 활용을 설명하기 위한 예이며 데모가 미제출 서류를 판정하는 것은 아닙니다.

데모 상단의 Design / Concept / ER로 보기를 바꿉니다. 드래그로 이동하고 휠 또는 +/−로 확대·축소하며 Fit으로 전체 보기에 돌아갑니다. 예제의 화면 미리보기는 실제 CRM 화면 캡처가 아닌 임시 표시입니다.

부동산 CRM 예제 모델

확인된 관계와 추론 구분하기

AI가 시스템을 정리할 때는 그럴듯한 선보다 선을 그은 근거가 중요합니다. 스킬은 주장별로 적절한 자료를 사용하도록 지시합니다. 테이블·외래 키에는 스키마·마이그레이션·ORM, 업무 의미에는 명세, 화면에는 라우트와 컴포넌트를 확인합니다.

관계의 confidence는 confirmed(확인됨)와 inferred(추론됨)를 구분합니다. Concept과 ER에서는 추론된 관계를 점선으로 표시합니다. 화면에서 함께 보인다는 이유만으로 데이터베이스 관계를 확정하지 말라는 규칙도 있습니다.

다만 confirmed는 모델에 기록된 판단입니다. 생성기가 근거 내용을 읽어 정확성을 증명하지는 않습니다. 출처와 미해결 가정은 결과물에 첨부하는 README에 남깁니다.

추출과 근거 규칙

설치하고 작은 범위부터 갱신하기

공개 데모는 설치 없이 볼 수 있습니다. 자신의 프로젝트에서는 저장소의 .claude/skills/domain-canvas/를 대상 프로젝트의 같은 위치로 복사한 후 Claude Code에서 호출합니다.

/domain-canvas contracts

contracts는 대상 범위의 예입니다. 계약 관련 화면·개념 모델·ER 다이어그램을 한 캔버스로 정리해 달라고 자연어로 요청할 수도 있습니다. 하나의 기능부터 시작하면 원본 자료와 비교하기 쉽습니다.

.domain-canvas/model.json

모델의 기준 파일. 변경은 여기에 반영합니다.

.domain-canvas/index.html

열람용으로 생성된 캔버스입니다.

.domain-canvas/README.md

출처, 미해결 가정, 갱신 명령을 기록합니다.

python .claude/skills/domain-canvas/scripts/generate_canvas.py \
  --model .domain-canvas/model.json \
  --out .domain-canvas/index.html

생성기는 Python 3만 필요하며 외부 Python 패키지에 의존하지 않습니다. 명령을 실행한 뒤 HTML을 브라우저에서 엽니다. 동봉 예제를 시험하려면 입력을 example/model.json, 출력을 example/index.html로 바꿉니다.

지속적으로 사용하려면 코드·명세 변경 시 모델 반영, 재생성, 검토를 함께 진행합니다. 생성된 HTML을 직접 수정하면 재생성 때 사라지므로 모델을 수정합니다. HTML에는 모델이 포함되므로 공유 전에 내부 구조와 참조 화면 자료를 전달해도 되는 상대인지 확인합니다.

스킬 정의: 프로젝트 작업 절차

다이어그램의 일치와 업무 정확성은 별도로 확인하기

현재 생성기는 필수 루트 항목, 객체·화면 ID 중복, 관계의 연결 대상, 화면 참조 등을 검사합니다. 데이터베이스의 모든 제약이나 업무 규칙과의 일치까지 자동 검증하지는 않습니다.

실제로 예제의 document.contract_id는 nullable: true지만 계약–서류 관계의 계약 쪽 다중도는 1입니다. 서류가 계약 없이도 존재할 수 있는지, 아니면 이미 계약에 연결된 서류만 표현하는지 확인해야 해석을 확정할 수 있습니다. 생성 성공은 이런 의미의 일관성까지 보장하지 않습니다.

HTML 뷰어는 모델을 직접 편집·저장하거나 코드·데이터베이스에 변경을 되쓰거나 변경을 상시 감시하지 않습니다. 개념 모델에서 기술적인 연결 테이블을 생략하는 일도 모델링 판단이 필요합니다. 현재 Concept과 ER은 같은 객체 목록을 사용합니다.

이 스킬의 실용적 가치는 이해의 차이를 검토할 수 있게 하는 데 있습니다. 기능 하나를 골라 근거가 있는 모델을 만들고 업무 담당자·개발자와 미확정 관계를 확인하세요. 이런 작은 유지관리 과정을 지속할 수 있다면 화면과 데이터의 연결을 인수인계하는 공통 자료가 됩니다.

생성 코드: 표시와 검증

출처와 검증 범위

README, 스킬 정의, 추출 규칙, 예제 모델, 생성 코드를 확인했습니다. 동봉 예제로 Python 생성기를 실행하여 객체 5개·화면 3개·관계 5개가 포함된 HTML 출력을 확인했습니다. 실제 프로젝트의 추출 정확도나 재작업 감소 효과는 측정하지 않았습니다. 소스 링크는 확인한 커밋으로 고정했으며 공개 데모는 이후 변경될 수 있습니다.

• README: 개요와 배포
• 생성 코드: 표시와 검증
• 부동산 CRM 예제 모델
• 추출과 근거 규칙
• 스킬 정의: 프로젝트 작업 절차

GitHub commit: 914d68fe3f12