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,62 @@
+---
+kind: REFERENCE
+slug: do-not-draw-a-link-that-does-not-resolve
+title: 서버가 준 주소는 라우트 표에 맞춰 보고, 맞는 라우트가 없으면 링크로 그리지 않는다
+topic: addresses-frozen-at-publish-time
+topicName: 주소가 만들어지고 굳어지는 곳
+project: TechLog
+status: 게시 전
+verifiedOn: 2026-09-04
+sourceRevision: tech-log@2026-09-02
+source:
+  - final/document.md#§9.2
+---
+
+# 서버가 준 주소는 라우트 표에 맞춰 보고, 맞는 라우트가 없으면 링크로 그리지 않는다
+
+주소를 서버가 만들어 내보내고 화면이 그대로 링크로 그리면, 그 주소가 틀렸다는 것은 방문자만 안다. 화면 코드 어디에도 그 주소가 없기 때문이다. 만드는 쪽과 그리는 쪽 양쪽에서 라우트 표와 맞춘다.
+
+## 관계
+
+- **계약은 앵커라고 적었고 만드는 쪽은 경로를 만들었다**
+  이 기준의 근거 사건이다.
+- **catch-all 라우트는 nginx 패턴으로 번역하지 않는다**
+  엣지의 404 가 감사에 남아야 이 기준이 성립한다.
+- **라우트에 딸린 목록은 라우트 계약에서 유도하고, 유도할 수 없는 것은 대조 검사를 둔다**
+  라우트 표가 어디서 오는지가 그 기준에 있다.
+
+## 목적
+
+서버가 만든 주소가 열리지 않는 것을 방문자보다 먼저 잡는다. 이 부류는 화면 코드에 흔적이 없어 저장소 안의 링크 리터럴을 훑는 감사로는 잡히지 않는다.
+
+## 규칙
+
+**만드는 쪽에서 생성한 경로를 공개 라우트 패턴에 맞춘다**
+종류마다 만들어 낸 주소가 실제 라우트에 걸리는지 백엔드 테스트가 본다.
+
+**그리는 쪽에서 서버가 준 주소를 라우트 표에 맞추고, 맞는 라우트가 없으면 링크로 그리지 않는다**
+같은 부류가 또 생겨도 방문자가 404 를 만나지는 않는다.
+
+**주소를 고쳤으면 이미 저장된 행도 함께 고친다**
+주소가 게시 시점에 굳어져 저장되면 코드만 고쳐도 기존 링크는 깨진 채 남는다.
+
+**배포 뒤 서버가 내보내는 주소를 전수로 훑는다**
+저장소를 훑는 감사와 다른 것을 본다. 실제로 나가는 주소는 DB 에 있다.
+
+## 적용 조건
+
+주소를 서버가 만들어 내보내고 화면이 그대로 링크로 그리는 구조. 게시 시점에 주소가 굳어져 저장되면 특히 걸린다.
+
+## 예외
+
+외부 주소는 라우트 표에 없으므로 이 대조의 대상이 아니다.
+
+그리는 쪽에만 가드를 두면 링크가 아예 그려지지 않는 것으로 끝나고 원인이 남는다. 만드는 쪽에도 같은 검사를 둔다.
+
+## 예시
+
+결정 링크가 404 였다. 계약은 앵커라고 적었고 만드는 두 곳이 경로를 만들었다.
+
+배포 후 서버가 내보내는 주소 26개와 주제·축 9개를 더해 35개 전부 200 인 것을 확인했다.
+
+저장소 안의 링크 리터럴을 훑는 감사로는 이 결함이 잡히지 않았다. 그 주소는 코드에 없다.
@@ -0,0 +1,59 @@
+---
+kind: REFERENCE
+slug: write-down-what-would-undo-a-workaround
+title: 우회를 남길 때는 되돌릴 조건을 함께 적는다
+topic: addresses-frozen-at-publish-time
+topicName: 주소가 만들어지고 굳어지는 곳
+project: TechLog
+status: 게시 전
+verifiedOn: 2026-09-04
+sourceRevision: tech-log@2026-09-02
+source:
+  - final/document.md#§9.4
+---
+
+# 우회를 남길 때는 되돌릴 조건을 함께 적는다
+
+그 화면이 줄 수 있는 것이 아직 비어 있어 링크를 다른 곳으로 돌린 적이 있다. 우회 자체는 틀리지 않았다. 문제는 우회를 남겨 두면 「왜 이 링크가 저기로 가지?」라는 질문이 계속 남는다는 것이다. 우회할 때 되돌릴 조건을 함께 적는다.
+
+## 관계
+
+- **축 링크가 자기 자신을 가리켰고, 고친 뒤에는 백엔드를 먼저 배포했다**
+  같은 주제 링크를 다루며 이 기준이 나왔다.
+- **홈의 비교 구역이 세 번 바뀌었다**
+  단계마다 무엇을 고치려 했는지 적어 둔 다른 예다.
+- **새 라우트는 프론트엔드를 먼저 배포한다**
+  같은 사건에서 나온 짝이 되는 결정이다.
+
+## 목적
+
+임시 조치가 영구 구조로 굳는 것을 막는다. 되돌릴 조건이 적혀 있지 않으면 다음 사람이 그 우회를 설계로 읽는다.
+
+## 규칙
+
+**우회를 넣는 커밋에 되돌릴 조건을 적는다**
+무엇이 채워지면 되돌리는지 한 줄로 적는다. 그 조건이 충족됐을 때 실제로 되돌린다.
+
+**우회할 때 무엇이 비어 있어서 우회하는지 함께 적는다**
+채울 것이 없어서 돌린 것과 구조상 그쪽이 맞아서 돌린 것은 다르다.
+
+**되돌릴 생각이 없으면 우회가 아니라 결정으로 적는다**
+그때는 조건이 아니라 근거와 감수한 비용을 적는다.
+
+## 적용 조건
+
+그 화면이 줄 수 있는 것이 아직 비어 있어 링크나 흐름을 다른 곳으로 돌릴 때.
+
+## 예외
+
+되돌릴 생각이 없는 영구 변경은 우회가 아니다. 조건 대신 근거를 적는다.
+
+조건을 적을 수 없으면 그것은 우회가 아니라 아직 정하지 않은 것이다. 열린 질문으로 남긴다.
+
+## 예시
+
+주제 화면이 주제 셋을 하드코딩해 두고 있어 실제 주제는 무엇이든 404 였다. 그때 주제 페이지를 채우는 대신 링크를 탐색 필터로 돌렸다.
+
+돌린 이유는 그 페이지만 줄 수 있는 것 — 설명, 범위, 선별한 대표 기록 — 이 전부 비어 있었고 Studio 에 주제 설명을 쓸 칸조차 없었기 때문이다.
+
+그 조건을 커밋 메시지에 적었고, 주제 화면을 계약에 잇고 하드코딩을 없앤 뒤 링크를 곧장 주제 화면으로 되돌렸다.