스킬	언제
`writing-tech-log-records`	Studio에 올릴 기록 한 건을 쓰거나 고칠 때. 종류 선택, 칸 채우기, 본문 작성, 게시 전 대조
`rewriting-technical-prose-naturally`	이미 쓴 문장이 AI가 쓴 것처럼 읽힐 때
`technical-visualizer`	다이어그램이 필요할 때. 손으로 SVG를 그리지 않습니다

.claude/skills/는 위 폴더를 가리키는 상대 경로 심링크입니다.

technical-visualizer는 스킬만 이 저장소에 있고 도구(techviz 파이썬 패키지)는 ai-tool/technical-visualization-haness에 있습니다. scripts/techviz가 래퍼이고, 경로가 다르면 TECHVIZ_HOME으로 알려 줍니다.

실행 순서

원자료
→ 종류 선택        Case · Concept · Reference · Question · Decision
→ 칸 채우기
→ 본문 작성        Case · Concept
→ 다이어그램       technical-visualizer 스킬
→ 파서 검사        check_body.mjs
→ 문장 검사        check_prose.mjs (error 0) · style_profile.mjs
→ 게시 전 대조
→ Studio 저장 → 게시 → 공개 화면 확인

코드·표·다이어그램·이미지는 본문에만 들어갑니다. 본문이 있는 종류는 Case와 Concept입니다. Reference·Question·Decision의 칸은 평문으로 렌더링됩니다. 그런 자료가 필요하면 Case나 Concept에 담고 관계로 가리킵니다.

작업 규칙과 보관 중인 문서 목록은 CLAUDE.md에 있습니다.

보관 구조

docs/ 아래를 프로젝트로 나눕니다. 프로젝트 문서는 그 폴더 밖에 두지 않습니다. 루트에는 .agents·.claude·.codex·.playwright-mcp와 CLAUDE.md·README.md·LICENSE·scripts/만 둡니다.

docs/
├── ca-tmpl/                              실행 가능한 클린 아키텍처
├── clean-architecture-backend-template/
│   └── final/document.md                 Redis 코드 상세 (20편을 합침)
├── keycloak/                             인증 패턴 네 가지
├── n+1liner/                             피드 조회 성능
└── TechLog/                              이 Studio를 만들며 만난 결함

프로젝트 하나는 이렇게 생겼습니다.

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은 그 주제 아래 어떤 글감이 있고 어디까지 썼는지를 한 파일에 모읍니다. 기록을 쓰거나 지운 뒤에는 다시 만듭니다.

python3 scripts/build-tech-log-tree.py            # 전부
python3 scripts/build-tech-log-tree.py keycloak   # 하나만

밖에서 문서를 가져올 때

원본을 docs/<프로젝트>/source/에 그대로 복사합니다
글·그림·증거를 final/로 옮깁니다 — 여기까지가 SSOT입니다
SSOT를 읽고 글감을 뽑아 tech-log-tree.json에 제목만 적습니다
글감 하나를 골라 <주제>/<종류>/에 기록을 씁니다
트리를 다시 만듭니다
Studio에 넣고 저장합니다

검사

게시 전에 둘 다 돌립니다. 하나는 파서를, 하나는 문장을 봅니다.

# 본문이 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에 제거했습니다. 제거 직전 상태는 pre-harness-removal 태그에 있습니다.

git show pre-harness-removal:src/claridoc/cli.py
git checkout pre-harness-removal -- <경로>

라이선스

MIT. LICENSE 참조.