refactor: 분리되어 관리하고 있던 문서 시스템을 하나로 통일

CLAUDE.md

@@ -1,9 +1,18 @@
 # CLAUDE.md
 
-이 저장소는 Tech Log Studio에 올릴 기록을 쓰고 보관하는 작업 공간이다. 기록을 쓰거나 고칠 때는
-`.claude/skills/writing-tech-log-records`를 사용한다. 문장이 AI가 쓴 것처럼 읽히면
-`.claude/skills/rewriting-technical-prose-naturally`로 다시 쓴다. 다이어그램은
-`.claude/skills/technical-visualizer`로 만든다.
+이 저장소는 코드베이스를 분석해 근거를 쌓고, 거기서 Tech Log Studio에 올릴 기록을 뽑아 쓰는
+작업 공간이다. 단계마다 스킬이 있다.
+
+| 단계 | 스킬 |
+|---|---|
+| 코드베이스를 모듈 단위로 분석해 `analysis/`와 `final/`을 쌓는다 | `analyzing-codebase-for-tech-log` |
+| SSOT에서 글감을 뽑아 트리를 만든다 | `deriving-tech-log-root-tree` |
+| 글감 하나를 기록으로 쓴다 | `writing-tech-log-records` |
+| 문장이 AI가 쓴 것처럼 읽히면 다시 쓴다 | `rewriting-technical-prose-naturally` |
+| 그림을 만든다 | `technical-visualizer` |
+| 분석에서 리팩터링 작업 항목을 뽑는다 | `refactoring-from-analysis` |
+
+구조가 갖춰졌는지는 `python3 scripts/verify-pipeline.py`가 검사한다.
 
 ## 실행 순서
 
@@ -60,14 +69,19 @@ SVG로 컴파일한다. 손으로 SVG를 그리지 않는다. **그림 안에는
 ```text
 docs/<프로젝트>/
 ├── source/                 밖에서 가져온 원본. 고치지 않는다
+├── state.json              분석 상태 — 어디까지 봤나, 어느 리비전을 봤나
+├── source-index.md         분석한 코드의 목록
+├── analysis/               모듈·서브시스템 단위 분석. 큰 저장소는 여기서 누적한다
+├── root-tree.md            글감 분해 계약 (선택 — json 을 쓰면 없어도 된다)
 ├── final/                  SSOT — 이 프로젝트에 대해 아는 것 전부
 │   ├── document.md         상세한 글
 │   ├── assets/             svg, drawio, 그림
 │   ├── .techviz/           그림의 정본 (context, spec, prompt)
-│   └── evidence/           증거. 아래 셋으로만 나눈다
-│       ├── terminal/       명령을 돌려 얻은 출력 (테스트·빌드·EXPLAIN·curl·가드)
-│       ├── metrics/        잰 값 (csv)
-│       └── screens/        캡처 (Playwright MCP 스크린샷 포함)
+│   └── evidence/           증거. 원문이 정본이고 그림은 표현물이다
+│       ├── raw/            명령 출력·csv·덤프 원문 — 정본
+│       ├── meta/           그 실행의 command·cwd·executedAt·exitCode·revision
+│       ├── rendered/       raw 에서 만든 터미널 SVG (표현물)
+│       └── browser/        브라우저 캡처 (Playwright MCP)
 └── tech-log-studio/        Studio 에 올릴 글만
     ├── tech-log-tree.json  글감 목록. 항상 최신으로 둔다
     └── <주제 slug>/
@@ -77,10 +91,23 @@ docs/<프로젝트>/
 `final/` 이 정본이고 `tech-log-studio/` 는 거기서 뽑아낸 글이다. 증거는 `final/evidence/` 에만
 두고 기록에서는 그 파일을 가리킨다. 같은 파일을 양쪽에 두지 않는다.
 
-증거 폴더는 프로젝트마다 같다. `terminal/` 아래에는 하위 폴더를 자유롭게 둔다
-(`terminal/explain/`, `terminal/guards/`). 캡처와 출력에는 무엇을 담았는지 한 줄을 같은 폴더의
+증거 폴더는 프로젝트마다 같다. `raw/` 아래에는 하위 폴더를 자유롭게 둔다
+(`raw/explain/`, `raw/guards/`). 캡처와 출력에는 무엇을 담았는지 한 줄을 같은 폴더의
 `README.txt` 에 적는다 — 파일 이름만으로는 6개월 뒤에 못 읽는다.
 
+**SVG 는 정본이 아니다.** 실행한 명령의 원문과 메타데이터가 정본이고 터미널 SVG 는 문서에 넣기
+위한 표현물이다. 원문 없이 SVG 만 남기지 않는다.
+
+```bash
+python3 scripts/terminal-evidence/render_terminal.py \
+  docs/<프로젝트>/final/evidence/raw/<이름>.txt \
+  docs/<프로젝트>/final/evidence/rendered/<이름>.svg \
+  --command "./gradlew test" --cwd <경로> --exit-code 0 --executed-at <ISO-8601>
+```
+
+렌더는 Bearer·Cookie·token·password·client_secret 을 `[REDACTED]` 로 바꾼다. 그래도 **원문에
+secret 이 들어가지 않도록 명령을 짜는 것이 먼저다.**
+
 기록은 frontmatter 로 잇는다. `assets` 는 Studio 에 올릴 그림이고 `evidence` 는 인용한 측정
 자료다. Studio 에 넣을 때 `assets` 를 보고 Asset 을 올린 뒤 본문의 `:::evidence key` 를 서버가
 준 키로 바꾼다.