docs(TechLog): 글감 56개를 기록으로 쓴다

주제 13개 · Case 28 · Concept 5 · Reference 15 · Question 4 · Decision 4. 계약의 노드마다 종류가 요구하는 칸을 채우고, 본문이 있는 두 종류에는 SSOT 가 이미 그려 둔 도식 셋(value-boundaries · decision-path-404 · topic-variant-model)을 tech-log-studio/ 로 옮겨 붙였다. 새로 그린 그림은 없다. 검사 셋 전부 통과한다. check_body.mjs 56 편 중 본문이 있는 33 편 PASS check_prose.mjs 56 편 error 0 check_evidence.mjs --repo 포함 문제 없음 verify-tech-log-tree.py 프로젝트 5 · error 0 · warn 0 인용한 코드블록은 전부 SSOT 에서 찾아 대조했다. check_evidence.mjs 가 본문의 각 줄과 source 앵커와 계약 제목을 다시 확인한다. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-07 15:29:33 +09:00
parent 6955611439
commit f6c825e858
62 changed files with 6381 additions and 186 deletions
@@ -0,0 +1,78 @@
+---
+kind: CASE
+slug: an-error-message-that-guessed
+title: 서버는 하나를 답했는데 화면은 추측 셋을 출력했다
+topic: one-thing-many-names
+topicName: 같은 것이 화면마다 다른 이름
+project: TechLog
+status: 게시 전
+lastVerifiedOn: 2026-09-04
+sourceRevision: tech-log@2026-09-02
+source:
+  - final/document.md#§13.4
+---
+
+# 서버는 하나를 답했는데 화면은 추측 셋을 출력했다
+
+작업본 삭제가 실패하면 화면이 「게시됐거나, 참조하는 곳이 있거나, 누가 먼저 고쳤을 수 있습니다」라고 적었다. 세 가지 추측이다. 서버는 정확히 하나를 답하고 있었다.
+
+## 관계
+
+- **삭제를 막는 이유 다섯 가지가 전부 같은 한 문장으로 나온다**
+  이 화면 문구를 고친 뒤에도 남은 문제다.
+- **화면은 못 읽은 것을 없다고 말하지 않는다**
+  화면이 모르는 것을 말할 때의 짝이 되는 규칙이다.
+- **한 화면에 종류 이름이 아홉 개 떠 있었다 — 표가 여섯 벌이었다**
+  같은 시기에 문구를 한 곳으로 모은 사건이다.
+
+## 문제
+
+작업본 삭제가 실패하면 화면이 세 가지 추측을 나열했다.
+
+서버는 정확히 하나를 답하고 있었다 — 「이 기록을 참조하는 곳이 있어 삭제할 수 없습니다」.
+
+## 결론
+
+화면이 서버의 답을 쓰지 않고 자기가 가능한 원인을 나열하고 있었다.
+
+그래서 버전 충돌이 「사용 중」으로 읽혔다. 어떤 삭제는 되고 어떤 삭제는 안 되는 것을 지켜보는 작성자는 둘을 구분할 방법이 없었다.
+
+게이트웨이가 서버의 클라이언트 안전 메시지를 실어 나르고 화면이 그것을 보이게 했다.
+
+## 검증 환경
+
+tech-log-frontend : 1801414
+tech-log-backend : 857e6a9 — 삭제 거절 사유를 클라이언트 안전 메시지로 답함
+확인 방식 : 실패하는 삭제를 실제로 시도해 화면 문구와 서버 응답을 대조
+
+## 재현 조건
+
+1. 다른 기록이 참조하는 작업본을 지운다 — 서버가 참조 사유를 답한다
+2. 버전이 어긋난 상태로 작업본을 지운다 — 서버가 다른 사유를 답한다
+3. 두 경우의 화면 문구가 다른지 본다
+
+## 본문
+
+<!-- body:start -->
+
+## 화면이 세 가지를 추측했다
+
+화면 문구는 「게시됐거나, 참조하는 곳이 있거나, 누가 먼저 고쳤을 수 있습니다」였다. 세 가지 원인을 나열하고 어느 것인지는 말하지 않는다.
+
+서버는 하나를 답하고 있었다. 게이트웨이가 그 답을 버리고 화면이 자기 목록을 그렸다.
+
+## 무엇이 구분되지 않았나
+
+버전 충돌은 「누가 먼저 고쳤다」이고 참조 존재는 「사용 중」이다. 문구가 셋을 함께 적으므로 작성자는 둘을 구분할 수 없다.
+
+두 경우에 해야 할 일이 다르다. 버전 충돌이면 다시 받아서 지우면 되고, 참조가 있으면 그 참조를 먼저 풀어야 한다.
+
+## 서버의 답을 실어 나른다
+
+게이트웨이가 서버의 클라이언트 안전 메시지를 그대로 싣고 화면이 그것을 보인다. 서버가 답하지 않은 것은 화면이 만들지 않는다.
+
+## 확인하지 못한 것
+
+서버가 답하는 그 한 문장이 다섯 이유를 다 같은 말로 덮고 있다. 참조 검사가 다섯 테이블을 하나로 묶어 검사하기 때문이고, 그 문제는 아직 열려 있다.
+
+<!-- body:end -->
@@ -0,0 +1,99 @@
+---
+kind: CASE
+slug: nine-names-for-five-kinds
+title: 한 화면에 종류 이름이 아홉 개 떠 있었다 — 표가 여섯 벌이었다
+topic: one-thing-many-names
+topicName: 같은 것이 화면마다 다른 이름
+project: TechLog
+status: 게시 전
+lastVerifiedOn: 2026-09-04
+sourceRevision: tech-log@2026-09-02
+source:
+  - final/document.md#§13.1
+  - final/document.md#§13.5
+---
+
+# 한 화면에 종류 이름이 아홉 개 떠 있었다 — 표가 여섯 벌이었다
+
+홈 한 화면에 문서 종류 이름이 아홉 개 떠 있었다. 최근 기록 목록은 계약의 enum 이름을, 바로 아래 「종류별로 읽기」는 사람이 붙인 이름을 쓰고 있었다. 독자는 둘이 같은 것이라는 단서를 어디서도 받지 못했다. 원인은 종류 이름 표가 화면마다 복사되어 여섯 벌이었다는 것이다.
+
+## 관계
+
+- **종류 이름을 두 번 바꿨다 — 화면의 이름과 계약의 kind 를 갈랐다**
+  이 표를 한 곳으로 모은 뒤에 이름 자체를 다시 정한 기록이다.
+- **개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다**
+  같은 종류 목록이 코드 쪽에서 갈라진 사건이다.
+- **톤을 지적받으면 고쳐 쓰지 말고 어떤 말을 쓸지 묻는다**
+  같은 시기에 문구를 다룬 기준이다.
+
+## 문제
+
+홈 화면 하나에 종류 이름이 아홉 개 있었다.
+
+```text
+최근 기록 목록:      CASE · CONCEPT · OPEN QUESTION · REFERENCE
+바로 아래 「종류별로 읽기」: 검증 기록 · 동작 원리 · 적용 기준 · 열린 질문
+```
+
+두 목록이 같은 다섯 종류를 가리키는데 이름이 겹치지 않는다. 독자는 그 둘이 같은 것이라는 단서를 받지 못한다.
+
+## 결론
+
+종류 이름 표가 화면마다 복사되어 여섯 벌이었고, 그래서 갈라졌다.
+
+> 표가 화면마다 복사되어 **여섯 벌**이었고 그래서 갈라졌다: 같은 QUESTION 이 공개 화면에서 "Open Question", 작업본 목록과 게시 기록에서 "Question", 편집기 상태 줄에서 "QUESTION" 이었다. **쓰는 사람은 같은 문서를 화면마다 다른 이름으로 만난다.**
+
+종류에서 이름으로 가는 표 하나로 모았다.
+
+편집기 칸 이름도 공개 화면과 맞췄다. 쓰는 사람이 지금 채우는 칸이 공개 화면 어디로 가는지 외우지 않아도 된다.
+
+## 검증 환경
+
+tech-log-frontend : dc2fda7 · ca1cfa2 계열 · 82e992d
+확인 방식 : 한 화면에 동시에 뜨는 종류 이름을 세고, 표가 몇 벌인지 확인
+
+## 재현 조건
+
+1. 홈 화면을 열고 최근 기록 목록과 「종류별로 읽기」를 함께 본다
+2. 두 목록에서 같은 종류를 가리키는 이름을 대조한다
+3. 작업본 목록·게시 기록·편집기 상태 줄에서 같은 종류의 이름을 확인한다
+
+## 본문
+
+<!-- body:start -->
+
+## 한 화면에 아홉 개
+
+```text
+최근 기록 목록:      CASE · CONCEPT · OPEN QUESTION · REFERENCE
+바로 아래 「종류별로 읽기」: 검증 기록 · 동작 원리 · 적용 기준 · 열린 질문
+```
+
+두 목록이 세로로 붙어 있다. 위는 계약의 enum 이름을, 아래는 사람이 붙인 이름을 쓴다.
+
+이름을 바꾸기 전보다 나빠진 유일한 화면이었다. 바꾸기 전에는 양쪽이 다 enum 이름이라 적어도 같아 보였다.
+
+## 표가 여섯 벌이었다
+
+> 표가 화면마다 복사되어 **여섯 벌**이었고 그래서 갈라졌다: 같은 QUESTION 이 공개 화면에서 "Open Question", 작업본 목록과 게시 기록에서 "Question", 편집기 상태 줄에서 "QUESTION" 이었다. **쓰는 사람은 같은 문서를 화면마다 다른 이름으로 만난다.**
+
+## 표 하나로 모았다
+
+종류에서 표시 이름으로 가는 표를 하나 만들고 여섯 곳이 그것을 쓰게 했다. 종류가 늘면 그 표에 자리가 비었다고 컴파일러가 잡는다.
+
+## 편집기 칸 이름도 맞췄다
+
+같은 문제가 칸 이름에도 있었다. 편집기에서 「목적」이라 부른 칸이 공개 화면에서는 다른 이름으로 나왔다.
+
+```text
+목적      → 이 기준을 쓰는 이유       규칙   → 판단 기준
+적용 조건  → 적용할 때               예외   → 예외와 주의
+사실      → 확인한 사실              미지수 → 남은 미지수
+선택지    → 검토한 선택지
+```
+
+## 확인하지 못한 것
+
+이름을 바꾸기 전보다 나빠진 화면이 홈 하나였다는 것은 화면으로 확인했다. 다른 화면에서 두 이름이 같이 뜨는 곳을 전수로 세지는 않았다.
+
+<!-- body:end -->
@@ -0,0 +1,95 @@
+---
+kind: CASE
+slug: renaming-the-kinds-twice
+title: 종류 이름을 두 번 바꿨다 — 화면의 이름과 계약의 kind 를 갈랐다
+topic: one-thing-many-names
+topicName: 같은 것이 화면마다 다른 이름
+project: TechLog
+status: 게시 전
+lastVerifiedOn: 2026-09-04
+sourceRevision: tech-log@2026-09-02
+source:
+  - final/document.md#§13.2
+---
+
+# 종류 이름을 두 번 바꿨다 — 화면의 이름과 계약의 kind 를 갈랐다
+
+이 저장소의 종류 이름은 글을 담아 둔 방식의 이름이었다. 독자는 그 말을 배우고 나서야 목록을 읽을 수 있었고, 뜻풀이는 홈 바닥 2,000px 아래에 있었다. 이름이 하는 일을 말하게 바꿨다가, 그 안이 기술 기록의 톤에 비해 가벼워 문어체로 다시 세웠다.
+
+## 관계
+
+- **한 화면에 종류 이름이 아홉 개 떠 있었다 — 표가 여섯 벌이었다**
+  이 이름을 한 곳으로 모은 뒤에 이 변경이 왔다.
+- **톤을 지적받으면 고쳐 쓰지 말고 어떤 말을 쓸지 묻는다**
+  두 번째 안이 왜 필요했는지가 그 기준에 있다.
+- **slug 생성이 한글을 버려 주제 만들기가 간헐적으로 실패했다**
+  이름을 주소로 옮기는 다른 사건이다.
+
+## 문제
+
+종류 이름이 Case, Reference, Open Question 이었다. 이것은 글을 담아 둔 방식의 이름이다.
+
+독자는 그 말을 배우고 나서야 목록을 읽을 수 있었고, 정작 뜻풀이는 홈 바닥 2,000px 아래에 있었다.
+
+## 결론
+
+두 번 바꿨다.
+
+1차 : 이름이 하는 일을 말하게 했다 — 직접 해보니 · 다음에 쓸 기준 · 아직 모르는 것 · 어떻게 동작하나 · 이렇게 하기로
+2차 : 역할은 그대로 말하되 문어체로 다시 세웠다 — 검증 기록 · 적용 기준 · 열린 질문 · 동작 원리 · 설계 결정
+
+1차 안이 기술 기록의 톤에 비해 가벼웠다.
+
+계약의 kind 는 그대로 뒀다. 바꾸는 것은 화면에 보이는 이름뿐이다.
+
+## 검증 환경
+
+tech-log-frontend : a6413d0 → af5a6bb
+계약 : RecordKind 다섯 값은 변경 없음
+확인 방식 : 화면의 표시 이름과 계약의 kind 를 대조
+
+## 재현 조건
+
+1. 공개 화면에서 종류 배지와 「종류별로 읽기」의 이름을 본다
+2. 편집기의 새 문서 화면에서 같은 종류의 이름을 본다
+3. 계약의 kind 값과 대조한다
+
+## 본문
+
+<!-- body:start -->
+
+## 담아 둔 방식의 이름
+
+Case, Reference, Open Question 은 그 글을 어떤 형식에 담았는지를 말한다. 그 글이 독자에게 무엇을 주는지는 말하지 않는다.
+
+독자는 그 말을 먼저 배워야 목록을 읽을 수 있었다. 뜻풀이는 홈 바닥 2,000px 아래에 있었다.
+
+## 1차 — 하는 일을 말하게 했다
+
+```text
+Case → 직접 해보니        Reference → 다음에 쓸 기준
+Question → 아직 모르는 것  Concept → 어떻게 동작하나
+Decision → 이렇게 하기로
+```
+
+## 2차 — 문어체로 다시 세웠다
+
+1차 안이 기술 기록의 톤에 비해 가벼웠다. 역할은 그대로 말하되 문어체로 바꿨다.
+
+```text
+CASE → 검증 기록        CONCEPT → 동작 원리
+REFERENCE → 적용 기준    DECISION → 설계 결정
+QUESTION → 열린 질문
+```
+
+## 계약의 kind 는 그대로 뒀다
+
+바꾼 것은 화면에 보이는 이름이다. 계약의 `RecordKind` 는 다섯 값 그대로이고, 주소도 그대로다.
+
+표시 이름과 계약 값을 갈라 두면 이름을 다시 바꿀 때 계약을 건드리지 않아도 된다.
+
+## 확인하지 못한 것
+
+바꾼 이름이 읽기 쉬워졌는지는 재지 않았다. 1차 안이 가볍다는 판단은 사용자의 지적이고 측정이 아니다.
+
+<!-- body:end -->