---
name: writing-tech-log-records
description: Use when writing or revising a Tech Log Studio record — Case, Concept, 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.
metadata:
  version: "1.1.0"
  language: "ko-KR"
  studioContract: "@tech-log/studio-contract@3.1.0"
  publicContract: "@tech-log/public-contract@2.1.0"
---

# Tech Log 기록 작성

## 개요

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

| 종류 | 쓰는 때 | 본문 |
|---|---|---|
| **Case** | 내가 재현하고 검증해 결론을 냈다 | 있음 |
| **Concept** | 남의 것이 어떻게 동작하는지 읽고 정리했다 | 있음 |
| **Reference** | 반복 적용할 기준을 굳혔다 | 없음 |
| **Question** | 아직 판단이 안 끝났다 | 없음 |
| **Decision** | 프로젝트가 방향을 정했다 (`PROJECT_DECISION`) | 없음 |

## 절대 규칙

**코드·표·다이어그램·이미지는 본문에만 들어간다. 본문이 있는 종류는 Case 와 Concept 둘뿐이다.**
본문이 없는 세 종류의 칸은 평문으로 렌더링돼 백틱과 파이프가 글자 그대로 보인다. 그런 자료는 Case 나
Concept 에 담고 `관계`로 가리킨다. `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` 로 남는다.
1. **종류 선택** — 위 표. 애매하면 "재현했나"를 묻는다.
2. **칸 채우기** — 칸과 게시 조건은 `references/record-kinds.md`.
3. **본문 작성**(Case·Concept) — **종류마다 무엇을 어떤 순서로 쓰는지는
   `references/writing-each-kind.md`.** 문법은 `references/body-syntax.md`, 표·코드·그림은
   `references/code-tables-diagrams.md`. **문장은 `references/explaining.md`.**
   **문서군 전체의 리듬은 `references/ai-tells.md`.** 이 둘은 첫 초안부터 적용한다 — AI 티를
   남겨 두고 나중에 걷어내는 순서가 아니다. **문체를 손보기 전에 문장을 고른다** — 설명이 끝난
   뒤에 붙은 평가·예고·되풀이·독자 오해 가정을 먼저 뺀다(`ai-tells.md` 첫 절). 문체 규칙의
   정본은 `ai-tells.md` 다.
   순서·경계·상태 전이처럼 문장만으로 따라가기 어려운 관계가 있으면 그때
   `technical-visualizer` 로 그림을 만든다. 손으로 SVG 를 그리지 않고, 모든 글에 그림을 만들지도
   않는다.
4. **검사** — 셋 다 돌린다. 파서와 문장과 증빙은 각각 다른 것을 본다.
   - `scripts/check_body.mjs` — Case 본문이 Studio 파서를 통과하는지. 같은 파서를 그대로 부른다.
   - `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. **게시** — 고칠 것이 없을 때만. 못 채운 칸은 그 칸 아래에 표시된다.

## 어느 스킬이 무엇을 하나

이 스킬이 첫 초안을 만든다. 나머지는 초안이 나온 뒤에 각각 다른 것을 고친다.

| 스킬 | 하는 일 | 하지 않는 일 |
|---|---|---|
| `deriving-tech-log-root-tree` | 후보에 처분을 매기고 `PROMOTE` 를 글감으로 올린다 | 글을 쓰지 않는다 |
| `writing-tech-log-records` | 종류를 고르고 칸과 본문을 쓴다. `explaining.md`·`ai-tells.md` 를 처음부터 적용한다 | — |
| `technical-visualizer` | 문장으로 따라가기 어려운 관계를 그림으로 만든다 | 모든 글에 그림을 붙이지 않는다 |
| `rewriting-technical-prose-naturally` | 사실과 구조가 이미 맞는 초안의 번역투·반복 문형·과한 대구를 고친다 | 분류가 틀렸거나 근거가 모자란 것은 못 고친다 |
| `writing-as-the-person-who-did-it` | 자료에 남아 있는 선택·비교·어긋남·확인하지 못한 범위를 제자리에 놓는다 | 자료에 없는 「처음에는」·「고민 끝에」를 만들지 않는다 |

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

## 보호 구간

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

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

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

## 쓰지 않는 것

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

## 흔한 실패

| 실패 | 대응 |
|---|---|
| Reference 규칙에 코드블록 | Case로 옮겨 관계 연결 |
| 본문 밖 칸에 백틱 | 평문이다. 백틱을 뺀다 |
| 평문 칸에 쉼표 나열 | `이름 : 값`으로 줄 나눔. 있음·없음은 `o`·`x` |
| 표 머리글이 명사뿐 | 질문으로. 비교 축은 `전`·`후` 시점으로 |
| 그림 안에 문장·숫자 | `<text>`는 이름만. 문장은 `<desc>`·옆 문단에 |
| 이름만 대고 넘어감 · 「역할이 다르다」로 끝냄 | 왜 있는지·왜 못 합치는지까지 |
| 산문에 내부 코드명 | 구조 이름으로. 번호는 표 축·식별자에만 |
| `**굵게**` 남발 · 끊어 나열 · 되풀이 강조 | 한 절에 하나, 한 문단으로, 한 번만 |
| `~하는 것은 ~이다` · 「~한 것은 아니다」로 시작 | 번역투다. 문제 → 할 일 → 확인 |
| `싣는다`·`낸다`·`둘이` · `자리`·`떠안다` | 동작을 풀고, 비유 없이 그대로 |
| 읽는 법을 지시 | 「봐야 한다」·「여기까지다」 삭제 |
| `..?`·`~해보자` 억지 구어체 | 명사구 제목으로. 본 것을 먼저 쓴다 |
| 문서마다 같은 문형·같은 길이 | `references/ai-tells.md` |
| 표를 `:::table`로 감쌈 | 그냥 파이프로 쓴다 |
| `![](https://…외부)` | Asset으로 올려 `/api/v1/public/media/…` |
| Decision에 근거 없음 | 관계 1개 이상 연결 |
| 측정 안 한 검증일 | 비워 둔다 |
| 설명 직후에 「~증거다」「~가 아니다」로 평가 | 지운다. 앞 문장이 사실을 말했으면 거기서 끝낸다 |
| 「~로 읽기 쉽다. 그렇지 않다」 | 오해를 지어내지 않는다. 관측부터 적는다 |
| 「먼저 ~를 보고 …」 차례 예고 · 「~를 함께 적는다」 | 지운다. 다음 절이 바로 시작한다 |

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