Tech Log 기록 작업 공간

이 저장소는 Tech Log Studio에 올릴 기록을 쓰고 보관하는 곳입니다. 작성 능력은 .agents/skills/의 Agent Skill이 담당하고, 완성된 글과 근거 자료는 docs/ 아래에 프로젝트별로 보관합니다.

스킬

스킬	언제
writing-tech-log-records	Studio에 올릴 기록 한 건을 쓰거나 고칠 때. 종류 선택, 칸 채우기, 본문 작성, 게시 전 대조
rewriting-technical-prose-naturally	이미 쓴 문장이 AI가 쓴 것처럼 읽힐 때
writing-as-the-person-who-did-it	정확한데 아무도 쓰지 않은 보고서처럼 읽힐 때. 자료에 남은 사람의 흔적을 제자리에 놓습니다
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/
│                                          분석 진행 중 (모듈 7편)
├── keycloak/                             인증 패턴 네 가지
├── keycloak-session-store/               세션 저장소와 장애 주입 실험 26건
│                                          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건이 있습니다. keycloak-session-store는 SSOT 까지 들어왔고 기록은 아직 없습니다.

tech-log-tree.json은 그 주제 아래 어떤 글감이 있고 어디까지 썼는지를 한 파일에 모읍니다. 기록을 쓰거나 지운 뒤에는 다시 만듭니다.

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

밖에서 문서를 가져올 때

1. 원본을 docs/<프로젝트>/source/에 그대로 복사합니다
2. 글·그림·증거를 final/로 옮깁니다 — 여기까지가 SSOT입니다
3. SSOT를 읽고 글감을 뽑아 tech-log-tree.json에 제목만 적습니다
4. 글감 하나를 골라 <주제>/<종류>/에 기록을 씁니다
5. 트리를 다시 만듭니다
6. 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로 알려 줍니다.

기록이 수백 건이면 하나씩 읽어 확인할 수 없습니다. 구조는 기계가 셉니다.

python3 scripts/audit-records.py            # 전부
python3 scripts/audit-records.py keycloak   # 하나만

칸이 비었는지, kind와 폴더가 맞는지, topic이 폴더 slug인지, 본문 마커가 있는지, assets·evidence가 가리키는 파일이 실제로 있는지, 본문이 부르는 자산이 frontmatter에 선언돼 있는지, 증거의 원문·메타·렌더가 짝을 이루는지를 봅니다. 문제가 있으면 종료 코드가 1입니다.

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 참조.