139 lines
10 KiB
Markdown
139 lines
10 KiB
Markdown
---
|
|
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` 로 남는다. 그 노드의 `ssot-assets`·`ssot-evidence` 도 함께 본다 —
|
|
SSOT 가 이미 그린 그림과 이미 돌린 측정 가운데 이 글감에 배정된 것이 거기 적혀 있다.
|
|
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` 다.
|
|
**그림이 필요한지, 필요하면 무엇을 그릴지는 `references/choosing-a-diagram.md`.** 자리(Case·
|
|
Concept 만) · 표가 아닌지 · 옆 문단이 이미 말하지 않았는지 세 관문을 지나야 그린다.
|
|
순서·경계·상태 전이처럼 문장만으로 따라가기 어려운 관계가 있으면 **`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. **게시** — 고칠 것이 없을 때만. 못 채운 칸은 그 칸 아래에 표시된다.
|
|
|
|
## 어느 스킬이 무엇을 하나
|
|
|
|
이 스킬이 첫 초안을 만든다. 나머지는 초안이 나온 뒤에 각각 다른 것을 고친다.
|
|
|
|
| 스킬 | 하는 일 | 하지 않는 일 |
|
|
|---|---|---|
|
|
| `deriving-tech-log-root-tree` | 후보에 처분을 매기고 `PROMOTE` 를 글감으로 올린다 | 글을 쓰지 않는다 |
|
|
| `writing-tech-log-records` | 종류를 고르고 칸과 본문을 쓴다. `explaining.md`·`ai-tells.md` 를 처음부터 적용한다 | — |
|
|
| `technical-visualizer` | 문장으로 따라가기 어려운 관계를 그림으로 만든다 | 무엇을 그릴지 정하지 않는다 — `choosing-a-diagram.md` 가 정한다 |
|
|
| `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`로 감쌈 | 그냥 파이프로 쓴다 |
|
|
| `` | Asset으로 올려 `/api/v1/public/media/…` |
|
|
| SSOT 에 있는 그림을 두고 새로 그림 | `final/assets/` 를 먼저 본다. `ssot-assets` 가 배정한 것을 쓴다 |
|
|
| SSOT 에 있는 측정을 두고 다시 돌림 | `final/evidence/` 의 원문을 가리킨다 |
|
|
| Decision에 근거 없음 | 관계 1개 이상 연결 |
|
|
| 측정 안 한 검증일 | 비워 둔다 |
|
|
| 설명 직후에 「~증거다」「~가 아니다」로 평가 | 지운다. 앞 문장이 사실을 말했으면 거기서 끝낸다 |
|
|
| 「~로 읽기 쉽다. 그렇지 않다」 | 오해를 지어내지 않는다. 관측부터 적는다 |
|
|
| 「먼저 ~를 보고 …」 차례 예고 · 「~를 함께 적는다」 | 지운다. 다음 절이 바로 시작한다 |
|
|
|
|
작성 후 `references/review-checklist.md`로 대조한다.
|