# 기록에 어떤 그림이 필요한지 정하는 기준

`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 로 떠서 눈으로 본다
```