refactor: 분리되어 관리하고 있던 문서 시스템을 하나로 통일

2026-09-04 18:56:01 +09:00
parent 4b9e7148b5
commit 43bccd08a8
121 changed files with 2861 additions and 534 deletions
@@ -11,6 +11,7 @@ Tech Log Studio에 올릴 기록을 쓰는 스킬. Case · Concept · Reference
 | `references/record-kinds.md` | 다섯 종류의 칸·상한·게시 조건 |
 | `references/from-ssot-to-records.md` | 긴 글에서 글감을 뽑는 기준과 `tech-log-tree.json` |
 | `references/writing-each-kind.md` | 종류마다 무엇을 어떤 순서로 쓰나 |
+| `templates/*.md` | 종류별 빈 틀. 복사해서 채운다 |
 | `references/body-syntax.md` | Case 본문의 허용·금지 문법 |
 | `references/code-tables-diagrams.md` | 코드블록·표·SVG·이미지 |
 | `references/explaining.md` | 설명의 깊이와 말투 |
@@ -108,3 +108,16 @@
 - [ ] 게시 후 공개 페이지를 열어 표·코드·그림이 의도대로 나오는지 봤다

 마지막 항목을 건너뛰지 않는다. 저장은 통과해도 공개 화면에서 다르게 보이는 경우가 있다.
