document-haness/.agents/skills/writing-tech-log-records/SKILL.md

name, description, metadata

name	description	metadata
writing-tech-log-records	Use when writing or revising a Tech Log Studio record — Case, Concept, Setup, Reference, Question, or Decision — including choosing the right kind, filling each kind's fields, authoring body Markdown with code blocks, tables, callouts, diagrams and evidence images, and linking records so a published document renders correctly on the public site.	version language studioContract publicContract 1.1.0 ko-KR @tech-log/studio-contract@3.1.0 @tech-log/public-contract@2.1.0

Tech Log 기록 작성

개요

Studio는 여섯 종류를 구분한다. 종류를 잘못 고르면 채울 칸이 맞지 않는다.

종류	쓰는 때	본문
Case	내가 재현하고 검증해 결론을 냈다	있음
Concept	남의 것이 어떻게 동작하는지 읽고 정리했다	있음
Setup	남이 자기 손으로 따라 할 절차를 남긴다 (SETUP, 화면 이름 「환경 구성」)	있음
Reference	반복 적용할 기준을 굳혔다	없음
Question	아직 판단이 안 끝났다	없음
Decision	프로젝트가 방향을 정했다 (PROJECT_DECISION)	없음

Setup 만 끝난 일을 적지 않는다. 나머지 다섯은 이미 일어난 일을 적고, Setup 은 읽는 사람이 자기 기계에서 실행할 순서를 적는다. 그래서 본문에 명령이 들어가고, 버전만 본문 밖의 pinnedVersions 에 남는다. 프로젝트가 필수이고 주제는 비워도 된다.

절대 규칙

코드·표·다이어그램·이미지는 본문에만 들어간다. 본문이 있는 종류는 Case·Concept·Setup 셋이다. 본문이 없는 세 종류(Reference·Question·Decision)의 칸은 평문으로 렌더링돼 백틱과 파이프가 글자 그대로 보인다. 그런 자료는 본문이 있는 종류에 담고 관계로 가리킨다. references/record-kinds.md

필수 절차

0. 글감 나누기 — 긴 글(SSOT)에서 옮겨 오는 것이면 먼저 나눈다. 기준은 references/from-ssot-to-records.md, 계약은 references/tech-log-tree-contract.md. tech-log-tree.json 에 노드가 없는 글은 쓰지 않는다 — 트리에 먼저 올리고, 그 노드의 후보가 PROMOTE 이면서 dispositionReview: CONFIRMED 인지 확인한 뒤에 쓴다. PENDING 은 사람이 다시 읽지 않았다는 뜻이라, 그 위에 쓴 글은 과분류를 그대로 물려받는다. 계약 밖에서 쓴 기록은 색인에 unlisted 로 남는다. 그 노드의 ssot-assets·ssot-evidence 도 함께 본다 — SSOT 가 이미 그린 그림과 이미 돌린 측정 가운데 이 글감에 배정된 것이 거기 적혀 있다.
1. 종류 선택 — 위 표. 애매하면 「끝난 일을 적나, 남이 따라 할 절차를 적나」를 먼저 묻고, 끝난 일이면 "재현했나"를 묻는다.
2. 칸 채우기 — 칸과 게시 조건은 references/record-kinds.md.
3. 본문 작성(Case·Concept·Setup) — 종류마다 무엇을 어떤 순서로 쓰는지는 references/writing-each-kind.md. Setup 은 본문을 쓰기 전에 Skill 도구로 writing-practitioner-guides 를 연다. 명령을 어떤 형태로 쓸지는 그 스킬이 정한다. 그다음이 references/writing-each-kind.md 의 Setup 절이다 — 단계 하나의 모양과 이 저장소에서만 걸리는 셋이 거기 있다. 문법은 references/body-syntax.md, 표·코드·그림은 references/code-tables-diagrams.md. 문장은 references/explaining.md. 문서군 전체의 리듬은 references/ai-tells.md. 이 둘은 첫 초안부터 적용한다 — AI 티를 남겨 두고 나중에 걷어내는 순서가 아니다. 문체를 손보기 전에 문장을 고른다 — 설명이 끝난 뒤에 붙은 평가·예고·되풀이·독자 오해 가정을 먼저 뺀다(ai-tells.md 첫 절). 문체 규칙의 정본은 ai-tells.md 다. 그림이 필요한지, 필요하면 무엇을 그릴지는 references/choosing-a-diagram.md. 담을 곳 (Case·Concept·Setup 만) · 표가 아닌지 · 옆 문단이 이미 말하지 않았는지 세 관문을 지나야 그린다. 순서·경계·상태 전이처럼 문장만으로 따라가기 어려운 관계가 있으면 final/assets/ 에 그 그림이 이미 있는지부터 본다. SSOT 를 만들 때 그려 둔 것이 있고 계약의 ssot-assets 가 이 글감에 배정해 두었으면 기록의 assets 가 그 파일을 그대로 가리킨다. 사본을 따로 만들지 않는다 — 사본에는 .techviz/<이름>/ 이 없어 다시 만들 수 없다. 없을 때만 technical-visualizer 로 새로 만든다. 손으로 SVG 를 그리지 않고, 모든 글에 그림을 만들지도 않는다. 인용할 측정도 같다. final/evidence/ 에 있는 원문을 가리키고 같은 것을 다시 돌리지 않는다. 그림과 측정을 그 자리에서 만들어 내기 전에 SSOT 가 이미 가진 것을 먼저 찾는다 — keycloak 에서는 그러지 않아 정본까지 갖춘 그림 13 장이 남고 이름이 다른 그림 5 장이 새로 만들어졌다.
4. 검사 — 셋 다 돌린다. 파서와 문장과 증빙은 각각 다른 것을 본다.
   • scripts/check_body.mjs — 본문이 Studio 파서를 통과하는지. 같은 파서를 그대로 부른다. 저장소의 그림은 마크다운 이미지이므로 python3 scripts/studio-body.py <기록> -o /tmp/x.md 로 바꾼 파일에 돌린다. 저장소 파일에 그대로 돌리면 unsafe image URL 로 실패한다.
   • rewriting-technical-prose-naturally/scripts/check_prose.mjs — 문장 규범. error 0 이 될 때까지 고친다. 칸 하나나 한 절만 고쳤으면 --doc 없이 부른다. 이어서 style_profile.mjs 로 문체 수치를 본다.
   • scripts/check_evidence.mjs <프로젝트> --repo — 인용한 것이 실재하는지. 본문 코드블록의 각 줄이 SSOT 안에 있는지, source 앵커가 SSOT 를 가리키는지, 제목이 계약과 같은지, sourceRepository 의 리비전이 그 저장소에 있는지를 본다.
