# 디자인·다이어그램 직무 전문가급 업그레이드 — 설계

- 날짜: 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](2026-07-08-consulting-layer-design.md), [harness-efficiency-audit](../harness-efficiency-audit-2026-07-07.md)

## 배경 / 문제

사용자 지적: 다이어그램·디자인 직무 산출물이 낮게 나온다. Mermaid는 실무급 그림이 아니다.

**근본 원인 (웹조사로 확인):** 현재 디자인 직무의 `working-method`는 *프레임워크·프로세스 서술*(Double Diamond, Atomic Design, C4, "one diagram one message")이다. 이는 디자이너가 *아는 것*이지, 특정 산출물을 전문가급으로 만드는 *제약(constraint)·판단로직·레퍼런스*가 아니다. LLM은 이 "추론층"이 비어 있으면 **그럴듯하지만 generic한 값으로 채운다**(fabricates the reasoning layer). → 평균적·일반적 산출.

## 웹조사 근거 (E3)

1. **DESIGN.md 패턴 — "제약 > 묘사"**: 작동하는 디자인 파일은 값이 아니라 *허용/금지/판단*을 준다. 토큰 = 값+의도+경계. "잘 고른 8개 규칙이 토큰 2배보다 낫다." 제품 브리프가 항상 먼저.
   - https://processtopixels.substack.com/p/writing-a-designmd-file-claude-can
   - https://github.com/VoltAgent/awesome-design-md
2. **레퍼런스 구동 ≠ 형용사 구동**: "modern/clean/minimal" → 인터넷 평균 = generic. 독창성은 구체 레퍼런스(≈6개 집중)+구체 제약에서. 미학 이전에 문제/결정 언어화.
   - https://www.nngroup.com/articles/vague-prototyping/
   - https://stensyl.ai/blog/reference-images-ai-style-consistency
3. **다이어그램: D2 / Excalidraw > Mermaid**: D2 = 중첩 컨테이너·레이아웃엔진(dagre/ELK/TALA)·테마·sketch, SVG/PNG CLI, CI 친화. Excalidraw = 손그림·설명용(.excalidraw JSON, auto-layout·roughness). Mermaid는 경량 폴백.
   - https://diagram-converter.orriguii.com/blog/d2-diagram-language-guide
   - https://skillsmp.com/creators/robtaylor/excalidraw-diagrams/skill

## 결정 (사용자 승인됨)

- 메커니즘: **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`에 스키마 정의. 앵커 순서(연구 근거):

1. **brief** (필수·최상단): 무엇을 만드나 / 누가 쓰나 / 이 산출물이 반드시 달성해야 하는 것 (2–3문장)
2. **references** (구체 3–6): 각 레퍼런스 + *그것이 나르는 구체 신호*(형용사 금지). 예: "Linear — 13px base·4px grid·단일 accent". anti-generic 앵커.
3. **tokens** (값+의도+경계): 각 토큰에 `value / intent / boundary(Don't)`. 다이어그램은 notation 토큰(shape=계층, arrow=의존방향, color 예약).
4. **decisions** (판단로직): 언제 A vs B (card vs list / D2 container vs 분리 다이어그램 / one-message split 규칙).
5. **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는 손대지 않음.

## 검증 방법

1. D2 설치 후 샘플 렌더 → 유효 SVG 확인.
2. `render_consult.py`로 `{type: d2}` 포함 덱 렌더 → D2 SVG가 exhibit로 박히는지.
3. `test_enforcement.py` 전체 통과.
4. gen_agents 재생성 후 디자인/비주얼 에이전트 본문에 craft·D2우선 반영 확인.
5. (선택) 실제 라이브: ca-tmpl 문서 다이어그램 1개를 Mermaid→D2로 재산출해 품질 대비.