DongHyeonkaandClaude Opus 5
73026cada6
Two things read as machine-written and both are now fixed with the repository's own tooling. The diagram labels counted abstractions instead of naming things — "틀린 예측 5건", "조용한 실패 9건", "로컬 아티팩트 76건". Replaced with what those actually were, which is also more useful in a drawing: 틀린 예측 5건 -> A-1 · A-2 · A-6 · B-4 · B-6 조용한 실패 9건 -> NetworkPolicy · tc · kill · iptables 로컬 아티팩트 76건 -> 연결수 0 · 50µs A층 결론 3건 반전 -> A-1 · A-2 · A-8 The prose was staccato: 30.7 characters average against a 48-75 reference, 45% of sentences under 25 characters, and causal connectives at 4.9 per 100 against a floor of 6. check_prose reported an error for closing six sentences with 「~것이 ~이다」. Roughly ninety sentences were rewritten — joining pairs that carry a real causal or contrastive relation, and varying the joins. The first pass overcorrected into a new monotony (는데 at 47 occurrences, connectives up to 31.9, above the ceiling), so twenty-three of those were varied into 지만, -고, em-dashes, or split back apart. check_prose FAIL error 1 -> OK error 0 평균 문장 길이 30.7 -> 43.1 25자 미만 비율 45.4% -> 23.4% 이유 연결어미 4.9 -> within range Two style_profile numbers still read outside the band, and the reason is worth writing down rather than editing around: the tool counts each image caption as a sentence, and this document carries 28 diagrams. Excluding captions and separators the prose is 46.4 characters average with 14.3% short — inside the reference range. Padding sentences to move the remaining gap is what CLAUDE.md forbids, so it stops here. Protected values were checked against source and are unchanged: 153건/149건, 1,872 ms, 20,000 ms, 22.2 초, 2305초, 845361바이트, 8856건, 205.7ms, 106초. All 28 diagrams still lint clean with no sentence left on any canvas. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Tech Log 기록 작업 공간
이 저장소는 Tech Log Studio에 올릴 기록을 쓰고 보관하는
곳입니다. 작성 능력은 .agents/skills/의 Agent Skill이 담당하고, 완성된 글과 근거 자료는
docs/ 아래에 프로젝트별로 보관합니다.
스킬
| 스킬 | 언제 |
|---|---|
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/
│ 분석 진행 중 (모듈 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 # 하나만
밖에서 문서를 가져올 때
- 원본을
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로 알려 줍니다.
기록이 수백 건이면 하나씩 읽어 확인할 수 없습니다. 구조는 기계가 셉니다.
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 참조.