카드는 본문 요약을 그대로 가져다 세 줄로 자른다. 그 요약은 Markdown 으로
쓰였으므로 작성자가 코드 표시로 쓴 백틱이 카드에도 그대로 나왔다 — 문서
본문에서는 <code> 가 되지만 카드에서는 그냥 문자다. 홈·탐색·검색이 같은
텍스트를 쓰므로 세 곳에서 같이 보였다. 배포된 검색 모달을 열어 보고서야
알았다: 본문만 고치고 카드는 그대로 두었다.
카드에서 코드 스타일을 살리지 않는 이유는 카드가 훑어보는 자리이기
때문이다. 한 줄 안에 배경색 조각이 여럿 끼면 제목보다 그쪽이 먼저 눈에
든다. 문단 줄바꿈도 공백으로 접는다 — 어차피 세 줄에서 잘리므로 줄을
지켜 봐야 잘리는 위치만 어긋난다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
검색 결과가 제목과 요약을 그대로 보여 주기만 했다. "session" 으로 찾아도
어느 대목이 걸렸는지 눈으로 다시 찾아야 했고, 요약은 목록에서 세 줄로
잘리므로 걸린 대목이 잘린 뒤쪽이면 왜 이 결과가 나왔는지조차 알 수 없었다.
대소문자는 구분하지 않는다 — 이 저장소의 글은 Session 과 session 을 섞어
쓴다. 배경을 칠하는 대신 밑줄과 굵기로 표시해 목록의 회색 톤을 지킨다.
릴리스 탭 제목이 판마다 「변경 기록 · Tech Log」로 같았다. 이 화면은 공개
문서 렌더러를 타지 않아 앞서 붙인 훅이 닿지 않았다.
훅은 이른 return 보다 앞에 둔다. 처음에 데이터를 꺼낸 뒤에 불렀더니 렌더마다
호출 순서가 달라져 lint 가 잡았다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
릴리스 노트의 각 칸은 Markdown 인데 줄을 쪼개 `- ` 만 떼는 것이 전부였다.
그래서 작성자가 소제목으로 쓴 `## 작성` 이 항목 하나로 섞였고, `:::note`
와 `---`, `` 도 글자 그대로 목록에 나왔다. 그 노트의 내용이
하필 "본문의 표·코드·callout·그림이 렌더링됩니다" 였다.
소제목·수평선·블록 울타리는 항목이 아니므로 버린다. 소제목까지 살리려면
화면이 절을 나눠야 하는데 이 칸은 「무엇이 바뀌었나」 아래의 한 목록이다.
번호 목록도 항목으로 읽는다. 백틱은 남겨 두고 화면이 코드로 그린다.
robots.txt 가 404 였다. 파일은 이미지에 들어 있었지만 nginx 설정이 서빙할
파일을 하나씩 명시하는 구조라 등록되지 않은 것은 SPA 폴백으로 떨어진다 —
크롤러가 index.html 을 규칙으로 읽을 수는 없으므로 규칙이 없는 것과 같았다.
설명(meta)에서 백틱을 지운다. 본문에서는 코드가 되지만 검색 결과에는 그
문자가 그대로 나간다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
에디터 칸 이름을 공개 화면과 맞춘다. 목적→이 기준을 쓰는 이유, 규칙→판단
기준, 적용 조건→적용할 때, 예외→예외와 주의, 사실→확인한 사실,
미지수→남은 미지수, 선택지→검토한 선택지. 쓰는 사람이 지금 채우는 칸이
공개 화면 어디로 가는지 외우지 않아도 된다.
대시보드의 세 칸이 같은 목록을 세 번 반복했다. 「검증과 미리보기」와
「게시 준비」가 「이어서 작성」을 걸러 낸 부분집합인데 「이어서 작성」은
전체를 그대로 그렸기 때문이다 — 모든 문서가 같은 단계면 세 칸이 겹친다.
각 문서는 지금 서 있는 구간 한 곳에만 나온다.
릴리스에서 「상태 공개 · 공개일 2026-08-22」 옆에 「아직 공개하지 않음」이
같이 나왔다. 경로가 비었다고 미공개는 아니다 — 공개 여부는 상태가 말한다.
행에서 눈에 띄는 단 하나가 되돌릴 수 없는 동작이었다. 편집을 같은 격의
버튼으로 올리고, 삭제는 danger 로 낮추고, 격자에 자리를 만들어 다음 줄로
떨어지지 않게 한다. 게시 기록이 이미 그 모양이었다.
주제·프로젝트는 「다음: 내용 편집」을 안내하면서 그 줄의 버튼은 게시 취소와
삭제뿐이었다. 공개 프로젝트 화면이 비어 있던 이유가 여기다.
죽은 코드였던 PublicDocumentHeader 를 걷어낸다. 화면을 실제로 그리는 것은
PublicRecordRenderer 이고 그 컴포넌트는 아무도 부르지 않았다 — 어제 이
컴포넌트에 줄바꿈을 고쳐 넣었지만 화면에는 닿지 않았다. 그 자리를 지키던
가드도 진짜로 그려지는 쪽으로 옮긴다.
탭 제목과 설명에 문서를 반영한다. 공개 문서가 전부 "Reference · Tech Log"
였고 설명은 모든 화면이 "Tech Log frontend" 하나였다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
칸이 내용을 따라 자란다. 112px 고정이라 659자짜리 규칙 본문을 세 줄짜리
구멍으로 편집했다 — 편집기의 칸 22개 중 10개가 내용이 넘쳐 잘려 있었다.
상한을 70vh 로 두는 이유는 긴 본문 하나가 화면을 통째로 차지하면 나머지
칸으로 이동할 수 없기 때문이다. field-sizing 을 모르는 브라우저는 예전
동작 그대로다 — 나빠지지 않는다.
미리보기가 제자리에 붙는다. 폼과 같은 흐름에 놓여 있어서 편집기가
8,872px 이면 미리보기도 그만큼 아래로 흘렀고, 아래쪽 칸을 고치는 동안
미리보기는 화면 밖이었다. 한 열로 접히는 폭에서는 붙박이를 푼다 —
위아래로 쌓인 상태에서 붙이면 폼을 가린다.
종류 이름을 한 곳에 모은다. 표가 화면마다 복사되어 여섯 벌이었고 그래서
갈라졌다: 같은 QUESTION 이 공개 화면에서 "Open Question", 작업본 목록과
게시 기록에서 "Question", 편집기 상태 줄에서 "QUESTION" 이었다. 쓰는
사람은 같은 문서를 화면마다 다른 이름으로 만난다. Record<RecordKind,
string> 이므로 종류가 늘면 빠진 자리를 타입이 잡는다.
미리보기는 공개 화면과 같은 렌더러를 쓰므로, 오늘 고친 문단·인라인 코드가
편집기 미리보기에도 그대로 적용된다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
Case 만 블록 파서를 타고 나머지 유형은 문자열을 그대로 내보내고 있었다.
그래서 두 가지가 깨졌다.
작성자가 백틱으로 적은 식별자가 백틱째 화면에 나왔다. 어떤 Reference 는
한 문서에 백틱이 32개였고, 그 원문이 홈 카드·탐색 카드·검색 결과까지
그대로 퍼졌다. 판단 기준은 `<p>{rule.body}</p>` 로, 적용할 때·예외·예시는
`<li>{item.text}</li>` 로 아무것도 거치지 않고 나가고 있었다.
빈 줄로 나눈 문단이 문단으로 보이지 않았다. 어제 넣은 PlainText 는 모든
줄바꿈을 <br> 로 만들었기 때문에 빈 줄도 <br><br> 로 나갔고, 문단 사이
여백이 없었다. Reference 7개 전부에 빈 줄이 9~16개 있다.
ProseText 로 바꾼다 — 빈 줄은 문단을 가르고, 문단 안 줄바꿈은 그 자리에
지키고, 백틱은 코드로 읽는다. 백틱 수가 홀수면 원문을 그대로 둔다:
작성자가 백틱 자체를 쓴 것일 수 있고, 반쯤 해석해 한쪽만 코드로 만드는
쪽이 더 나쁘다.
블록 파서(parseCaseContent)를 쓰지 않는 이유는 그쪽이 Case 전용 문법과
도식 참조까지 물고 있어 이 칸들에 없는 해석기를 끌고 오기 때문이다.
머리말 가드는 <br> 개수로 재고 있었다. 이제 기준이 문단이므로 문단 수와
문단 안 줄바꿈을 함께 확인하도록 고친다 — 가드가 낡은 것이지 화면이
틀린 것이 아니다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
손으로 찍으면 두 가지를 반드시 놓친다.
뷰포트: 브라우저 세션이 리셋되면 창은 기본 크기(약 877px)로 돌아간다.
이 사이트의 분기는 1179/1050/900/767 이라 877px 는 900 아래로 떨어져
헤더가 접힌 좁은 화면이 나온다 — 방문자 대부분이 보지 않는 배치를 놓고
디자인을 논하게 된다.
축소: 전체 페이지를 한 장으로 찍으면 세로로 긴 문서가 통째로 줄어든다.
실제로 1425x4466 이 638x2000 으로 들어와 17px 글자가 7~8px 이 되었다.
덩어리는 보이지만 정작 타이포는 못 본다.
그래서 폭 세 개를 고정으로 돌고 화면 높이만큼 잘라 찍는다. 잊을 자리를
없앤다. 눈은 어디가 이상한지까지만 알려 주므로 폭마다 측정도 함께 남긴다
— 이번에 고친 결함(목록 항목 간격 0px, 한 줄 53자)은 전부 측정에서 나왔다.
목록 판정에서 gapPx 만 보면 여백이 항목 안(padding)에 있는 경우를 구분이
없는 것으로 잘못 읽는다. 실제로 그렇게 읽어서 「판단 기준」을 결함으로
지목했었다. separatedByPadding 을 따로 남겨 같은 오독을 막는다.
networkidle 은 기다리지 않는다 — 이 앱은 유휴 상태에서도 요청을 보내
그 순간이 오지 않는다. 본문 제목이 그려질 때까지 기다린다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
요청을 만드는 조립기가 질의 인자를 손으로 나열하는데 거기 page 가 없었다.
그래서 숫자를 눌러도, 꺾쇠를 눌러도 서버에는 page 없이 나갔고 늘 1쪽이
돌아왔다. 작업본과 게시 기록 둘 다 그랬다.
이것이 타입 검사를 통과한 이유: 조립기가 입력을 `(input: never)` 로 받아
캐스팅한다. 계약에 인자를 더해도 여기 적지 않으면 컴파일러는 아무 말도
하지 않고 요청만 조용히 그 값을 뺀다. 같은 모양으로 값이 사라지는 결함을
이 저장소에서 여러 번 만났으므로, 요청을 실제로 만들어 page 가 실리는지
확인하는 가드를 함께 둔다 — 되돌리면 깨지는 것을 확인했다.
UI: 테두리 있는 흰 버튼을 줄지어 놓으니 화면에서 가장 눈에 띄는 덩어리가
되었다. 봐야 할 것은 목록이다. 상자를 걷어내고 `‹ 1 | 2 | 3 ›` 로 두되
누르는 자리는 40px 로 남긴다 — 보이는 반응은 글자뿐이지만 손가락이 닿는
범위까지 글자만큼 줄이면 터치에서 누르기 어렵다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
본문 목록에 마커도 항목 사이 간격도 없었다. 항목 하나가 여러 줄이면
어디서 끝나고 다음이 시작하는지 알 방법이 없어서, Open Question 의
「확인한 사실」 6개가 12줄짜리 덩어리 하나로 보였다. 「남은 미지수」 7개,
Reference 의 「적용할 때·예외와 주의·예시」도 같았다.
한 줄은 50~53자였다. 한글은 그보다 짧아야 읽힌다 — 줄이 길면 줄 끝에서
다음 줄 첫머리로 돌아올 때 같은 줄을 다시 읽거나 한 줄을 건너뛴다.
같은 화면의 머리말 요약이 이미 40자로 잡혀 있고 그쪽은 잘 읽히므로
본문도 그 자수에 맞춘다(720 / 18 ≈ 40자).
번호를 붙인 `.reference-rules` 는 padding 22px 와 경계선으로 이미 나뉘어
있어 건드리지 않는다. 처음에 「목록 간격이 전부 0」이라고 본 것은 바운딩
박스만 재서 생긴 오독이었다 — 여백이 항목 안에 있으면 0으로 나온다.
대비(9.4:1)와 줄간(1.82)은 이미 좋았다. 문제는 색이 아니라 구조였다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
600 은 「아래 저장 경로가 이미 600 이니 거기 맞추자」는 판단이었지 실제로
쓰는 글의 길이를 본 것이 아니었다. 요약은 여러 문단이다.
길어진 요약이 드러낸 두 가지를 함께 고친다.
목록: 최근 기록·탐색·검색·홈 초점은 요약을 통째로 그렸다. 2000자면 한
항목이 화면을 덮어 목록이 목록이 아니게 된다. 세 줄에서 자른다 — 전문은
문서를 열면 나온다.
머리말: `public-document-header` 만 `PlainText` 를 거치지 않고 요약을
그대로 넣고 있었다. 작성자가 나눈 문단이 전부 한 덩어리로 이어졌다.
판단 결정 요약에서 고쳤던 것과 같은 결함이고, 이 자리를 빠뜨렸다.
되돌리면 <br> 가 3개에서 0개가 되어 가드가 깨지는 것을 확인했다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
요약 칸이 300자에서 말없이 입력을 멈췄다. 아무 표시가 없어 키보드가
고장 난 것처럼 보인다.
계약 상한을 600 으로 올리고(입력·공개 렌더 모델 함께) 칸 아래에
`412 / 600` 을 둔다. 한계에 닿으면 붉게 바뀐다.
글자 수는 label 밖에 둔다. 안에 두면 label 의 글자가 모두 칸의 이름이
되어 이름이 "요약 412 / 600" 으로 타자마다 바뀐다 — 기존 테스트 둘이
실제로 그것을 잡아냈다. 읽어 주는 것은 한계에 닿는 순간뿐이다. 글자마다
세어 읽으면 받아쓰기가 된다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
「다음」 버튼 하나뿐이라 뒤로 넘어가면 앞쪽으로 돌아올 수 없었다. 커서
페이지네이션이라 앞으로만 갈 수 있었기 때문이다.
서버가 총 쪽수를 주고(StudioPageMetadata) 목록은 `‹ 1 2 3 ›` 을 그린다.
쪽이 많으면 현재 쪽 좌우 2개씩만 그리고 첫·끝은 늘 남긴다 — 어디에
있든 처음과 끝으로 한 번에 갈 수 있다.
게시 기록은 페이지 이동이 아예 없었다(limit 100 으로 한 번에 다 가져왔다).
작업본과 같은 20개 단위로 맞춘다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
프로젝트 기록에서 Open Question 이 보이지 않았다. 이 목록은 탐색의 지식 목록과 응답 모양이
다른데(유형이 네 가지고 요약이 `summary` 한 칸에 온다) 지식 목록의 매퍼를 그대로 쓰고 있었다.
그 매퍼는 CASE/REFERENCE 가 아니면 `null` 을 돌려주고 호출부가 `filter` 로 걸러 내므로, 질문과
개념은 오류도 빈 자리도 남기지 않고 조용히 없어졌다 — 목록이 한 줄 짧아질 뿐이라 눈으로는
알아채기 어렵다.
살아남은 줄도 온전하지 않았다. 매퍼가 `primarySummary`·`primaryTopic` 을 찾는데 이 응답에는
그 이름이 없어서 요약과 주제가 빈 채로 그려졌고, 게시일은 응답 자체에 없었다 — 그래서 목록의
모든 줄이 "제목만 있고 · 만 남은" 모양이었다.
계약이 요약·주제·게시일을 싣게 하고(design-package 76a7ccb), 이 응답 전용 매퍼를 둔다. 네
유형이 모두 살아남는지와 그 칸들이 채워지는지를 함께 묻는 테스트를 세운다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
공개 결정 화면에 네 가지가 어긋나 있었다 — 제목 자리에 결정문 전문이 나오고, 요약이 아예
없고, 줄바꿈이 전부 접히고, 영향과 근거 기록이 늘 비어 있었다.
원인은 하나로 모인다. 결정에는 상세 endpoint 가 없다 — 공개 주소가 목록 위의 앵커다. 그런데
계약의 목록 항목에 title·summary·consequences·evidence 가 없어서, 프론트는 statement 를
제목 자리에도 쓰고 영향은 빈 배열로 고정해 두고 있었다. DB 에는 작성자가 쓴 값이 그대로
들어 있었다 — 제목, 여러 줄 요약, 영향 4건.
근거는 두 자리에서 온다. `sourceQuestion`/`sourceCase` 는 결정 하나가 원천 하나를 지목하던
예전 모양이고 지금 작성자는 관계로 여러 개를 건다. 둘을 합치되 같은 경로는 한 번만 싣는다.
줄바꿈은 별개 원인이다. 이 칸들은 Markdown 을 거치지 않고 텍스트 노드로 들어가는데 이 화면만
`PlainText` 를 쓰지 않고 값을 그대로 넣고 있었다. 글자만 확인하는 테스트로는 접힘이 보이지
않으므로, 두 줄짜리 픽스처를 두고 `<br>` 이 남는지 요소로 묻는다 — 되돌리면 빨개진다.
즉시 미리보기도 같은 구조로 맞췄다. 미리보기와 공개가 다르게 그리면 무엇을 믿을지 알 수 없다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
편집기가 「문서를 불러오지 못했습니다」로 열리지 않았다. 개념 작업본을 하나 만드는 순간부터
`/studio/catalog` 가 400 이 됐고, 편집기는 네 종류를 한꺼번에 부르므로 개념과 무관한 Case 를
열어도 화면 전체가 오류가 됐다.
`CatalogEntry.kind` 가 개념을 몰랐다. 같은 목록을 쓰는 자리를 파싱해 훑으니 둘이 더 나왔다 —
`ResolvedRelation.targetKind` 와 관리 계약의 `RelatedEntry.type`. 개념을 잇는 것이 이 종류의
핵심인데 그 경로가 전부 막혀 있었다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
앞선 커밋은 렌더러와 편집기까지만 붙였다. 화면을 열어 보니 탐색의 유형 선택지에 개념이 없고
`/concepts/:slug` 라우트도 없었다 — 라벨 표만 고치고 실제 선택지와 라우트를 빠뜨렸다.
라우트를 하나 더하자 이 저장소가 라우트 수를 고정해 둔 자리가 전부 울렸다. 라우트 계약,
런타임 등록, 메시지 카탈로그, nginx 서빙 패턴, 코드 분할 청크, 그리고 CI 게이트의 수동
접근성 증거까지 — 라우트마다 증거 문서를 하나씩 갖는 규칙이라 `TECH_LOG_CONCEPT.md` 를
다른 라우트와 같은 `pending-manual-review` 상태로 만들었다. 사람이 서명할 자리는 비워 둔다.
게이트 형상 해시는 규칙대로 다시 계산했다 — 옛 `gates.json` 에서 이전 상수 fb138e7c… 를
먼저 재현해 계산 방법이 맞는지 확인한 뒤 새 파일을 해싱했다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
Kubernetes 내부 동작처럼 처음부터 풀어 읽어야 하는 글을 쓸 자리를 만든다. Reference 는
판단 기준을 빨리 찾는 글이라 규칙·적용·예외로 나뉘고, 그 틀에 개념을 넣으면 두 글이 서로를
망친다 — 기준을 찾으러 온 사람은 배경을 지나야 하고, 개념을 배우러 온 사람은 규칙에서
시작한다.
편집기는 Case 의 본문 칸과 Asset Picker 를 그대로 쓴다. 아키텍처 도식은 같은
`:::evidence` 로 들어오고, `##` 소제목이 목차가 된다. 개념이 따로 갖는 것은 기준 버전
하나다 — 개념이 낡는 방식은 날짜가 아니라 버전이다.
공개 렌더는 Case 와 본문·목차를 공유하되 머리말이 다르다. 문제도 결론도 검증 환경도 없고,
프로젝트 마디는 값이 있을 때만 그린다 — 개념은 프로젝트 없이 서는 유일한 종류다.
픽스처가 실제 결함을 하나 드러냈다. 프로젝트 없는 기록이 처음 생기자 `?project=` 빈 값이
"프로젝트가 없는 기록 전부" 를 뜻하게 됐다 — 고르지 않은 것이 고른 것이 되어 버린다. 빈
필터는 아무것도 고르지 않도록 고쳤다. 예전에는 빈 값에 걸릴 기록이 없어 저절로 맞았다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
Reference 는 판단 기준을 빨리 찾는 글이고, Kubernetes 내부 동작처럼 처음부터 풀어 읽어야
하는 글은 그 틀에 들어가지 않는다. 종류를 하나 더하고 Reference 구조는 그대로 둔다.
개념 글은 프로젝트 없이 게시될 수 있는 유일한 종류이므로 주제를 게시 조건으로 둔다 —
집 없는 글이 생기지 않게.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
주제 링크를 고쳤는데 화면은 그대로 `/topics/:slug` 로 갔다. 공개 문서의 머리말을 그리는
것은 `PublicDocumentHeader` 의 breadcrumb 이 아니라 렌더 모델의 `topic.publicPath` 이고,
같은 파일 안에서 두 자리가 같은 경로를 만들고 있었다. 한 자리만 고쳤으니 배포하고 눌러
보기 전까지는 고친 것처럼 보였다.
테스트도 이 링크를 묻지 않고 있었다. 머리말 검사가 `Case/JPA/Backend Skeleton` 이라는
글자만 확인해서, 그 글자가 어디로 가는지는 아무도 보지 않았다. 되돌려 보면 공개 문서
여섯 개가 모두 빨개진다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
게시한 질문이 홈 최근 기록에 나오지 않았다. 계약의 `LatestEntry.entryType` 이 네 값만
허용해 백엔드가 담을 수 없었다 — design-package ef49d3a 에서 `QUESTION` 을 더했고 여기서
계약을 다시 생성한다. 포트의 `LatestRecordEntry.entryType` 도 같이 넓히고, 홈의 표기는
목록의 다른 이름들과 같은 규칙(대문자에 공백)을 따라 `OPEN QUESTION` 으로 적는다.
문서 머리말의 주제 링크는 `/topics/:slug` 로 가고 있었는데, 그 화면은 `jpa`/`authentication`
/`redis` 세 개를 하드코딩해 두고 있어 실제 주제는 무엇이든 404 가 됐다. 게시한 모든 문서의
주제 링크가 거기로 갔다.
주제 페이지를 채우는 대신 링크를 탐색 필터로 돌린다. 지금 그 페이지만 줄 수 있는 것 —
설명, 범위, 선별한 대표 기록 — 이 전부 비어 있고, Studio 의 주제 만들기는 `{name, slug}` 만
보내므로 설명을 쓸 칸조차 없다. 독자가 거기서 기대하는 것은 같은 주제의 기록 목록이고,
그것은 `/explore?topic=` 이 그대로 준다. 주제가 여러 개가 되고 설명을 쓸 수 있게 되면 그때
페이지를 만드는 것이 순서다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
질문 상세는 프로젝트를 `question` 이 아니라 `relations.primaryProject` 에 담는다 —
Case/Reference 와 다른 자리다. `question` 에서 찾고 있었으므로 머리말의 프로젝트 칸이 늘
비어 있었다.
그 자리의 값은 `RelatedEntry` 라 `title`/`path` 를 쓴다. 머리말이 기다리는 것은
`name`/`slug` 이므로 옮겨 준다 — slug 는 경로의 마지막 마디다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
게시한 질문의 공개 상세가 「요청을 처리하지 못했습니다」만 띄웠다. 게이트웨이가 `points`
를 `{group, items}` 배열로 읽고 `.filter` 를 불렀는데, 계약의 `QuestionPointGroup` 은
`facts`/`assumptions`/`unknowns`/`constraints` 를 키로 갖는 객체다. 객체에는 `.filter` 가
없으니 매핑이 통째로 터졌다.
목록은 이 칸들을 빈 배열로 두고 만들기 때문에 탐색에서는 멀쩡히 보였다. 그래서 "게시했는데
public 에 안 뜬다" 로만 드러났고 어느 층이 깨졌는지는 보이지 않았다. `as` 캐스트가 그
어긋남을 타입 검사에서 가렸다 — 이제 계약의 타입을 그대로 써서 모양이 바뀌면 컴파일이
먼저 막는다.
관계도 같은 종류로 어긋나 있었다. 계약이 주는 이름은 `resultCase`/`producedDecision`/
`derivedReferences` 인데 매퍼는 `derivedCases`/`projectDecisions`/`relatedQuestions` 를
찾고 있었고, 하나도 맞지 않아 이유 자리에 영문 키가 그대로 나왔다. `primaryProject` 는
관계가 아니라 이 질문이 속한 프로젝트이므로 관계 목록에서 뺀다 — 머리말이 이미 보여 준다.
이 사고가 지나간 이유는 HTTP 게이트웨이의 질문 상세 매핑을 지나는 테스트가 없었기
때문이다. 화면 테스트는 정적 픽스처 어댑터를 쓰므로 계약 모양을 한 번도 통과시키지
않는다. 계약 모양 그대로의 응답을 진짜 게이트웨이에 넣고 네 칸이 채워져 나오는지 묻는
테스트를 넣는다 — 되돌려 보면 운영에서 난 것과 같은 `points.filter is not a function`
으로 실패한다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
주제 필터를 걸면 「조건에 맞는 공개 기록이 없습니다」만 남았다. 선택지가
`<option>{이름}</option>` 이라 값이 없어 이름이 그대로 나갔고 — `topic=OAuth/OIDC 인증
경계` — API 는 slug 로 거르므로 0건을 돌려줬다. 프로젝트 선택지는 처음부터
`value={slug}` 였고, 그래서 프로젝트만 멀쩡했다. 주제도 같은 모양으로 맞춘다.
테스트가 이 결함을 통과시킨 이유는 픽스처의 주제 이름이 `JPA`, `Authentication` 처럼
slug 와 구분되지 않는 값이어서다. 이름과 slug 가 다른 값을 쓰는 운영에서만 드러났다.
선택지의 값이 slug 인지 직접 묻는 단언을 넣는다.
`RecordFilters.topic` 은 어댑터마다 뜻이 달랐다. 정적 어댑터는 이름으로, HTTP 어댑터는
그 값을 그대로 API 에 넘겨 slug 로 걸렀다. 프로젝트가 이미 slug/제목 둘 다 받는 것과
같이 주제도 둘 다 받게 해서 두 어댑터가 같은 값을 이해하게 한다. 주제 페이지도 이름
대신 경로의 slug 로 묻는다.
「전체」를 고른 칸은 조건이 아니다. 빈 값까지 실어 보내고 있었고, URL 이 지저분해질 뿐
아니라 이 값을 그대로 API 에 넘기는 화면에서는 `topic=` 이 "slug 가 빈 문자열인 주제"로
해석되어 0건이 된다.
편집기는 미리보기를 붙박이로 두고 자체 스크롤을 줬다. 편집기를 내려도 미리보기는
제자리였고, 보려면 그 안을 따로 굴려야 했다 — 나란히 둔 이유가 둘을 같이 보는 것인데
움직임이 갈라지면 그 이점이 없다. 둘 다 페이지 스크롤을 그대로 타게 한다.
폭도 넓힌다. `.studio-main` 은 모든 Studio 화면이 1180px 를 함께 쓰는데, 본문 두 벌이
들어가야 하는 이 화면에서는 한 칸이 566px 였다. 편집기가 놓인 경우에만 1600px 로
넓히고 헤더도 같이 넓혀 좌우 끝을 맞춘다. 다른 화면은 그대로다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
편집기는 탭이었다. 고친 것이 어떻게 보이는지 확인하려면 편집하던 자리를 화면에서
치워야 했고, 돌아오면 스크롤 위치도 잃었다. 두 패널을 나란히 두면 그 왕복이 통째로
없어진다.
작업 상태와 저장·게시는 오른쪽 세로 rail 이었다. 그 자리는 편집기와 미리보기가 함께
쓸 가로 폭을 가져갔고, 편집 칸이 길어질수록 rail 은 위에 붙은 채 본문만 멀어졌다.
화면 아래에 고정하면 폭을 돌려주면서 스크롤 위치와 무관하게 손이 닿는다.
탭을 없앴으므로 각 패널이 스스로 이름을 가져야 한다. `aria-labelledby` 로 제목을
가리켜 landmark 로 만든다 — 탭 목록이 하던 "여기는 편집, 저기는 미리보기" 안내를
대신한다. `aside` 와 「작업 상태」라는 이름은 그대로 둔다. 자리가 바뀐 것이지 이
묶음이 무엇인지가 바뀐 것은 아니다.
미리보기가 늘 떠 있게 되면서 Picker 테스트의 단언도 함께 고쳤다. 「Picker 가
좁아졌는가」를 화면 전체에 묻고 있었는데, 이제는 미리보기 쪽의 같은 Asset 까지
세게 된다. 그 김에 `.studio-asset-panel` 의 `aria-labelledby` 가 role 없는 div 에서
아무 이름도 만들지 못하던 것도 `role="group"` 으로 실효화했다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0189NzCryfeqDzS81EWidnBx
Reference 머리말에 「이 기준을 쓰는 이유」와 같은 글이 나오고 있었다. Case 도 마찬가지로
바로 아래 「문제」와 같은 글을 두 번 말했다.
문서가 스스로 밝히는 한 줄 요약이 공개 응답에 없어서, 화면이 유형별 요약
(`problemSummary` / `scopeSummary`)을 대신 쓰고 있었다. Question 에는 이미 `summary` 가
있었으므로 셋이 같은 자리를 갖게 한다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
Reference 를 공개했는데 Studio 에서는 다 보이고 공개 화면만 비어 있었다.
게이트웨이가 읽던 이름이 계약에 없는 것들이었다 — `purposeSummary`,
`applyWhenMarkdown`, `exceptionsMarkdown`, `examplesMarkdown`. 계약이 주는 이름은
`scopeSummary`, `appliesTo`, `excludedScope` 다. 전부 undefined 로 떨어졌고, `as string`
단언 때문에 타입 검사는 아무 말도 하지 않았다.
규칙은 `content` 마크다운을 잘라 만들고 있었다. Reference 의 본문은 마크다운 한 덩어리가
아니라 제목이 붙은 규칙의 목록이고, Studio 의 편집기가 그렇게 받아 `body_markdown` 은
비워 둔다 — 자를 것이 없으니 언제나 빈 목록이었다. 계약이 구조로 주는 것을 그대로 쓴다.
값이 아니라 이름을 지키는 테스트를 둔다. 계약에서 그 칸이 사라지면 `satisfies` 가 먼저
깨진다 — 이번 결함은 값을 검사해서는 잡히지 않았다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
브라우저의 Ctrl+S 는 "페이지를 파일로 저장"이다. 글을 쓰다가 그 손버릇이 나오면 저장
대화상자가 뜨고 편집한 내용은 그대로 남는다 — 저장한 줄 알고 창을 닫으면 잃는다.
문서·프로젝트·릴리즈 세 편집기에서 기본 동작을 막고 그 화면의 저장으로 돌린다.
저장할 것이 없을 때도 기본 동작은 막는다. 막지 않으면 "저장할 것이 없다"는 화면 상태와
브라우저의 저장 대화상자가 동시에 나와, 무엇이 일어났는지 알 수 없다.
Ctrl+Shift+S 와 Alt 조합은 가로채지 않는다 — 다른 뜻으로 쓰는 곳이 있다.
버튼에 단축키를 적어 둔다. 단축키는 알려 주지 않으면 없는 것과 같다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
Decision 은 결정일이 없으면 미리보기가 열리지 않았다. 검증은 그것을 경고로만 다루므로
날짜 없이 게시할 수 있는데 렌더 모델이 필수로 요구했다 — 작성자는 "경고라면서 왜 안
되냐"를 만난다. 계약을 nullable 로 열고 화면이 "결정일 미정"이라고 말하게 한다.
한 칸의 실패가 화면을 통째로 날리지 않게 한다. `Promise.all([gateway.foo()])` 은 foo 가
거절하는 것만 잡는다 — 호출이 동기적으로 던지면 배열을 만드는 중에 터져 rejection
handler 를 지나지 못하고, 그러면 홈 focus 한 칸 때문에 대시보드 전체가 빈 화면이 된다.
프로젝트 편집도 같은 모양이라 함께 고친다.
`IntersectionObserver` 가 없는 환경을 견딘다. 목차는 픽스처 Case 하나에서만 쓰여 그런
환경을 만난 적이 없었는데, 모든 Case 가 목차를 받게 되면서 jsdom 에서 문서가 통째로
깨졌다. 없으면 "지금 읽는 절" 표시만 못 할 뿐이다.
픽스처의 최근 기록에서 릴리스를 뺀다. 서버의 `latestEntries` 는 공개 투영에서 고르므로
릴리스가 없고, 홈이 릴리스를 따로 읽어 합친다 — 픽스처가 넣으면 같은 릴리스가 두 번
나온다.
화면 테스트는 `test:unit` 이 아니라 `test:tech-log` 가 돌린다. 그것을 돌리지 않아 위
두 결함과, 라우트 두 개·`--body-copy`·Case 배치 통합·활동 링크 제거처럼 의도한 변경에
고정돼 있던 단언들이 23건 빨간 채로 여러 커밋을 지나갔다. 단언을 실제 동작으로 옮긴다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
"PROJECT public path is required" 는 사실이지만 작성자가 무엇을 해야 하는지 말하지
않는다. Decision 의 공개 주소는 프로젝트 주소 아래에 있으므로, 프로젝트를 먼저
게시해야 한다는 것과 그 화면이 어디인지 적는다.
프로젝트를 고르지 않았을 때의 문구도 같이 바꾼다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
활동을 Studio 에서 손으로 적어야 했다. 그러면 "언제 무엇을 올렸는가" 가 실제로 올린
사실과 따로 관리되고, 적기를 잊으면 타임라인에 구멍이 남는다. 게시가 곧 사건이므로
게시가 기록한다.
공개 화면에서는 링크를 없앤다. 각 줄에 그 기록으로 가는 링크가 있으면 같은 글에 닿는
길이 둘이 되고, 읽는 사람은 "기록"과 "활동"이 어떻게 다른지 매번 다시 판단해야 한다.
활동은 날짜와 무엇을 올렸는지만 말하고, 글을 읽는 자리는 기록 화면 하나로 둔다.
Studio 의 활동 칸도 읽기 전용 로그가 된다 — 만들기·고치기·지우기 폼을 걷어낸다.
맥락에서 경계와 시스템 개요 칸을 뺀다. 저장은 되지만 공개 화면 어디에도 나오지 않는다
— 프로젝트 화면이 그리는 것은 목적 하나다. 쓰는 사람에게는 어딘가 실릴 것처럼 보이는
칸이었고 실제로는 아무도 읽지 않았다. 열의 데이터는 남겨 두고 서버 값을 그대로
왕복시킨다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
저장·공개·공개에서 내리기가 각각 두 개씩 나왔다.
편집 폼을 목록에서 떼어 낼 때 잘라 온 조각에 이미 그 푸터가 들어 있었는데, 새 화면을
조립하면서 같은 푸터를 한 번 더 붙였다. 둘 다 같은 핸들러를 부르므로 어느 쪽을 눌러도
동작은 했고, 그래서 화면을 열어 개수를 세기 전까지는 드러나지 않았다.
자식이 하나뿐이라 감쌀 이유가 없어진 프래그먼트도 함께 걷어낸다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
앞 커밋에서 편집 폼만 떼어 내고 그것을 움직이던 상태와 핸들러를 목록에 남겨 두었다.
`GuardedStudioLink` import 는 빠졌고 `navigate` 는 아예 정의된 적이 없다. 운영에서
릴리즈 목록이 ReferenceError 로 비었다.
`npx tsc --noEmit` 이 통과했기 때문에 이것을 못 봤다. 루트 tsconfig 는 `"files": []` 에
project references 만 나열하므로 그 명령은 한 파일도 검사하지 않고 성공한다 — 실제 검사는
`npm run check:types` 가 여섯 개 프로젝트를 돌며 한다. 그 명령으로 돌리자 이 저장소에
남아 있던 다른 오류도 함께 드러났다:
- `CatalogEntry` 는 `contracts/studio/contract.ts` 가 export 하지 않는다 (project-editor,
home-focus-editor). 문서 편집기처럼 generated 에서 지역 타입으로 뽑는다.
- 라우트 파라미터는 `unknown` 으로 들어온다. `params.id` 를 그대로 문자열 자리에 넘기고
있었다.
- `message("route.auth.returnTo", …)` 는 파라미터를 받는 키로 등록되지 않았다.
- `ReleaseIndexItem` 에는 `summary` 가 없다 — 목록 행은 마크다운을 싣지 않는다. 대신
공개 경로를 적는다.
목록의 남은 로직도 정리한다. 새 릴리즈를 만들면 그 행을 `aria-current` 로 짚어 준다 —
목록이 길면 어느 것이 새것인지 알기 어렵다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
편집 폼이 릴리즈 목록 아래에 열렸다. 릴리즈가 열 개 스무 개로 늘면 편집하려고 목록
전체를 지나 내려가야 하고, 저장 버튼은 그보다 더 아래에 있다. 목록이 길어질수록 편집이
멀어지는 구조다.
`/studio/releases/:id` 를 연다 — 문서와 프로젝트가 각자 편집 주소를 갖는 것과 같은
이유다. 목록의 "편집" 은 토글이 아니라 링크가 되고, 새 릴리즈를 만들면 곧바로 그 화면으로
간다(만들자마자 편집할 것이 분명하다).
라우트가 하나 늘어 CI 게이트가 함께 움직였다 — 아티팩트 기준선 133→134, 증거 개수
112→113, 게이트 형태 다이제스트 재계산(f9e7e521… 을 이전 gates.json 에서 먼저 재현해
계산 방법을 확인했다), 서빙 패턴 하나 추가.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
릴리즈 편집 맨 아래에서 저장과 공개가 서로 다른 높이에 서 있었다.
`.studio-secondary-button` 는 목록 행에서 쓰려고 전역으로 `margin-top: 24px` 를 갖는데
하단 푸터에서 primary 만 그 여백을 풀어 주고 있었다 — 그래서 저장은 위에, 공개와
공개에서 내리기는 24px 아래에 앉았다.
로그인은 화면이 없었다. `ui-page` 위에 제목 한 줄과 버튼 하나가 전부라, 보호된 주소를
열었을 때 페이지처럼 보이지 않았다. 카드 하나로 세우고 eyebrow·제목·설명·행동을 갖춘
뒤, 로그인하면 어디로 돌아오는지까지 적는다 — 그것이 이 화면이 답해야 할 질문이다.
오류 화면과 다른 모양이어야 한다. 같은 모양이면 작성자는 무언가 고장 난 줄로 읽는다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
프로젝트 편집 화면에서 활동 유형이나 제목을 한 글자 치면 화면이 통째로 죽었다 —
"Cannot read properties of null (reading 'value')".
setState 업데이터는 핸들러가 끝난 뒤 다음 렌더에 실행된다. 그때 React 는 이미
`event.currentTarget` 을 null 로 되돌려 놓았으므로, 업데이터 안에서 그것을 읽으면
반드시 터진다. 타입 검사도 lint 도 이것을 잡지 못했고, 첫 입력에서야 드러났다.
값은 핸들러가 도는 동안 지역 변수로 꺼내 두고 업데이터에는 그 값을 넘긴다.
같은 실수를 다시 못 하도록 lint 규칙을 세운다: `setXxx(...)` 에 곧바로 넘기는 화살표
함수 안에서는 `currentTarget` 을 읽을 수 없다. 처음 쓴 선택자는 동기 핸들러까지 잡아
(map 콜백, 즉시 호출되는 update 등 아홉 자리) 너무 넓었으므로, 실제로 위험한 setter
업데이터만 겨냥하도록 좁혔다. 결함을 되돌려 규칙이 잡는 것을 확인했다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
주요 주제 — 프로젝트 화면은 처음부터 `project.topics` 를 읽고 있었는데 공개 계약에
그 자리가 없었다. `project_topic` 은 테이블도 있고 조인할 수도 있었지만 응답에 실을
곳이 없었고, 고를 화면도 없었다. 계약에 자리를 만들고, 편집 화면에 주제 선택을 붙이고,
공개 조회가 ACTIVE 인 주제만 고른 순서대로 내보내게 한다.
활동 위치 열기 — 그 링크는 활동의 관련 기록을 따라간다. 백엔드는 처음부터 그 경로를
유도하고 있었지만, 활동을 만들 때 기록을 고를 방법이 없어 모든 줄이 관련 기록 없이
저장됐다. 활동 추가 폼에 유형·일시·제목·요약·연결할 기록·노출을 모두 둔다.
Case 목차 — 오른쪽 목차가 어떤 문서에서도 나오지 않았다. Case 렌더러가 둘이었고
어느 쪽을 쓸지 `publicPath === "/cases/collection-fetch-join-pagination"` 이라는 슬러그
비교가 정했다. 설계 픽스처 문서 하나만 breadcrumb·목차가 있는 완성된 배치를 받고, 실제로
작성한 Case 는 전부 축약본으로 떨어졌다. 배치를 하나로 합치고, 목차는 본문에 제목이
있을 때만 그린다.
Studio UI — 새로 만든 화면들이 기존 디테일을 따라가지 않고 있었다. `<label htmlFor>` +
별도 컨트롤 대신 편집기가 쓰는 `<label><span>` 묶음을, 임시로 만든 폼 클래스 대신
`studio-editor-section`·`studio-field-grid` 를 쓴다. 릴리즈 목록 행에는 유형 라벨이
빠져 격자 첫 열이 비어 있었고(제목이 당겨져 다른 목록과 줄이 맞지 않았다) 버튼 둘이
묶이지 않은 채였다. 프로젝트 행에는 단계·공개 범위를 한국어로 적고 "내용 편집" 을
다음 행동으로 둔다.
로그인 화면 — "인증 연동 지점을 확인하기 위한 보호 라우트" 는 이 뼈대를 만들던 사람에게
하는 말이었다. 이 화면을 보는 사람은 글을 쓰러 온 작성자다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
홈의 집중 카드가 제목만 보여 주고 "현재 목표"·"다음 작업" 칸이 비어 있었다.
프로젝트 페이지의 "활동" 도 늘 비어 있었다.
프로젝트를 만들 수는 있었지만 고칠 화면이 없었다. 그래서 이름과 slug 말고는 아무
값도 가질 수 없었고, 그 값을 읽는 공개 화면들은 빈칸을 그렸다 — 백엔드의
`updateProject` 는 처음부터 구현돼 있었고 채울 화면만 없었다.
`/studio/projects/:id` 를 연다. 프로젝트 필드 전부와 활동 목록을 한 화면에 둔다 —
프로젝트 밖의 활동은 존재하지 않고, 무엇이 공개 타임라인에 실리는지를 프로젝트 필드와
같은 자리에서 보는 편이 낫다.
이미 공개된 프로젝트는 저장한 뒤 투영도 함께 갱신한다. 투영은 게시할 때 세워지므로,
저장만 하면 공개 화면에는 예전 값이 남는다.
단계와 활동 유형의 선택지는 DB CHECK 제약과 같은 목록이다. 화면이 더 많은 값을
보여 주면 저장이 제약에서 터지고, 작성자는 왜 안 되는지 알 수 없다.
라우트가 하나 늘어 CI 게이트가 함께 움직였다 — FE-GATE-009 는 설치된 라우트마다 수동
접근성 증거를 하나씩 요구하고 그 집합이 정확히 일치하지 않으면 거절한다. 아티팩트
기준선 132→133, 증거 개수 111→112, 게이트 형태 다이제스트 재계산(이전 상수 187dbd96…
을 이전 gates.json 에서 먼저 재현해 계산 방법을 확인했다), 서빙 패턴 하나 추가.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
관계를 고르고 저장하면 400 이 돌아왔고, 편집기에는 "saveStudioDocument broke its
contract." 한 줄만 남았다. 저장은 통째로 실패했다.
새 관계·규칙·선택지·문장의 id 를 `createLocalId` 로 만들고 있었다. 그 함수는 접두사를
붙여 `relation-<uuid>` 를 돌려준다 — React key 나 Idempotency-Key 로는 맞지만 계약이
그 자리에 요구하는 것은 uuid 다. 서버는 파싱조차 못 하고 InvalidFormatException 으로
거절했다.
목록에 고를 대상이 하나도 없던 동안에는(catalog RELATION/EVIDENCE 가 스텁이었다) 아무도
이 경로를 지나지 않아 드러나지 않았다. 두 결함이 서로를 가리고 있었다.
Case 는 목록 항목이 없어 무사했다. Reference 의 규칙, Question 의 선택지, Decision 의
consequences 는 모두 같은 이유로 저장되지 않았을 것이다.
`createNewItemId` 로 나눈다. 서버는 자기가 소유하지 않은 id 를 어차피 새로 부여하므로
(`StudioRelationStore.replace`) 이 값은 "이 줄은 새것"이라는 표시일 뿐이다 — 지켜야 할
것은 형식뿐이다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
공개 화면 다섯 곳이 조용히 비어 있었다. 원인은 하나씩 달랐지만 모두 "값을 채울
방법이 없었다"는 같은 모양이었다.
홈의 "지금 집중하는 것" — `home_focus_config` 는 마이그레이션이 빈 행 하나만
넣어 두었고, 계약에 선언된 `getHomeFocus`/`updateHomeFocus` 는 구현이 없었다.
세 슬롯이 모두 비면 홈은 그 영역을 아예 그리지 않으므로, 운영에서는 한 번도
나타난 적이 없다. Studio 대시보드에 고르는 화면을 둔다.
홈의 "최근 기록" — 화면이 공개된 프로젝트를 하나씩 돌며 타임라인을 조립했다.
그래서 게시한 문서라도 그 프로젝트가 공개되어 있지 않으면 목록에서 통째로
빠졌고, 실제로 릴리스 한 줄만 남았다. 무엇이 최근인지는 공개 투영이 이미 알고
있으므로 그것을 그대로 읽는다. 프로젝트마다 요청을 보내던 N+1 도 사라진다.
프로젝트 공개 — 프로젝트는 `RecordKind` 에 없어 문서 게시 파이프라인을 타지
못하는데, 공개 화면들(프로젝트 목록·프로필의 "현재 프로젝트"·홈 focus)은 전부
`public_resource_projection` 의 PROJECT 행을 가시성 관문으로 쓴다. 그 행을
세우는 경로가 없었으므로 프로젝트는 영원히 비공개였다. 계약에 이미 있던
`publishProject`/`unpublishProject` 를 구현하고 주제·프로젝트 화면에 버튼을 둔다.
문서 사이 관계 연결 — `JdbcCatalogQueryAdapter` 의 RELATION/EVIDENCE 가
`List.of()` 스텁이라 어떤 기록도 연결 대상 목록을 채울 수 없었다. RELATION 은
작성 중에 고르는 것이므로 작업본까지 포함하고, EVIDENCE 는 읽는 사람이 따라갈
수 있어야 하므로 공개된 것만 포함한다.
본문 너비 — 문서 한 편이 세 폭으로 갈라져 있었다. 머리말 920px, 유형·프로젝트
줄은 shell 전체 1180px, 본문은 672px 를 가운데 정렬. 셋을 같은 폭·같은 왼쪽
끝에 세우고 읽는 단을 56rem 으로 넓힌다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XEHXspz4rv5pB5wiiSsVDu
Every failure in the management screens printed a guess. Deleting a working
copy said "it may be published, or something may reference it, or someone may
have edited it first" — three maybes, while the server had answered with
exactly one: "이 기록을 참조하는 곳이 있어 삭제할 수 없습니다". A version
conflict read as "in use" because the same sentence covered both, and an author
watching some deletions succeed and others fail had no way to tell them apart.
The gateway now carries the server's client-safe message and the screens show
it. The canned sentences remain only as a fallback for a failure that never
reached the server.
The topic status label said "사용 중" for every active topic, including one
created seconds earlier that nothing references. Next to a refusal about
records that use a topic, the two read as the same statement. It says "활성"
now, which is what the status means.
Publishing also stops demanding a finished document — the mock validator moves
with the real one, so what an author sees against fixtures matches production.
Publishing was reachable only by walking the whole chain blind. The editor
offered one link — "저장본 검증" — and the word "게시" appeared nowhere until
three screens later, so an author with a finished draft could not tell how to
publish it. The working-copy list already named the next step, but the name was
plain text with nowhere to go.
The editor now shows the whole path: 검증 → 미리보기 → 게시, each a link. The
list's next step is a link to that step. Neither weakens the gates — an
unvalidated document is still refused at preview, an unpreviewed one at
publish. What changes is that the order stops being a secret.
What is blocking publication now appears where it gets fixed. The validation
report lived on its own screen, so an author read the list, navigated back, and
had to remember which field each item meant. The editor shows the same issues
above the fields, in red, and says plainly when they describe an older saved
version rather than the current one.
The clock is read during render, not captured as an effect dependency. It is a
new function on every render of the provider, so depending on it refetched the
document endlessly — the editor never settled, and a tab click did not even
register. A value you are asking about now does not belong in a dependency
array.
The validation screen presented a report from an earlier version with the same
weight as a current one — same status badge, same full error list — and marked
the difference with two small words. An author read a version 2 report on a
version 5 document and understood those errors as the document's present state.
Every error in that list had already been fixed.
The report now leads with what it is: which version it judged, that the
document has changed since, and where to re-run it. The badge stops claiming a
verdict and the issue list recedes, because a judgement about an older version
is not a verdict about this one.
A document with no preview yet answers 404 when the screen asks for its current
one, and the screen turns that into "make a preview". The sweep counted it as a
failure, so every run ended with the same red line under a healthy deployment.
A check that cries wolf on every run stops being read, and a real failure would
have sat unnoticed beside it. The session probe's 401 before sign-in is the
same kind of expected answer and is excluded on the same terms; every other
4xx and 5xx still fails the sweep.
An uploaded figure never appeared, and no request for it was ever made. The
resolver substituted 1x1 when an asset carried no dimensions, and a 1x1 box
with `loading="lazy"` never enters the viewport — so the browser had no reason
to fetch it. The image was not failing to load; it was never asked for.
Unknown dimensions now say so. The figure omits the attributes and loads
eagerly, letting the browser size the image from the file, and reserves layout
space only when the size is actually known. Guessing a number to fill an
attribute is what turned a missing measurement into a missing picture.
Four things an author could not do, and the check that should have caught them.
A Decision could not be deleted. Case, Reference and Question all could, so an
author who opened a decision draft had no way to close it. The contract gained
the operation and the list now offers it for every kind. Its path carries the
project because a decision belongs to one; a row with no project says so rather
than failing.
Assets could only be managed by leaving the document. The picker now deletes
one in place — the server still refuses an asset a document uses — so a
mistaken upload does not cost the author their editing session.
Zoom was decided for the author and could not be changed: only a DIAGRAM got
it, so a screenshot uploaded as an image or attachment went in with zoom off
and no way to turn it on. It now defaults on for images and the picker offers
the choice. The toggle is a picker control, not a document field, and carries
its own class — wearing the field class put it in the editor's field list.
`scripts/smoke/production-sweep.ts` walks every public and Studio screen and
the document flow, reporting console errors, failed API calls and error text.
It exists because verifying only the screen I had just changed is what let
broken screens reach production repeatedly; this runs before a deploy, not
after a report.
The earlier fix covered the Markdown body and stopped there, so the preview
still ran lines together — which is exactly what it looked like from the
outside: nothing had changed.
Summary, problem, conclusion, environment and the rest are plain text. They
never pass through the Markdown parser, so their newlines sit in a text node
and HTML collapses them, and the renderer that now emits <br> for the body was
never asked about them.
They render through the same rule now. One helper, one behaviour: a line the
author broke stays broken, wherever they typed it.
Validation reported a slug the author could see on screen as missing. Both
halves of that were the editor's fault.
The document slug must match `^[a-z0-9]+(?:-[a-z0-9]+)*$`, which the editor
never said and never helped with. A Korean slug was rejected by the server with
a 422 carrying no details — and the editor answered that only through
`setRequestAnnouncement`, which is an aria-live region and shows a sighted
author nothing at all. The value stayed in the field, so it looked saved. Then
validation, which reads the saved version by design, correctly reported no
slug, and the author read that as the tool contradicting itself.
An empty slug is now derived from the title, romanizing Hangul the same way
topic slugs do, so a Korean title produces a valid slug and the author never
has to learn the rule. A slug that cannot work is refused before the request,
naming the rule instead of letting the server answer with an unexplained 422.
Every save failure now renders where the author is looking, not only where a
screen reader would hear it.
The rail shows one message rather than two: a conflict already says what to do,
so it outranks the server's wording, and everything else shows the server's
reason.