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,85 @@
+---
+kind: CASE
+slug: the-guard-worked-and-i-did-not-run-it
+title: 가드는 작동했는데 제가 그것을 돌리지 않아 두 번 새어 나갔다
+topic: when-a-guard-can-be-trusted
+topicName: 가드를 언제 믿을 수 있는가
+project: TechLog
+status: 게시 전
+lastVerifiedOn: 2026-09-04
+sourceRevision: tech-log@2026-09-02
+source:
+  - final/document.md#§7.5
+  - final/document.md#§8.5
+  - final/document.md#§17.4
+---
+
+# 가드는 작동했는데 제가 그것을 돌리지 않아 두 번 새어 나갔다
+
+가드를 넣고 제가 그것을 돌리지 않아 두 번 새어 나갔다. 화면 테스트를 다른 명령이 돌리는데 그 명령을 안 돌려서 23건이 빨간 채로 여러 커밋을 지나갔고, 주제 화면 셋을 더하면서 CI 게이트 기준값을 빠뜨려 게이트가 빨간 채로 여러 커밋을 지나갔다.
+
+## 관계
+
+- **가드는 결함을 되돌려 실제로 멈추는 것을 확인한 뒤 커밋한다**
+  가드가 무엇을 잡는지 확인하는 기준이다.
+- **배포 전에 사람이 돌려야 하는 것과 그 함정**
+  이 사건 뒤에 목록으로 굳혔다.
+- **라우트 하나가 건드리는 여덟 곳과, 그것들이 우는 시점**
+  두 번째 사건에서 빠뜨린 목록이 그 기록에 있다.
+
+## 문제
+
+가드는 있었고 작동했다. 실행되지 않았다.
+
+화면 테스트는 단위 테스트 명령이 아니라 별도 명령이 돌린다. 그 명령을 돌리지 않으면 화면 테스트가 빨간 것을 아무도 모른다.
+
+CI 게이트도 마찬가지였다. 라우트를 더하면서 기준값을 함께 올리지 않으면 게이트가 거절하는데, 그 게이트가 빨간 것을 확인하지 않은 채 커밋을 이어 갔다.
+
+## 결론
+
+두 번 다 가드가 아니라 실행이 빠진 것이었다.
+
+첫 번째 : 화면 테스트를 별도 명령이 돌리는데 그것을 안 돌려 23건이 빨간 채로 여러 커밋을 지나갔다
+두 번째 : 주제 화면 셋을 더하면서 게이트 기준값을 빠뜨려 게이트가 빨간 채로 여러 커밋을 지나갔다
+
+> **가드는 CI 에 묶여야 의미가 있습니다.** 사람이 기억해서 돌리는 가드는 절반만 존재합니다.
+
+## 검증 환경
+
+tech-log-frontend : fd73bc8 · fe6b56a
+명령 : check:types · lint · test:unit · test:component · test:tech-log 다섯
+확인 방식 : 다섯 명령을 각각 돌려 어느 것이 무엇을 잡는지 확인
+
+## 재현 조건
+
+1. 화면 테스트가 깨지는 변경을 하나 넣는다
+2. 단위 테스트 명령만 돌린다 — 통과한다
+3. 화면 테스트 명령을 돌린다 — 깨진다
+
+## 본문
+
+<!-- body:start -->
+
+## 화면 테스트를 돌리지 않았다
+
+> 화면 테스트는 `test:unit` 이 아니라 `test:tech-log` 가 돌린다. 그것을 돌리지 않아 위 두 결함과, 의도한 변경에 고정돼 있던 단언들이 **23건 빨간 채로 여러 커밋을 지나갔다.**
+
+23건 중에는 실제 결함을 잡은 것도 있고 의도한 변경에 고정된 단언도 있었다. 둘을 구분하려면 그 명령을 돌려야 하는데, 돌리지 않으니 둘 다 그대로 남았다.
+
+## 게이트 기준값을 빠뜨렸다
+
+주제 화면 셋을 더할 때 CI 게이트가 요구하는 기준값 셋을 함께 올리지 않았다. 게이트는 정확히 그것을 거절한다.
+
+게이트가 빨간 채로 여러 커밋을 지나갔고, 결정 링크 404 를 고치던 커밋에서야 함께 맞췄다.
+
+## 가드가 아니라 실행이 빠졌다
+
+두 번 다 가드는 정확했다. 화면 테스트는 실제 결함을 잡았고 게이트는 기준값이 어긋난 것을 정확히 거절했다.
+
+> **가드는 CI 에 묶여야 의미가 있습니다.** 사람이 기억해서 돌리는 가드는 절반만 존재합니다.
+
+## 확인하지 못한 것
+
+다섯 명령을 CI 에 묶는 작업은 하지 않았다. 지금 남은 것은 메모리와 배포 전 검증 목록이다.
+
+<!-- body:end -->
@@ -0,0 +1,68 @@
+---
+kind: REFERENCE
+slug: revert-the-defect-and-watch-the-guard-fail
+title: 가드는 결함을 되돌려 실제로 멈추는 것을 확인한 뒤 커밋한다
+topic: when-a-guard-can-be-trusted
+topicName: 가드를 언제 믿을 수 있는가
+project: TechLog
+status: 게시 전
+verifiedOn: 2026-09-04
+evidence:
+  - ../../../final/evidence/raw/guards/guards-actually-fail.txt
+sourceRevision: tech-log@2026-09-02
+source:
+  - final/document.md#§15
+  - final/document.md#§3.5
+  - final/document.md#§17.4
+---
+
+# 가드는 결함을 되돌려 실제로 멈추는 것을 확인한 뒤 커밋한다
+
+가드를 넣었다는 것과 그 가드가 무엇을 잡는다는 것은 다르다. 결함을 되돌려 실제로 빨개지는 것을 확인한 뒤에 커밋한다. 확인하지 않은 가드는 그 결함이 원래 없었는지 검사가 안 도는지 구별되지 않는다.
+
+## 관계
+
+- **가드는 작동했는데 제가 그것을 돌리지 않아 두 번 새어 나갔다**
+  가드가 정확해도 돌리지 않으면 소용없다는 사건이다.
+- **매번 우는 검사는 읽히지 않는다 — 기대된 실패는 조건을 적어 빼고 나머지는 전부 실패시킨다**
+  가드가 늘 빨간 상태로 남는 다른 실패 모양이다.
+- **이음매마다 그 이음매를 실제로 지나는 검사를 하나씩 둔다**
+  어디에 가드를 둘지를 다루는 기준이다.
+
+## 목적
+
+무엇도 잡지 못하는 가드가 초록불로 남는 것을 막는다. 이 상태는 가드가 있는 것과 화면에서 구분되지 않는다.
+
+## 규칙
+
+**결함을 되돌려 그 가드가 실제로 멈추는 것을 확인한 뒤 커밋한다**
+계약에서 값을 빼고 대조 검사가 빨개지는지 본다. 매핑을 떼어 보고 그 연산 하나를 짚는지 본다.
+
+**가드가 짚는 대상이 하나인지 본다**
+전부를 짚으면 어디가 문제인지 알 수 없고, 결과가 곧 읽히지 않는다.
+
+**되돌릴 수 없는 것은 현재 상태를 대신 증거로 남긴다**
+이미 마이그레이션으로 고친 데이터는 실패 상태를 다시 만들 수 없다. 그럴 때는 지금 고쳐져 있다는 것을 남긴다.
+
+**가드를 CI 에 묶는다**
+사람이 기억해서 돌리는 가드는 절반만 존재한다.
+
+## 적용 조건
+
+재발 방지로 넣는 테스트·아키텍처 규칙·CI 게이트. 결함을 고치는 커밋에서 함께 넣을 때 걸린다.
+
+## 예외
+
+결함을 되돌릴 수 없는 것 — 이미 마이그레이션으로 고친 데이터, 지난 배포에서만 나던 상태 — 은 현재 상태가 고쳐져 있음을 대신 증거로 남긴다.
+
+기존 가드를 옮기거나 이름만 바꾸는 변경은 되돌려 확인하지 않아도 된다. 다만 옮긴 뒤에 한 번은 돌린다.
+
+## 예시
+
+가드 셋을 각각 결함으로 되돌려 실제로 빨개지는 것을 확인한 기록을 남겼다.
+
+계약에서 CONCEPT 을 빼자 백엔드의 계약 대조 테스트가 빨개졌다.
+
+매핑을 떼어 보고 계약 대조 테스트가 그 연산 하나를 정확히 짚는 것을 확인했다.
+
+굵기 선언을 빼 보고 제목 급 검사가 실제로 멈추는 것을 확인했다.
@@ -0,0 +1,71 @@
+---
+kind: REFERENCE
+slug: what-a-person-must-run-before-deploying
+title: 배포 전에 사람이 돌려야 하는 것과 그 함정
+topic: when-a-guard-can-be-trusted
+topicName: 가드를 언제 믿을 수 있는가
+project: TechLog
+status: 게시 전
+verifiedOn: 2026-09-04
+sourceRevision: tech-log@2026-09-02
+source:
+  - final/document.md#§15.4
+  - final/document.md#§12.3
+  - final/document.md#§12.7
+  - final/document.md#§12.8
+  - final/document.md#§16.6
+---
+
+# 배포 전에 사람이 돌려야 하는 것과 그 함정
+
+CI 에 묶이지 않은 검증이 남아 있으면 그것을 돌리는 것은 사람이다. 다섯 명령을 다 돌려야 하고, 그중 둘은 순서와 환경 때문에 그냥 돌리면 틀린 답을 준다.
+
+## 관계
+
+- **가드는 작동했는데 제가 그것을 돌리지 않아 두 번 새어 나갔다**
+  이 목록이 필요해진 사건이다.
+- **npx tsc --noEmit 이 한 파일도 검사하지 않고 성공했다**
+  목록의 첫 줄이 왜 그 명령이 아닌지가 그 기록에 있다.
+- **레지스트리 없이 tar 를 import 하는 배포 경로**
+  빌드 산출물에 커밋 해시가 들어가는 이유가 그 개념에 있다.
+
+## 목적
+
+배포 전에 돌려야 하는 것을 사람이 기억에 의존해 고르는 것을 막는다. 두 번 빠뜨려 결함이 배포까지 갔다.
+
+## 규칙
+
+**프론트는 다섯 개를 다 돌린다**
+타입 검사 · lint · 단위 테스트 · 컴포넌트 테스트 · 화면 테스트다. 화면 테스트는 단위 테스트 명령이 돌리지 않는다.
+
+**타입 검사는 프로젝트를 순회하는 명령으로 돌린다**
+루트 tsconfig 를 직접 부르는 명령은 한 파일도 검사하지 않고 성공한다.
+
+**백엔드는 커밋한 뒤에 빌드한다**
+빌드 산출물 이름에 커밋 해시가 들어간다. 작업 트리가 더러우면 해시가 달라져 stale 산출물 검사가 멈춘다.
+
+**테스트를 npm 이나 npx 로 감싸 돌리지 않는다**
+`npm_config_*` 환경 변수가 설정되어 CI 워크플로 생성 테스트가 실패한다. 그 변수를 지우고 실행기를 직접 부른다.
+
+## 적용 조건
+
+CI 에 묶이지 않은 검증이 남아 있는 저장소에서 배포 직전에 하는 일.
+
+## 예외
+
+CI 가 그 명령을 돌리면 이 목록에서 뺀다. 사람이 기억해서 돌리는 가드는 절반만 존재한다.
+
+환경 때문에 실패하는 것은 실패로 세지 않는다. 하위 프로세스를 띄우는 세 케이스는 이 환경에서 실패하고 같은 리비전의 다른 실행에서도 똑같이 재현되므로 코드 변경과 무관하다.
+
+## 예시
+
+프론트 다섯 명령 :
+npm run check:types
+npm run lint
+단위 · 컴포넌트 · 화면 테스트
+
+백엔드 : 커밋한 뒤 stale 산출물을 지우고 빌드한다. 이 순서를 몰라 두 번 헤맸다.
+
+설계 패키지 : 계약 자체의 유효성 · 세 계약 사이의 정합 · 프론트와 백엔드가 아는 종류와 오류 코드가 같은지, 셋을 돌린다.
+
+테스트 JVM 힙이 기본값이면 컨텍스트 캐시와 아키텍처 검사와 컨테이너가 겹치면서 메모리가 모자란다. 증상이 테스트 실패가 아니라 실행기를 완료할 수 없다는 메시지라 원인을 가린다.