feat: 가상화 문서들 추가

2026-09-10 08:54:05 +09:00
parent e9f6a93327
commit 43e1aadef0
695 changed files with 153404 additions and 12754 deletions
@@ -5,12 +5,14 @@

 | 단계 | 스킬 |
 |---|---|
+| **일곱 단계를 한 줄기로 잇고 단계마다 서브에이전트를 띄운다** | **`running-tech-log-pipeline`** |
 | 코드베이스를 모듈 단위로 분석해 `analysis/`와 `final/`을 쌓는다 | `analyzing-codebase-for-tech-log` |
 | SSOT에서 글감을 뽑아 트리를 만든다 | `deriving-tech-log-root-tree` |
 | 글감 하나를 기록으로 쓴다 | `writing-tech-log-records` |
 | 문장이 AI가 쓴 것처럼 읽히면 다시 쓴다 | `rewriting-technical-prose-naturally` |
 | 맞는 말인데 아무도 쓰지 않은 보고서처럼 읽히면 | `writing-as-the-person-who-did-it` |
 | 그림을 만든다 | `technical-visualizer` |
+| Studio 에 넣고 저장한다 (Playwright MCP, 게시하지 않는다) | `publishing-tech-log-to-studio` |
 | 분석에서 리팩터링 작업 항목을 뽑는다 | `refactoring-from-analysis` |

 구조가 갖춰졌는지는 `python3 scripts/verify-pipeline.py`가 검사한다.
@@ -37,6 +39,48 @@
 Reference·Question·Decision의 칸은 평문으로 렌더링된다. 그런 자료가 필요하면 Case나 Concept에
 담고 `관계`로 가리킨다.

+## 한 줄기로 실행할 때
+
+위 실행 순서를 사람이 손으로 잇지 않고 한 번에 돌리려면 `running-tech-log-pipeline` 을 쓴다.
+일곱 단계를 정의하고 **단계마다 서브에이전트를 하나씩 띄운다.** 한 세션이 일곱 단계를 겸하면
+앞 단계의 문맥이 새어 들어 스킬을 안 읽고도 그럴듯한 결과가 나오고, 그러면 스킬이 적용됐는지
+확인할 방법이 없어진다.
+
+| # | 단계 | 스킬 |
+|---|---|---|
+| S1 | 코드베이스 → SSOT | `analyzing-codebase-for-tech-log` |
+| S2 | SSOT → 분해 계약 | `deriving-tech-log-root-tree` |
+| S3 | 글감 → 기록 | `writing-tech-log-records` |
+| S4 | 기록 → 그림 | `technical-visualizer` |
+| S5 | AI 티 제거 | `rewriting-technical-prose-naturally` |
+| S6 | 일한 사람의 목소리 | `writing-as-the-person-who-did-it` |
+| S7 | Studio 저장 | `publishing-tech-log-to-studio` |
+
+**S4 의 입력은 둘이다.** 무엇을 그릴지는 방금 쓴 기록 본문이 정하고, 그림의 사실은 그 기록의
+`source` 앵커가 가리키는 SSOT 절이 댄다. 기록 `.md` 를 `techviz prepare` 에 넣지 않는다.
+
+**S5 가 S6 보다 먼저다.** 번역투와 반복 문형을 걷어낸 뒤라야 S6 이 채울 자리가 보인다.
+그리고 S6 이 넣은 문장을 `check_prose` 가 다시 본다.
+
+**S7 은 저장까지다.** 한 번이라도 게시한 문서는 게시를 취소해도 삭제가 409 로 거절된다.
+
+한 런이 남기는 것은 산출물과 **런 원장** 둘이다. 원장은 단계마다 어떤 스킬을 실제로 열었고
+(`skillEcho` — 그 SKILL.md 의 문장을 원문 그대로 옮긴 것) 어떤 관문을 어떤 종료 코드로
+지났는지를 적는다.
+
+```bash
+python3 scripts/verify-pipeline-run.py --init runs/<프로젝트>/<runId>/run.json \
+  --project <프로젝트> --record <기록 경로>
+python3 scripts/verify-pipeline-run.py runs/<프로젝트>/<runId>/run.json
+```
+
+이 검사기는 글의 품질을 보지 않는다. **절차의 준수**를 본다 — 단계가 빠졌는지, 영수증이 그
+스킬의 실제 문장인지, 관문이 돌았고 종료 코드가 0 이었는지, 적어 낸 산출물이 디스크에 있는지.
+건너뛴 단계도 사유를 적어야 한다. **S3·S5·S6 은 건너뛸 수 없다.**
+
+원장은 `runs/<프로젝트>/<runId>/` 에 둔다. 프로젝트 폴더 안에 두지 않는다 — 거기는
+`final/` 과 `tech-log-studio/` 뿐이다.
+
 조사와 실행 검증을 묶어서 관리하는 절차는 이 저장소에 없다.

 ## 다이어그램