5. 관계 연결 — Decision은 근거가 1개 이상 없으면 게시가 거절된다.
6. Studio에서 확인 — 넣고 저장까지만 한 뒤 미리보기로 읽는다. 절차는 references/studio-draft-review.md. 게시하지 않는다.
7. 색인 갱신 — 기록을 쓰거나 지웠으면 다시 만들고 검사한다. python3 scripts/build-tech-log-tree.py <프로젝트> · python3 scripts/verify-tech-log-tree.py <프로젝트> — error 0 이어야 한다.
8. 게시 — 고칠 것이 없을 때만. 못 채운 칸은 그 칸 아래에 표시된다.

어느 스킬이 무엇을 하나

이 스킬이 첫 초안을 만든다. writing-practitioner-guides 는 Setup 본문을 쓰는 동안 함께 열고, 나머지는 초안이 나온 뒤에 각각 다른 것을 고친다.

스킬	하는 일	하지 않는 일
deriving-tech-log-root-tree	후보에 처분을 매기고 PROMOTE 를 글감으로 올린다	글을 쓰지 않는다
writing-tech-log-records	종류를 고르고 칸과 본문을 쓴다. explaining.md·ai-tells.md 를 처음부터 적용한다	—
writing-practitioner-guides	사람이 직접 치는 명령의 형태를 정한다 — 한 줄에 담는 계층, 도구 우선순위, 출력을 읽는 형태와 값 하나만 뽑는 형태, 넓은 명령에서 좁은 명령으로	Tech Log 의 종류와 칸을 모른다. SSOT 대조도 색인 갱신도 하지 않는다
technical-visualizer	문장으로 따라가기 어려운 관계를 그림으로 만든다	무엇을 그릴지 정하지 않는다 — choosing-a-diagram.md 가 정한다
rewriting-technical-prose-naturally	사실과 구조가 이미 맞는 초안의 번역투·반복 문형·과한 대구를 고친다	분류가 틀렸거나 근거가 모자란 것은 못 고친다
writing-as-the-person-who-did-it	자료에 남아 있는 선택·비교·어긋남·확인하지 못한 범위를 제자리에 놓는다	자료에 없는 「처음에는」·「고민 끝에」를 만들지 않는다

