feat: 가상화 문서들 추가

2026-09-10 08:54:05 +09:00
parent e9f6a93327
commit 43e1aadef0
695 changed files with 153404 additions and 12754 deletions
@@ -0,0 +1,82 @@
+# 기록에 어떤 그림이 필요한지 정하는 기준
+
+`code-tables-diagrams.md` 는 그림을 **어떻게** 그리는지를 말한다. 이 문서는 그 앞 단계 —
+**이 기록에 그림이 필요한가, 필요하다면 무엇을 그리는가** 를 정한다.
+
+## 세 관문
+
+순서대로 통과해야 그림을 만든다. 하나라도 걸리면 그리지 않는다.
+
+### 1. 자리가 있는가
+
+`assets` 는 본문이 있는 두 종류만 갖는다 — **Case 와 Concept**. Reference·Question·Decision 의
+칸은 평문으로 렌더링돼 그림이 들어갈 자리가 없다.
+
+파생 기록에 그림이 필요해 보이면 그 그림은 **짝이 되는 Case 나 Concept 의 것**이다. 거기 담고
+`관계`로 가리킨다. 담을 Case 나 Concept 이 없으면 그 그림은 아직 집이 없다 — 계약의
+`assetLedger.unassigned` 에 그렇게 적고, 새 글감을 세울지는 따로 판단한다.
+
+### 2. 표가 아닌가
+
+> **관계선을 다 지워도 뜻이 남는가.** 남으면 표다.
+
+표는 값을 비교하고, 그림은 **포함·순서·경계**처럼 자리로만 보이는 것을 맡는다. 항목을 같은
+속성으로 늘어놓은 것은 마크다운 표로 쓴다. `verify-project-layout.py` 의 「표로 되는 그림」이
+관계선 없이 항목마다 같은 수의 `details` 를 늘어놓은 spec 을 센다.
+
+### 3. 옆 문단이 이미 말하지 않았는가
+
+> **이 그림이 없으면 독자가 무엇을 못 보나.** 한 문장으로 답할 수 없으면 그리지 않는다.
+
+기록에 이미 그 비교표가 있으면 그림은 중복이다. 실제로 그렇게 만든 그림 셋을 지웠다 —
+`keyset-vs-offset` 을 넣은 기록에는 훑은 행·buffers·exec 까지 있는 플랜 비교표가 이미 있었다.
+
+## 종류마다 무엇을 그리나
+
+세 관문을 통과했을 때, 그 기록이 요구하는 그림은 종류마다 다르다.
+
+| 종류 | 그림이 답하는 물음 | 흔한 profile |
+|---|---|---|
+| **Case** | 이 요청 한 번이 어떤 순서로 무엇을 지나갔나 | `sequence` · `component-flow` |
+| **Case** (경계가 논지일 때) | 무엇이 어느 경계 안에 있고 무엇이 밖에 있나 | `two-zone-pipeline` |
+| **Concept** | 남의 것이 어떤 순서·구조로 동작하나 | `sequence` · `component-flow` · `ports-adapters` |
+
+Case 는 **내가 돌려서 본 것**이라 대개 순서가 논지다. Concept 은 **남의 것이 어떻게 동작하는지**라
+구조나 변환 사슬이 논지다. 어느 쪽이든 「무엇이 무엇으로 바뀌는가」를 못 적으면 아직 그릴 것이
+없다는 뜻이다.
+
+**한 절에 그림 하나.** 같은 절에 구조 그림과 흐름 그림을 둘 다 넣으면 독자가 어느 쪽을 먼저
+읽어야 하는지 알 수 없다. 둘 다 필요하면 절을 나눈다.
+
+## 어디를 근거로 삼나 — 기록의 `source` 가 앵커다
+
+`techviz prepare` 는 `final/document.md` 를 받는다. 기록은 `tech-log-studio/` 에 있지만 **그림의
+근거는 기록이 아니라 기록이 가리키는 SSOT 절**이다. 기록의 `source` 앵커를 그대로 쓴다.
+
+```bash
+# 기록의 source: final/document.md#선택의-이유와-지킨-경계-ap1  이면
+./scripts/techviz prepare docs/<프로젝트>/final/document.md \
+  --heading "AP1: OAuth와 JWT 계약을 가장 가까이서 관찰한다" \
+  -o docs/<프로젝트>/final/.techviz/<id>/context.json
+```
+
+`--line` 은 쓰지 않는다. context 는 관리 블록을 접은 좌표를 쓰므로 파일의 줄 번호와 어긋난다.
+`--heading` 이나 `--marker` 로 절을 지목한다.
+
+**그림이 주장하는 것을 기록 본문이 말해야 한다.** SSOT 에 근거가 있어도 기록이 그 단계를 적지
+않았으면 그림만 넣지 않는다 — 설명 없는 주장이 남는다. 순서는 하나다.
+
+> 본문을 먼저 보강한다 → 그다음 그림을 붙인다.
+
+`ap1-browser-bearer-flow` 가 그랬다. 마지막 단계인 `/api/me` 응답 4필드를 기록이 말하지 않아
+붙이지 못하고 있다가, SSOT §474 를 근거로 본문에 한 줄을 더한 뒤에 붙였다.
+
+## 만든 뒤
+
+`code-tables-diagrams.md` 의 규범과 아래 둘을 함께 돌린다. lint 는 라벨이 상자를 덮는 것을
+못 잡는다.
+
+```bash
+python3 scripts/check-figure-text.py <프로젝트>            # <text> 가 전부 이름인가
+python3 scripts/preview-figure.py <프로젝트> -o /tmp/figs  # PNG 로 떠서 눈으로 본다
+```