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

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 앵커를 그대로 쓴다.

# 기록의 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 는 라벨이 상자를 덮는 것을 못 잡는다.

python3 scripts/check-figure-text.py <프로젝트>            # <text> 가 전부 이름인가
python3 scripts/preview-figure.py <프로젝트> -o /tmp/figs  # PNG 로 떠서 눈으로 본다

4.4 KiB Raw Blame History