refactor: 문서 사람처럼 작성하기

This commit is contained in:
donghyeon-ka
2026-09-22 18:05:20 +09:00
parent 8f518175f6
commit 6b483a1e63
68 changed files with 550 additions and 389 deletions
@@ -17,7 +17,7 @@ source:
새 라우트를 여는 변경은 프론트엔드를 먼저 배포한다. nginx 설정이 라우트 계약에서 생성되므로, 프론트가 배포되기 전까지 그 경로는 엣지에서 404 다. 백엔드를 먼저 배포하면 서버는 이미 그 주소를 내보내고 사용자는 전부 404 인 화면을 본다.
## 근거
## 백엔드를 먼저 배포하면 아직 없는 프론트 라우트를 응답할 수 있다
- **축 링크가 자기 자신을 가리켰고, 고친 뒤에는 백엔드를 먼저 배포했다**
이 순서를 정하게 된 사건이다. 반대 순서로 배포해 사용자가 네 링크 전부 404 인 화면을 봤다.
@@ -26,11 +26,11 @@ source:
- **catch-all 라우트는 nginx 패턴으로 번역하지 않는다**
이 순서가 필요해진 이유가 그 결정에 있다.
## 결정문
## 새 공개 라우트는 프론트엔드를 먼저 배포한다
새 공개 라우트를 여는 변경은 프론트엔드를 먼저 배포하고, 그 주소를 내보내는 백엔드 변경을 다음 배포에 넣는다.
## 판단 이유
## 라우트가 실제로 서빙된 뒤 서버가 그 주소를 내보내게 한다
nginx 설정은 라우트 계약에서 생성된다. 프론트 이미지가 배포되기 전까지 그 경로는 서빙 패턴에 없고, 엣지에서 404 로 끝난다.
@@ -38,7 +38,7 @@ nginx 설정은 라우트 계약에서 생성된다. 프론트 이미지가 배
catch-all 을 서빙 패턴으로 번역하지 않기로 했으므로 이 구간이 soft 200 으로 덮이지 않는다.
## 영향
## 배포 순서 검증이 라우트 계약의 일부가 된다
새 주소를 내보내는 백엔드 변경이 한 배포 늦게 나간다. 두 저장소를 한 번에 배포하고 싶은 변경에서 그 사이가 벌어진다.
@@ -16,7 +16,7 @@ source:
주소를 서버가 만들어 내보내고 화면이 그대로 링크로 그리면, 그 주소가 틀렸다는 것은 방문자만 안다. 화면 코드 어디에도 그 주소가 없기 때문이다. 만드는 쪽과 그리는 쪽 양쪽에서 라우트 표와 맞춘다.
## 관계
## 서버가 내려준 주소와 실제 공개 라우트는 함께 검증한다
- **계약은 앵커라고 적었고 만드는 쪽은 경로를 만들었다**
이 기준의 근거 사건이다.
@@ -25,11 +25,11 @@ source:
- **라우트에 딸린 목록은 라우트 계약에서 유도하고, 유도할 수 없는 것은 대조 검사를 둔다**
라우트 표가 어디서 오는지가 그 기준에 있다.
## 목적
## 존재하지 않는 주소를 링크로 그리지 않는다
서버가 만든 주소가 열리지 않는 것을 방문자보다 먼저 잡는다. 이 부류는 화면 코드에 흔적이 없어 저장소 안의 링크 리터럴을 훑는 감사로는 잡히지 않는다.
## 규칙
## 렌더링 전에 route contract와 주소를 대조한다
### 1. 만드는 쪽에서 생성한 경로를 공개 라우트 패턴에 맞춘다
@@ -47,20 +47,20 @@ source:
저장소를 훑는 감사와 다른 것을 본다. 실제로 나가는 주소는 DB 에 있다.
## 적용 조건
## 서버가 링크 대상 URL이나 path를 직접 내려줄 때
- 주소를 서버가 만들어 내보내고 화면은 받은 문자열을 링크로 그릴 때
- 게시 시점에 주소가 굳어져 저장되는 구조일 때. 코드만 고치면 이미 저장된 행이 깨진 채 남는다
- 공개 라우트를 더하거나 지워 주소의 모양이 바뀔 때
- 배포 뒤 서버가 내보내는 주소를 전수로 훑을 때
## 예외
## 현재 화면의 anchor처럼 별도 상세 route가 없는 경우
- 외부 주소는 라우트 표에 없으므로 이 대조의 대상이 아니다.
- 그리는 쪽에만 가드를 두면 링크가 아예 그려지지 않는 것으로 끝나고 원인이 남는다. 만드는 쪽에도 같은 검사를 둔다.
## 예시
## 결정 목록과 축 링크의 공개 주소
- 결정 링크가 404 였다. 계약은 앵커라고 적었고 만드는 두 곳이 경로를 만들었다.
@@ -16,7 +16,7 @@ source:
그 화면이 줄 수 있는 것이 아직 비어 있어 링크를 다른 곳으로 돌린 적이 있다. 우회 자체는 틀리지 않았다 — 그때는 채울 내용이 없었다. 되돌릴 조건은 우회를 넣는 커밋에 적고, 그 조건이 충족되면 되돌린다.
## 관계
## 임시 우회는 나중에 제거할 조건까지 함께 남겨야 한다
- **축 링크가 자기 자신을 가리켰고, 고친 뒤에는 백엔드를 먼저 배포했다**
같은 주제 링크를 다루며 이 기준이 나왔다.
@@ -25,11 +25,11 @@ source:
- **새 라우트는 프론트엔드를 먼저 배포한다**
같은 사건에서 나온 짝이 되는 결정이다.
## 목적
## 우회가 영구 설계로 굳는 것을 막는다
임시 조치가 영구 구조로 굳는 것을 막는다. 되돌릴 조건이 적혀 있지 않으면 다음 사람이 그 우회를 설계로 읽는다.
## 규칙
## 우회 이유와 제거 조건을 같은 기록에 적는다
### 1. 우회를 넣는 커밋에 되돌릴 조건을 적는다
@@ -43,19 +43,19 @@ source:
그때는 조건이 아니라 근거와 감수한 비용을 적는다.
## 적용 조건
## 현재 구조 때문에 임시 분기나 예외 처리를 넣을 때
- 그 화면이 줄 수 있는 것이 아직 비어 있어 링크나 흐름을 다른 곳으로 돌릴 때
- 임시라고 말하면서 코드에 남기는 변경을 커밋할 때
- 왜 이 링크가 저기로 가는지 다음 사람이 물을 만한 변경을 넣을 때
## 예외
## 장기 정책으로 확정된 동작은 우회로 기록하지 않는다
- 되돌릴 생각이 없는 영구 변경은 우회가 아니다. 조건 대신 근거를 적는다.
- 조건을 적을 수 없으면 그것은 우회가 아니라 아직 정하지 않은 것이다. 열린 질문으로 남긴다.
## 예시
## fallback과 임시 호환 처리
- 주제 화면이 주제 셋을 하드코딩해 두고 있어 실제 주제는 무엇이든 404 였다. 그때 주제 페이지를 채우는 대신 링크를 탐색 필터로 돌렸다.
@@ -22,7 +22,7 @@ source:
주제 안의 축은 세 테이블로 표현된다. 주제가 축의 이름을 스스로 정하고, 축의 값들이 따로 있고, 어느 기록이 어느 축에 걸리는지를 종류와 아이디의 쌍으로 적는다. 기록이 종류마다 다른 테이블에 살기 때문에 그 쌍에 외래키를 걸지 못한다.
## 관계
## Topic Variant와 Record Variant는 서로 다른 분류 축이다
- **주제를 넷으로 쪼개지 않고 주제 안에 축을 하나 뒀다**
이 구조를 만든 결정이다.
@@ -31,7 +31,7 @@ source:
- **홈의 비교 구역이 세 번 바뀌었다**
이 구조가 화면에서 어떻게 쓰이는지가 그 기록에 있다.
## 본문
## 주제가 축 이름을 정하고 기록은 kind와 id로 연결된다
<!-- body:start -->
@@ -73,7 +73,7 @@ topic (주제)
주제를 지울 때와 반대다. 주제는 그것을 쓰는 기록이 있으면 아예 거절한다.
> 주제를 지웠다는 이유로 그 주제를 쓰던 문서의 분류가 조용히 사라지면 안 되기 때문이다 — 지우려면 먼저 그 문서들을 옮기라는 뜻이다.
> 주제를 지웠다는 이유로 그 주제를 쓰던 문서의 분류가 자동으로 사라지면 안 되기 때문이다 — 지우려면 먼저 그 문서들을 옮기라는 뜻이다.
주제는 그 기록이 무엇에 관한 것인지를 말하는 분류이고, 축은 같은 주제 안에서 무엇과 견주는지를 말하는 비교 축이다. 분류가 사라지면 기록의 뜻이 바뀌고, 비교 축이 사라지면 비교만 없어진다.
@@ -21,7 +21,7 @@ source:
「브라우저와 서버 사이 credential 책임을 어디에 둘 것인가」 하나의 질문에 네 구조를 만들어 봤는데, 기록에 붙는 축이 주제와 프로젝트뿐이라 그 넷을 담을 데가 없었다. 주제를 넷으로 쪼개는 대신 주제 안에 축을 하나 뒀다.
## 근거
## 네 패턴은 하나의 인증 주제를 비교하는 축이다
- **축은 주제가 이름을 정하고, 기록은 종류와 아이디의 쌍으로 축에 걸린다**
이 결정을 담은 스키마다.
@@ -30,13 +30,13 @@ source:
- **축의 결론 문장과 기록 수는 기록을 붙여도 따라오지 않는다**
이 결정으로 감수한 비용이 그 질문에 있다.
## 결정문
## 패턴마다 주제를 만들지 않고 한 주제 안에 축을 둔다
한 질문에 여러 구조를 만들어 비교하는 경우, 주제를 그 수만큼 쪼개지 않고 주제 안에 축을 하나 둔다.
축의 이름은 주제가 정하고, 기록은 여러 축에 걸릴 수 있으며, 아무 축에도 걸리지 않은 기록은 그 주제의 공통 기록으로 읽는다.
## 판단 이유
## 비교 대상과 프로젝트 맥락을 같은 화면에서 유지한다
주제를 넷으로 쪼개면 네 구조가 함께 쓰는 기록을 어디에 둘지 애매해진다. PKCE(Proof Key for Code Exchange)와 CSRF(Cross-Site Request Forgery) 방어, Authorization Code 흐름이 그런 기록이다. 어느 한 주제에 넣으면 나머지 셋에서 그 기록에 닿을 수 없고, 넷에 복사하면 같은 글이 넷이 된다.
@@ -46,7 +46,7 @@ source:
축 이름을 주제가 정하게 한 것은 주제마다 비교하는 것이 다르기 때문이다. 인증 경계 주제는 credential 을 어디에 두느냐로 갈리고 조회 성능 주제는 같은 데이터를 어떻게 읽느냐로 갈린다.
## 영향
## 축 링크와 기록 연결 규칙을 별도로 관리해야 한다
축의 이름·요약·결론이 기록에서 자동으로 나오지 않는다. 주제의 논지와 축의 요약·결론은 사람이 쓰는 칸이고, 기록을 스무 개 붙여도 그 문장은 누가 고치기 전까지 그대로다.
@@ -19,7 +19,7 @@ source:
홈의 비교 구역에서 줄은 문서가 아니라 축이다. 기록을 스무 개 붙여도 줄 수는 늘지 않고, 줄에 보이는 결론 문장은 축에 손으로 쓴 글이라 누가 고치기 전까지 바뀌지 않는다. 주제 화면에는 축마다 기록 수가 붙는데 홈에는 없다.
## 관계
## 축의 결론 문장과 기록 수는 서로 다른 값으로 저장된다
- **주제를 넷으로 쪼개지 않고 주제 안에 축을 하나 뒀다**
이 결정으로 감수한 비용이 이 질문이다.
@@ -28,7 +28,7 @@ source:
- **프록시 지표가 아니라 보이는 것을 측정한다**
화면에서 무엇이 달라지는지 확인하는 방법이 그 기준에 있다.
## 사실
## 기록을 추가해도 결론 문장과 개수는 자동으로 갱신되지 않는다
홈의 비교 구역에서 한 줄은 축 하나다. 기록을 스무 개 붙여도 줄 수는 그대로다.
@@ -42,13 +42,13 @@ source:
주제의 논지와 축의 결론은 2026-09-01 에 AI 가 써서 DB 에 직접 넣은 초안이다. 사용자 검토 대상이고 아직 검토되지 않았다.
## 가정
## 일부 값은 실제 기록에서 파생할 수 있다
결론을 사람이 쓰게 한 것이 의도라고 보고 있다. 요약은 「무엇인가」이고 결론은 「무엇을 알게 됐나」라서 기록의 요약 첫 줄을 잘라 쓰면 안 된다고 판단했는데, 그 판단이 지금도 맞는지 다시 보지 않았다.
기록 수는 유도할 수 있다고 보고 있다. 주제 화면이 이미 그 수를 그리므로 같은 값을 홈에 붙이면 된다고 짐작하지만, 홈의 목록 호출이 그 수를 싣는지 확인하지 않았다.
## 미지수
## 작성자 문장과 파생 값의 경계를 어디에 둘 것인가
홈에 기록 수를 붙이면 축에 기록을 더했을 때 화면이 달라지는가. 달라진다면 결론 문장이 낡았다는 것도 같은 화면에서 드러나는가.
@@ -56,13 +56,13 @@ source:
DB 에 직접 넣은 초안을 누가 언제 검토하는가. 검토 전까지 그 문장을 공개 화면에 그대로 둘지.
## 제약
## 수동 입력과 자동 집계를 함께 두면 불일치가 생긴다
축의 요약과 결론은 기록을 합쳐 자동으로 만들지 않는다. 결론은 비교표가 읽는 칸이라 기록의 요약 첫 줄을 잘라 쓰면 안 된다.
홈이 처음 보내는 요청은 목록 하나와 주제 하나로 고정한다. 기록 수를 붙이려고 주제마다 상세를 미리 받지 않는다.
## 선택지
## 결론을 직접 쓰게 둘지 일부를 파생할지
**홈 비교표에 기록 수를 붙인다**
목록 호출이 이미 그 수를 실을 수 있으면 요청이 늘지 않는다. 결론 문장은 그대로 사람이 쓴다. 기록이 늘면 수가 바뀌므로 결론만 낡은 상태가 화면에 드러난다.
@@ -73,7 +73,7 @@ DB 에 직접 넣은 초안을 누가 언제 검토하는가. 검토 전까지
**결론을 쓰지 않은 축은 결론 줄을 비운다**
쓰지 않은 것과 낡은 것을 구분한다. 지금은 초안이 들어 있어 둘이 같아 보인다.
## 다음 검증
## 기록 추가와 삭제 뒤 축 화면을 다시 확인한다
1. 홈의 목록 호출 응답에 축별 기록 수가 실려 있는지 확인하고, 없으면 싣는 비용을 잰다
2. 축 하나에 기록을 더하고 홈에서 무엇이 달라지고 무엇이 그대로인지 화면으로 가른다
@@ -19,7 +19,7 @@ source:
격자와 열을 재고 「정상」이라고 답했는데, 전체 페이지 스크린샷을 찍으니 제목이 26px 에 굵기 400 이었다. 목록 간격을 바운딩 박스로만 재서 엉뚱한 곳을 결함으로 지목한 적도 있다. 화면이 잘못됐다는 보고는 보이는 것을 재서 확인한다.
## 관계
## 간접 지표와 사용자가 보는 결과는 다를 수 있다
- **규칙이 없었던 게 아니라 절반만 있었다**
이 기준의 근거 사건이다.
@@ -28,11 +28,11 @@ source:
- **홈의 비교 구역이 세 번 바뀌었다**
폭마다 측정을 남긴 기록이다.
## 목적
## 프록시 지표만 보고 화면 동작을 판단하지 않는다
화면이 잘못됐다는 보고를 확인할 때 엉뚱한 값을 재고 「정상」이라 답하는 것을 막는다.
## 규칙
## 최종 사용자 결과와 가장 가까운 지점을 직접 측정한다
### 1. 보고된 증상과 같은 축의 값을 잰다
@@ -52,19 +52,19 @@ source:
축소되어 글자 크기가 실제와 달라진다. 1425x4466 이 638x2000 으로 들어오면 17px 글자가 7~8px 이 되고, 그 그림에서는 크기 문제를 볼 수 없다. 화면 높이만큼 잘라 찍는다.
## 적용 조건
## 중간 계층의 성공 여부로 UI나 API 결과를 추정할 때
- 화면이 잘못됐다는 보고를 확인할 때
- 배포본의 실제 렌더 결과를 판단 근거로 삼을 때
- 고쳤다고 답하기 전에 무엇을 쟀는지 대야 할 때
- 여러 폭에서 배치가 갈리는 사이트를 검토할 때
## 예외
## 프록시 지표 자체가 검증 대상인 경우
- 측정 대상이 좌표나 간격 자체라면 바운딩 박스는 프록시가 아니라 대상이다.
- CSS 선언이 정본과 같은지를 보는 검사는 렌더 결과를 재지 않는다. 그 검사가 덮는 범위를 알고 쓰면 된다.
## 예시
## healthy container와 실제 SPA 403 비교
- 격자와 열만 재고 「정상」이라 답했다. 사용자가 다시 지적한 뒤 전체 페이지 스크린샷을 찍어서야 26px 과 400 을 봤다
- 목록 간격을 바운딩 박스로만 재서 엉뚱한 구역을 결함으로 지목한 적이 있다
@@ -16,7 +16,7 @@ source:
구역 클래스 아래에 태그 선택자로 배치를 걸면 그 구역 안의 모든 같은 태그가 걸린다. 제목 안의 링크가 행용 격자에 갇혀 h2 높이가 199px 이 됐다. 배치를 거는 규칙은 그 배치를 쓰는 요소까지 좁혀 적는다.
## 관계
## CSS layout rule은 적용 범위를 넓히면 의도하지 않은 요소까지 잡는다
- **구역 전체에 건 격자가 제목까지 잡아 h2 높이가 199px 이 됐다**
이 기준의 근거 사건이다.
@@ -25,13 +25,13 @@ source:
- **규칙이 없었던 게 아니라 절반만 있었다**
같은 화면에서 난 다른 부류의 CSS 결함이다.
## 목적
## 배치 규칙을 실제 배치를 쓰는 요소에만 적용한다
「디자인이 안 된 것처럼 보인다」는 보고의 원인이 되는 선택자 누출을 막는다.
이 부류는 규칙 자체는 맞고 걸리는 대상이 넓다. 그래서 규칙을 읽어서는 틀린 것을 찾을 수 없고, 그려진 결과를 봐야 한다.
## 규칙
## selector 범위를 layout container까지 좁힌다
### 1. 배치 속성은 그 배치를 쓰는 요소까지 좁혀 적는다
@@ -51,19 +51,19 @@ display: grid|flex·grid-template-columns·padding 을 구역 클래스 아래
module 은 클래스 이름을 빌드 때 바꿔 전역 선택자와 겹치지 않게 만든다. 그래서 전역 규칙을 고쳐도 module 을 쓰는 화면에는 닿지 않고, 한 화면 안에서 두 언어가 섞이면 더 눈에 띈다.
## 적용 조건
## grid와 flex 규칙을 section 단위로 추가할 때
- 구역 클래스 아래에 태그 선택자로 배치를 거는 CSS 를 쓸 때
- 같은 구역 안에 제목과 목록이 함께 있을 때
- 전역 규칙과 CSS module 이 한 화면에 섞여 있을 때
- 「디자인이 안 된 것처럼 보인다」는 보고를 받았을 때
## 예외
## 전체 section이 동일한 layout을 공유하는 경우
- 색이나 글꼴만 거는 규칙은 새어도 티가 나지 않으므로 대상이 아니다. 검사에 넣으면 결과가 늘 빨갛다.
- 구역 안의 모든 같은 태그가 실제로 같은 배치를 써야 하는 화면이라면 좁히지 않아도 된다. 그때는 그 의도를 검사의 예외 목록에 적는다.
## 예시
## home comparison h2가 grid item이 된 문제
- 비교 행을 위한 격자가 제목 안의 링크까지 잡아 제목이 200px 칸에 갇히고 h2 높이가 199px 이 됐다
- 같은 모양이 다른 구역 아홉 곳에도 있어 선택자 51개를 고쳤다
@@ -17,7 +17,7 @@ source:
계약이 한 저장소에 있고 두 저장소가 그것을 반입해 각자 구현하면, 어느 한쪽이 빠뜨린 것을 컴파일러가 보지 못한다. 이 저장소에서 그 구멍이 서버 쪽으로 다섯 번, 화면 쪽으로 네 번 났다. 두 쪽 모두에서 계약과 대조하는 검사를 돌린다.
## 관계
## 계약 하나를 서버와 화면이 서로 다르게 구현할 수 있다
- **계약에 선언만 있고 구현이 없어 화면 다섯 곳이 비어 있었다**
서버 쪽 누락의 근거 사건이다.
@@ -26,13 +26,13 @@ source:
- **종류를 나열하는 곳은 컴파일러나 계약 대조 검사가 세게 만든다**
컴파일러가 볼 수 있는 범위 안쪽을 다루는 짝이 되는 기준이다.
## 목적
## 타입 생성 성공만으로 계약 구현을 완료로 보지 않는다
계약이 선언한 연산에 구현이 없는 상태를 배포 전에 잡는다.
이 상태는 오류를 내지 않는다. 서버는 404 를 주고 화면은 그것을 빈 데이터로 그린다. 계약에서 모델을 생성하는 단계도 스키마와 속성만 보므로 구현이 없어도 모델이 만들어지고 컴파일이 통과한다.
## 규칙
## contract operation과 backend handler, frontend call을 전수 대조한다
### 1. 서버 쪽은 매핑을 리플렉션으로 모아 계약의 경로와 전수 대조한다
@@ -58,13 +58,13 @@ source:
관리 계약에는 86 operation 이 있다. 검사 범위를 좁힌 이유는 그 숫자 자체가 아니라 당시 반복해서 깨진 형태가 「한 종류만 빠진 항목」이었기 때문이다. 그래서 관리 계약 쪽 가드는 그 패턴을 보며, 전체 계약과 구현의 동등성을 증명한다고 말하지 않는다.
## 적용 조건
## operation이나 field를 계약에 추가하거나 이름을 바꿀 때
이 대조가 필요한 때는 계약이 한 저장소에 있고 두 저장소가 그것을 반입해 각자 구현하는 구조에서 연산을 더하거나 지울 때다. 화면이 「데이터가 없습니다」를 그리는데 저장소에는 값이 있을 때도 먼저 본다. 구현이 없어서 404가 난 경우와 정말 0건인 경우가 화면에서는 같은 빈 상태로 보이기 때문이다.
실제 검증에서는 매핑 하나를 떼었을 때 대조 검사가 그 연산 하나를 정확히 짚는 것을 확인한 뒤 커밋했다. 두 목록 조회에 컨트롤러가 없던 때에는 홈 편집기가 「이 프로젝트에 열린 질문이 없습니다」를 그렸지만 실제로는 넷이 있었고 공개 사이트에도 나오고 있었다. 화면 쪽에서는 기여 목록에 등록하지 않은 연산 넷을 만났고, 둘은 옆 분기로 떨어져 다른 기록을 다뤘으며 둘은 빈 목록이 됐다.
## 예외
## 자동 생성으로 양쪽 구현까지 함께 만들어지는 항목
계약과 구현이 같은 저장소에 있어도 컴파일러가 대신할 수 있는 범위는 실제로 같은 타입이나 생성 산출물에 연결된 곳뿐이다. 문자열 라우트나 별도 컨트롤러 등록처럼 타입 시스템 밖에 있는 항목은 별도 대조가 필요하다. 봉투 규약을 따르지 않는 연산을 경로 대조에서 빼야 한다면, 제외 이유는 명시 목록에 남긴다.
@@ -77,7 +77,7 @@ tech-log-backend : 911e8ba — 없던 두 컨트롤러를 구현
홈이 무엇을 앞에 세울지 정하는 설정은 지목한 대상에 외래키를 걸지 않는다. 설정이 대상보다 오래 살아남는 것을 허용하는 설계다.
대신 저장할 때 그 대상이 실제로 있는지 확인한다. 확인하지 않으면 없는 id 가 그대로 저장되고, 공개 화면은 조용히 빈 focus 를 그린다 — 저장은 성공했는데 화면에는 아무것도 안 나오는, 이유를 알 수 없는 실패가 된다.
대신 저장할 때 그 대상이 실제로 있는지 확인한다. 확인하지 않으면 없는 id 가 그대로 저장되고, 공개 화면은 빈 focus를 그린다 — 저장은 성공했는데 화면에는 아무것도 안 나오는, 이유를 알 수 없는 실패가 된다.
확인하는 것은 있는지까지다. 그 대상이 공개인지는 저장할 때 보지 않는다. 아직 게시하지 않은 프로젝트를 미리 지목해 두고 게시와 동시에 홈에 뜨게 하는 것이 정상적인 순서이고, 공개 여부는 공개 조회 쪽이 매번 다시 판단한다.
@@ -1,7 +1,7 @@
---
kind: CASE
slug: records-disappeared-without-a-trace
title: 매퍼가 null 을 돌려주고 호출부가 걸러 내, 기록이 조용히 사라졌다
title: 매퍼가 null을 반환해 QUESTION과 CONCEPT가 목록에서 누락됐다
topic: failure-drawn-as-absence
topicName: 실패를 없음으로 그린다
project: TechLog
@@ -12,7 +12,7 @@ source:
- final/document.md#§10.6
---
# 매퍼가 null 을 돌려주고 호출부가 걸러 내, 기록이 조용히 사라졌다
# 매퍼가 null을 반환해 QUESTION과 CONCEPT가 목록에서 누락됐다
프로젝트 기록 목록에서 Open Question 이 보이지 않았다. 이 목록은 탐색의 지식 목록과 응답 모양이 다른데 그쪽 매퍼를 쓰고 있었다. 그 매퍼는 두 종류가 아니면 null 을 돌려주고 호출부가 걸러 내므로, 질문과 개념은 오류도 빈 줄도 남기지 않고 사라진다.
@@ -20,7 +20,7 @@ source:
- **화면은 못 읽은 것을 없다고 말하지 않는다**
같은 부류를 다루는 규칙이다.
- **개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다**
- **CONCEPT를 추가하자 종류 처리 누락이 열세 곳에서 드러났다**
이 매퍼가 그 열세 곳 중 하나다.
- **합성 루트에 테스트가 없어 공개 사이트 전체가 오류 화면이었다**
스텁 때문에 매핑이 검사되지 않던 다른 사건이다.
@@ -16,7 +16,7 @@ source:
배포 뒤 전 화면을 훑는 스윕이 기대된 404 를 실패로 셌다. 건강한 배포 아래에 매번 같은 빨간 줄이 남았고, 그 줄은 곧 읽히지 않게 됐다. 기대된 실패는 조건을 적어 빼고 나머지는 전부 실패시킨다.
## 관계
## 항상 실패하는 검사가 있으면 실제 회귀 실패가 묻힌다
- **화면은 못 읽은 것을 없다고 말하지 않는다**
같은 프로젝트에서 실패를 어떻게 다룰지 정한 짝이 되는 기준이다.
@@ -25,13 +25,13 @@ source:
- **계약은 앵커라고 적었고 만드는 쪽은 경로를 만들었다**
같은 스윕이 실제 결함을 잡아야 했던 사건이다.
## 목적
## 기대된 실패와 새 실패를 구분한다
검사 결과를 사람이 계속 읽게 하려고 정한 기준이다.
매번 늑대를 외치는 검사는 읽히지 않게 되고, 진짜 실패가 그 옆에 눈에 띄지 않은 채 앉아 있게 된다.
## 규칙
## 기대 실패는 조건을 명시하고 나머지 실패는 그대로 실패시킨다
### 1. 기대된 실패는 조건을 적어 뺀다
@@ -51,18 +51,18 @@ source:
왜 그 응답이 기대된 것인지 적혀 있지 않으면 다음 사람이 조건을 넓힌다. 비슷한 404 가 하나 더 나왔을 때 같은 조건에 넣을지 판단할 근거가 없기 때문이다.
## 적용 조건
## 현재 환경에서 의도적으로 통과시킬 수 없는 검사가 있을 때
- 배포 뒤 전 화면을 훑는 스윕처럼 결과를 사람이 훑어보는 검사를 만들 때
- 정상 동작이 오류 상태 코드로 나타나는 화면이 있는 서비스에서
- 같은 빨간 줄이 매번 남기 시작했을 때
## 예외
## 원인과 제거 조건을 설명할 수 없는 실패
- 기계가 판정하고 사람이 결과를 읽지 않는 검사라면 빨간 줄이 쌓여도 무뎌지지 않는다. 그래도 통과 기준은 정해야 한다.
- 그 응답이 정말 고쳐야 하는 것이면 조건으로 빼지 말고 고친다. 뺄지 고칠지는 사람이 고칠 것이 있는가로 가른다.
## 예시
## 배포 전 guard와 환경 의존 검사
- 미리보기가 없는 문서의 404 를 스윕이 실패로 셌다. 건강한 배포 아래에 매번 같은 빨간 줄이 남았다
- 로그인 전 세션 탐침의 401 도 같은 부류라 같은 조건으로 제외했다
@@ -17,22 +17,22 @@ source:
목록이나 요약처럼 「비어 있음」이 정상값인 화면에서는 실패와 0건이 같은 모양으로 그려진다. 작성자는 그것을 자기가 아직 쓰지 않은 것으로 읽는다. 못 읽었으면 못 읽었다고 적는다.
## 관계
## 조회 실패와 빈 결과는 다른 상태다
- **「이 프로젝트에 열린 질문이 없습니다」 — 실제로는 넷이 있었다**
이 규칙의 근거 사건이다.
- **한 칸의 실패가 옆 칸을 끌고 내려갔다**
실패가 어디까지 번지는지를 다룬 사건이다.
- **매퍼가 null 을 돌려주고 호출부가 걸러 내, 기록이 조용히 사라졌다**
- **매퍼가 null을 반환해 QUESTION과 CONCEPT가 목록에서 누락됐다**
실패가 아니라 항목이 사라진 변종이다.
## 목적
## 읽지 못한 데이터를 없다고 표시하지 않는다
작성자가 「아직 안 썼다」와 「못 읽었다」를 구분할 수 있게 한다.
이 둘이 같은 화면이면 작성자는 다음에 무엇을 할지 정할 수 없다. 실패면 다시 부르거나 서버를 봐야 하고 0건이면 쓰면 되는데, 화면이 「없습니다」 하나로 답하면 뒤쪽으로 읽고 다시 쓰게 된다.
## 규칙
## 오류와 empty state를 UI에서 분리한다
### 1. 요청이 실패하면 실패했다고 적는다
@@ -58,19 +58,19 @@ source:
목록에 몇 개가 있어야 하는지 아는 사람만 알아챌 수 있다. 공개 화면에서는 그것을 아는 사람이 작성자뿐이다.
## 적용 조건
## 목록 API 실패를 화면에서 처리할 때
- 목록·요약·카운트처럼 「비어 있음」이 정상값이라 실패와 구분되지 않는 화면을 만들 때
- 작성 도구를 만들 때. 작성자가 자기 작업물과 화면을 대조하므로 오독이 곧바로 작업 판단이 된다
- 한 화면이 여러 목록을 함께 받아 그릴 때
- 매퍼가 모르는 값에 빈 값을 돌려주고 호출부가 그것을 거를 때
## 예외
## 계약상 실패를 빈 결과로 정의한 endpoint
- 정말로 0건인 것과 못 읽은 것을 구분할 수 없는 화면이라면 그 구분을 먼저 만든다. 구분 없이 문구만 바꾸면 0건이 실패로 읽힌다.
- 읽는 사람이 그 데이터를 만들지 않는 화면에서는 실패를 화면 전체의 오류로 다뤄도 된다. 방문자에게는 어느 목록이 실패했는지가 할 일을 바꾸지 않는다.
## 예시
## 질문 조회 404가 열린 질문 0개로 보인 문제
- 「이 프로젝트에 열린 질문이 없습니다」가 적혀 있는 동안 그 프로젝트에는 질문이 넷 있었고 공개 사이트에도 나오고 있었다
- 결정 목록만 404 인데 함께 묶어 읽은 질문 목록까지 「불러오지 못했습니다」가 됐다
@@ -1,7 +1,7 @@
---
kind: CASE
slug: one-new-kind-fell-through-thirteen-places
title: 개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다
title: CONCEPT를 추가하자 종류 처리 누락이 열세 곳에서 드러났다
topic: hand-listed-kinds
topicName: 손으로 나열한 종류 목록
project: TechLog
@@ -20,7 +20,7 @@ source:
- final/document.md#§10.3
---
# 개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다
# CONCEPT를 추가하자 종류 처리 누락이 열세 곳에서 드러났다
문서 종류에 CONCEPT 을 더했다. 컴파일도 통과하고 테스트도 통과했는데, 개념을 지우면 「질문을 찾을 수 없습니다」가 나오고 개념 상세 주소는 404 였고 탐색에서 type=CONCEPT 은 0건이었다. 그 뒤로도 같은 모양이 계속 나와 열세 번을 셌다. 매번 원인이 같았다 — 다섯 종류를 손으로 적어 둔 곳이 있었고 새 종류가 마지막 else 로 떨어졌다.
@@ -39,7 +39,7 @@ source:
문서 종류는 다섯이다 — CASE, REFERENCE, QUESTION, CONCEPT, PROJECT_DECISION. 새 종류를 하나 더하면 그 종류를 아는 곳이 전부 함께 늘어나야 한다.
실제로는 늘지 않은 곳이 열세 곳 있었고, 그중 어느 곳도 오류를 내지 않았다. 삼항 사슬의 마지막 else 와 배열 리터럴의 끝이 모르는 값을 조용히 받아 갔다.
실제로는 늘지 않은 곳이 열세 곳 있었고, 그중 어느 곳도 오류를 내지 않았다. 삼항 사슬의 마지막 else 와 배열 리터럴의 끝이 모르는 값을 오류 없이 마지막 분기로 처리했다.
## 결론
@@ -17,16 +17,16 @@ source:
같은 언어 안에서도 어떤 분기는 새 값을 더할 때 컴파일러가 빠진 값을 짚고 어떤 분기는 아무 말도 하지 않는다. 삼항 사슬과 배열 리터럴은 후자이고, Record<Kind, _> 와 식으로 쓴 sealed switch 는 전자다.
## 관계
## 유한한 종류 목록은 누락을 컴파일 시점에 드러내야 한다
- **개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다**
- **CONCEPT를 추가하자 종류 처리 누락이 열세 곳에서 드러났다**
이 개념이 없으면 그 열세 건이 왜 컴파일을 지나갔는지 읽히지 않는다.
- **종류를 나열하는 곳은 컴파일러나 계약 대조 검사가 세게 만든다**
이 개념에서 두 방법을 골라 규칙으로 굳혔다.
- **TypeScript 가 검사를 놓아 주는 네 곳**
같은 컴파일러가 검사를 놓아 주는 다른 곳들이다.
## 본문
## Record 표와 exhaustive switch가 빠진 가지를 잡는 방식
<!-- body:start -->
@@ -102,7 +102,7 @@ Java 에서도 같은 갈림이 있다. `switch` 를 문으로 쓰면 아무 가
위 `pathOf` 는 식으로 쓴 switch 인데도 `default` 가 있어 그 요구를 받지 않는다. 분기 대상이 `String` 이라 컴파일러가 셀 수 있는 값 집합이 없고, `default` 없이는 컴파일되지 않기 때문이다.
이 저장소의 백엔드에서 게시 상태 코드와 활동 유형과 소유자 유형과 slug 중복 검사와 렌더 모델은 전부 sealed 타입을 대상으로 식으로 쓰인 switch 를 지난다. 그래서 종류를 하나 더했을 때 백엔드에서 조용히 넘어간 곳이 프론트보다 적었다.
이 저장소의 백엔드에서 게시 상태 코드와 활동 유형과 소유자 유형과 slug 중복 검사와 렌더 모델은 전부 sealed 타입을 대상으로 식으로 쓰인 switch 를 지난다. 그래서 종류를 하나 더했을 때 백엔드에서 누락을 오류 없이 통과시킨 곳이 프론트보다 적었다.
## 같은 함수 안에서 두 목록이 갈릴 수 있다
@@ -18,16 +18,16 @@ source:
종류를 나열하는 곳을 표와 sealed switch 식으로 바꾸면서 둘을 남겼다. 하나는 담기는 값이 종류 밖으로 나가서, 하나는 아직 손대지 않아서다. 둘 다 새 종류를 더할 때 컴파일이 통과하고 값만 틀린다.
## 관계
## 문서 종류를 나열하는 곳 대부분은 컴파일러가 확인한다
- **개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다**
- **CONCEPT를 추가하자 종류 처리 누락이 열세 곳에서 드러났다**
이 질문이 남은 사건이다.
- **컴파일러가 빠진 가지를 요구하게 만드는 두 가지 — Record 표와 sealed switch 식**
왜 이 두 곳이 표로 바뀌지 못했는지가 그 개념에 있다.
- **계약은 앵커라고 적었고 만드는 쪽은 경로를 만들었다**
pathOf 가 만든 주소가 틀렸던 다른 사건이다.
## 사실
## 두 종류 표는 아직 문자열 목록으로 남아 있다
공개 경로 생성기는 문서 종류가 아니라 공개 투영의 종류 칸(String)으로 switch 하고 default -> null 이 남아 있다.
@@ -41,7 +41,7 @@ PublicPathsTest 가 지금 종류마다 만들어 낸 경로를 공개 라우트
남은 사슬은 배타적이 아니라 가산형이다. 종류를 빠뜨리면 잘못된 분기로 떨어지는 것이 아니라 그 종류의 추가 칸을 검사하지 않는다.
## 가정
## 계약에서 파생하면 새 종류 누락을 줄일 수 있다
PROJECT 와 RELEASE 를 다른 분기로 빼면 나머지를 sealed 로 좁힐 수 있다고 보고 있다. 그 둘이 공개 투영에서 어떤 경로를 갖는지 전수로 확인하지 않았다.
@@ -49,7 +49,7 @@ PROJECT 와 RELEASE 를 다른 분기로 빼면 나머지를 sealed 로 좁힐
홈 focus 의 최근 결정 경로가 PublicPathsTest 를 지나지 않는다고 보고 있다. 그 테스트가 도는 대상 목록을 직접 세지 않았다.
## 미지수
## 두 표를 어느 정본에서 만들 것인가
공개 경로 생성기가 읽는 칸이 종류 밖의 값도 담는 상태에서, 그 둘을 어디로 옮기면 나머지를 컴파일러가 세게 만들 수 있는가.
@@ -57,13 +57,13 @@ PublicPathsTest 가 닿지 않는 경로가 몇 개인가.
문자열 칸 목록을 표로 바꾸면 지금과 다른 결과를 내는 종류가 있는가.
## 제약
## 런타임 데이터와 빌드 타임 타입의 경계가 다르다
공개 투영은 한 테이블이 문서와 프로젝트와 릴리스를 함께 담는다. 이 구조는 바꾸지 않는다.
계약의 문서 종류는 다섯이고 여기에 프로젝트와 릴리스를 더하지 않는다. 그 둘은 문서 게시 파이프라인을 타지 않고, 릴리스는 자체 상태로 공개되므로 투영에 행이 아예 없다.
## 선택지
## Record 표로 옮길지 계약 대조 검사를 둘지
**경로 생성기를 두 분기로 가른다**
문서 종류를 받는 sealed switch 와 프로젝트·릴리스를 받는 분기로 나눈다. 호출부가 어느 쪽인지 알아야 하므로 호출부를 함께 본다.
@@ -74,7 +74,7 @@ PublicPathsTest 가 닿지 않는 경로가 몇 개인가.
**문자열 칸 목록만 먼저 표로 바꾼다**
가산형이라 위험이 낮고 다른 것과 얽히지 않는다. 이 선택만으로는 경로 생성기가 null 을 내보내는 것을 막지 못한다.
## 다음 검증
## 새 kind를 하나 추가해 두 표가 실패하는지 확인한다
1. 경로 생성기를 문서 종류 switch 와 프로젝트·릴리스 분기로 갈라 보고, 새 종류를 하나 더해 컴파일이 멈추는지 본다
2. PublicPathsTest 가 도는 대상 목록을 세고, 홈 focus 의 최근 결정 경로가 거기 있는지 확인한다. 없으면 그 경로를 테스트에 넣는다
@@ -16,24 +16,24 @@ source:
# 종류를 나열하는 곳은 컴파일러나 계약 대조 검사가 세게 만든다
값이 유한한 집합을 코드 여러 곳에서 분기할 때, 그 목록을 사람이 세면 새 값이 조용히 빠진다. 이 저장소에서 같은 실수가 열세 번 났고, 그 뒤로 두 가지만 쓴다 — 컴파일러가 항목을 요구하게 만들거나, 컴파일러가 못 보는 경계에는 계약을 읽어 대조하는 검사를 두거나.
값이 유한한 집합을 코드 여러 곳에서 분기할 때, 그 목록을 사람이 세면 새 값이 누락돼도 오류가 나지 않는다. 이 저장소에서 같은 실수가 열세 번 났고, 그 뒤로 두 가지만 쓴다 — 컴파일러가 항목을 요구하게 만들거나, 컴파일러가 못 보는 경계에는 계약을 읽어 대조하는 검사를 두거나.
## 관계
## 새 kind 누락은 손으로 나열한 분기에서 반복됐다
- **개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다**
- **CONCEPT를 추가하자 종류 처리 누락이 열세 곳에서 드러났다**
이 규칙의 근거가 되는 사건이다.
- **컴파일러가 빠진 가지를 요구하게 만드는 두 가지 — Record 표와 sealed switch 식**
규칙이 쓰는 두 방법을 그 개념이 설명한다.
- **계약과 구현은 서버와 화면 양쪽에서 전수 대조한다**
컴파일러가 못 보는 경계를 다루는 짝이 되는 기준이다.
## 목적
## 유한한 종류 목록을 컴파일러나 계약 검사에 맡긴다
새 값을 더했을 때 오류 없이 잘못된 값이 나가는 것을 막는다.
이 부류는 컴파일도 테스트도 지나간다. 마지막 else 가 모르는 값을 받아 가면 모든 값에 갈 곳이 있고 각 가지가 내놓는 타입도 같으므로, 타입 검사가 물을 것이 남지 않는다. 그래서 배포된 뒤 사용자가 만나기 전까지 아무도 모른다.
## 규칙
## Record와 exhaustive switch를 우선 사용한다
### 1. 유한한 집합의 분기는 값마다 항목을 요구하는 형태로 쓴다
@@ -63,15 +63,15 @@ Record<K, V> 는 키 집합이 K 와 정확히 같은 객체 타입이라, 키
세 계약을 파싱해 「일부 값만 열거한 enum」을 전부 뽑는 편이 눈으로 찾는 것보다 빠르고 빠뜨림이 없다.
## 적용 조건
## CASE·REFERENCE·QUESTION 같은 닫힌 종류 집합을 분기할 때
- 값이 유한한 집합인 것을 코드나 계약 여러 곳에서 분기하거나 열거하는 곳. 문서 종류, 상태, 역할, 오류 코드, 라우트 이름이 여기 해당한다.
- 새 값을 더하는 변경을 시작할 때 이 규칙을 먼저 건다. 다 더한 뒤에 빠진 곳을 찾는 순서로는 조용히 빠진 곳을 못 찾는다 — 조용히 빠진 곳은 증상이 없으므로 훑어서는 나오지 않는다.
- 새 값을 더하는 변경을 시작할 때 이 규칙을 먼저 건다. 다 더한 뒤에 빠진 곳을 찾는 순서로는 오류 없이 누락된 곳을 찾기 어렵다. 이런 누락은 증상이 없으므로 훑어서는 나오지 않는다.
- 계약을 소유한 저장소가 따로 있으면 계약 쪽 열거형에도 같이 건다. 이 저장소에서 열세 건 중 셋이 계약 안에 있었다.
## 예외
## 런타임 계약 데이터처럼 컴파일러가 볼 수 없는 경계
- 그 칸이 집합 밖의 값도 담으면 표로 좁힐 수 없다. 공개 투영의 resource_type 이 그런 칸이다 — 문서 종류 다섯에 더해 PROJECT 와 RELEASE 를 담는다. 이때는 대조 검사를 대신 둔다.
@@ -79,11 +79,11 @@ Record<K, V> 는 키 집합이 K 와 정확히 같은 객체 타입이라, 키
- 값이 하나뿐이거나 분기가 한 곳에만 있으면 표로 바꾸는 비용이 이득보다 크다.
## 예시
## CONCEPT 추가 뒤 열세 곳에서 드러난 누락
- 종류를 하나 더한 커밋에서 컴파일러가 게시 상태 코드와 활동 유형과 소유자 유형과 slug 중복 검사와 렌더 모델까지 짚었다. 식으로 쓴 switch 였기 때문이다.
- 같은 종류를 더할 때 프론트엔드에서는 열세 곳이 조용히 지나갔다. 삼항 사슬과 배열 리터럴이었다.
- 같은 종류를 더할 때 프론트엔드에서는 열세 곳의 누락이 오류 없이 통과했다. 삼항 사슬과 배열 리터럴이었다.
- 계약에서 CONCEPT 을 빼자 백엔드의 계약 대조 테스트가 빨개졌다. 그 확인을 하고 커밋했다.
@@ -19,7 +19,7 @@ source:
라우트 계약에서 nginx 서빙 패턴을 만들 때 catch-all 라우트는 번역하지 않는다. 모든 미매치 주소에 index.html 을 주면 엣지의 404 가 soft 200 이 되고, 깨진 링크가 크롤러에도 우리 감사에도 잡히지 않는다.
## 근거
## SPA catch-all과 nginx의 정적 파일 경로는 같은 계약이 아니다
- **nginx 가 모르는 라우트는 새로고침에서 404 다**
서빙 패턴을 라우트 계약에서 유도하기로 한 사건이고, 이 결정이 그 유도 규칙의 일부다.
@@ -28,13 +28,13 @@ source:
- **계약은 앵커라고 적었고 만드는 쪽은 경로를 만들었다**
엣지의 404 가 감사에 잡혀야 하는 이유를 보여 주는 사건이다.
## 결정문
## catch-all 라우트를 nginx location 패턴으로 변환하지 않는다
라우트 계약에서 nginx 서빙 패턴을 생성할 때, catch-all 라우트는 패턴으로 번역하지 않고 버린다.
등록된 Public 라우트마다 정규식 하나를 만들고, 파라미터는 한 세그먼트만 잡되 슬래시는 잡지 않는다.
## 판단 이유
## 정적 파일 요청까지 SPA fallback으로 보내는 오동작을 막는다
모든 미매치 URL 에 index.html 을 주면 엣지에서 404 였을 요청이 200 으로 바뀐다. 라우터는 그 주소를 모르므로 「없는 화면」을 그리지만, 상태 코드는 200 이다.
@@ -44,7 +44,7 @@ source:
대안은 catch-all 을 번역하고 라우터가 404 화면을 그리게 하는 것이었다. 사람에게 보이는 화면은 같지만 기계가 읽는 상태 코드가 달라지므로 고르지 않았다.
## 영향
## 공개 라우트와 웹 서버 서빙 규칙을 별도로 검증한다
라우트를 더할 때마다 서빙 패턴이 함께 움직인다. 이 비용은 라우트 계약에서 유도해 없앴다 — 손으로 배열을 고치지 않는다.
@@ -17,7 +17,7 @@ source:
CI 게이트가 설치된 라우트마다 수동 접근성 증거 파일을 하나씩 요구한다. 파일은 라우트마다 있고 그중 사람이 서명한 것은 하나도 없다. 게이트는 파일의 존재만 세고 서명은 보지 않는다.
## 관계
## 라우트 배포에는 수동 접근성 확인 항목이 포함돼 있다
- **라우트 하나가 건드리는 여덟 곳과, 그것들이 우는 시점**
이 게이트가 그 목록의 한 줄이다.
@@ -26,7 +26,7 @@ CI 게이트가 설치된 라우트마다 수동 접근성 증거 파일을 하
- **가드는 작동했는데 제가 그것을 돌리지 않아 두 번 새어 나갔다**
이 게이트를 빠뜨려 빨간 채로 지나간 사건이다.
## 사실
## 필요한 증거 개수는 세지만 실제 확인자는 남지 않는다
`FE-GATE-009` 프론트엔드 게이트는 설치된 라우트마다 증거 파일 하나를 요구하고, 그 집합이 정확히 일치하지 않으면 거절한다.
@@ -40,13 +40,13 @@ review:a11y-manual 스크립트는 그래서 실패하는 것이 지금은 정
게이트가 세는 것은 파일의 존재이고 그 안의 서명 상태는 보지 않는다.
## 가정
## 체크 결과와 확인자를 함께 남기면 누락을 구분할 수 있다
게이트가 파일의 존재만 세는 것이 의도라고 보고 있다. 서명을 조건에 넣으면 라우트를 더할 때마다 배포가 막히므로 그렇게 두었다고 짐작하지만, 그 판단이 적힌 곳을 찾지 못했다.
서명 절차 자체는 사람이 화면을 열어 확인하는 일이라고 보고 있다. 어떤 항목을 어디까지 보는지 정한 문서를 확인하지 않았다.
## 미지수
## 수동 증거를 어떤 형식과 위치에 보관할 것인가
게이트가 서명 여부까지 보게 하면 지금 몇 개의 라우트가 막히는가.
@@ -54,13 +54,13 @@ review:a11y-manual 스크립트는 그래서 실패하는 것이 지금은 정
라우트 하나를 사람이 실제로 검토하는 데 얼마가 드는가. 그 비용을 모르면 어느 쪽도 고를 수 없다.
## 제약
## 자동 검사만으로 확인할 수 없는 항목이 남아 있다
프론트엔드 게이트 `FE-GATE-009`는 라우트 집합과 증거 집합이 정확히 일치하기를 요구한다. 이 규칙은 바꾸지 않는다 — 빠뜨림이 통과가 되면 게이트가 아니다.
수동 접근성 증거는 사람이 만든다. 자동 검사로 대신하지 않는다.
## 선택지
## 체크리스트에 서명을 남길지 CI 입력으로 받을지
**서명을 게이트의 통과 조건으로 올린다**
라우트마다 사람이 검토하고 서명해야 배포된다. 지금 상태에서는 모든 라우트가 막히므로 한 번에 올릴 수 없고, 라우트별로 나눠 올려야 한다.
@@ -71,7 +71,7 @@ review:a11y-manual 스크립트는 그래서 실패하는 것이 지금은 정
**게이트는 그대로 두고 서명 현황을 별도로 보고한다**
배포는 막지 않고 서명되지 않은 라우트 수를 드러낸다. 막지 않는 지표가 읽히지 않게 되는 것을 감수한다 — 이 저장소에서 매번 우는 검사가 읽히지 않게 된 사례가 이미 있다.
## 다음 검증
## 새 라우트 하나를 배포 절차 끝까지 따라가 본다
1. 라우트 하나를 골라 실제로 사람이 검토하고 서명해, 그 검토에 얼마가 드는지 잰다
2. 게이트가 서명 여부까지 보게 고치고 나머지 라우트에서 실제로 빨개지는지 확인한다
@@ -17,7 +17,7 @@ source:
라우트를 하나 더하면 서빙 패턴·청크 이름·게이트 기준값이 함께 움직인다. 손으로 유지하는 목록은 같은 방식으로 두 번 실패했다. 유도할 수 있는 것은 라우트 계약에서 유도하고, 유도할 수 없는 상수는 옛 값을 재현한 뒤에 갱신한다.
## 관계
## 라우트 목록을 여러 파일에 손으로 복사하면 서로 어긋난다
- **nginx 가 모르는 라우트는 새로고침에서 404 다**
이 기준의 근거 사건이다.
@@ -26,13 +26,13 @@ source:
- **종류를 나열하는 곳은 컴파일러나 계약 대조 검사가 세게 만든다**
같은 병을 다른 유한 집합에서 다루는 기준이다.
## 목적
## 파생 가능한 라우트 목록은 route contract에서 만든다
라우트를 더할 때 함께 움직여야 하는 목록이 빠지는 것을 막는다.
이 부류는 우는 시점이 제각각이다. 어떤 것은 빌드 매니페스트 단계에서, 어떤 것은 배포 직전 CI 에서, 어떤 것은 배포한 뒤 방문자가 먼저 만난다.
## 규칙
## 정본 하나에서 manifest와 검사 목록을 유도한다
### 1. 서빙 패턴은 라우트 계약에서 유도한다
@@ -54,19 +54,19 @@ source:
빠뜨림이 통과가 되지 않게 하려면 집합이 정확히 일치해야 한다. 그러면 라우트를 더할 때마다 상수들이 함께 움직이고, 그 갱신을 사람이 한다.
## 적용 조건
## 같은 라우트 집합을 build와 deploy, accessibility에서 함께 쓸 때
- 라우트 하나가 서빙 패턴·청크 이름·게이트 기준값 같은 목록을 함께 움직이는 프론트엔드. 라우트를 더하거나 지우는 변경에서 걸린다.
- 새 화면을 여는 작업을 시작할 때 그 목록부터 세고 시작한다. 다 만든 뒤에 세면 배포 직전에 걸린다.
## 예외
## 정본에서 계산할 수 없는 수동 검증 항목
- catch-all 라우트는 서빙 패턴으로 번역하지 않는다. 모든 미매치 URL 에 index.html 을 주면 엣지 404 가 soft 200 이 된다.
- 목록이 하나이고 그 목록을 빌드가 강제하면 유도 규칙을 따로 두지 않아도 된다.
## 예시
## 새 라우트가 건드리던 여덟 위치
/studio/releases 가 평문 404 였다. 라우트도 청크도 있었고 서빙 계약의 손 배열에만 없었다.
@@ -21,7 +21,7 @@ source:
- **종류 이름을 두 번 바꿨다 — 화면의 이름과 계약의 kind 를 갈랐다**
이 표를 한 곳으로 모은 뒤에 이름 자체를 다시 정한 기록이다.
- **개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다**
- **CONCEPT를 추가하자 종류 처리 누락이 열세 곳에서 드러났다**
같은 종류 목록이 코드 쪽에서 갈라진 사건이다.
- **톤을 지적받으면 고쳐 쓰지 말고 어떤 말을 쓸지 묻는다**
같은 시기에 문구를 다룬 기준이다.
@@ -18,7 +18,7 @@ source:
작업본 삭제가 막히는 이유는 다섯 가지인데 전부 같은 한 문장으로 나온다. 실제 사례에서 막은 것은 프로젝트 링크 한 행이었고, 문구는 「다른 기록이 참조한다」고 말했다.
## 관계
## 삭제 거부 사유는 서버에서 여러 조건으로 나뉜다
- **서버는 하나를 답했는데 화면은 추측 셋을 출력했다**
화면 쪽 문구를 고친 사건이고, 서버 쪽 문구는 고치지 않았다.
@@ -27,7 +27,7 @@ source:
- **화면은 못 읽은 것을 없다고 말하지 않는다**
화면이 무엇을 말해야 하는지를 다루는 기준이다.
## 사실
## 화면에는 다섯 사유가 같은 문장으로 표시된다
작업본 삭제 실패는 다섯 참조 중 무엇이 막았든 같은 오류 코드로 나간다 — DOCUMENT_IN_USE.
@@ -43,7 +43,7 @@ source:
사용자는 Project 필드를 「미지정」으로 바꾸고 저장한 뒤 삭제했다.
## 가정
## 서버의 원인 코드를 유지하면 화면도 정확히 설명할 수 있다
문구가 「another record」라고 하니 사용자가 Studio의 「관계」 편집기를 먼저 확인한다고 보고 있다. 실제 사례가 하나이고, 다른 사용자가 같은 순서로 움직이는지는 확인하지 않았다.
@@ -51,7 +51,7 @@ source:
질문 삭제처럼 참조가 둘뿐이면 이 문제가 덜하다고 보고 있다. 질문 삭제에서 사용자가 실제로 헤맨 기록은 없다.
## 미지수
## 사용자에게 어느 수준까지 원인을 노출할 것인가
무엇이 막는지 말하면서 내부 표 이름을 노출하지 않는 문구가 무엇인가.
@@ -59,7 +59,7 @@ source:
코드를 다섯으로 나누면 계약의 오류 코드 열거형도 함께 늘어난다. 그것을 반입하는 두 저장소가 그 값을 알아야 하는데, 그 비용이 얼마인가.
## 제약
## 도메인 정보와 내부 구현 세부사항을 구분해야 한다
클라이언트에 내보내는 메시지에 내부 표 이름이나 컬럼 이름을 넣지 않는다.
@@ -67,7 +67,7 @@ source:
오류 코드는 계약이 열거한다. 코드를 늘리면 계약과 반입한 두 저장소가 함께 움직인다.
## 선택지
## 원인 코드를 세분화할지 현재 문구를 유지할지
**참조 검사를 종류별로 갈라 어느 것이 걸렸는지 돌려준다**
다섯 개의 존재 검사를 따로 돌리고 걸린 종류를 응답에 싣는다. 화면이 그 종류를 사용자가 고칠 수 있는 화면의 이름으로 옮긴다. 코드를 늘리지 않고 응답의 부가 필드로 실으면 계약 변경이 작다.
@@ -81,7 +81,7 @@ source:
**문구만 고쳐 프로젝트 연결을 함께 언급한다**
가장 싸다. 다섯 중 어느 것인지는 여전히 말하지 못하고, 사용자가 확인할 화면이 셋으로 늘어난다.
## 다음 검증
## 다섯 거부 조건을 각각 만들어 응답과 화면을 비교한다
1. 참조 검사를 종류별로 갈라 걸린 종류를 응답에 실어 보고, 삭제 경로의 응답 시간이 얼마나 달라지는지 잰다
2. 다섯 종류를 사용자가 고칠 수 있는 화면 이름으로 옮겨 적고 몇 가지로 줄어드는지 센다
@@ -16,7 +16,7 @@ source:
사용자가 프로필의 문구가 AI 스럽다고 지적했다. 고쳐 쓴 첫 번째 안도 거절당했고, 결국 사용자가 직접 쓴 텍스트를 그대로 실었다. 이 사이트의 글은 작성자가 자기 말로 쓴다.
## 관계
## 톤 문제는 기술 사실보다 표현 선택에서 생긴다
- **종류 이름을 두 번 바꿨다 — 화면의 이름과 계약의 kind 를 갈랐다**
두 번째 안을 문어체로 세울 때 이 기준을 썼다.
@@ -25,13 +25,13 @@ source:
- **한 화면에 종류 이름이 아홉 개 떠 있었다 — 표가 여섯 벌이었다**
같은 시기에 종류 이름을 표 하나로 모았다.
## 목적
## 사용자가 원하는 말투를 추측으로 다시 만들지 않는다
작성자의 목소리로 쓰인 글을 고쳐 쓰다 두 번 거절당하는 것을 막는다.
톤을 지적할 때 사용자가 가리키는 것은 문장의 품질이 아니라 그 말을 누가 쓰는가다. 「더 나은 문장」을 제안할 때와 그 사람의 말투로 쓸 때 필요한 것이 다르고, 후자는 제안하는 쪽이 잘하지 못한다.
## 규칙
## 표현 지적을 받으면 사용할 단어와 피할 단어를 확인한다
### 1. 톤을 지적받으면 고쳐 쓰기 전에 어떤 말을 쓸지 묻는다
@@ -49,18 +49,18 @@ source:
무엇이 무엇으로 바뀌었는지 남겨 두면 다음에 같은 문구를 고칠 때 방향이 정해진다.
## 적용 조건
## 내용은 맞지만 문체나 용어 선택이 맞지 않을 때
- 공개 화면의 글이 작성자의 목소리인 곳 — 프로필, 프로젝트 소개, 구역 제목, 기록의 소제목
- 톤이 어색하다는 지적을 받았을 때
- 기존 글에 없던 낱말이나 어미를 새로 넣으려 할 때
## 예외
## 오탈자나 명백한 문법 오류처럼 의도가 분명한 수정
- 오류 문구처럼 서버가 답한 사실을 그대로 실어야 하는 곳에서는 말투를 묻지 않는다. 무엇을 실을지를 먼저 정한다.
- 계약이나 코드가 정한 이름은 이 규칙에서 뺀다. 표시 이름만 바꾸고 계약 값은 그대로 둔다.
## 예시
## 기술 용어를 사용자 표현으로 맞추는 경우
- 「섞는다」·「함께 기록한다」·「흩어지지 않게」가 무엇을 하는지 말하지 않는 동사로 끝난다고 지적받았다
- 「결론이 서는 조건」·「프로젝트를 답니다」·「접근을 나눠 견주고」가 번역투로 지적받았다
@@ -17,7 +17,7 @@ source:
이 사이트는 이미지 레지스트리를 쓰지 않는다. 로컬에서 빌드한 이미지를 tar 로 말아 서버에 올리고, 클러스터 안에 일회성 Job 을 띄워 컨테이너 런타임으로 import 한 뒤 이미지 태그를 바꾼다. 이 경로 때문에 빌드 인자와 파일 권한이 배포에서만 드러난다.
## 관계
## 이미지 Registry 없이도 노드에 같은 이미지를 배포할 수 있다
- **배포 인자를 빠뜨려 배포본이 존재하지 않는 주소를 불렀다**
이 경로에서 빌드 인자가 어떻게 새는지가 그 기록에 있다.
@@ -26,7 +26,7 @@ source:
- **배포 전에 사람이 돌려야 하는 것과 그 함정**
이 경로에서 사람이 기억해야 하는 것들이 그 기준에 있다.
## 본문
## tar export와 import를 이용한 이미지 전달 경로
<!-- body:start -->
@@ -24,7 +24,7 @@ source:
- **이음매마다 그 이음매를 실제로 지나는 검사를 하나씩 둔다**
합성 루트가 그 목록의 한 줄이다.
- **매퍼가 null 을 돌려주고 호출부가 걸러 내, 기록이 조용히 사라졌다**
- **매퍼가 null을 반환해 QUESTION과 CONCEPT가 목록에서 누락됐다**
스텁 때문에 보이지 않던 다른 매핑 결함이다.
- **한 경계를 고쳤으면 값의 여정 끝에서 확인한다**
이 사건이 그 규칙의 근거 하나다.
@@ -1,7 +1,7 @@
---
kind: CASE
slug: the-generator-dropped-four-contract-fields
title: 생성기가 계약 필드 넷을 조용히 빠뜨렸다 — 파생 스펙에 남은 YAML alias 34곳
title: 생성기가 계약 필드 넷을 누락했고 파생 스펙에 YAML alias 34곳이 생겼다
topic: seams-no-test-crosses
topicName: 테스트가 지나지 않는 이음매
project: TechLog
@@ -12,7 +12,7 @@ source:
- final/document.md#§7.6
---
# 생성기가 계약 필드 넷을 조용히 빠뜨렸다 — 파생 스펙에 남은 YAML alias 34곳
# 생성기가 계약 필드 넷을 누락했고 파생 스펙에 YAML alias 34곳이 생겼다
계약에 있는 필드 넷이 생성된 모델에서 사라져 있었다. 파생 단계의 YAML alias 때문에 파서가 스키마 15개를 거절했고, 거절당한 스키마들은 전부 타입을 명시하고 있어 계약 결함처럼 보이지 않았다. 검증을 끄면 생성이 성공했고, 그렇게 만든 모델에 그 넷이 없었다. 컴파일은 통과한다 — 아직 아무도 그 필드를 안 쓰니까.
@@ -16,7 +16,7 @@ source:
「모든 검사가 통과했는데 운영에서 깨졌다」가 다섯 번 있었다. 매번 그 이음매를 아무 테스트도 지나지 않았다. 층을 스텁으로 나눠 시험하는 구조에서는 그 나눈 자국마다 검사가 하나씩 필요하다.
## 관계
## 값이 여러 변환 경계를 지나면 각 경계에서 누락될 수 있다
- **파드가 두 번 CrashLoopBackOff 로 들어갔다**
스프링 컨텍스트 이음매의 근거 사건이다.
@@ -24,16 +24,16 @@ source:
persistence SQL 이음매의 근거 사건이다.
- **합성 루트에 테스트가 없어 공개 사이트 전체가 오류 화면이었다**
합성 루트와 HTTP 매퍼 이음매의 근거 사건이다.
- **생성기가 계약 필드 넷을 조용히 빠뜨렸다**
- **생성기가 계약 필드 넷을 누락했다**
생성기 이음매의 근거 사건이다.
## 목적
## 경계마다 실제 입력과 출력을 지나는 검사를 둔다
층을 스텁으로 나눠 시험하는 구조에서 그 나눈 자국이 검사되지 않고 남는 것을 막는다.
이 부류는 모든 검사가 초록불인 상태로 배포된다. 각 층의 검사는 자기 층을 정확히 보고 통과하며, 통과하지 않은 것은 층과 층 사이다.
## 규칙
## 생성·매핑·직렬화·렌더링 경계를 각각 확인한다
### 1. 스프링 컨텍스트를 띄우는 검사를 하나 둔다
@@ -59,13 +59,13 @@ source:
컨테이너를 띄우는 검사를 표준 검사에 넣으면 모든 빌드가 느려진다. 빼는 것은 되지만, 뺀 뒤에 그 태스크가 돌지 않으면 검사가 없는 것과 같다.
## 적용 조건
## 한 값이 backend에서 frontend까지 여러 모델을 통과할 때
- 스텁으로 층을 나눠 시험하는 구조. 계약이 다른 저장소에 있고 생성기를 지나 들어오거나, 컨테이너가 필요한 검사를 별도 태스크로 뺀 저장소에서 걸린다.
- 「모든 검사가 통과했는데 운영에서 깨졌다」가 나오면 무엇이 깨졌는지보다 어느 이음매를 아무 검사도 지나지 않았는지를 먼저 센다.
## 예외
## 한 단계 안에서만 사용되고 외부 경계를 넘지 않는 값
- 그 층을 실제로 지나는 검사가 이미 있으면 더 두지 않는다.
@@ -73,7 +73,7 @@ source:
- 정적으로 셀 수 있는 규칙은 컨텍스트를 띄우지 않고도 걸린다. 그때는 무거운 검사를 새로 두지 않는다.
## 예시
## 계약 필드와 relation summary 누락
- 컨텍스트를 띄우지 않아 파드가 두 번 CrashLoopBackOff 로 들어갔다. 실제 PostgreSQL 위에서 도는 통합 테스트 26개도 통과한 상태였다.
@@ -92,7 +92,7 @@
"kinds": {
"case": [
{
"title": "개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다",
"title": "CONCEPT를 추가하자 종류 처리 누락이 열세 곳에서 드러났다",
"slug": "one-new-kind-fell-through-thirteen-places",
"readiness": "READY",
"source": [
@@ -720,7 +720,7 @@
"evidenceFiles": []
},
{
"title": "생성기가 계약 필드 넷을 조용히 빠뜨렸다 — 파생 스펙에 남은 YAML alias 34곳",
"title": "생성기가 계약 필드 넷을 누락했고 파생 스펙에 YAML alias 34곳이 생겼다",
"slug": "the-generator-dropped-four-contract-fields",
"readiness": "READY",
"source": [
@@ -1198,7 +1198,7 @@
"evidenceFiles": []
},
{
"title": "매퍼가 null 을 돌려주고 호출부가 걸러 내, 기록이 조용히 사라졌다",
"title": "매퍼가 null을 반환해 QUESTION과 CONCEPT가 목록에서 누락됐다",
"slug": "records-disappeared-without-a-trace",
"readiness": "READY",
"source": [
@@ -20,7 +20,7 @@ source:
공개 화면의 한 줄은 PostgreSQL 의 투영 테이블에서 출발해 열한 번 모양을 바꾼 뒤에 그려진다. 그 사이 어느 한 곳이 값을 담지 않아도 오류가 나지 않는다. undefined 는 빈 문자열로 그려지고 빈 배열은 「항목이 없습니다」로 그려진다.
## 관계
## 공개 화면의 값 하나도 여러 계약과 변환을 지난다
- **공개 Reference 가 통째로 비어 있었다 — 이름이 어긋났고 본문은 다른 테이블에 있었다**
이 경계 중 두 곳에서 값이 사라진 사건이다.
@@ -29,7 +29,7 @@ source:
- **한 경계를 고쳤으면 값의 여정 끝에서 확인한다**
이 경계 수가 그 규칙의 근거다.
## 본문
## DB에서 공개 화면까지 값이 지나는 열한 경계
<!-- body:start -->
@@ -17,7 +17,7 @@ source:
Studio 편집기에서는 값이 다 보이는데 공개 화면만 비어 있다면, 작성과 공개 사이의 계약 경계를 먼저 확인할 만한 강한 신호다. 이 저장소에서는 같은 신호가 여덟 번 계약 누락을 가리켰지만, 저장 구조가 종류별로 다른 경우에는 조회 로직이 원인일 수 있다.
## 관계
## Studio에는 보이는데 공개 화면에만 없으면 경계 중 하나가 값을 버린 것이다
- **공개 Reference 가 통째로 비어 있었다 — 이름이 어긋났고 본문은 다른 테이블에 있었다**
이 신호가 처음 잡힌 사건이다.
@@ -26,13 +26,13 @@ Studio 편집기에서는 값이 다 보이는데 공개 화면만 비어 있다
- **한 경계를 고쳤으면 값의 여정 끝에서 확인한다**
칸을 더한 뒤 무엇을 확인할지가 그 기준에 있다.
## 목적
## UI 문제처럼 보여도 먼저 contract와 mapper를 확인한다
데이터베이스에 값이 있는데 화면이 비어 있을 때 어디를 먼저 볼지 정한다.
이 부류는 오류를 내지 않으므로 로그에서 출발하면 아무것도 나오지 않는다. undefined 는 빈 문자열로 그려지고 빈 배열은 「항목이 없습니다」로 그려진다.
## 규칙
## DB에서 public response까지 field 이름을 순서대로 대조한다
### 1. Studio 에서는 보이고 공개 쪽만 비면 그 사이의 계약을 먼저 본다
@@ -54,13 +54,13 @@ Reference 의 본문은 문서 본문 칸이 아니라 규칙과 예시를 담
게이트웨이가 읽는 이름이 계약의 타입에 있는지를 묻는다. 값을 비교하는 검사는 픽스처를 게이트웨이가 읽는 이름으로 만들면 그대로 통과한다 — 테스트 작성자와 게이트웨이 작성자가 이름에 대해 합의한 것을 확인할 뿐이다.
## 적용 조건
## 작성 화면에는 값이 있지만 공개 화면에는 없을 때
- 같은 데이터를 두 표면이 각자의 계약으로 읽고, 한쪽만 비어 보이는 화면. 작성 계약과 조회 계약이 나뉜 구조에서 걸린다.
- 계약에 칸을 더하거나 화면에 칸을 더하는 변경에서도 건다. 화면이 먼저 늘면 그 칸이 응답에 있는지 확인할 곳이 없다.
## 예외
## 공개 정책상 의도적으로 숨기는 field
- 두 표면이 같은 계약을 쓰면 이 신호는 성립하지 않는다. 그때는 매퍼나 질의를 먼저 본다.
@@ -68,7 +68,7 @@ Reference 의 본문은 문서 본문 칸이 아니라 규칙과 예시를 담
- 값이 있는데 겹쳐 보이는 경우는 이 신호가 아니다. 빈 칸을 다른 값으로 메우면 같은 글이 두 번 나온다.
## 예시
## Reference 본문 field 이름 불일치
- 공개 Reference 가 통째로 비었을 때 게이트웨이가 읽던 네 이름이 전부 계약에 없었다.
@@ -18,7 +18,7 @@ source:
값이 여러 경계를 갈아타는 구조에서 한 경계를 고치고 「고쳤다」고 판단해 세 번 틀렸다. 타입 검사도 단위 테스트도 「코드를 읽어 보니 맞다」도 전부 중간 지점이다. 배포본에서 그 값이 실제로 그려지는 곳까지 가서 확인한다.
## 관계
## 중간 경계를 고쳐도 최종 화면까지 값이 도달하지 않을 수 있다
- **관계의 요약이 경계 세 곳을 지나며 사라졌다**
한 경계를 고치고 판단해 두 번 틀린 사건이다. 여기서 요약은 공개 계약의 `ResolvedRelation.summary`다.
@@ -27,13 +27,13 @@ source:
- **TypeScript 가 검사를 놓아 주는 네 곳**
타입 통과가 반영의 증거가 아닌 이유가 그 개념에 있다.
## 목적
## 수정한 값이 실제 사용 지점까지 도착했는지 확인한다
「고쳤다」는 판단이 틀리는 것을 막는다.
값이 열한 경계를 지나는 구조에서 한 경계만 보고 판단하면, 다음 경계가 같은 값을 다시 버려도 알 수 없다. 이 저장소에서 그 판단이 세 번 틀렸다.
## 규칙
## 가장 마지막 consumer에서 결과를 재검증한다
### 1. 고친 값이 실제로 그려지는 곳까지 가서 본다
@@ -55,19 +55,19 @@ source:
값이 아니라 이름을 지키는 검사를 두면 여정의 한 구간을 그 검사가 대신한다. 그 구간이 어디까지인지 적어 두지 않으면 다음 사람이 검사를 여정 전체로 읽는다.
## 적용 조건
## mapper나 contract field를 수정한 뒤
- 값이 계약·매퍼·포트를 여러 번 갈아타는 구조에서 「고쳤다」를 판단할 때. 계약을 소유한 저장소가 따로 있고 생성기를 지나 들어오면 특히 걸린다.
- 앞선 커밋이 같은 값을 고치려다 못 고친 이력이 있으면 반드시 건다. 그 커밋이 무엇을 근거로 고쳤다고 판단했는지가 대개 중간 지점이다.
## 예외
## 중간 변환 자체가 최종 산출물인 테스트
- 경계가 하나뿐이거나 고친 그 곳이 여정의 끝이면 중간 확인으로 충분하다.
- 배포본을 열 수 없는 변경 — 아직 배포되지 않은 경로 — 은 여정의 끝까지 갈 수 없다. 그때는 어디까지 확인했는지를 적는다.
## 예시
## relation summary를 세 경계에서 수정한 뒤 공개 목록 확인
- 관계 요약을 세 번 고쳤다. 매번 화면을 보고 나서야 다음 경계가 버리는 것을 알았다.
@@ -18,7 +18,7 @@ source:
「타입 검사가 통과했으니 반영됐다」는 판단이 이 저장소에서 네 번 틀렸다. 매번 다른 이유였다 — 메서드 매개변수의 bivariance, as 단언, never 로 받아 캐스팅하는 조립기, 그리고 검사할 파일을 갖지 않은 tsconfig 다.
## 관계
## TypeScript 타입 검사가 모든 런타임 누락을 잡지는 못한다
- **구현이 종류를 좁게 적어도 넓은 포트를 만족했다**
bivariance 가 통과시킨 사건이다.
@@ -27,7 +27,7 @@ source:
- **공개 Reference 가 통째로 비어 있었다**
as 단언이 통과시킨 사건이다.
## 본문
## bivariance와 type assertion, never cast, tsconfig 경계
<!-- body:start -->
@@ -65,7 +65,7 @@ as 는 「이 값을 이 타입으로 다루겠다」는 선언이다. 그 이
요청을 만드는 조립기가 입력을 `(input: never)` 로 받아 캐스팅하면, 계약에 인자를 더해도 컴파일러가 아무 말도 하지 않는다. `never` 는 어떤 값도 속하지 않는 타입이라 무엇을 넘겨도 검사할 것이 없다.
조립기가 손으로 나열한 질의 인자에 그 값이 없으면 요청에서 조용히 빠진다. 목록의 페이지 번호를 눌러도 쪽이 넘어가지 않던 것이 이 모양이었다 — `page` 가 조립기의 목록에 없었다.
조립기가 손으로 나열한 질의 인자에 그 값이 없으면 요청에서 누락돼도 오류가 나지 않는다. 목록의 페이지 번호를 눌러도 쪽이 넘어가지 않던 것이 이 모양이었다 — `page` 가 조립기의 목록에 없었다.
## 검사할 파일이 없는 tsconfig
@@ -20,7 +20,7 @@ source:
결함을 되돌려 실제로 빨개지는 것을 확인한 뒤에 커밋한다. 확인하지 않은 가드는 그 결함이 원래 없었는지 검사가 안 도는지 구별되지 않는다.
## 관계
## Guard가 존재하는 것과 실제 결함을 잡는 것은 다르다
- **가드는 작동했는데 제가 그것을 돌리지 않아 두 번 새어 나갔다**
가드가 정확해도 돌리지 않으면 소용없다는 사건이다.
@@ -29,13 +29,13 @@ source:
- **이음매마다 그 이음매를 실제로 지나는 검사를 하나씩 둔다**
어디에 가드를 둘지를 다루는 기준이다.
## 목적
## 회귀 검사가 문제를 실제로 탐지하는지 확인한다
무엇도 잡지 못하는 가드가 초록불로 남는 것을 막는다.
가드를 넣었다는 것과 그 가드가 무엇을 잡는다는 것은 다르다. 둘은 화면에서 구분되지 않는다 — 검사가 통과했을 때 그 결함이 원래 없었는지 검사가 그것을 안 보는지 알 방법이 없다.
## 규칙
## 결함을 잠시 되돌려 guard가 실패하는지 본다
### 1. 결함을 되돌려 그 가드가 실제로 멈추는 것을 확인한 뒤 커밋한다
@@ -55,18 +55,18 @@ source:
사람이 기억해서 돌리는 가드는 절반만 존재한다. 가드가 정확해도 결과를 아무도 읽지 않으면 빨간 채로 여러 커밋을 지나간다.
## 적용 조건
## 새 회귀 테스트나 CI guard를 추가할 때
- 재발 방지로 테스트·아키텍처 규칙·CI 게이트를 넣을 때
- 결함을 고치는 커밋에서 가드를 함께 넣을 때
- 이미 있는 가드가 무엇을 잡는지 확인해야 할 때
## 예외
## 파괴적이거나 외부 시스템을 실제로 손상시키는 재현
- 결함을 되돌릴 수 없는 것 — 이미 마이그레이션으로 고친 데이터, 지난 배포에서만 나던 상태 — 은 현재 상태가 고쳐져 있음을 대신 증거로 남긴다.
- 기존 가드를 옮기거나 이름만 바꾸는 변경은 되돌려 확인하지 않아도 된다. 다만 옮긴 뒤에 한 번은 돌린다.
## 예시
## route와 UI contract guard 검증
- 가드 셋을 각각 결함으로 되돌려 실제로 빨개지는 것을 확인한 기록을 남겼다
- 계약에서 CONCEPT 을 빼자 백엔드의 계약 대조 테스트가 빨개졌다
@@ -20,7 +20,7 @@ source:
CI 에 묶이지 않은 검증이 남아 있으면 그것을 돌리는 것은 사람이다. 다섯 명령을 다 돌려야 하고, 그중 둘은 순서와 환경 때문에 그냥 돌리면 틀린 답을 준다.
## 관계
## 자동화돼 있지 않은 검사는 사람이 실행하지 않으면 빠진다
- **가드는 작동했는데 제가 그것을 돌리지 않아 두 번 새어 나갔다**
이 목록이 필요해진 사건이다.
@@ -29,13 +29,13 @@ CI 에 묶이지 않은 검증이 남아 있으면 그것을 돌리는 것은
- **레지스트리 없이 tar 를 import 하는 배포 경로**
빌드 산출물에 커밋 해시가 들어가는 이유가 그 개념에 있다.
## 목적
## 배포 전에 필요한 수동 명령을 명시한다
배포 전에 돌려야 하는 것을 사람이 기억에 의존해 고르는 것을 막는다.
이 저장소에서 두 번 빠뜨려 결함이 배포까지 갔다. 명령이 여럿이고 그중 일부만 도는 것이 가능한 구조에서는 「돌렸다」가 무엇을 돌렸다는 뜻인지 정해 두어야 한다.
## 규칙
## 명령과 기대 결과, 실패 시 중단 조건을 함께 적는다
### 1. 프론트는 다섯 개를 다 돌린다
@@ -57,18 +57,18 @@ npm_config_* 환경 변수가 설정되어 CI 워크플로 생성 테스트가
하위 프로세스를 띄우는 세 케이스는 이 환경에서 실패하고 같은 리비전의 다른 실행에서도 똑같이 재현된다. 코드 변경과 무관하다는 것을 적어 두지 않으면 다음 사람이 그것을 고치려 든다.
## 적용 조건
## CI가 아직 실행하지 않는 검사나 로컬 검증
- CI 에 묶이지 않은 검증이 남아 있는 저장소에서 배포 직전에 하는 일
- 명령이 여럿이고 그중 일부만 도는 것이 가능할 때
- 빌드 산출물이 작업 트리 상태에 따라 달라지는 저장소에서
## 예외
## 이미 배포 파이프라인에서 강제되는 검사
- CI 가 그 명령을 돌리면 이 목록에서 뺀다. 사람이 기억해서 돌리는 가드는 절반만 존재한다.
- 테스트 실행기가 메모리를 더 필요로 하는 조합이면 힙을 올린다. 증상이 테스트 실패가 아니라 실행기를 완료할 수 없다는 메시지로 나와 원인을 가린다.
## 예시
## 별도 화면 테스트와 typecheck 명령
- 화면 테스트를 돌리지 않아 23건이 빨간 채로 여러 커밋을 지나갔다
- 루트 tsconfig 를 직접 부르는 명령이 통과해서 운영의 ReferenceError 를 못 봤다