@@ -51,7 +95,26 @@ Reference·Question·Decision의 칸은 평문으로 렌더링된다. 그런 자

 문서를 읽어 context를 만들고, 구성 문법(profile)을 고르고, VizSpec 1.1을 쓰고, lint를 통과한 뒤
 SVG로 컴파일한다. 손으로 SVG를 그리지 않는다. **그림 안에는 이름만 넣고 문장은 `<desc>`와 옆 문단에
-둔다.**
+둔다.** 기억으로 지키지 않는다 — 컴파일한 뒤 검사기를 돌린다.
+
+```bash
+python3 scripts/check-figure-text.py <프로젝트>          # 그림 안 <text> 가 전부 이름인가
+python3 scripts/preview-figure.py <프로젝트> -o /tmp/figs # PNG 로 떠서 눈으로 본다
+```
+
+**lint 도 검사기도 라벨이 상자를 덮는 것은 못 잡는다.** 앵커 점만 보고 폭을 재지 않는다.
+컴파일한 뒤 한 번은 눈으로 본다.
+
+**기록의 `.md` 에는 `:::evidence` 를 쓰지 않는다.** 그것은 Studio 렌더러의 구문이라 편집기에서
+그림이 안 보인다. 저장소에는 마크다운 이미지로 쓰고, Studio 로 보낼 때만 바꾼다.
+
+```bash
+python3 scripts/studio-body.py <기록.md> -o /tmp/x.md   # check_body 는 바꾼 파일에 돌린다
+python3 scripts/studio-body.py <기록.md> --body-only     # Studio 에 붙여넣을 본문
+```
+
+마침표로 끝나거나, 서술어가 있거나, 조사로 두 대상을 이으면 문장이다. `<title>`과 `<desc>`는
+화면을 못 보는 사람이 듣는 자리라 검사하지 않는다.

 ## 작업 규칙

@@ -78,7 +141,7 @@ docs/<프로젝트>/
 ├── final/                  SSOT — 이 프로젝트에 대해 아는 것 전부
 │   ├── document.md         상세한 글
 │   ├── assets/             그림. 그림 하나가 폴더 하나다 — <이름>/<이름>.svg 와 편집 형식들
-│   │   └── tech-log-studio/  Studio 에 올릴 표현물. 기록의 assets: file: 이 가리키는 자리
+│   │                       기록의 assets: file: 도 여기를 가리킨다. 사본을 따로 두지 않는다
 │   ├── .techviz/           그림의 정본 (context, spec, prompt). <이름>/ 이 assets 와 짝이다
 │   └── evidence/           증거. 원문이 정본이고 그림은 표현물이다
 │       ├── raw/            명령 출력·csv·덤프 원문 — 정본
@@ -135,6 +198,15 @@ anchor·classification·missing-verification·relations 를 사람이 적고,
 | `analysis/**/*.md` | final 이 이미 채택한 주장을 상세히 확인하는 보조 근거. 분석 중에만 있다 |
 | `tech-log-tree.json` | 사람이 고른 글감. 분해 계약이자 색인이고 이 파일이 정본이다 |

+**검사기가 뒤늦게 보게 된 것 넷.** 오래 안 보이던 자리라 기존 프로젝트에서 결함이 나온다.
+
+| 무엇 | 왜 안 보였나 |
+|---|---|
+| 앵커가 실재하는 절을 가리키나 | SSOT 경로를 포함하는지만 봤다. 절 제목을 슬러그로 쓰는 프로젝트에서만 대조한다 |
+| 계약과 기록의 `source` 가 같은가 | `build` 가 이 칸을 다시 채우지 않아 갈린 채로 남았다. SSOT 를 가리키는 것끼리만 견준다 |
+| 범위 안인데 아무 후보도 안 짚은 절 | 「후보 ↔ 글감」만 보고 「SSOT ↔ 후보」는 안 봤다 |
+| 그림의 근거가 SSOT 인가 | `techviz prepare` 는 기록 `.md` 도, 저장소 밖 문서도 받아 준다 |
+
 `analysis/**` 를 글감을 찾으려고 열지 않는다. 분석에만 있는 자료를 발견하면 트리에 바로 넣지 말고
 `final/document.md` 를 먼저 보강한다. 그러지 않으면 모듈 문서마다 정본 노릇을 하고 트리는 그 절
 수의 합만큼 자란다.
@@ -172,6 +244,11 @@ error 다. 경고로 두면 재판정하지 않은 트리로 글을 쓰기 시
 (`raw/explain/`, `raw/guards/`). 캡처와 출력에는 무엇을 담았는지 한 줄을 같은 폴더의
 `README.txt` 에 적는다 — 파일 이름만으로는 6개월 뒤에 못 읽는다.