Reference·Question·Decision 은 그림을 렌더링할 곳이 없다. 그림이 필요한 내용은 짝이 되는 Case·Concept·Setup 에 담고 관계로 가리킨다.

보호 구간

수치, 날짜, 버전, 단위, 코드, 명령어, URL, 인용, 공식 명칭은 원문과 한 글자도 달라지면 안 된다. 측정하지 않은 값을 채우지 않는다 — 검증일은 실제로 확인한 날이다.

옮겨 적었다고 확인한 것이 아니다. 앞선 기록에서 코드를 가져오거나 기억으로 경로를 쓰면 SSOT 에 없는 인용이 생긴다. 실제로 그렇게 게시된 기록에 잘못된 redirect URI 가 네 곳 남아 있었고, realm 설정이 와일드카드라 실행해도 드러나지 않았다. 인용한 줄은 SSOT 에서 찾아 대조한다. check_evidence.mjs 가 그 대조를 기계로 한 번 더 한다.

SSOT 에 없는데 필요한 인용이라면 순서가 반대다 — final/document.md 를 먼저 보강하고, 그것도 저장소에서 확인한 뒤에 한다. sourceRepository.path 가 그 저장소를 가리킨다.

쓰지 않는 것

• 자료가 뒷받침하지 않는 선택 이유. 썼다는 사실을 왜 골랐는지로 바꾸지 않는다.
• 지어낸 경험·실패·감정. 자료에 없는 1인칭 서술.
• 가능성을 확정으로, 한 구조에서 본 것을 protocol 전체로 넓히기.

흔한 실패

실패	대응
Reference 규칙에 코드블록	Case로 옮겨 관계 연결
본문 밖 칸에서 백틱을 뺌	이 칸도 백틱은 <code> 로 산다. 빼는 것은 별표·파이프·# 다
평문 칸에 쉼표 나열	이름 : 값으로 줄 나눔. 있음·없음은 o·x
표 머리글이 명사뿐	질문으로. 비교 축은 전·후 시점으로
그림 안에 문장·숫자	<text>는 이름만. 문장은 <desc>·옆 문단에
이름만 대고 넘어감 · 「역할이 다르다」로 끝냄	왜 있는지·왜 못 합치는지까지
산문에 내부 코드명	구조 이름으로. 번호는 표 축·식별자에만
**굵게** 남발 · 끊어 나열 · 되풀이 강조	한 절에 하나, 한 문단으로, 한 번만
~하는 것은 ~이다 · 「~한 것은 아니다」로 시작	번역투다. 문제 → 할 일 → 확인
싣는다·낸다·둘이 · 자리·떠안다	동작을 풀고, 비유 없이 그대로
읽는 법을 지시	「봐야 한다」·「여기까지다」 삭제
..?·~해보자 억지 구어체	명사구 제목으로. 본 것을 먼저 쓴다
문서마다 같은 문형·같은 길이	references/ai-tells.md
표를 :::table로 감쌈	그냥 파이프로 쓴다
	Asset으로 올려 /api/v1/public/media/…
SSOT 에 있는 그림을 두고 새로 그림	final/assets/ 를 먼저 본다. ssot-assets 가 배정한 것을 쓴다
SSOT 에 있는 측정을 두고 다시 돌림	final/evidence/ 의 원문을 가리킨다
Decision에 근거 없음	관계 1개 이상 연결
Setup에 끝난 일을 적음	따라 할 순서가 아니면 Case다
Setup 본문에 printf >·echo >>·python3 -c	사람이 치는 형태로 바꾼다. 설정 파일은 에디터로 연다
Setup 본문의 명령만 고치고 SSOT 를 그대로 둠	final/document.md 를 먼저 고친다. check_evidence.mjs 가 막는다
Setup 본문에 「2026-09-12 기준」	검증일 칸이 없다. 버전은 pinnedVersions 에 적는다
Setup에 프로젝트를 안 고름	「환경 구성은 프로젝트에 속합니다」로 막힌다
측정 안 한 검증일	비워 둔다
설명 직후에 「~증거다」「~가 아니다」로 평가	지운다. 앞 문장이 사실을 말했으면 거기서 끝낸다
「~로 읽기 쉽다. 그렇지 않다」	오해를 지어내지 않는다. 관측부터 적는다
「먼저 ~를 보고 …」 차례 예고 · 「~를 함께 적는다」	지운다. 다음 절이 바로 시작한다

작성 후 references/review-checklist.md로 대조한다.