제목 아래 맥락 블록(ContextNavigator)과 난간의 Related 가 같은 것을 두 번
말하고 있었다. 난간 하나만 남기고, 거기에 주제가 정한 사고 순서의 바로
앞·뒤 한 칸을 둔다. 기록 화면은 그 순서를 알아야 하므로 자기 주제의 기록
목록을 함께 받는다.
주제의 사고 순서는 종류마다 한 편이 아니라 전부를 세우고, 관계가 가리키는
프로젝트 결정을 기준 다음 칸에 끼운다. 답이 나온 질문은 흐름에는 남되
「아직 답하지 못한 질문」으로 다시 서지 않는다.
문서 머리말의 빵부스러기는 프로젝트/주제만 남기고 종류는 링크가 아닌 한
줄로 내린다. 홈의 「종류별로 읽기」는 주 내비가 이미 데려가므로 내린다.
`tests/component/inline-line-breaks.test.tsx` 는 머리말의 `<p>` 를 전부
세고 있어서 종류 한 줄이 늘자 깨졌다. 요약만 세도록 좁혔다 — 문단 나누기를
망가뜨리면 여전히 실패한다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cfj8mZ9QmT3MEKonzM5xPj
흐름을 그릴지 말지를 화면 안에서만 판단했다. 기록이 하나뿐인 주제에서는 흐름을 그리지 않으면서
목록 쪽은 "흐름에 올랐다" 며 그 하나를 빼, 화면에 아무것도 남지 않았다(네트워크 가상화).
그리는 쪽과 빼는 쪽이 같은 값을 보게 한다. 한 칸짜리는 흐름이 아니므로 `reasoningSteps` 가
빈 목록을 준다.
함께: 프로젝트 화면의 세 목록 링크가 기록 목록을 내리면서 폭 전체를 세로로 쓰게 된 것을 한 줄로
되돌리고, 홈 「지금」의 옆 두 칸은 목록 카드와 같이 세 줄에서 자른다 — 작성자의 요약이 문단
여럿이면 「한눈에」를 말하면서 화면 두 개를 차지한다.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
홈에 「맥락 흐름」(기록의 사슬)·「지금 집중하는 것」(작업 상태)·「주제별 흐름」(주제 내부
구조)이 연달아 섰다. 데이터로는 서로 다른 계층이지만 읽는 사람에게는 셋 다 "그래서 뭘
읽으라는 거지" 에 답하는 같은 종류의 안내였고, 같은 말을 세 방식으로 반복하는 화면이 됐다.
계층마다 제 자리를 준다.
- 홈: 지금 무엇을 하고 있는가. 탭 셋을 한 번에 펴고(`HomeNow`), 맥락 흐름과 주제 비교를
내리고, 들어갈 입구로 프로젝트 목록을 세운다. 고를 것이 없어졌으므로 주소의 `focus` 도
계약에서 내린다.
- 프로젝트: 어떤 주제 순서로 파고들었는가. 기록을 펼치던 조사 지도를 주제까지만 그리는
흐름(`ProjectPath`)으로 바꾼다. 한 줄 설명은 주제 목록에서 찾아 붙인다.
- 주제: 어떤 순서로 생각했는가. 원리 → 확인 → 기준을 흐름으로 세우고(`TopicReasoningPath`),
남은 기록은 「정리해 둔 것」, 답하지 못한 질문은 「아직 답하지 못한 것」이 받는다. 축 비교표는
길 안내가 아니라 이 주제가 세운 모델이므로 이름을 그렇게 고친다.
기록 화면은 그대로다 — 위치와 앞뒤만 보이고 새 맥락 경로를 다시 그리지 않는다.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
즉시 미리보기(`InstantPreview`)와 동작 원리 띠(`MechanismMap`)는 파일로만 남아 있었다.
아무 화면도 부르지 않는데 규칙과 검사는 그대로여서, 고칠 때마다 살아 있는 코드처럼 따라왔다.
함께 죽어 있던 것들:
- `createAssetCatalogResolver` — 즉시 미리보기만 쓰던 픽셀 해석기
- `mergeAssetCatalog` 와 편집기의 자료 목록 — 그 목록을 읽던 화면이 없어졌다
(`DocumentEditor` 는 이미 `assets: _assets` 로 받아만 두고 있었다)
- 분할 편집기·미리보기 모드·예전 검증 패널의 CSS 규칙
검사는 지우지 않고 살아 있는 쪽으로 옮겼다. 자료 열쇠 합의 검사는 이제 목 어댑터의 투영과
공개 화면이 실제로 쓰는 해석기를 맞대고 본다 — READY 검사를 빼 보면 144개 조합 중 16개가
어긋난다.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
pnpm 11 은 스크립트를 돌리기 전에 node_modules 가 package.json 과 맞는지 보고, 어긋나면
스스로 `pnpm install` 을 돌린다(`verify-deps-before-run` 의 기본값). 게이트 검사는 빈 임시
폴더에 package.json 만 복사해 두고 게이트를 돌리므로 매번 509개를 설치했고, 그 진행 표시가
8KB 짜리 기록 상한을 먼저 채워 남겨야 할 진단이 잘려 나갔다.
의존성이 없으면 설치가 아니라 명령이 실패해야 한다. 설치는 게이트 앞의 제 단계가 할 일이다.
고치기 전: ci-workflow-generation 의 3개 실패, 파일 전체 36초.
고친 뒤: 408개 전부 통과, 8초.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
핵심은 제목 아래 요약이 이미 말한다. 문제·결론 두 칸은 그 요약이 어디서 나왔는지
확인하려는 사람에게 필요한 자세한 이야기이고, 네 문단짜리 결론이 늘 펴져 있으면 본문이
두 번째 화면으로 밀린다.
검증 환경과 같은 모양의 `details` 로 둔다. 이어지는 손잡이 둘은 떨어진 덩어리가 아니라
한 벌의 줄로 선다.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`.studio-secondary-button` 은 홀로 설 때를 위해 전역으로 `margin-top: 24px` 를 갖는다.
줄 안에서 이 여백을 풀어 주지 않으면 가운데 정렬이 여백까지 포함해 재기 때문에 단추만
12px 아래로 내려앉는다. 「본문에 자료 넣기 / 종류 / 업로드」 가 그 상태였다.
운영 화면에서 잰 값: 두 단추 top 1179, 선택 상자 top 1167.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`~/Desktop/tech-log-frontend` 가 세 번 더 고쳐져 있었다. 소스 열셋이 바뀌고 둘이
새로 생겼다(`markdown-block-editor`, `catalog-property-picker`). 검사 넷도 함께 바뀌었다.
기능이 바뀐 것부터 적는다.
**편집기에서 즉시 미리보기가 빠졌다.** v2 에서 「편집/나란히/미리보기」 모드가 생겼고,
v4 가 그 모드 자체를 없앴다 — 글 쓰는 화면은 하나이고 공개 렌더는 편집기의 두 번째
상태가 아니라는 판단이다. 직전 리뷰의 완료 조건 하나("preview 는 Desktop/Mobile 을
실제로 전환할 수 있다")가 이로써 다시 미적용이 된다. `InstantPreview` 는 파일로 남아
있으나 편집기 어디서도 부르지 않는다.
**본문이 textarea 에서 블록 편집기로 바뀌었다.** 기존 markdown 을 문단·제목·목록·인용·
코드·구분선·raw 로 읽고 같은 `bodyMarkdown` 계약으로 되돌려 쓴다. 읽었다가 그대로 다시
쓰는 왕복이 글을 바꾸면 작성자가 문서를 열어 저장하기만 해도 내용이 상하므로, 이
저장소가 실제로 쓰는 문법(앵커 단 소제목, 이름표 단 코드 울타리, `:::evidence`, 표,
인용, 목록, 구분선)을 하나씩 넣어 왕복을 검사로 고정했다. 빈 줄이 겹친 자리만 한 줄로
접히고 글자는 그대로다 — 그 예외도 검사에 적었다.
Project·Topic 이 검색 가능한 고르개로, 상태가 인라인 알약으로 바뀌었고, 메타데이터는
접히는 속성 면으로 내려갔다.
`useImperativeHandle` 안에서 부르는 `commit` 이 렌더마다 새로 만들어져 lint 가 막았다.
`useCallback` 으로 고정했다 — 바뀌는 것은 `onChange` 하나다.
Node 24 로 게이트 재실행: check:types · lint · test:unit(1829) · test:component(152) ·
test:tech-log(432) 전부 통과.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
`~/Desktop/tech-log-frontend` 의 재디자인 결과물(DESIGN_REVISION.md)을 그대로 가져왔다.
바뀐 것은 소스 일곱과 검사 둘이고, 나머지 파일은 이 저장소의 것과 같았다.
공개 화면 — 홈을 큰 빈 히어로 + 평평한 줄 목록에서 실제 조사 경로로 흐르게 고쳤고,
프로젝트·주제·현재·관련 맥락을 본문 흐름 밖의 고정 레일로 옮겼다(좁은 화면은 접이식 유지).
Case·Concept 장문을 읽기 폭 + 맥락/목차 레일 한 짜임으로 통일했고, Question·Reference 도
같은 짜임으로 다시 세웠다. Case 의 검증 조건은 곁다리 details 줄이 아니라 의도된 근거
공개로 바꿨다. 제목·본문 폭과 프로젝트 목록 밀도를 줄이고 상태 격자를 반응형으로 만들었다.
Studio — Asset Picker 를 파일 이름·미리보기·치수·사용 수를 가진 검색 가능한 줄로 다시
만들었다. 지우는 동작은 Asset 화면에 남긴다.
내가 넣었던 개념 흐름 지도(`MechanismMap`)는 이 수정본이 뺐다 — 소제목을 알약으로 늘어놓은
근사치라 절 사이에 태그를 붙여 놓은 것처럼 보인다는 판단이다. 컴포넌트와 CSS 는 아직 남아
있으나 어디서도 부르지 않는다.
수정본은 Node 22 에서 검증됐다고 적혀 있어 이 저장소가 선언한 Node 24 로 다시 돌렸다:
check:types · lint · test:unit(1829) · test:component(152) · test:tech-log(422) 전부 통과.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
지난 보고에서 P0·P1 단위로만 세고 리뷰 §26 완료 조건 대비로는 세지 않았다. 세어 보니
일곱이 빠져 있었다.
편집기에 맥락 패널이 없었다. 읽는 쪽은 맥락을 잃지 않게 해 놓고 쓰는 쪽은 잃게 두고
있었다 — 작성자는 지금 쓰는 글이 어느 프로젝트의 어느 주제에 속하고 무엇과 이어져
있는지를 기본 정보 칸까지 거슬러 올라가야만 볼 수 있었다.
대체 텍스트를 고칠 자리가 없었다. 업로드할 때 한 번 적고 끝이라 잘못 적은 것을 알아도
고칠 수 없었는데, 그 글은 그림을 못 보는 사람에게는 그림 자체다. 설명(caption)은 같은
그림을 기록마다 다르게 설명할 수 있으므로 자료가 아니라 본문이 갖는다.
자료를 종류와 쓰임으로 거른다. 종류는 계약이 주는 필터라 서버가 거르고, 쓰임은 계약에
없어 받아 온 목록에서 거른다 — 다음 쪽까지 세지 못한다는 사실을 화면에 적는다. 없는
필터를 있는 척하는 것이 가장 나쁘다.
작업본 목록에 「다음 할 일」 필터를 둔다. 작성자가 목록에서 실제로 묻는 것이 그것이다.
주제·관계 없음·자료 없음은 `DocumentSummary` 에 값이 없어 아직 못 한다.
레일에 앞뒤 단계를 붙인다. 맥락은 "어디에 속하는가"까지고, 길은 "어디에서 와서 어디로
가는가"다. 홈의 사슬에는 각 단계의 요약 첫 문장을 붙인다 — 무엇이 이어지는지만 적으면
목록이고, 왜 이어지는지를 적어야 길이 된다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
리뷰의 P0 여섯과 P1 일곱을 반영한 결과를 남긴다. 채우지 못한 것(프로젝트·주제의 내용,
Publish 의미 diff, 작업본 목록의 주제 필터)도 이유와 함께 적는다 — 무엇을 안 했는지가
적혀 있지 않으면 다음 검토가 그것을 다시 찾아야 한다.
로그인 창은 사람이 타이핑하는 동안 몇 분씩 떠 있다. 기본 설정으로 띄우면 그 시간 내내
메모리를 크게 물고 있어 이 기계의 감시에 걸려 죽었고, 창이 죽으면 세션도 못 받았다.
그림을 그릴 일이 없는 창이므로 GPU 와 큰 공유 메모리를 쓰지 않게 한다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
게시 화면이 버전 번호만 말했다. 관계는 공개 화면의 「다음에 읽을 것」이 되고 본문의
자료는 그림 자리가 되므로, 무엇이 함께 나가는지를 수로 먼저 보인다. 둘 다 0 이면 이
기록은 홀로 서는 글이라는 뜻이고, 그건 게시 전에 알아야 하는 사실이다.
프로젝트의 논지와 주제가 답하는 질문이 비어 있으면 화면이 빈 문단을 그렸다. 아직 안
쓴 것과 쓸 것이 없는 것은 다르다 — 빈 자리는 화면이 덜 만들어진 것처럼 보이고, 읽는
사람은 이 프로젝트에 결론이 없다고 읽는다. 조사가 어디쯤인지를 말한다.
Studio 구조 화면은 현재 목표가 비어 있는 프로젝트와 답하는 질문이 비어 있는 주제를
짚는다. 그 값들이 공개 화면의 첫 문단을 그리는데, 무엇이 비었는지는 편집기를 하나씩
열어야 알 수 있었다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
Asset 상세는 이름과 사실 몇 줄뿐이었다. 목록의 썸네일은 "이게 그건가"를 가리는 데
쓰고, 상세에서는 실제로 무엇이 그려져 있는지 읽어야 한다 — 바꾸거나 지우기 전에
확인하는 자리다. 큰 그림을 싣고, 쓰이는 자료라면 지우기 전에 몇 개 기록이 깨지는지를
동작 옆에 못 박는다.
주제와 프로젝트 화면은 목록 둘뿐이라 여느 CMS 의 분류 관리와 같았다. 이 제품에서
값어치 있는 것은 그 둘의 관계다. 「구조」를 먼저 두고 프로젝트 → 주제 나무를 그린다.
답하는 질문이 비어 있는 주제와, 어느 프로젝트에도 걸리지 않은 주제를 함께 드러낸다 —
걸리지 않았다는 사실 자체가 구조의 상태이므로 숨기면 그 주제는 어느 화면에서도 보이지
않는다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
열린 질문의 네 구역이 같은 제목+본문 모양이라, 긴 글을 훑을 때 「확인한 사실」과
「가정」이 눈으로 구분되지 않았다. 이 기록의 값어치가 바로 그 구분에 있는데 화면에서
사라져 있었다. 색을 다섯 개 칠하지 않고 표식 하나와 왼쪽 선만 다르게 둔다.
다음 검증은 「무엇을 확인할 것인가」만 있었다. 이 질문이 열려 있는 이유는 남은
미지수이므로 그것을 여기 다시 세워 둘을 잇는다 — 작성자가 따로 적지 않아도 사슬이 보인다.
개념은 여느 긴 글과 똑같이 제목 다음에 첫 문단이 왔다. 어느 계층을 지나는 이야기인지
알려면 끝까지 읽어야 했다. 본문의 소제목이 곧 그 계층이므로 손으로 적지 않고 거기서
흐름을 만든다 — 손으로 적게 하면 본문을 고칠 때 그 줄만 낡는다.
편집기 목차는 구역만 읽어서 Question 에서는 「판단과 다음 검증」 한 줄이었다. 확인한
사실·가정·남은 미지수·제약이 전부 그 한 구역 안의 묶음이기 때문이다. 묶음도 함께 읽어
7,540px 짜리 폼에서 목차가 제 일을 하게 한다.
프로젝트 목록은 이름과 단계만 있어 한 줄이 차지하는 높이에 비해 말하는 것이 적었다.
기록·열린 질문·결정 수를 실어, 그 프로젝트가 지금 모으는 중인지 정리된 상태인지가
목록에서 보이게 한다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
주제를 보관으로 내리거나 지우면 그 주제를 가리키던 작업본이 즉시 터졌다. 작성자는
「초안을 미리 볼 수 없습니다 / TOPIC catalog entry not found: cf1fe22a…」라는 UUID 만
보고, 무엇을 어디서 고쳐야 하는지 알 수 없었다 — 미리보기가 죽으면 고칠 화면까지 함께
죽는다. 이름 없는 자리로 대신해 문서를 그리고, 무엇이 잘못됐는지는 편집 폼의 그 칸이
말한다. 목록에 없는 값도 셀렉트에 임시 항목으로 남긴다: 남기지 않으면 「선택하지 않음」
으로 보여서, 고른 적 없는 주제 때문에 경고가 뜬다고 읽힌다.
편집 폼 아래에 고를 수 있는 자료가 전부 펼쳐져 있었다. 36개면 36줄이고 줄마다 파일
이름과 삭제 단추가 따라붙어 본문보다 자료 목록이 길었다 — 글을 쓰는 화면이 자료 관리
화면이 되어 있었다. 폼에는 지금 몇 개를 쓰는지와 넣는 단추만 두고, 고르는 일은 창
안에서 한다. 고르기 화면과 관리 화면은 같은 자료를 다루되 하는 일이 다르다.
Studio 위쪽은 네 가지 일만 보인다. 목적지 여섯에 구분선을 그어도 처음 들어온 사람은
여섯 중 어디부터 가야 하는지를 스스로 판단해야 했다 — 나뉘어 보이는 것과 적어 보이는
것은 다르다. 그 일 안의 화면은 일을 고른 뒤에 나타나고, 화면이 하나뿐인 일은 이름을
두 번 적지 않는다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
새로 찍은 화면에서 드러났다. 홈은 `DESIGN` 이라는 저장값을 그대로 찍고 있었고,
프로젝트 화면은 같은 값을 「설계」로 부르고 있었다 — 한 사이트가 같은 것을 두 이름으로
말했다. 활동 종류에서 겪은 것과 같은 실수다.
이름표를 도메인으로 옮긴다. 어댑터는 표현 계층을 import 할 수 없고(경계 규칙), 이름표를
어댑터마다 다시 적으면 정확히 이 문제가 다시 난다. 단계 집합도 도메인이 갖게 해서 포트가
그것을 쓰도록 했다 — 같은 집합을 두 곳에 적으면 한쪽만 늘어난다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
리뷰와 무관하게, 제가 이전 세션에 DB 로 직접 넣은 주제 다섯이 기록 0개인 채로 공개돼
있었다 — 「A층 열 편을 직접 치는 순서」처럼 독자에게 아무것도 말하지 않는 이름이었고,
환경 구성을 별도 주제로 떼어 낸 것 자체가 틀렸다. 환경 구성은 조사 주제가 아니라 어떤
주제를 검증하기 위한 조건이므로 그 주제 안에 들어가야 한다.
지우지 않고 상태만 내린다. 기록이 붙어 있으면 거부하고, 그 판단을 스크립트 안의 목록이
아니라 서버에 물어 확인한다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
주제로 묶었더니 이 구역이 배포본에서 통째로 사라졌다 — 지금은 한 주제에 기록이 하나씩뿐이라
이을 것이 없었다. 조사는 프로젝트 안에서 여러 주제를 오가며 자라므로 프로젝트가 사슬의
자연스러운 단위다. 기록마다 어느 주제인지 함께 적어, 하나의 조사가 여러 주제를 오간다는 것을
그 줄이 보여 주게 한다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
미리보기가 늘 좁은 칸에 갇혀 있었다. 공개 화면은 1,180px 셸인데 그 칸은 절반도 안
되므로, 작성자가 보던 것은 공개 화면이 아니라 좁은 화면용 배치였다 — 데스크톱에서
어떻게 보이는지는 게시한 뒤에야 알 수 있었다. 나란히·넓게·숨김과 데스크톱·모바일 폭을
고를 수 있게 한다.
관계 대상이 105개다. 평면 셀렉트에서 그것을 이름으로 찾으려면 목록 전체를 눈으로
훑어야 하고, 종류로 묶어도 한 묶음이 마흔이 넘으면 마찬가지다 — 셀렉트는 열어 둔 채
타이핑으로 걸러지지 않는다. 거르는 칸을 위에 둔다. 이미 고른 대상은 걸러도 남긴다:
사라지면 그 줄이 무엇을 가리키는지 읽을 수 없다.
게시 화면이 어느 주소로 나가는지 말하지 않았다. 게시는 공개 주소 하나를 만들거나
갈아 끼우는 일이고, 작성자가 확인하고 싶은 것도 그 주소다.
Studio 의 좁은 화면 좌우 여백이 16px 이라 글이 테두리에 붙었다. 공개 화면과 같은
20px 로 맞춘다.
hover 는 120ms 로 색만 옮긴다. 자리를 옮기는 전환은 목록에서 줄이 흔들려 보인다.
움직임을 줄이라고 한 사람에게는 기존 `prefers-reduced-motion` 블록이 0 으로 만든다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
Asset 목록이 `assetKey` 를 앞세우고 있었다. key 는 본문이 가리키는 불변 식별자이지
사람이 기억하는 이름이 아니다 — 스무 줄이면 해시 같은 문자열 스무 개에서 찾던 도식을
눈으로 골라야 했다. 파일 이름을 앞에 두고 형식·치수·크기를 함께 적는다. key 는 아래에
작게 남긴다(복사해 쓰는 값이라 지우지 않는다).
「사용 0건」과 「사용 3건」이 같은 회색으로 나란했다. 쓰이지 않는 자료는 지워도 되는
것이고 쓰이는 자료는 지우면 화면이 깨지므로, 그 차이를 말로 가른다. 상세에서는 어느
기록이 쓰는지를 링크로 연다 — 바꾸거나 지우기 전에 무엇이 깨질지 숫자만으로는 알 수
없다. 관리 상태도 `ARCHIVED` 대신 「보관됨」으로 적는다.
검증 결과는 오류와 경고가 한 목록에 섞여 있었다. 게시 전에 작성자가 알아야 하는 것은
"게시를 막는 것이 몇 개인가" 하나인데, 그 답을 얻으려면 줄마다 배지를 읽어야 했다.
둘을 갈라 각각의 수를 제목에 적는다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
탐색 여섯 자리가 같은 무게로 늘어서 있었다. 「작업본」과 「릴리즈」가 같은 크기로
나란하면 어디부터 봐야 하는지를 화면이 말해 주지 않는다. 글을 쓰는 일·구조를 손보는
일·자료를 관리하는 일·내보내는 일 넷으로 묶는다. 이름과 순서는 계약이 갖고 있으므로
여기서는 묶음만 정하고, 표가 `Record` 라 탐색 항목이 늘면 컴파일러가 잡는다.
대시보드는 숫자 넷과 목록 셋으로 무엇이 얼마나 있는지를 보고했다. 작성자가 이 화면을
여는 이유는 보고를 읽으려는 것이 아니라 하던 일을 이어서 하려는 것인데, 그 다음 한
걸음은 세 목록 중 어딘가에 같은 크기로 섞여 있었다. 가장 최근에 손댄 것 하나를 맨 위에
세우고 그 작업본의 다음 화면으로 바로 보낸다.
작업본 목록의 「삭제」는 61줄에서 61번 반복돼 이 화면의 기본 동작처럼 보였다. 한 겹
안으로 넣는다. 계약이 주고 있었지만 화면이 쓰지 않던 `hasUnpublishedChanges` 도
드러낸다 — 작성자는 "이미 게시했는데 고친 게 아직 안 나갔다"를 목록에서 알 수 없었다.
다음 할 일의 이름과 갈 곳을 한 벌로 모았다. 대시보드와 목록이 각자 표를 들고 있었다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
기록 목록은 제목과 요약만 늘어놓았다. 그러면 이 사이트의 기록은 여느 블로그 글과
구분되지 않는다 — 이 기록이 사슬의 한 마디라는 것이 목록에서부터 보여야 한다. 줄마다
이어지는 기록 하나와 작성자가 그 관계에 남긴 문장을 붙인다. 한 줄만 붙인다: 여럿이면
줄마다 문단이 되어 훑을 수 없다.
검색은 결과를 한 줄로 늘어놓았다. "가상화" 로 찾는 사람이 정말 원하는 것은 그 말이
들어간 문서 열두 개가 아니라 어디서부터 읽을지다. 들어가는 자리(프로젝트)를 기록보다
위에 세우고, 그 말이 어느 주제에 모여 있는지를 한 줄로 말한다. 걸린 말은 제목과 요약
안에서 표시한다 — `HighlightMatch` 는 이미 있었는데 검색 화면이 쓰지 않고 있었다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
레일에는 「이 글에서」만 있었다. 이 글 안의 위치는 알아도 이 조사 안의 위치는 알 수
없었고, 제목 아래의 맥락 덩어리는 화면을 몇 번 넘기면 사라진다. 레일 아래 칸에
프로젝트·주제·종류를 짧게 붙여 따라오게 한다. 관계 목록은 두지 않는다 — 제목 아래에
이미 있고, 같은 목록이 한 화면에 두 번 있으면 목록이 아니라 소음이다.
레일이 둘을 담게 되었으므로 이름도 갈랐다. 「이 글에서」와 「맥락」은 서로 다른 질문에
답한다.
작성자가 확대를 끈 도식도 좁은 화면에서는 확대할 수 있게 했다. 390px 화면에서 폭
1,200px 짜리 도식은 3분의 1 로 눌려 덩어리만 보이고 글자는 읽히지 않는다 — 설명하는
일을 하지 못한다. 기준은 치수다: 본문 폭(720px)보다 넓은 그림은 어디선가 반드시 줄어든다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
제목이 컸다. 데스크톱 52~56px 은 짧은 영문 제목에는 맞지만 한국어 기술 제목에서는
넉 줄이 되고, 모바일 38~44px 은 제목만으로 첫 화면을 채워 맥락이 두 번째 화면으로
밀린다. 데스크톱 44~48px, 모바일 30~34px 로 내리고 눌려 있던 줄간(1.05~1.14)을
1.18~1.26 으로 편다.
Case 의 실험 조건은 재현하려는 사람에게 필요하고 처음 읽는 사람에게는 본론을 막는
벽이다. 버전과 데이터셋을 여러 줄로 적으면 좁은 화면에서 이 덩어리만으로 한 화면을
채운다. 접어 두되 손잡이가 무엇이 들었는지 말하게 한다.
표와 코드가 옆으로 넘어간다는 것을 말하지 않았다. 좁은 화면에서는 잘린 채 끝난
것처럼 보여서, 읽는 사람은 오른쪽 칸이 있다는 것 자체를 몰랐다. 넘어가는 쪽에만
그림자가 서게 하고(자바스크립트 없이 `local`/`scroll` 배경을 겹친다), 좁은 화면에서는
첫 칸을 붙여 둔다 — 옆으로 넘기는 동안 그 행이 무엇에 대한 줄인지 사라지면 표를 읽을
수 없다.
적용 기준의 「적용할 때」·「예외와 주의」를 판단 기준 위로 올렸다. 아래에 있으면 읽는
사람은 기준 여럿을 다 읽은 뒤에야 "이건 내 경우가 아니었다"를 알게 된다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
홈의 첫 문장은 글 쓰는 태도를 말했다 — "문제를 재현하고 검증해 정리합니다". 맞는
말이지만 처음 온 사람이 알아야 하는 것은 태도가 아니라 길이다. 이 사이트에서 기록은
한 편으로 끝나지 않고 프로젝트 안의 주제에 속하고 주제 안에서 서로 이어진다. 그 구조를
설명하는 문장보다 실제 사슬 하나가 빠르므로, 최근 기록이 가장 많이 모인 주제를 골라
프로젝트 → 주제 → 기록으로 편다. 예시를 코드에 적어 두지 않는다 — 그 기록을 지우는
순간 홈이 죽은 링크를 가리킨다.
프로젝트 활동은 종류 자리에 `CONCEPT_PUBLISHED` 를 그대로 찍고 있었다. 그것은
데이터베이스 제약(`project_activity_activity_type_check`)이 허용하는 값이지 방문자에게
할 말이 아니다 — 감사 로그처럼 읽히고, 정작 무슨 일이 있었는지는 알 수 없었다.
포트의 타입은 `"PUBLICATION" | "PROJECT UPDATE" | "QUESTION"` 셋으로 적혀 있었는데
서버는 그중 무엇도 보내지 않는다. 매퍼가 단언으로 통과시켜서 타입 검사도 이것을 잡지
못했다. 실제 값 열하나로 맞추고, `Record<ProjectActivityType, string>` 표로 사람이 읽는
문장을 만든다. 픽스처도 같은 값을 쓰게 했다 — 픽스처가 자기만의 말을 쓰던 동안 화면은
픽스처에서만 멀쩡했다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
주제 화면은 기록이 하나뿐이면 제목과 한 줄, 목록 한 줄이 전부였다. 그 상태에서는
"아직 아무것도 없는 곳"과 "이제 막 시작한 조사"가 구분되지 않는다 — 둘 다 빈 화면으로
보인다. 무엇이 있고 무엇이 아직 없는지를 먼저 적는다. 「아직 없는 것」이 이 화면에서
가장 쓸모 있는 줄이다.
프로젝트의 「주요 주제」는 이름만 있는 목록이었다. 프로젝트를 여는 사람이 알고 싶은
것은 이름이 아니라 그 질문에 대해 지금까지 무엇을 만들어 놨는가인데, 이름만 있으면
주제 화면까지 한 번 더 들어가야 알 수 있었고 프로젝트 화면이 목차의 목차가 됐다.
주제마다 이 프로젝트의 기록을 읽는 순서대로 펴서 조사의 모양이 한 화면에 보이게 한다.
다루기로 했지만 비어 있는 주제도 지우지 않는다 — 그 사실이 조사의 상태다.
결정 화면은 결정이 없으면 통째로 빈 종이였다. 남은 질문을 함께 읽어, 그 빈 화면이
"결정할 것이 없다"가 아니라 "아직 결정에 이르지 못했다"를 말하게 한다.
읽는 순서 표를 한 벌로 모았다. 세 화면이 각자 자기 목록을 들고 있으면 종류를 더할 때
한 곳만 고쳐지고 나머지는 새 종류를 맨 앞이나 맨 뒤에 조용히 던져 놓는다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
이 사이트의 차별점은 "기록 하나에 아무 데서나 들어와도 그 결론을 만든 맥락의 사슬을
잃지 않는다"는 것이다. 그런데 그 사슬이 화면에서는 제목 위 얇은 breadcrumb 한 줄과
문서 맨 아래 「다음에 읽을 것」으로만 표현돼 있었다 — 검색으로 Case 하나에 들어온
사람은 바닥까지 내려가야 이 기록이 어느 프로젝트의 어느 질문에서 나왔는지 알 수
있었다. 저장은 되어 있는데 겪게 되지는 않는 상태였다.
제목·요약 바로 아래에 맥락을 하나의 덩어리로 세운다. 프로젝트 → 주제로 올라가는
길과, 같은 조사 안에서 이웃한 기록들을 함께 보인다. 이웃에는 작성자가 그 관계에 남긴
문장을 붙인다 — 「다음에 무엇을」보다 「왜 그것을」이 먼저 있어야 목록이 아니라 사슬로
읽힌다. 지금 보는 기록도 목록에 남겨 자기 자리가 보이게 한다.
여섯 종류 전부에 들어간다. 종류마다 하나씩 픽스처를 둔 `Record<RecordKind, …>` 검사로
막았다 — 한 종류에서만 빠지면 그 종류로 들어온 방문자에게만 조용히 사슬이 끊긴다.
Question 에서 빼 보고 그 검사만 실패하는 것을 확인했다.
화면 촬영기(`scripts/capture-screens.ts`)도 함께 넣는다. 라우트 레지스트리를 돌며
공개·Studio 전 화면을 찍는다. 찍을 목록을 손으로 적지 않고 `Record<RouteId, …>` 로
두어 라우트가 늘면 컴파일러가 빈 자리를 잡는다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015c8cBFUaVr7KLVUx6ujz7D
세 가지가 각각 다른 곳에서 조용히 깨져 있었다.
작업본 목록의 프로젝트·정렬은 주소에 적히자마자 지워졌다. 라우트 검색 코덱이
STRIP_UNKNOWN 이라 선언하지 않은 키를 버리는데 `project` 와 `sort` 가 없었다 —
화면은 주소를 쓰고 라우터가 그것을 지워서, 프로젝트를 골라도 목록이 그대로였다.
카탈로그는 한 번만 불렀다. 한 번의 상한은 계약이 100으로 정해 두었으므로,
기록이 101개가 된 날 101번째부터는 관계 대상 선택에도 프로젝트 필터에도 나타나지
않았다. 응답의 `nextCursor` 를 따라 끝까지 읽는다.
게시 기록의 필터 줄은 세 칸 격자에 「검색칸 · 버튼 · 이벤트」로 잘려, 검색칸이
871px 로 벌어지고 이벤트 셀렉트는 91px 로 눌렸다 — 「게시 취소」가 그 너비에
들어가지 않았다. 버튼을 검색칸에 붙이고 칸을 둘로 줄인다.
검색 안내는 「제목 또는 요약」·「제목, 요약, slug」라고 적혀 있었지만 서버가 뒤지는
것은 제목뿐이다. 적힌 대로 고친다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
H2. 편집기.
7,540px 폼에 섹션으로 갈 수단이 목차도 접기도 앵커도 없었다. 화면에 실제로 있는
`section[aria-labelledby]` 를 읽어 목차를 만든다 — 목록을 손으로 적지 않으므로
섹션이 바뀌어도 이 파일은 그대로다.
미리보기가 sticky 로 문서 맨 위에 고정돼, 폼 중반에서 지금 쓰는 문단이 미리보기
어디인지 볼 방법이 없었다. 커서가 지난 마지막 `##` 을 찾아 미리보기의 같은 제목으로
옮긴다. 스크롤 비율을 맞추는 방식은 두 쪽 길이가 다르면 늘 어긋난다. 손으로 넘기는
중에는 따라가지 않는다.
반복 그룹은 접을 수 있고 순서는 끌어서 바꾼다. 「위로/아래로」는 남긴다 — 끌기는
키보드로 할 수 없고, 그것만 두면 키보드로 쓰는 사람에게서 순서 바꾸기를 빼앗는다.
대신 작게 적는다.
H3. 주제와 프로젝트를 탭으로 나눈다.
한 화면이 성격이 다른 두 엔티티를 같은 문법으로 다뤘다. 「추가」 버튼 둘이 같은
이름·같은 모양으로 한 줄에 있었고, 주제 행은 프로젝트에 맞춘 그리드라 절반이
빈칸이었다. 버튼 이름을 「주제 추가」·「프로젝트 추가」로 가르고, 프로젝트 행에서
같은 주소를 두 번 가리키던 「내용 편집」 하나를 없애고, 주제 행에 편집 버튼을 둔다.
M10. 프로필에 연락·구독 수단. 계약은 처음부터 `contacts` 를 주고 있었고 화면이
읽지 않았다 — 읽고 나서 할 수 있는 일이 하나도 없었다. 프로필이 게시 전이면 빈
목록이고 그때는 구역을 그리지 않는다.
M11. 공개 화면 HTML 에 Studio 청크 셋이 modulepreload 로 붙어 있었다. 읽기만 하는
사람이 편집기 번들을 내려받았다. 빌드에서 그 셋만 뺀다 — 공개 라우트의 미리 받기는
그대로 둔다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
게시 Snapshot 화면이 figure 와 alt 는 그리면서 img src 를 비워 두었다. 서버는
주소를 제대로 실어 보냈고(renderModel 의 asset.publicPath) 화면이 그것을 버렸다.
원인은 kind === "CASE" ? model.bodyBlocks : [] 다. 개념이 더해진 뒤에도 그대로여서
개념·환경 구성은 해석기에 빈 목록이 갔다. 종류를 짚는 대신 본문 블록이 있으면
그것을 준다 — 새 종류가 본문을 가지면 저절로 걸린다.
프로젝트의 주요 주제는 고른 목록이 비어 있으면 기록에서 뽑는다. 고르는 것은
별도 동작이라 대부분 비어 있었고, 그동안 이 구역은 제목만 있는 빈 목록이었다.
이 프로젝트의 공개 기록이 어느 주제에 사는지가 곧 이 프로젝트가 다루는 주제다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
프로젝트를 만들고 주제를 넷 만들어도 공개 화면의 「주요 주제」는 비어 있었다.
주제를 만드는 것과 프로젝트에 붙이는 것이 다른 동작인데 그 사실이 어디에도
적혀 있지 않았고, 공개 화면은 제목만 있는 빈 목록을 그려서 화면이 고장난 것처럼
보였다.
공개 화면은 고른 주제가 없으면 구역을 그리지 않는다. Studio 는 여기서 고른 것만
공개 화면에 나온다고 적는다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
CPU 가상화 주제에 글을 게시했는데 홈 탭은 「아직 공개된 기록이 없습니다」였다.
축을 쓰지 않는 주제의 목록을 상세의 featuredCases 로 만들었는데, 그 칸은 작성자가
주제마다 손으로 골라 두는 값이라 대부분 비어 있다. 게다가 Case 만 담아서, 게시한
것이 동작 원리면 애초에 담기지 않는다 — 주제 목록의 recordCount 는 1 인데 탭은
0 이라고 말했다.
주제 화면이 하는 것과 같이 기록 자체를 읽는다. 받는 중에는 「없습니다」라고 말하지
않는다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
편집기 오른쪽이 통째로 「초안을 미리 볼 수 없습니다」가 되고 이유로 UUID 하나만
보여 줬다. 본문을 쓰는 동안 본문을 볼 수 없었다.
원인은 관계 후보 목록의 개수 상한이다. 계약이 limit 을 100 으로 못박고 있고,
기록이 그 수를 넘자 목록 밖의 기록을 가리킨 문서는 전부 이 상태가 됐다.
관계가 실제로 끊겼는지는 검증이 판정한다(RELATION_TARGET_NOT_FOUND). 서버가 자기
저장소를 직접 보므로 목록 상한과 무관하다. 미리보기가 할 일은 지금 쓰고 있는 글을
보여 주는 것이고, 이름을 모르는 관계 한 줄은 그렇다고 적으면 된다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
홈은 「지금 집중하는 것」이 비교표보다 위다. M8 을 따라 비교표를 첫 화면으로
올렸는데, 이 사이트의 첫 화면이 무엇이어야 하는지는 리뷰가 아니라 쓰는 사람이
정한다.
Public Preview 화면은 검증 기록이 없으면 만들기 버튼이 나타나지 않는데, 화면은
"현재 검증 결과를 기준으로 생성합니다" 라고만 적어 두었다 — 할 수 있는 일을
설명하면서 그 일을 할 자리는 주지 않았고, 왜 없는지도 말하지 않았다. 작성자에게는
미리보기가 고장난 것으로 보인다. 검증이 먼저라고 말한다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
주제 탭 (H1 연장). 홈 탭에 주제를 전부 세우고 목록 아래 「다른 주제 N개 보기」
줄을 없앴다. 축이 둘 이상인 주제만 탭이 되던 규칙 때문에 여섯 중 둘만 올라오고
나머지 넷은 비교표를 다 읽어야 만나는 작은 글씨 한 줄로 갔다. 축은 주제가
자라면서 생기는 것이지 기록이 없다는 뜻이 아니다. 축이 없는 주제는 그 주제의
기록을 세우고, 기록이 없으면 그렇다고 분명히 말한다.
탭 하나가 패널 하나를 가리키게 고쳤다. 탭 전부가 같은 패널을 가리키면 고르지
않은 탭이 "내가 저 패널을 연다" 고 말하면서 패널은 다른 탭의 이름을 달게 된다.
H1. `/studio/documents` 와 `/studio/publications` 의 검색·필터·쪽수를 주소에
담는다. 담지 않던 동안 3쪽에서 문서를 열고 뒤로 오면 1쪽이었고 필터도 사라졌다.
공개 `/search` 는 처음부터 담고 있었다.
H4. 문서 종류 이름을 `document-kind-labels.ts` 하나로 모았다. 세 곳에 흩어져
있어서 같은 CASE 가 목록에서는 「검증 기록」, 새 문서에서는 「Case」, 검색에서는
또 다른 이름이었다.
H5. `project.stage` 가 화면에 `DESIGN` 으로 그대로 새어 나왔다. 같은 프로젝트를
Studio 는 「설계」로 불렀다 — 두 화면이 다른 말을 했다.
H6. 값이 없는데 라벨만 그려지던 자리를 막았다. 네 프로젝트 중 셋이 「현재 목표」
라벨만 있고 값이 비어 있었다.
M2. 대시보드의 숫자를 목록으로 가는 길로 만들고, 할 일이 없는 구역은 그리지
않는다. 공개 홈 설정 폼은 작업 목록 한가운데에서 뒤로 옮겼다.
M3. 작업본 목록에 프로젝트 필터와 정렬을 더했다. 공개 `/explore` 는 독자에게
셋을 주는데 61개를 관리하는 작성자에게는 둘뿐이었다.
M4. 게시 기록의 필터 제출 방식을 작업본 목록에 맞췄다 — 셀렉트는 즉시, 검색만
버튼이다.
M5. MOCK 시절 문구("세션이 끝나면 사라집니다")를 지웠다. 실서버에는 작업본이
남는다.
M7. `aria-current="page"` 가 현재 페이지가 아닌 링크에 붙었다. 정확히 일치할
때만 붙게 하고 구역 강조는 따로 계산한다.
M8. 홈의 첫 화면을 비교표로 바꿨다. 다른 데서 얻을 수 없는 유일한 것이 y≈600 에
묻혀 있었다.
`ListDocumentsQuery.kind` 가 손으로 적은 union 이라 개념과 환경 구성이 빠져
있었다 — 그 둘은 작업본 목록에서 걸러 볼 수가 없었다. 계약 타입으로 바꿨다.
M9 는 고치지 않는다. 「문제·결론이 11px 회색」이라는 지적이 지금 빌드에서
재현되지 않는다 — 실측은 17px `rgb(63,66,73)` 이고 본문이 18px 같은 색이다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
B1. 검증·미리보기 화면이 CSS 없이 배포됐다. `workflow.module.css` 를 import
하는 파일이 하나도 없었고, Vite 의 CSS Module 은 import 되어야 번들에 들어간다.
제목이 62px 가 아니라 16px 로 나왔고 미리보기의 링크 두 개가 공백 없이 붙었다.
규칙이 전부 `:global()` 이었으므로 모듈일 이유가 없다 — studio.css 로 옮겼다.
B2. Asset 라이브러리에 스타일이 없고 진입 경로도 없었다. 네 클래스에 규칙이
하나도 없어 key·상태·사용 수가 공백 없이 이어 붙었다. 스무 개짜리 목록에
썸네일도 없어 무엇을 고르는지 눌러 봐야 알았다. 내비게이션에도 없어서 URL 을
직접 쳐야 닿았다 — "정리하는 화면" 에 정리하러 갈 길이 없었다.
B3. 삭제에 확인이 없었다. 문서·주제·프로젝트·릴리즈·Asset 전부 한 번에 영구
삭제였고, 그 「삭제」가 행에서 시각적으로 가장 강한 요소였다(16px/600 빨강).
정작 그 행에서 해야 할 일인 「검증하기」는 13px/400 이었다. 확인 창을 하나
만들어 다섯 곳에 붙이고, 행의 우선순위를 되돌렸다.
B4(일부). robots.txt 가 광고하던 sitemap 이 404 였다. 무엇이 게시됐는지는
서버만 알므로 정적 파일이 아니라 조회로 만든다(백엔드 커밋 참조). robots.txt
가 그 주소를 가리키게 했다.
B5. 라우트 프리픽스 밖 URL 이 nginx 의 맨 `Not Found` 로 끝났다. 404 상태는
그대로 두고 — 크롤러에게 링크가 깨졌다고 말하는 것이 그것이다 — 본문만 앱을
주도록 `error_page 404 @not_found` 를 뒀다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
계약의 종류 enum 이 한 곳이 아니다. RecordKind 말고도 CatalogEntry.kind 와
ResolvedRelation.targetKind 가 따로 종류를 나열한다. 둘을 빠뜨리면 Case 가
셋업을 관계로 걸 수 없고, 걸어도 응답에서 종류가 튕긴다.
백엔드의 계약 union Jackson 테스트가 CatalogEntry 쪽을 잡았고, 프론트의
타입 검사가 ResolvedRelation 쪽을 잡았다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
다섯 종류는 전부 끝난 일을 남긴다. 없는 것은 읽는 사람이 자기 손으로 다시
하려면 무엇부터 하는가다. Case 의 environment 는 평문 한 칸이라 명령이
들어가지 않고, 같은 셋업을 쓰는 Case 가 넷이면 같은 문장이 네 벌 복제된다.
프로젝트는 필수, 주제는 선택으로 둔다. 주제 없는 셋업이 그 프로젝트의 공통
구성이고, 주제를 붙이면 그 주제의 구성이다 — 스키마를 나누지 않고 두 범위를
같은 종류로 받는다.
버전만 본문 밖에 둔다(pinnedVersions). 이 절차가 어느 버전 위에서 성립했는지는
그 기록의 유효 범위이고, 목록과 머리말이 본문을 열지 않고 보여 줘야 한다.
나머지 셋(실행 절차·구성 값·확인 방법)은 명령과 표를 담아야 하므로 본문이다.
이름은 SETUP 이다. ENVIRONMENT 가 영어로는 자연스럽지만 case_detail.environment
와 겹친다 — 이 저장소가 열네 번 밟은 실패가 「종류를 손으로 나열한 곳을
빠뜨린다」이고 그걸 찾는 수단이 grep 이다.
손으로 나열해 두었던 자리를 이번에 표로 바꿨다. publicPath 의 삼항 사슬은
마지막 else 가 「나머지 전부」여서 새 종류의 주소가 조용히 /questions/… 가
됐고, document-editor 의 칸 경로도 같은 모양이었다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
앞 커밋이 로그인 제목의 파란 사각형을 고쳤다고 적었지만 배포된 화면에는 그대로 있었다.
두 가지를 잘못 봤다.
- 이 저장소의 `theme.css` 에 `[data-route-heading]:focus { outline: none }` 이 있어 그것이
정본이라고 판단했는데, 그 파일은 이 앱이 import 하지 않는다. 죽은 파일이다.
- 그래서 실제로 링을 그리던 것은 globals.css 의 전역 `:focus-visible` 이었고, 앞 커밋이
거기에 `.auth-gate .page-header h1:focus-visible` 을 더해 특이도로 덮으면서 offset 만
바꿨다 — 없애려던 것을 더 또렷하게 만들었다.
규칙을 실제로 적용되는 자리(전역 `:focus-visible` 바로 옆)에 둔다. 라우트가 바뀌면
`page-header.tsx` 가 제목에 초점을 주는데 그 제목은 `tabindex="-1"` 이라 키보드로는 닿을 수
없다 — 링은 「누를 수 있다」는 뜻이 되어 거짓말을 한다. 초점 자체는 그대로 준다(없애면
보조기술이 새 화면의 이름을 놓친다). 보이는 표시만 뺀다.
빌드된 CSS 에 규칙이 들어갔는지와, 초점이 걸린 상태에서 outline 이 none 인지를 브라우저에서
직접 재고 확인했다.
작성자가 처음 만나는 화면인데 사이트가 쓰지 않는 말을 쓰고 있었다 — 테두리를 두른 둥근
카드, 파란 채움 버튼, 파란 mono eyebrow. 나머지 화면은 상자를 두지 않고 글자의 굵기와
색으로만 격을 나눈다(805d400 에서 Studio 전체를 그렇게 바꿨는데, 이 화면만 「유일한
행동이니 채워 둔다」는 이유로 예외였다). 처음 만나는 화면이 예외면 그 사이트가 아닌 것처럼
보인다.
홈의 머리(`.home-identity`)와 같은 배치로 세운다 — shell 왼쪽 끝에 kicker·제목·설명이 서고,
헤어라인 아래에 「로그인 시작」과 돌아갈 곳이 한 줄로 온다. 상자도 채움도 없고 반응은
hover 밑줄뿐이다.
- 제목에 초점을 줄 때(page-header.tsx 의 라우트 초점) 파란 사각형이 제목을 두르고 있었다.
`:focus-visible` 일 때만 바깥쪽으로 표시한다.
- kicker 를 「SIGN IN」에서 「STUDIO」로 바꾼다. 사이트의 다른 머리말은 Topic·Explore 처럼
어디인지를 말하고, 「SIGN IN」이면 바로 아래 제목과 같은 말을 두 번 한다.
- 제목이 그 자리에서 이유를 말하게 하고(「기록을 쓰려면 로그인이 필요합니다」) 설명에서
겹치던 첫 문장을 뺀다.
router 컴포넌트 검사가 「세션이 필요합니다.」라는 옛 제목을 그대로 적어 두어, 그 말이 바뀐
뒤로 계속 빨간 채 지나가고 있었다 — 잡아야 할 것(보호된 라우트가 로그인 관문으로 떨어진다)은
멀쩡한데 검사만 낡았다. 문구가 아니라 `data-surface` 를 묻게 한다.
급을 칩으로 낮추고 나니 이번에는 목록 위에 글자만 떠 있는 것처럼 보였다. 두 가지 때문이다 —
고른 것이 색으로만 달라 누를 수 있는 것으로 읽히지 않았고, 탭 줄과 목록 사이가 선 없이
30px 비어 있어 두 덩어리로 갈렸다.
- 고른 탭에 형태를 준다(알약). 색만 바꾸면 「진한 글자와 연한 글자」로 읽힌다. 밑줄은 쓰지
않는다 — 주제가 스무 개면 밑줄 설 자리 스무 개가 함께 늘어선다.
- 묶음의 윗선을 목록이 아니라 패널이 갖고, 탭 줄이 그 선에 바로 얹힌다. 선이 목록에 있으면
축 이름 줄만 선 위로 밀려 나가 탭과 한 덩어리처럼 보이고 정작 목록은 저 혼자 시작한다.
- 알약의 좌우 여백만큼 줄을 당겨, 첫 탭의 글자가 아래 목록의 왼쪽 끝과 한 줄로 선다.
탭이 데이터를 따른다는 것도 검사로 박는다. 화면에는 주제 이름도 개수도 상한도 적혀 있지
않지만, 그 사실은 코드를 읽어야만 알 수 있었다 — 주제 화면이 주제 셋을 코드에 적어 두고
그 셋만 열던 때가 있었으므로 물어볼 만한 것이다.
탭을 구역 제목 급(30px/650)으로 세웠다. 주제가 둘일 때는 그럴듯했지만 열 개, 스무 개가
되면 이름만으로 화면이 덮인다 — 여기서 하려는 말은 「이것이 이 구역의 제목이다」가 아니라
「고를 것이 이만큼 있다」이므로 급도 그쪽이어야 한다. 지금 무엇을 읽는지는 목록 바로 위의
축 이름과 「전체 보기」 줄이 말한다.
고른 탭의 파란 밑줄도 없앤다. 주제가 스무 개면 밑줄이 설 자리 스무 개가 함께 늘어선다.
고르지 않은 것은 색만 죽인다.
개수 상한도 없앤다. 상한은 주제마다 상세를 미리 받느라 둔 것이었는데, 그러면 상한 밖의
주제는 다시 「다른 주제 N개 보기」로 밀린다 — 이 구역이 없애려던 문제로 되돌아간다.
탭은 목록이 주는 전부이고, 상세는 고른 것만 그때 받는다. 요청은 목록 하나 + 처음 열린
주제 하나로 고정되고, 주제가 늘어도 그대로다.
받지 못한 주제는 그 자리에 남긴다. 홈이 두 읽기를 `Promise.all` 로 묶었을 때는 하나가
실패하면 나머지까지 통째로 사라져 흔적이 없었다.
홈은 주제 하나만 펴 두고 나머지는 비교 목록 밑 「다른 주제 N개 보기」 한 줄로 보냈다.
그 줄은 목록을 다 읽고 나서야 만나는 자리라 대개 지나쳤고, 그래서 JPA 주제는 홈에
있으면서도 없는 것과 같았다.
구역 제목이 서 있던 자리(「구조별로 알게 된 것」)를 주제 이름 탭이 대신한다. 무엇이 더
있는지가 목록을 읽기 전에 먼저 보이고, 탭을 고르면 그 주제의 축이 그대로 열린다 —
인증 경계면 SPA·Mediator·BFF·Forward-Auth, JPA면 그 주제의 조회 전략들이다.
- 축의 이름은 목록 바로 위로 내렸다. 제목 자리를 탭이 가져갔으니 「이 넷은 구조다」는
목록에 붙어 있어야 짝이 보인다.
- 패널은 전부 그려 두고 감춘다. 상세는 이미 받아 온 것이라 탭을 눌러도 요청이 나가지
않고, 페이지 내 검색이 감춘 주제까지 찾는다.
- 탭이 되는 주제 수에 상한을 둔다. 주제마다 상세 요청이 하나씩 나가므로, 주제가 늘어도
홈의 요청 수는 정해져 있다.
- 「다른 주제」 줄은 축이 없어 탭이 되지 못한 주제만 받는다.
탭은 h2 가 아니지만 구역 제목의 자리를 물려받았으므로 `section-heading-rank` 가 그 급을
정본과 함께 묶는다.
「다음에 읽을 것」에 걸린 결정 링크가 404 였다. 주소는 서버가 게시할 때 만들어 저장한
문자열이라 화면 코드 어디에도 흔적이 없었고, 방문자만 그것을 만났다.
- `resolvesToPublicRoute` 가 route contract 에서 읽은 라우트 표에 주소를 맞춰 본다. 맞는
라우트가 없는 줄은 관계 목록이 링크로 그리지 않는다.
- 결정 목록의 각 항목이 `slug` 를 element id 로 단다 — 결정의 공개 주소가 이 목록 위의
앵커이므로, id(UUID)를 달면 다른 기록이 건 링크가 갈 곳을 잃는다.
- 앵커로 들어오면 그 결정까지 내려간다. 목록은 받아온 뒤에 그려지므로 브라우저의 기본
앵커 이동만으로는 닿지 않는다.
주제 화면 셋을 더하면서 함께 늘려야 했던 것들도 여기서 맞춘다 — nginx 로 나가는 경로
패턴, 라우트마다 하나씩인 수동 접근성 증거, 그리고 그 둘을 세는 CI 게이트 기준값.
게이트 형상 digest 는 이전 gates.json 에서 옛 값(87a22f68…)을 먼저 재현한 뒤 새로 계산했다.
「결론이 서는 조건」·「자리」·「프로젝트를 답니다」·「결정 순서로 읽는다」·「접근을 나눠
견주고」가 모두 번역투이거나 이 기록에서 쓰지 않는 말이었다. 사용자가 직접 적어 준 세 항목을
그대로 싣는다.
프로젝트 화면의 「이 프로젝트가 밝힌 것」은 「프로젝트를 통해 확인한 결과」로, 소개 문구의
「운영 가능한 설계로 연결합니다」는 「실제 운영에 적용할 수 있는 형태로 정리합니다」로 바꾼다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