init: company-haness 설계

2026-07-23 17:49:00 +09:00
parent 57d1bab894
commit f668d6a158
962 changed files with 98989 additions and 1 deletions
@@ -0,0 +1,83 @@
+---
+name: diagram-craft
+description: Use when producing ANY technical diagram (software architecture, dependency graphs, flows, C4, sequence) — picks the abstraction level and audience FIRST, then renders with D2 (professional diagram-as-code) as primary engine and Excalidraw for explanatory sketches. Mermaid is a last-resort fallback only; it is not a professional-grade visual.
+---
+
+# Diagram Craft — 실무급 다이어그램 산출 표준
+
+## 불변식
+
+1. **Abstraction-first.** 그리기 도구보다 *추상화 계층·독자·전달 메시지*를 먼저 정한다. 도구 선택은 마지막.
+2. **One diagram, one message.** 한 그림은 한 독자에게 한 메시지만. 넘치면 쪼갠다.
+3. **엔진 우선순위: D2 → Excalidraw → Mermaid(폴백).** Mermaid로 보여주는 건 실무급 시각자료가 아니다 — 자제하라.
+
+## 1단계 — 추상화 계층 정하기 (C4)
+
+| 레벨 | 무엇 | 언제 |
+|---|---|---|
+| L1 System Context | 시스템 + 외부 관계(사용자·외부시스템) | 스코프 정렬, 비개발자 포함 |
+| **L2 Container** | 배포 단위 + 기술 스택 | **가장 범용** — 기본값 |
+| L3 Component | 컨테이너 내부 구조 | 정말 복잡할 때만 |
+| L4 Code | 클래스/함수 | 손유지 금지 — 소스에서 자동생성(즉시 stale) |
+
+독자를 먼저 적어라. "이 그림은 누가, 무엇을 알기 위해 보나?" 답이 없으면 그리지 마라.
+
+## 2단계 — 엔진 선택
+
+```
+소프트웨어 아키텍처 · 의존성 · 중첩 컨테이너 · 시퀀스   → D2        (1급)
+설명용 · 워크숍 발산 · 손그림 느낌 · 개념 스케치          → Excalidraw (보조)
+정말 어쩔 수 없을 때(경량·플랫폼 네이티브가 유일 제약)    → Mermaid    (폴백)
+```
+
+**왜 D2인가:** 중첩 컨테이너(계층/경계 표현), 레이아웃 엔진 교체(dagre 기본 / elk 대형그래프 / tala 복잡), 테마, sketch 모드, SVG/PNG CLI(CI 친화) — Mermaid가 못 하는 것들.
+
+## 3단계 — D2 관용구 (실물 산출)
+
+```d2
+direction: right                # 방향 고정 (right/down)
+vars: { d2-config: { layout-engine: elk } }   # 큰 그래프는 elk
+
+domain: 도메인 계층 {           # 중첩 컨테이너로 계층/경계를 표현
+  entity: Entity
+  vo: Value Object
+}
+app: 애플리케이션 계층 {
+  usecase: UseCase
+}
+infra: 인프라 계층 {
+  repo: JPA Repository
+}
+
+app.usecase -> domain.entity: 사용         # 엣지에 라벨(의미)
+infra.repo -> app.usecase: 구현(의존역전) { style.stroke-dash: 3 }
+```
+
+렌더:
+- 렌더러 경유(권장): storyline exhibit에 `{type: d2, code: "...", layout: elk}` → `render_consult.py`가 d2 CLI로 실물 SVG.
+- 직접: `d2 --theme 0 --pad 16 [--layout elk] [--sketch] in.d2 out.svg` (바이너리: `~/.local/bin/d2`).
+
+D2 옵션: `--theme 0`(Neutral), `--layout elk`(대형), `--sketch`(손그림 느낌), 컨테이너는 `name { ... }`, 방향은 `direction:`.
+
+## 4단계 — notation 규율
+
+- 그림마다 **스코프 한 줄 제목** + **범례** + **일관된 방향** + **예약색**(색은 의미 전용, 장식 금지).
+- shape/arrow에 의미를 고정하라(예: 실선=동기 호출, 점선=의존역전/비동기). 범례에 명시.
+
+## Anti-cheap-diagram self-check
+
+- [ ] 독자와 한 메시지를 한 문장으로 쓸 수 있나?
+- [ ] C4 레벨을 의식적으로 골랐나(기본 L2)?
+- [ ] Mermaid로 도망치지 않았나? 아키텍처/의존성이면 D2여야 한다.
+- [ ] 범례·방향·예약색이 있나?
+- [ ] 요소가 넘치나? → 두 그림으로 쪼개라.
+
+## Excalidraw (보조 — 설명·발산)
+
+`.excalidraw` JSON으로 산출(VS Code Excalidraw 확장·excalidraw.com에서 편집). 그리드 정렬(50–100px 배수)·roughness로 손그림 강도 조절. 확정·유지 대상은 D2로, 손그림은 발산·워크숍에만.
+
+## 근거 (E3)
+- D2 vs Mermaid(컨테이너·레이아웃엔진·테마): https://diagram-converter.orriguii.com/blog/d2-diagram-language-guide
+- D2 공식: https://d2lang.com/
+- C4 model: https://c4model.com/
+- Excalidraw 아키텍처 다이어그램: https://plus.excalidraw.com/use-cases/software-architecture-diagram