+**그림은 한 곳에만 산다.** 기록이 가리키는 SVG 도 `final/assets/<이름>/<이름>.svg` 다. Studio 에
+올릴 사본을 `assets/tech-log-studio/` 에 따로 두면 정본이 둘이 되고, 사본 쪽에는 `.techviz/<이름>/`
+이 없어 다시 만들 수 없다. `verify-project-layout.py` 의 「기록이 가리키는 그림에 techviz 정본이
+없다」가 그 상태를 센다.
+
 **SVG 는 정본이 아니다.** 실행한 명령의 원문과 메타데이터가 정본이고 터미널 SVG 는 문서에 넣기
 위한 표현물이다. 원문 없이 SVG 만 남기지 않는다. 그림도 같다 — `.techviz/<이름>/` 없이 남은
 SVG 는 다시 만들 수 없고, `verify-project-layout.py` 가 그런 그림을 센다.
@@ -193,7 +270,7 @@ secret 이 들어가지 않도록 명령을 짜는 것이 먼저다.**
 ```yaml
 assets:
  - key: eager-lazy-query-sequence
-    file: ../../../final/assets/tech-log-studio/eager-lazy-query-sequence.svg
+    file: ../../../final/assets/diagrams/eager-lazy-query-sequence/eager-lazy-query-sequence.svg
 evidence:
  - ../../../final/evidence/explain/highlights-child-plan-A.txt
 ```
@@ -254,8 +331,10 @@ Redis 20편은 한 글을 나눠 쓴 것이라 `docs/clean-architecture-backend-
 프로젝트 트리 정합성은 이 검사기가 본다(`--skip-projects` 로 끌 수 있다).

 ```bash
+python3 scripts/verify-pipeline-run.py runs/<프로젝트>/<runId>/run.json  # 런이 절차를 지켰나
+                                                     # verify-pipeline.py 도 runs/ 를 전부 훑는다
 python3 scripts/verify-tech-log-tree.py <프로젝트>   # 글감 계약. error 0 까지 고친다
-python3 scripts/verify-project-layout.py <프로젝트>  # 폴더 배치. 그림의 정본이 있는지도 본다
+python3 scripts/verify-project-layout.py <프로젝트>  # 폴더 배치. 그림의 정본·근거·겹침도 본다
 python3 scripts/fold-analysis-into-final.py <프로젝트>        # 분석 재료 → final/document.md
 python3 scripts/fold-studio-contract-into-index.py <프로젝트>  # 분해 재료 → tech-log-tree.json
 python3 scripts/build-tech-log-tree.py <프로젝트>    # 파생 칸(file·publication·status)만 다시 채운다
@@ -266,10 +345,12 @@ python3 -m unittest discover -s scripts/tests        # 파서·검사기·생성
 게시 전에는 아래 둘을 돌린다. 하나는 파서를, 하나는 문장을 본다.

 **본문이 Studio 파서를 통과하는지.** Studio가 쓰는 파서를 그대로 부르므로 통과하면 저장도 통과한다.
+저장소의 그림은 마크다운 이미지라 **Studio 형태로 바꾼 파일**에 돌린다.

 ```bash
+python3 scripts/studio-body.py 초안.md -o /tmp/studio-body.md
 node --experimental-transform-types \
-  .agents/skills/writing-tech-log-records/scripts/check_body.mjs 초안.md
+  .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/studio-body.md
 ```

 **인용한 것이 실재하는지.** 본문 코드블록의 각 줄이 SSOT 안에 있는지, `source` 앵커가 SSOT 를
@@ -285,6 +366,21 @@ node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로
 **문장이 규범을 지키는지.** `error` 가 남아 있으면 덜 된 글이다. 칸 하나나 한 절만 고쳤으면
 `--doc` 을 빼고 부른다.

+**그림 안이 이름뿐인지, 그리고 상자와 라벨이 서로를 덮지 않는지.** 그림을 만들거나 고쳤으면
+둘 다 돌린다.
+
+```bash
+python3 scripts/check-figure-text.py <프로젝트>       # <text> 가 전부 이름인가
+python3 scripts/check-figure-overlap.py <프로젝트>    # 상자와 라벨이 겹치지 않는가
+```
+
+**lint 는 좌표를 안 본다.** 관계가 이어져 있는지만 본다. 그래서 구역 둘이 겹쳐 그려지거나
+라벨이 상자에 먹혀도 통과한다. 겹침 검사는 렌더러가 남긴 배경 사각형의 좌표를 그대로 읽으므로
+글자 폭을 어림하지 않는다. `verify-project-layout.py` 가 이 검사를 함께 돈다.
+
+**그래도 마지막에는 눈으로 본다.** 글자가 상자 밖으로 조금 나가거나 화살표가 라벨을 지나는
+것은 좌표로 안 잡힌다.
+
 ```bash
 S=.agents/skills/rewriting-technical-prose-naturally/scripts
 node $S/check_prose.mjs --warn 초안.md      # error 0 까지 고친다