feat: 문서 구조 변경 및 tech-visual 스킬 추가

README.md

@@ -1,67 +1,124 @@
-# 한국어 기술 블로그 작업 공간
+# Tech Log 기록 작업 공간
 
-이 저장소는 한국어 기술 블로그를 쓰고 보관하는 곳입니다. 글쓰기 능력은 `.agents/skills/`의
-Agent Skill 세 개가 담당하고, 완성된 글과 근거 자료는 `.run/` 아래에 런 단위로 보관합니다.
+이 저장소는 [Tech Log Studio](https://hyeonworks.com/studio)에 올릴 기록을 쓰고 보관하는
+곳입니다. 작성 능력은 `.agents/skills/`의 Agent Skill이 담당하고, 완성된 글과 근거 자료는
+`docs/` 아래에 프로젝트별로 보관합니다.
 
 ## 스킬
 
-| 스킬 | 역할 |
+| 스킬 | 언제 |
 |---|---|
-| `writing-korean-technical-blogs` | 자료를 문제·제약·선택·구현·결과·한계 구조로 작성하거나 재구성합니다 |
-| `reducing-ai-like-korean-writing` | 상투성, 추상화, 반복, 과잉 구조화를 줄이되 사실과 기술 의미는 보존합니다 |
-| `editing-korean-grammar-and-expression` | 맞춤법, 띄어쓰기, 문법, 호응을 보수적으로 검수합니다 |
+| `writing-tech-log-records` | Studio에 올릴 기록 한 건을 쓰거나 고칠 때. 종류 선택, 칸 채우기, 본문 작성, 게시 전 대조 |
+| `rewriting-technical-prose-naturally` | 이미 쓴 문장이 AI가 쓴 것처럼 읽힐 때 |
+| `technical-visualizer` | 다이어그램이 필요할 때. 손으로 SVG를 그리지 않습니다 |
 
-출처는 `korean-technical-blog-skills-bundle-v1` 번들이고 상류를 수정하지 않고 그대로 씁니다.
-`.claude/skills/`는 위 세 폴더를 가리키는 상대 경로 심링크입니다.
+`.claude/skills/`는 위 폴더를 가리키는 상대 경로 심링크입니다.
+
+`technical-visualizer`는 스킬만 이 저장소에 있고 도구(`techviz` 파이썬 패키지)는
+`ai-tool/technical-visualization-haness`에 있습니다. `scripts/techviz`가 래퍼이고, 경로가
+다르면 `TECHVIZ_HOME`으로 알려 줍니다.
 
 ## 실행 순서
 
 ```text
-원자료·초안
-→ writing-korean-technical-blogs
-→ reducing-ai-like-korean-writing
-→ editing-korean-grammar-and-expression
-→ 사실·수치·코드·인용 최종 대조
+원자료
+→ 종류 선택        Case · Concept · Reference · Question · Decision
+→ 칸 채우기
+→ 본문 작성        Case · Concept
+→ 다이어그램       technical-visualizer 스킬
+→ 파서 검사        check_body.mjs
+→ 문장 검사        check_prose.mjs (error 0) · style_profile.mjs
+→ 게시 전 대조
+→ Studio 저장 → 게시 → 공개 화면 확인
 ```
 
-작업 규칙은 `CLAUDE.md`에 있습니다.
+**코드·표·다이어그램·이미지는 본문에만 들어갑니다. 본문이 있는 종류는 Case와 Concept입니다.**
+Reference·Question·Decision의 칸은 평문으로 렌더링됩니다. 그런 자료가 필요하면 Case나 Concept에
+담고 `관계`로 가리킵니다.
 
-## 보관 중인 문서
+작업 규칙과 보관 중인 문서 목록은 `CLAUDE.md`에 있습니다.
 
-| 런 | 제목 | 분량 |
-|---|---|---:|
-| `executable-clean-architecture` | 실행 가능한 클린 아키텍처 — 선언이 아니라 빌드가 지키는 경계 | 1,759줄 |
-| `keycloak-four-patterns` | 브라우저 토큰에서 엣지 세션까지: Keycloak 인증 패턴 네 가지의 경계 설계 | 1,532줄 |
-| `n+1liner` | 하이라이트 피드 조회 성능 — N+1 진단과 조회 전략의 진화 | 1,764줄 |
+## 보관 구조
 
-각 런의 구조는 다음과 같습니다.
+`docs/` 아래를 프로젝트로 나눕니다. 프로젝트 문서는 그 폴더 밖에 두지 않습니다. 루트에는
+`.agents`·`.claude`·`.codex`·`.playwright-mcp`와 `CLAUDE.md`·`README.md`·`LICENSE`·`scripts/`만
+둡니다.
 
 ```text
-.run/<slug>/
-├── final/
-│   ├── document.md      완성된 글
-│   ├── assets/          다이어그램 (svg, drawio, d2, mmd, dot)
-│   └── evidence/        측정 자료 (실행계획, csv)
-└── (런에 따라) brief.json, sources.json, outline.json
+docs/
+├── ca-tmpl/                              실행 가능한 클린 아키텍처
+├── clean-architecture-backend-template/
+│   └── final/document.md                 Redis 코드 상세 (20편을 합침)
+├── keycloak/                             인증 패턴 네 가지
+├── n+1liner/                             피드 조회 성능
+└── TechLog/                              이 Studio를 만들며 만난 결함
 ```
 
-`keycloak-four-patterns`의 `brief.json`, `sources.json`, `outline.json`은 제거된 하네스가
-남긴 파일입니다. 재생성할 수 없지만 그 글이 어떤 증거 위에서 쓰였는지를 담고 있어 남겨 두었습니다.
+프로젝트 하나는 이렇게 생겼습니다.
 
-## 스킬 검증
+```text
+docs/<프로젝트>/
+├── source/                 밖에서 가져온 원본. 고치지 않습니다
+├── final/                  SSOT — 이 프로젝트에 대해 아는 것 전부
+│   ├── document.md         상세한 글
+│   ├── assets/             svg, drawio, 그림
+│   ├── .techviz/           그림의 정본 (context, spec, prompt)
+│   └── evidence/           터미널 기록, 실행계획, csv, 스크린샷
+└── tech-log-studio/        Studio에 올릴 글만
+    ├── tech-log-tree.json  글감 목록
+    └── <주제 slug>/
+        ├── case/  concept/  reference/  question/  decision/
+```
+
+`final/`이 정본이고 `tech-log-studio/`는 거기서 뽑아낸 글입니다. 증거는 `final/evidence/`에만
+두고 기록은 그 파일을 가리킵니다.
+
+주제 폴더 이름은 Studio 주제의 slug입니다. Studio가 주제별로 다섯 종류를 나눠 보여 주므로
+폴더도 같은 모양입니다. 지금은 `keycloak`에 `oauth-oidc-auth-boundary` 23건,
+`n+1liner`에 `jpa-feed-query-performance` 24건이 있습니다.
+
+`tech-log-tree.json`은 그 주제 아래 어떤 글감이 있고 어디까지 썼는지를 한 파일에 모읍니다.
+기록을 쓰거나 지운 뒤에는 다시 만듭니다.
 
 ```bash
-for d in .agents/skills/*/; do ( cd "$d" && python3 scripts/validate_skill.py ); done
+python3 scripts/build-tech-log-tree.py            # 전부
+python3 scripts/build-tech-log-tree.py keycloak   # 하나만
 ```
 
-세 스킬 모두 PASS여야 합니다. PyYAML이 필요합니다.
+## 밖에서 문서를 가져올 때
+
+1. 원본을 `docs/<프로젝트>/source/`에 그대로 복사합니다
+2. 글·그림·증거를 `final/`로 옮깁니다 — 여기까지가 SSOT입니다
+3. SSOT를 읽고 글감을 뽑아 `tech-log-tree.json`에 제목만 적습니다
+4. 글감 하나를 골라 `<주제>/<종류>/`에 기록을 씁니다
+5. 트리를 다시 만듭니다
+6. Studio에 넣고 저장합니다
+
+## 검사
+
+게시 전에 둘 다 돌립니다. 하나는 파서를, 하나는 문장을 봅니다.
+
+```bash
+# 본문이 Studio 파서를 통과하는지. 같은 파서를 그대로 부릅니다
+node --experimental-transform-types \
+  .agents/skills/writing-tech-log-records/scripts/check_body.mjs 초안.md
+
+# 문장이 규범을 지키는지. error가 남아 있으면 덜 된 글입니다
+S=.agents/skills/rewriting-technical-prose-naturally/scripts
+node $S/check_prose.mjs --warn 초안.md
+node $S/style_profile.mjs 초안.md
+```
+
+`check_body.mjs`는 `tech-log-frontend` 체크아웃을 읽습니다. 경로가 다르면 `--frontend` 또는
+`TECH_LOG_FRONTEND`로 알려 줍니다.
+
+`style_profile.mjs`의 기준값은 우아한형제들 기술블로그 5편에서 잰 것입니다. 수치를 맞추려고
+문장을 넣지 않습니다 — 두 검사기 모두 표면 패턴만 보고 뜻은 못 봅니다.
 
 ## 이력
 
 이 저장소에는 ClariDoc 하네스(파이썬 패키지 `claridoc-harness` 0.2.0과 CLI)가 있었습니다.
-2026-08-07에 제거했습니다. 판단 근거와 삭제 인벤토리는
-[docs/decisions/2026-08-07-remove-claridoc-harness.md](docs/decisions/2026-08-07-remove-claridoc-harness.md)에 있고,
-제거 직전 상태는 `pre-harness-removal` 태그에 있습니다.
+2026-08-07에 제거했습니다. 제거 직전 상태는 `pre-harness-removal` 태그에 있습니다.
 
 ```bash
 git show pre-harness-removal:src/claridoc/cli.py