5.2 KiB
5.2 KiB
name, description, metadata
| name | description | metadata | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| writing-tech-log-records | 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. |
|
Tech Log 기록 작성
개요
Studio는 다섯 종류를 구분한다. 종류를 잘못 고르면 채울 칸이 맞지 않는다.
| 종류 | 쓰는 때 | 본문 |
|---|---|---|
| Case | 내가 재현하고 검증해 결론을 냈다 | 있음 |
| Concept | 남의 것이 어떻게 동작하는지 읽고 정리했다 | 있음 |
| Reference | 반복 적용할 기준을 굳혔다 | 없음 |
| Question | 아직 판단이 안 끝났다 | 없음 |
| Decision | 프로젝트가 방향을 정했다 (PROJECT_DECISION) |
없음 |
절대 규칙
코드·표·다이어그램·이미지는 본문에만 들어간다. 본문이 있는 종류는 Case 와 Concept 둘뿐이다.
본문이 없는 세 종류의 칸은 평문으로 렌더링돼 백틱과 파이프가 글자 그대로 보인다. 그런 자료는 Case 나
Concept 에 담고 관계로 가리킨다. references/record-kinds.md
필수 절차
- 글감 나누기 — 긴 글(SSOT)에서 옮겨 오는 것이면 먼저 나눈다. 기준과
tech-log-tree.json형식은references/from-ssot-to-records.md. 나눈 뒤 글을 쓴다. - 종류 선택 — 위 표. 애매하면 "재현했나"를 묻는다.
- 칸 채우기 — 칸과 게시 조건은
references/record-kinds.md. - 본문 작성(Case·Concept) — 종류마다 무엇을 어떤 순서로 쓰는지는
references/writing-each-kind.md. 문법은references/body-syntax.md, 표·코드·그림은references/code-tables-diagrams.md. 문장은references/explaining.md. 문서군 전체의 리듬은references/ai-tells.md. 그림이 필요하면 손으로 그리지 말고technical-visualizer스킬로 만든다. 이미 쓴 문장이 AI가 쓴 것처럼 읽히면rewriting-technical-prose-naturally로 다시 쓴다. - 검사 — 둘 다 돌린다. 파서와 문장은 다른 것을 본다.
scripts/check_body.mjs— Case 본문이 Studio 파서를 통과하는지. 같은 파서를 그대로 부른다.rewriting-technical-prose-naturally/scripts/check_prose.mjs— 문장 규범. error 0 이 될 때까지 고친다. 칸 하나나 한 절만 고쳤으면--doc없이 부른다. 이어서style_profile.mjs로 문체 수치를 본다.
- 관계 연결 — Decision은 근거가 1개 이상 없으면 게시가 거절된다.
- Studio에서 확인 — 넣고 저장까지만 한 뒤 미리보기로 읽는다.
절차는
references/studio-draft-review.md. 게시하지 않는다. - 게시 — 고칠 것이 없을 때만. 못 채운 칸은 그 칸 아래에 표시된다.
보호 구간
수치, 날짜, 버전, 단위, 코드, 명령어, URL, 인용, 공식 명칭은 원문과 한 글자도 달라지면 안 된다. 측정하지 않은 값을 채우지 않는다 — 검증일은 실제로 확인한 날이다.
쓰지 않는 것
- 자료가 뒷받침하지 않는 선택 이유. 썼다는 사실을 왜 골랐는지로 바꾸지 않는다.
- 지어낸 경험·실패·감정. 자료에 없는 1인칭 서술.
- 가능성을 확정으로, 한 구조에서 본 것을 protocol 전체로 넓히기.
흔한 실패
| 실패 | 대응 |
|---|---|
| Reference 규칙에 코드블록 | Case로 옮겨 관계 연결 |
| 본문 밖 칸에 백틱 | 평문이다. 백틱을 뺀다 |
| 평문 칸에 쉼표 나열 | 이름 : 값으로 줄 나눔. 있음·없음은 o·x |
| 표 머리글이 명사뿐 | 질문으로. 비교 축은 전·후 시점으로 |
| 그림 안에 문장·숫자 | <text>는 이름만. 문장은 <desc>·옆 문단에 |
| 이름만 대고 넘어감 · 「역할이 다르다」로 끝냄 | 왜 있는지·왜 못 합치는지까지 |
| 산문에 내부 코드명 | 구조 이름으로. 번호는 표 축·식별자에만 |
**굵게** 남발 · 끊어 나열 · 되풀이 강조 |
한 절에 하나, 한 문단으로, 한 번만 |
~하는 것은 ~이다 · 「~한 것은 아니다」로 시작 |
번역투다. 문제 → 할 일 → 확인 |
싣는다·낸다·둘이 · 자리·떠안다 |
동작을 풀고, 비유 없이 그대로 |
| 읽는 법을 지시 | 「봐야 한다」·「여기까지다」 삭제 |
..?·~해보자 억지 구어체 |
명사구 제목으로. 본 것을 먼저 쓴다 |
| 문서마다 같은 문형·같은 길이 | references/ai-tells.md |
표를 :::table로 감쌈 |
그냥 파이프로 쓴다 |
 |
Asset으로 올려 /api/v1/public/media/… |
| Decision에 근거 없음 | 관계 1개 이상 연결 |
| 측정 안 한 검증일 | 비워 둔다 |
작성 후 references/review-checklist.md로 대조한다.