홈 한 화면에 종류 이름이 아홉 개 떠 있었다. 최근 기록 목록은 `CASE`·`CONCEPT`·`OPEN
QUESTION`·`REFERENCE` 로, 바로 아래 「종류별로 읽기」는 「검증 기록」·「동작 원리」·
「적용 기준」·「열린 질문」으로 같은 넷을 불렀다. 독자는 둘이 같은 것이라는 단서를 어디서도
받지 못했다 — 이름을 바꾸기 전보다 나빠진 유일한 자리다. 목록도 공용 표에서 가져온다.
주제 허브의 「먼저 읽을 것」은 넷 다 열린 질문이었다. 서버가 주는 대표 값은 순서가 아니라
통 두 개(대표 Case · 열린 질문)이고 앞쪽이 비어 있어서, 아직 답이 없는 질문만 모아 놓고
「먼저 읽을 것」이라 부르고 있었다. 그리고 그 넷이 바로 아래 목록에 그대로 다시 나왔다.
이제 기록에서 순서를 만든다 — 원리 → 확인한 기록 → 기준 → 아직 모르는 것 — 그리고 위에
오른 편은 아래에서 뺀다.
개념은 목록 매퍼에서 통째로 버려지고 있었다. 서버는 보내고 필터에는 「동작 원리」가 있는데
결과가 0건이라, 독자에게는 기록이 없는 것으로 보였다. 손으로 나열한 종류 목록에 개념을
빠뜨리는 일이 이 저장소에서 반복됐고, 이번에는 계약에서 종류를 읽어 대조하는 가드를 둔다.
그 밖에: 질문 줄의 맥락이 「· 프로젝트」로 시작하던 것(계약에 주제가 없었다), 릴리스가
주 내비에서만 빠지고 홈 목록에는 남아 있던 것, 홈 목록이 화면의 절반을 차지하던 것,
값이 없는 「현재 목표」·「다음 작업」이 빈 칸으로 남던 것, 종류 배지 넷이 시각적으로 같던 것.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
주제 없이 게시된 기록이 있는데, 화면이 그것을 모르고 `/topics/` 로 가는 이름 없는 링크를
만들고 있었다 — 문서 머리말의 breadcrumb 과 탐색의 「주제 없음」 묶음 둘 다. 프로젝트
조각은 처음부터 조건부였는데 주제 쪽만 아니었다.
관계 목록의 제목도 기본값으로 옮긴다. 부르는 쪽마다 적게 했더니 다섯 자리 중 둘만
고쳐졌고, 같은 목록이 화면에 따라 두 이름으로 나왔다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
필터가 종류를 손으로 나열하고 있어 개념이 통째로 빠져 있었다 — 개념 작업본은 만들 수는
있는데 걸러 볼 수가 없었다. 이름도 영문(`Case`, `Question`)이라 같은 화면 안의 배지와
어긋났고, 같은 문서가 한 화면에서 두 이름으로 보였다.
`Record<RecordKind, …>` 에서 뽑아 종류가 늘면 컴파일러가 빈 자리를 잡게 한다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
vite 설정이 화면 파일 → chunk 이름 표를 손으로 들고 있다. 주제 편집 화면을 더하고 이
표를 빠뜨렸더니 번들은 만들어지는데 빌드 매니페스트 단계에서 「Missing built route
chunk」로 멈췄다 — 다섯 개의 검사를 다 통과한 뒤 배포 직전에야 드러난다는 뜻이다.
이 표도 손으로 나열한 목록 중 하나이므로 다섯 검사 안에서 대조한다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
유형별 칸 목록이 삼항 사슬이라 개념이 어디에도 없었다. 그래서 개념 작업본은 「알 수 없는
종류」로 거절되고 그 문서의 모든 칸이 「허용되지 않은 속성」이 됐다 — 모의 구성으로
개념을 편집하면 아무것도 저장되지 않았다는 뜻이다.
`Record<종류, …>` 로 두어 종류가 늘면 컴파일러가 빈 자리를 잡게 한다. `variantIds` 는
계약에서 `required` 가 아니므로 허용하되 요구하지는 않는다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
문서 머리말의 주제 링크는 탐색 필터(`/explore?topic=…`)를 가리키고 있었다. 주제 화면이
주제 셋만 열어 두어 나머지가 404 였기 때문에 우회한 것인데, 그 하드코딩이 없어졌으므로
이제 곧장 주제 화면으로 간다.
축의 주소도 실제로 있는 자리로 맞춘다. `/topics/{주제}/{축}` 이라 적어 두었는데 그런
화면이 없다 — 축은 주제 화면 안의 한 줄이므로 그 줄에 앵커를 달고 그것을 가리킨다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
숫자 셋(기록 12 · 결정 4 · 활동 9)은 이 프로젝트가 얼마나 큰지는 말해도 어디서부터
읽어야 하는지는 말하지 않는다. 세는 자리를 처음 몇 편으로 바꾸고, 숫자는 각 목록으로
가는 줄에 남긴다.
「주요 주제」는 글자 목록이었다. 매퍼가 이름만 남기고 slug 를 버려서 그 주제로 갈 수가
없었는데, 계약은 처음부터 둘 다 주고 있었다.
논지 자리의 제목도 고친다 — 「프로젝트가 지키는 기준」이 아니라 이 프로젝트가 밝힌
것이고, 여러 문단으로 쓸 수 있으므로 산문으로 그린다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
홈은 「무엇을 만들었나」로 시작했다. 30초 안에 알아야 할 것은 무엇을 견줬고 무엇이
남았나인데, 그 답은 주제 화면까지 들어가야 있었다. 가장 많이 다룬 주제 하나를 앞에
세우고 축마다 무엇을 알게 됐는지를 나란히 둔다 — 요약을 쓰면 무엇인가만 말하고 무엇을
알게 됐는지는 말하지 않으므로 결론 칸을 읽는다.
종류별 입구에는 개념이 아예 없었고, 문서 머리말의 종류 링크는 삼항의 마지막 else 를 타
개념 문서에서 `/projects` 로 갔다. `/explore/concepts` 는 처음부터 열려 있었는데 그리로
가는 길이 세 화면 어디에도 없었다. 대응을 표 하나로 모은다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
기록↔축 연결을 저장할 경로가 없었다. `record_variant` 는 공개 조회가 읽기만 할 뿐
아무도 쓰지 않았고, 계약의 `variantIds` 도 어디에도 닿지 않았다. 관계와 같은 「통째
교체」 방식으로 세 저장소(문서·질문·결정)에 배선한다 — 클라이언트가 보낸 배열이 곧 최종
상태이고, diff 를 뜨면 순서 재배열과 삭제를 구분하지 못한다.
문서 편집기에서 고른 주제의 축을 체크박스로 고른다. 축은 주제 안에서만 뜻이 있으므로
카탈로그에 섞지 않고 따로 읽는다. 아무 축에도 걸지 않아도 되고, 그 경우 이 기록은 그
주제의 공통 기록이 된다 — 빈 줄이 곧 「공통」이라 따로 표시하지 않는다.
탐색은 `type=CONCEPT` 을 조용히 버리고 있었다. 필터 폼은 개념을 고를 수 있게 하는데
화면 쪽 목록에는 개념이 없어서, 고르면 주소만 바뀌고 아무것도 걸리지 않았다. 목록을
손으로 적지 않고 `Record<RecordKind, …>` 에서 뽑아 컴파일러가 잡게 한다.
그리고 탐색을 주제로 묶는다. 게시 순서 한 줄로는 무엇이 있는지는 보여도 무엇에 대한
것들인지가 보이지 않아, 스무 편이 넘어가면 목록이 아니라 더미가 된다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
「주제·프로젝트」 화면은 주제를 만들고 지울 수만 있었다. 이름과 slug 말고는 쓸 자리가
없어, 주제가 답하는 질문(논지)도 축의 이름도 어디에도 적을 수 없었다 — 공개 주제
화면이 그 둘을 읽는데 쓸 곳이 없으니 늘 비어 있었다.
주제 편집 화면을 프로젝트 편집기와 같은 자리·같은 클래스로 둔다. 축(variant)은 주제
안의 접근/구조 하나다. 인증 경계라면 SPA·BFF·Mediator 가 각각 하나고, 각자 만들어 보고
무엇을 알게 됐는지가 다르다. 비교표가 읽는 것은 요약이 아니라 그 결론이라, 두 칸을
따로 둔다 — 기록의 요약 첫 줄을 잘라 쓰면 안 되는 자리다.
프로젝트에도 논지 칸을 둔다. 목적은 시작할 때 쓰는 글이고 논지는 끝나고 쓰는 글이다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
주제 화면은 주제 셋(`jpa`, `authentication`, `redis`)을 코드에 적어 두고 그 셋만
열었다. 제목과 설명까지 코드에 있었고, 목록에 없는 주제는 기록이 멀쩡히 있어도 404 로
갔다 — 픽스처의 `kubernetes` 가 그랬다. 계약에는 처음부터 `/topics/{slug}` 가 있었지만
아무도 부르지 않았다. 이제 그 연산을 부르고, 주제가 답하는 질문(논지)과 그 질문에 대해
실제로 만들어 본 답들(축)을 화면의 뼈대로 둔다.
프로젝트의 논지도 마찬가지다. 담을 칸이 없어 목적(`purpose`)을 대신 보여 주고
있었는데, 목적은 시작할 때 쓰는 글이라 화면에는 늘 시작할 때의 말만 남았다.
축 CRUD 네 연산은 계약에 있으면서 기여 목록에 없었다 — 등록되지 않은 연산은 타입에는
멀쩡히 보이는데 부를 수가 없다. `getPublicConcept` 과 `deleteConceptDraft` 가 정확히
그래서 못 불렸고, 개념 삭제가 질문 삭제를 불러 "질문을 찾을 수 없습니다" 가 떴다.
그래서 가드를 둘 넣는다. 공개 계약은 전수 대조하고(봉투 없이 바이트를 주는 `/media` 만
면제), 관리 계약은 **한 종류만 빠진 자리**를 본다 — 깨진 것이 늘 그 모양이었다.
개념 삭제 등록을 지워 보고 실제로 멈추는 것을 확인했다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
관계 한 줄에 세 가지가 뭉쳐 있었다. 대상이 어떤 종류인지, 작성자가 왜 걸었는지,
대상이 무엇인지 — 셋 다 `reason` 한 칸을 지나느라 경로마다 다른 것이 같은 자리에
나왔다. 렌더 모델 경로에서는 작성자의 문장이 묶음 이름 자리에 눌려 한 줄짜리 라벨인
척했고, 공개 조회 경로에서는 묶음 이름이 그 자리를 차지하고 작성자의 문장은 아예
버려졌다. 「다음에 무엇을 읽을지」의 답이 그 문장인데 공개 화면에 한 번도 나오지 않았다.
이제 셋이 각자의 칸을 갖는다. `label` 은 대상의 종류, `note` 는 작성자가 쓴 문장,
`summary` 는 대상의 요약이다. 설명 자리에는 문장이 있으면 문장을, 없으면 요약을
보인다 — 요약은 대상을 설명하고 문장은 왜 지금 이것을 읽어야 하는지를 설명한다.
공개 주소로 종류를 되짚던 삼항 사슬도 표로 바꾼다. `/concepts/` 가 어디에도 없어서
개념으로 가는 관계가 전부 `PROJECT` 로 떨어지고 있었다 — 손으로 나열한 목록에 새
종류를 빠뜨리는 일이 이 저장소에서만 다섯 번째다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
앞선 커밋의 「직접 해보니 · 다음에 쓸 기준」 은 기술 기록의 톤에 비해
가벼웠다. 역할은 그대로 말하되 문어체로 세운다:
CASE → 검증 기록 CONCEPT → 동작 원리
REFERENCE → 적용 기준 DECISION → 설계 결정
QUESTION → 열린 질문
계약의 kind 는 그대로 둔다. 바꾸는 것은 화면에 보이는 이름뿐이다 —
CASE 와 CONCEPT 는 데이터 모델에서 서로 다른 것을 뜻하고 독자가 얻는
것도 다르므로, 다섯을 셋으로 합치지 않는다. 상태 셋(확인됨·정리됨·미해결)은
색을 다섯 칠하지 않기 위한 시각 계층으로만 쓴다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
이 저장소의 종류 이름은 글을 담아 둔 방식의 이름이었다 — Case, Reference,
Open Question. 독자는 그 말을 배우고 나서야 목록을 읽을 수 있었고, 정작
뜻풀이는 홈 바닥(2,000px 아래)에 있었다. 이름이 하는 일을 말하게 한다:
Case → 직접 해보니 Reference → 다음에 쓸 기준
Question → 아직 모르는 것 Concept → 어떻게 동작하나
Decision → 이렇게 하기로
이름이 스스로 설명하므로 홈 바닥의 뜻풀이 섹션은 종류별 입구로 바꾼다.
그 목록에 손으로 적어 둔 `OpenQuestion` 은 사이트 어디에도 없는 여섯 번째
표기였다. 탐색 필터·Case/개념 breadcrumb·종류별 화면 제목도 각자 이름을
적고 있었다 — 전부 공용 표를 쓰게 한다.
목록의 종류 표시는 다섯이 같은 회색 11px 이라 스캔되지 않았다. 색을 다섯
칠하는 대신 지식의 상태 셋(확인함·정리함·미해결)으로 가르고 미해결만
강조한다. 이 기록에서 가장 정직한 신호인데 가장 안 보였다.
mono 글꼴과 대문자 변환도 걷어낸다 — 이름이 한국어 문구가 되었고, mono 는
한글을 갖지 않아 낱말 사이만 벌어진다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
「지금 집중하는 것」은 프로젝트·질문·결정 셋을 각각 고르는 구조였고, 고르는
목록이 전체였다. 그래서 프로젝트만 바꾸면 질문·결정은 이전 프로젝트 것이
그대로 남았다 — 홈에 프로젝트는 Liner 인데 결정은 Keycloak 것이 나왔다.
프로젝트를 고르면 그 프로젝트의 질문·결정만 목록에 온다. 질문은 항목이
`primaryProject` 를 들고 오므로 그것으로 거르고(계약의 ProjectSummary 에는
id 가 없어 공개 경로에서 뽑은 slug 로 맞춘다), 결정은 경로 자체가 프로젝트를
요구하므로 고른 프로젝트의 것만 온다. 프로젝트를 바꾸면 이전 선택은 함께
비운다 — 남겨 두면 같은 어긋남이 다시 난다.
listStudioQuestions·listStudioProjectDecisions 는 계약에 있었지만 기여 목록에
등록되지 않아 부를 수 없었다. 오늘 같은 누락을 세 번째 만난다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
개념 화면에 `relatedRecords` 가 한글 라벨 없이 나왔다. 앞선 커밋에서 개념
라벨 표를 다른 유형에서 유추해 네 키(supportingCases 등)를 적었는데 계약이
주는 이름은 `relatedRecords` 하나였다 — 하나도 맞지 않았다.
같은 실수를 Reference 에서도 했다(`originCases` 라고 적혀 있었다). 세 번째라
표를 계약에 묶는다: 계약 문서에서 관계 이름을 읽어, 라벨이 없는 이름과
계약에 없는 이름을 양쪽으로 잡는다. `primaryProject` 는 관계가 아니라
소속이므로 제외한다 — 머리말이 이미 보여 준다.
개념은 관계를 한 묶음으로 받으므로 그 묶음만 명시적으로 골라 넘긴다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
`/concepts/idp-brokering` 이 「페이지를 찾을 수 없습니다」였다. API 도
라우트도 200 인데 화면만 404 였고, 콘솔을 보니 개념 화면이
`/api/v1/public/questions/idp-brokering` 을 부르고 있었다.
세 가지가 겹쳤다. 계약 타입에는 getPublicConcept 이 있었지만 기여 목록에
등록되지 않아 부를 수 없었다. 게이트웨이는 종류를 삼항으로 이어 붙여
마지막 else 가 남은 것을 다 질문 조회로 보냈다. 응답을 기록으로 바꾸는
분기에도 개념이 없어, 설령 불렸어도 질문 매핑으로 떨어졌을 것이다.
개념 삭제에서 겪은 것과 같은 모양이다 — 손으로 나열한 분기의 마지막
else 가 새 종류를 조용히 삼킨다. 표로 두어 종류가 늘면 타입이 잡게 하고,
네 종류가 각각 자기 주소로 나가는지 확인하는 가드를 둔다.
개념 본문은 Case 와 같은 규칙을 쓴다(Markdown 한 덩어리 + `:::evidence`).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
라벨은 고쳤는데 요약이 여전히 비어 있었다. 값이 경계 세 곳을 지나며 사라진다:
평탄화가 담고(고침), 렌더 모델로 바꿀 때 버리고, 화면 목록으로 넘길 때 또
버렸다. 렌더 모델 계약(ResolvedRelation)에 담을 자리 자체가 없었고
additionalProperties: false 라 실을 수도 없었다.
계약에 summary 를 더하고(required 아님 — 이미 나가 있는 응답을 깨지 않는다)
세 경계를 모두 잇는다. Studio 미리보기도 같은 렌더 모델을 쓰므로 그쪽에서도
같은 요약이 보인다.
가드는 요약이 화면에 그려지는 것과, 그것이 링크 이름에는 들어가지 않는 것을
함께 본다 — 이름에 들어가면 관계 목록을 훑을 때 링크 하나가 문단이 된다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
Reference 화면에 `supportingCases` 가 한글 라벨 없이 네 번 반복해서 나왔다.
라벨 표의 키가 계약이 실제로 주는 이름과 어긋나 있었기 때문이다 —
`originCases`·`projectDecisions` 로 적혀 있었고 계약은 `supportingCases`·
`relatedDecisions` 를 준다. 표에 없는 키는 그대로 화면에 나온다.
Question 은 같은 결함을 이미 겪고 고친 자리다(주석에 남아 있다). 이번에는
표를 상수로 빼서 계약이 주는 이름 전부가 등록됐는지 확인할 수 있게 한다.
계약은 관계마다 요약도 함께 주는데 평탄화가 그것을 버렸다. 독자가 목록에서
보는 것이 제목뿐이라, 왜 이 기록이 걸려 있는지는 눌러 봐야 알 수 있었다.
요약을 흘려보내 제목 아래 두 줄로 보여 준다.
요약은 링크의 이름에서 뺀다 — 이름에 들어가면 관계 목록을 훑을 때 링크
하나하나가 문단이 되어 목록으로서 쓸모가 없어진다.
`cardSummary` 를 domain 으로 옮긴다. 어댑터가 presentation 을 import 하는
것을 아키텍처 규칙이 막았고, 그 지적이 옳다 — 이 함수는 화면이 아니라
글을 다루는 규칙이다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
앞선 커밋은 게이트웨이를 고치지 못했다. 편집 스크립트가 중간에서 실패했는데
그 뒤 단계만 다시 돌리고 이 파일은 손대지 않은 채 넘어갔다. 배포된 번들에
옛 삼항이 그대로 남아 서버 로그에
`DELETE /api/v1/studio/questions/{id} 404` 가 계속 찍혔다.
타입 검사가 잡지 못한 이유는 메서드 매개변수가 TypeScript 에서 bivariant
이기 때문이다 — 구현이 종류를 `"CASE" | "REFERENCE" | "QUESTION"` 으로
좁게 적어도 넓은 포트 시그니처를 만족한 것으로 통과한다. 그래서 "타입
통과"를 보고 반영됐다고 판단한 것이 틀렸다.
계약에 주소가 있는지만 보던 가드도 이것을 놓쳤다. 게이트웨이를 실제로 불러
어떤 연산이 실행되는지 확인하는 가드를 더한다 — CONCEPT 을 deleteQuestion
으로 되돌리면 깨지는 것을 확인했다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
개념을 지우려 하면 「질문을 찾을 수 없습니다」가 났다. 세 가지가 겹쳤다.
게이트웨이가 종류를 삼항으로 이어 붙여, 마지막 else 가 모르는 종류를 다
받아 갔다 — 개념이 deleteQuestion 으로 떨어졌다. 화면은 종류를
`as "CASE" | "REFERENCE" | "QUESTION"` 으로 좁혀 넘겼으므로 타입도 잡지
못했다. 포트의 종류 목록도 손으로 나열해 셋에 머물러 있었다.
삼항을 Record<DeletableDocumentKind, string> 표로 바꾼다 — 종류가 늘면
빠진 자리를 타입이 잡는다. 캐스팅을 걷어내고, 계약 기여 목록에
deleteConceptDraft 를 등록한다. 이 목록에 빠뜨리면 요청이 조용히 다른
주소로 나가므로(어제 페이지 인자가 그랬다) 네 종류가 각각 자기 주소로
나가는지 확인하는 가드를 함께 둔다 — 등록을 지우면 깨지는 것을 확인했다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
앞선 변경은 `.studio-app` 규칙만 고쳤다. 게시 기록·게시 흐름·워크플로
게이트는 CSS module 을 쓰므로 그 규칙이 닿지 않아, 다른 화면에서 상자를
걷어낸 뒤에도 「Snapshot 보기」·「게시 취소」·「적용」만 테두리와 파란 채움으로
남아 있었다. 한 화면 안에서 두 언어가 섞여 더 눈에 띄었다.
같은 규칙을 적용한다 — 상자도 선도 없이 글자의 굵기와 색으로만 격을 나누고,
반응은 hover 밑줄로만 나타난다. 입력 칸과 대화상자 테두리는 그대로 둔다:
그쪽은 누르는 것이 아니라 담는 것이라 경계가 필요하다.
로그인 게이트(`auth-gate`)의 채운 버튼은 남긴다. 그 화면의 유일한 행동이고,
폭을 채워 어디를 눌러야 하는지 묻지 않게 한다는 판단이 이미 기록돼 있다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
버튼이 이 사이트의 언어와 달랐다. 무채색 바탕에 타이포로만 말하는 화면에
테두리를 두른 둥근 상자와 파란 채움이 얹혀 있어서, 가장 먼저 눈에 드는
것이 목록이나 글이 아니라 버튼이었다. 페이지 이동을 `‹ 1 | 2 | 3 ›` 으로
바꾼 것과 같은 판단이다.
상자도 선도 두지 않는다. 격은 글자의 굵기와 색으로만 나눈다 — 주 동작은
진한 굵은 글자, 보조는 옅은 글자, 되돌릴 수 없는 것은 붉은 글자. 반응은
hover 에서만 밑줄로 나타난다. 누르는 자리는 44px 로 남긴다: 보이는 것이
글자뿐이어도 손가락이 닿는 범위는 좁히지 않는다.
파란 채움은 Studio 전체에서 사라진다 — 대화상자 확인, 라우트 상태 버튼,
편집기 저장·게시까지.
그리고 오늘 만든 회귀를 고친다. 프로젝트 결정 화면의 절은 `150px | 650px`
격자이고 제목이 첫 칸, 본문이 둘째 칸에 앉는다. ProseText 로 바꾸면서 문단이
여럿이 되자 둘째 문단부터 150px 칸으로 떨어져 글이 네댓 글자마다 끊겼다.
문단들을 한 칸에 묶는다. 다른 화면도 훑어 같은 사고가 없는 것을 확인했다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
카드는 본문 요약을 그대로 가져다 세 줄로 자른다. 그 요약은 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