7.2 KiB
디자인·다이어그램 직무 전문가급 업그레이드 — 설계
- 날짜: 2026-07-08
- 상태: 구현 완료(2026-07-08) — 115/115 enforcement 통과, D2 실물 렌더 검증, 60 에이전트 재생성
- 미결(사용자 결정): (a) DES-*/ENG-FE에 Figma MCP 물리는 후속 gated 연동, (b) hook 활성화(settings.json)
- 관련: consulting-layer-design, harness-efficiency-audit
배경 / 문제
사용자 지적: 다이어그램·디자인 직무 산출물이 낮게 나온다. Mermaid는 실무급 그림이 아니다.
근본 원인 (웹조사로 확인): 현재 디자인 직무의 working-method는 프레임워크·프로세스 서술(Double Diamond, Atomic Design, C4, "one diagram one message")이다. 이는 디자이너가 아는 것이지, 특정 산출물을 전문가급으로 만드는 제약(constraint)·판단로직·레퍼런스가 아니다. LLM은 이 "추론층"이 비어 있으면 그럴듯하지만 generic한 값으로 채운다(fabricates the reasoning layer). → 평균적·일반적 산출.
웹조사 근거 (E3)
- DESIGN.md 패턴 — "제약 > 묘사": 작동하는 디자인 파일은 값이 아니라 허용/금지/판단을 준다. 토큰 = 값+의도+경계. "잘 고른 8개 규칙이 토큰 2배보다 낫다." 제품 브리프가 항상 먼저.
- 레퍼런스 구동 ≠ 형용사 구동: "modern/clean/minimal" → 인터넷 평균 = generic. 독창성은 구체 레퍼런스(≈6개 집중)+구체 제약에서. 미학 이전에 문제/결정 언어화.
- 다이어그램: D2 / Excalidraw > Mermaid: D2 = 중첩 컨테이너·레이아웃엔진(dagre/ELK/TALA)·테마·sketch, SVG/PNG CLI, CI 친화. Excalidraw = 손그림·설명용(.excalidraw JSON, auto-layout·roughness). Mermaid는 경량 폴백.
결정 (사용자 승인됨)
- 메커니즘: 3층 모두 — design-brief 아티팩트 + 공유 SKILL.md + working-method 재작성
- 범위: DOC-VISUAL + DES-PROD + DES-PLATFORM + DES-INTERNAL
- 엔진: D2 기본 + Excalidraw 보조, Mermaid 최후 폴백
설계
① design-brief 계약 (DESIGN.md 내재화)
디자인/비주얼 엔게이지먼트가 산출·소비하는 아티팩트. org-os/06-agent-work/design-brief-spec.yaml에 스키마 정의. 앵커 순서(연구 근거):
- brief (필수·최상단): 무엇을 만드나 / 누가 쓰나 / 이 산출물이 반드시 달성해야 하는 것 (2–3문장)
- references (구체 3–6): 각 레퍼런스 + 그것이 나르는 구체 신호(형용사 금지). 예: "Linear — 13px base·4px grid·단일 accent". anti-generic 앵커.
- tokens (값+의도+경계): 각 토큰에
value / intent / boundary(Don't). 다이어그램은 notation 토큰(shape=계층, arrow=의존방향, color 예약). - decisions (판단로직): 언제 A vs B (card vs list / D2 container vs 분리 다이어그램 / one-message split 규칙).
- donts (명시적 8±): anti-pattern 가드레일.
context-package-spec.yaml에 design-mode 확장으로 참조 연결(worker는 design-brief 없이 시작 금지 — 기존 "context-package 없이 시작 금지" 규칙의 디자인판).
② working-method 재작성 (4 직무)
role-working-methods.yaml의 DES-PROD/DES-PLATFORM/DES-INTERNAL/DOC-VISUAL을 프레임워크 나열 → 제약+판단+레퍼런스 운영절차로. 각 직무 공통 추가:
- 제품 브리프 + 레퍼런스 클러스터에서 출발("modern/clean/minimal" 금지, 구체 레퍼런스+신호 명명)
- 토큰은 값+의도+경계, 컴포넌트는 판단로직, 명시적 Don'ts — 추론층을 비워 두지 않는다
- DOC-VISUAL: 도구 우선순위 재배치 → D2(아키텍처·의존성·중첩) / Excalidraw(설명·손그림) 우선, Mermaid 최후 폴백; abstraction-first(도구보다 C4 레벨·독자·메시지 먼저)
프레임워크 grounding(Double Diamond 등)은 유지 — 제거가 아니라 제약·레퍼런스 층을 덧댐.
③ 공유 skill (SKILL.md 2종)
.claude/skills/design-craft/SKILL.md, .claude/skills/diagram-craft/SKILL.md:
- design-craft: 제품브리프-우선 / 레퍼런스구동(6집중·신호명명) / 제약>묘사 / 토큰=값+의도+경계 / 판단로직 / Don'ts / anti-generic self-check("'modern/clean'으로 설명되면 generic — 명명된 레퍼런스에 앵커").
- diagram-craft: abstraction-first(C4레벨→독자→one message) / 엔진선택 매트릭스(D2=아키·의존·중첩, Excalidraw=설명·손그림, Mermaid=폴백) / D2 관용구(container·레이아웃엔진 ELK/TALA·theme·direction) / notation 규율(범례·방향·예약색) / 렌더(d2 CLI→SVG).
gen_agents.py가 이 craft 핵심(체크리스트)을 해당 디자인/비주얼 에이전트 본문에 embed(서브에이전트가 skill auto-load 없이도 craft 보유) + standalone SKILL.md로 세션 invoke 가능. → "둘 다".
④ 렌더러/툴링 (D2 실물 산출)
- D2 설치: static binary →
~/.local/bin(무루트, 이 환경 쓰기 가능 확인). 렌더 검증(SVG 생성). render_consult.py:{type: d2, code}exhibit 추가 → 실제 D2 SVG(1급). mermaid는 유지하되 폴백으로 강등(권고에서 후순위).RENDER_CONSULT_NO_D2폴백 env(테스트 고속화, mermaid 폴백 env와 동형)./consult커맨드 + gen_agents lead storyline exhibit 규칙: 소프트웨어 구조·흐름은 D2 우선(mermaid 아님).
강제기 / 검증 영향
- 기존 불변식 유지(report immutability, evidence, 권한). 신규 파일은 git 미관리(사용자 지시).
gen_agents.py재실행 → 60 에이전트(카운트 불변). 디자인/비주얼 에이전트 본문에 craft 체크리스트 반영.test_enforcement.py: design-brief-spec 존재, 2 SKILL.md 존재, D2 exhibit 렌더 경로(NO_D2 폴백), working-method 재작성(레퍼런스/Don'ts 키워드), DOC-VISUAL 도구우선순위(D2 우선·Mermaid 폴백) 테스트 추가.- org-os 정합성(73/28/12) 불변.
비목표 (YAGNI)
- Figma MCP 연동·실제 UI 코드 생성은 범위 밖(디자인 직무의 산출 방식 표준까지).
- Excalidraw PNG 자동 export(Playwright)는 2차 — 우선 D2 실물 렌더로 "실무급 그림" 갭을 닫고, Excalidraw는
.excalidraw산출+수동 검토로 시작. - 나머지 디자인 무관 직무의 working-method는 손대지 않음.
검증 방법
- D2 설치 후 샘플 렌더 → 유효 SVG 확인.
render_consult.py로{type: d2}포함 덱 렌더 → D2 SVG가 exhibit로 박히는지.test_enforcement.py전체 통과.- gen_agents 재생성 후 디자인/비주얼 에이전트 본문에 craft·D2우선 반영 확인.
- (선택) 실제 라이브: ca-tmpl 문서 다이어그램 1개를 Mermaid→D2로 재산출해 품질 대비.