+
+## 분석에서 뽑아 쓸 때 (document-detail 계약)
+
+- [ ] 이 글감의 `readiness` 가 글을 써도 되는 상태인가
+- [ ] 모든 실질 주장이 분석·출처·증거 앵커 하나로 되짚어지는가
+- [ ] 추론을 관측한 것처럼 적지 않았는가
+- [ ] 로컬·테스트에서 본 것을 운영 사실로 올리지 않았는가
+- [ ] Case 가 개념 설명이 아니라 구체적인 사건·검증 절차인가
+- [ ] Reference 가 짝이 되는 Case 의 서사를 통째로 되풀이하지 않는가
+- [ ] Decision 에 근거가 하나 이상 있고, 무엇을 보고 정했는지가 적혀 있는가
+- [ ] 지어낸 경험·실패·동기·감정이 없는가
+- [ ] 그림이 실제 asset 파일을 가리키고, 있어야 할 이유가 있는가
+- [ ] 그림이 관측하지 않은 사건을 만들어 내지 않았는가
@@ -0,0 +1,119 @@
+# Root Tree Contract
+
+The root tree is the explicit boundary between deep project analysis and Tech Log record generation.
+
+## Required document header
+
+A root tree records:
+
+- `schemaVersion`
+- `project`
+- `sourceDocument`
+- `sourceDocumentSha256`
+- `sourceRevision`
+- `generatedAt`
+
+The hash/revision prevents a scheduled generator from treating a tree derived from old code as current.
+
+## Required human-readable tree
+
+Each Topic has a title, slug, and four branches:
+
+```text
+PROJECT
+<project>
+
+TOPIC
+<Topic title>
+<topic-slug>
+
+├── CASE
+├── REFERENCE
+├── OPEN QUESTION
+└── DECISION
+```
+
+Empty branches are allowed. Do not manufacture nodes to fill all four kinds.
+
+## Node source contract
+
+Every candidate includes a specification after the human-readable tree.
+
+### Case
+
+Required:
+
+- `slug`
+- `readiness`
+- one or more `source` anchors
+- `classification` explaining the concrete incident/experiment/diagnosis
+- relevant code/evidence when the conclusion depends on them
+- `missing-verification`
+- `relations`
+
+A Case with `NEEDS_EVIDENCE`, `BLOCKED`, or `REJECTED` is not generated.
+
+### Reference
+
+Required:
+
+- `slug`
+- `readiness`
+- `source`
+- `classification` explaining the reusable criterion
+- `scope`
+- `exceptions`
+- `relations`
+
+A Reference must be useful beyond retelling one Case. If removing the originating project's names leaves no rule, it is probably still a Case.
+
+### Open Question
+
+Required:
+
+- `slug`
+- `readiness: OPEN`
+- `source`
+- `known`
+- `unknown`
+- `next-verification`
+- `decision-criterion`
+- `relations`
+
+Do not generate a Question when the detailed analysis already contains a verified answer. Move the material to Case/Reference/Decision as appropriate and update the tree first.
+
+### Decision
+
+Required:
+
+- `slug`
+- `readiness`
+- `decision-status`
+- `source`
+- `decision-evidence`
+- `grounds`
+- `classification`
+- `relations`
+
+`decision-status` is one of `PROPOSED`, `ADOPTED`, `SUPERSEDED`, `NOT_DECIDED`. A `NOT_DECIDED` candidate uses `NEEDS_DECISION` and is not generated as a Decision.
+
+## Readiness semantics
+
+| readiness | meaning | generation |
+|---|---|---|
+| `READY` | grounded enough for the kind | allowed |
+| `NEEDS_EVIDENCE` | material assertion still lacks verification | blocked |
+| `NEEDS_DECISION` | direction sounds plausible but project has not decided | blocked |
+| `OPEN` | legitimate unresolved Question | allowed as Open Question |
+| `BLOCKED` | sources are incomplete or contradictory | blocked |
+| `REJECTED` | should not become a record | blocked |
+
+## Derivation rules
+
+1. Start from sections and evidence already present in detailed analysis; do not begin by brainstorming titles.
+2. Prefer several narrowly grounded Cases over one broad Case that combines unrelated incidents.
+3. Extract References only after identifying the invariant/selection criterion that survives outside the incident.
+4. Extract Questions from explicit uncertainty, missing verification, operational unknowns, or conflicting constraints.
+5. Extract Decisions only from explicit project choice evidence: ADR, commit/history, configuration plus recorded rationale, issue/PR decision, or user-supplied decision record.
+6. A node may relate to several siblings, but each record has one primary purpose.
+7. If new runtime evidence changes the answer, update detailed analysis and regenerate/review the tree before editing downstream records.
@@ -0,0 +1,49 @@
+---
+id: <Studio 가 준 uuid. 아직 없으면 빈 값>
+kind: CASE
+slug: <slug>
+title: <제목>
+topic: <주제 이름>
+project: <프로젝트 이름>
+status: 게시 전
+studio: "<편집 화면 주소. 아직 없으면 빈 값>"
+lastVerifiedOn: <실제로 확인한 날 또는 빈 값>
+assets:
+  - key: <본문의 :::evidence key 와 같은 값>
+    file: <../../../final/assets/… 상대 경로>
+evidence:
+  - <../../../final/evidence/raw/… 상대 경로>
+---
+
+# <title>
+
+<summary>
+
+## 관계
+
+- **<related record>**
+  <why related>
+
+## 문제
+
+<concrete observed problem and scope>
+
+## 결론
+
+<bounded conclusion supported by evidence>
+
+## 검증 환경
+
+<plain text exact environment>
+
+## 재현 조건
+
+<ordered concrete conditions/steps>
+
+## 본문
+
+<!-- body:start -->
+
+<rich Case body>
+
+<!-- body:end -->
@@ -0,0 +1,43 @@
+---
+id: <Studio 가 준 uuid. 아직 없으면 빈 값>
+kind: CONCEPT
+slug: <slug>
+title: <제목>
+topic: <주제 이름>
+project: <프로젝트 이름>
+status: 게시 전
+studio: "<편집 화면 주소. 아직 없으면 빈 값>"
+basisVersion: <무엇을 보고 썼는지. 예 Keycloak 26.7.0 · oidc-client-ts 3.3.0>
+assets:
+  - key: <본문의 :::evidence key 와 같은 값>
+    file: <../../../final/assets/… 상대 경로>
+evidence:
+  - <../../../final/evidence/raw/… 상대 경로>
+---
+
+# <제목>
+
+<요약. 이 개념이 무엇을 어떻게 하는지 한 문단>
+
+## 관계
+
+- **<이어지는 기록>**
+  <왜 이어지는지>
+
+## 본문
+
+<!-- body:start -->
+
+## <무엇이 무엇을 주고받나>
+
+<첫 절은 참여자와 오가는 것을 세운다>
+
+## <단계마다 실제로 일어나는 일>
+
+## <그 설계가 막지 않는 것>
+
+## <지금 확인한 범위>
+
+<규격이 정한 것과 이 구현이 그렇게 한 것을 구분한다. 「확인했다」는 Case 의 말이라 쓰지 않는다>
+
+<!-- body:end -->
@@ -0,0 +1,37 @@
+---
+id: <Studio 가 준 uuid. 아직 없으면 빈 값>
+kind: PROJECT_DECISION
+slug: <slug>
+title: <제목>
+topic: <주제 이름>
+project: <프로젝트 이름>
+status: 게시 전
+studio: "<편집 화면 주소. 아직 없으면 빈 값>"
+decisionStatus: PROPOSED
+assets:
+  - key: <본문의 :::evidence key 와 같은 값>
+    file: <../../../final/assets/… 상대 경로>
+evidence:
+  - <../../../final/evidence/raw/… 상대 경로>
+---
+
+# <title>
+
+<summary>
+
+## 근거
+
+- **<Case or Reference>**
+  <how it grounds this decision>
+
+## 결정문
+
+<the actual project choice>
+
+## 판단 이유
+
+<only rationale explicitly supported by decision evidence>
+
+## 영향
+
+- <grounded consequence/trade-off>
@@ -0,0 +1,51 @@
+---
+id: <Studio 가 준 uuid. 아직 없으면 빈 값>
+kind: QUESTION
+slug: <slug>
+title: <제목>
+topic: <주제 이름>
+project: <프로젝트 이름>
+status: 게시 전
+studio: "<편집 화면 주소. 아직 없으면 빈 값>"
+questionStatus: OPEN
+assets:
+  - key: <본문의 :::evidence key 와 같은 값>
+    file: <../../../final/assets/… 상대 경로>
+evidence:
+  - <../../../final/evidence/raw/… 상대 경로>
+---
+
+# <title>
+
+<summary of unresolved issue>
+
+## 관계
+
+- **<related record>**
+  <why related>
+
+## 사실
+
+- <grounded fact>
+
+## 가정
+
+- <explicit assumption, if any>
+
+## 미지수
+
+- <unknown>
+
+## 제약
+
+- <constraint>
+
+## 선택지
+
+### 1. <grounded candidate, only when it really exists>
+
+<what is known and what must be checked>
+
+## 다음 검증
+
+1. <next concrete verification>
@@ -0,0 +1,46 @@
+---
+id: <Studio 가 준 uuid. 아직 없으면 빈 값>
+kind: REFERENCE
+slug: <slug>
+title: <제목>
+topic: <주제 이름>
+project: <프로젝트 이름>
+status: 게시 전
+studio: "<편집 화면 주소. 아직 없으면 빈 값>"
+assets:
+  - key: <본문의 :::evidence key 와 같은 값>
+    file: <../../../final/assets/… 상대 경로>
+evidence:
+  - <../../../final/evidence/raw/… 상대 경로>
+---
+
+# <title>
+
+<summary>
+
+## 관계
+
+- **<related record>**
+  <why related>
+
+## 목적
+
+<why this reusable criterion exists>
+
+## 규칙
+
+### 1. <rule title>
+
+<plain-text rule>
+
+## 적용 조건
+
+- <condition>
+
+## 예외
+
+- <exception or explicitly none>
+
+## 예시
+
+- <plain-text example>