Commit Graph
225 Commits
Author SHA1 Message Date
DongHyeonkaandClaude Opus 5 7bcbaefc47 fix: 홈 순서를 되돌리고 미리보기가 막힌 이유를 말한다
홈은 「지금 집중하는 것」이 비교표보다 위다. M8 을 따라 비교표를 첫 화면으로
올렸는데, 이 사이트의 첫 화면이 무엇이어야 하는지는 리뷰가 아니라 쓰는 사람이
정한다.

Public Preview 화면은 검증 기록이 없으면 만들기 버튼이 나타나지 않는데, 화면은
"현재 검증 결과를 기준으로 생성합니다" 라고만 적어 두었다 — 할 수 있는 일을
설명하면서 그 일을 할 자리는 주지 않았고, 왜 없는지도 말하지 않았다. 작성자에게는
미리보기가 고장난 것으로 보인다. 검증이 먼저라고 말한다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
2026-09-09 17:45:53 +09:00
DongHyeonkaandClaude Opus 5 b9e29369ee fix: UX 리뷰의 남은 항목을 반영한다
주제 탭 (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
2026-09-09 17:15:04 +09:00
DongHyeonkaandClaude Opus 5 0d4d1e5c0c feat: sitemap 을 공개 계약에 올린다
서버가 공개 프리픽스 아래에 내는 것은 전부 계약에 있어야 한다 —
PublicContractDriftTest 가 양방향으로 본다. 봉투를 쓰지 않는 자리는 media 가
선례이고, sitemap 도 같다: XML 이고 읽는 것은 브라우저가 아니라 크롤러다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
2026-09-09 15:46:32 +09:00
DongHyeonkaandClaude Opus 5 871e791cbc fix: robots.txt 가 실제로 있는 sitemap 주소를 가리킨다
경로 조각에 점을 쓸 수 없어(D19) /api/v1/public/sitemap 이다. 확장자는
sitemap 프로토콜이 요구하지 않는다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
2026-09-09 15:37:27 +09:00
DongHyeonkaandClaude Opus 5 bb6eba00db fix: UX 리뷰의 출시 차단 다섯 건을 고친다
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
2026-09-09 15:31:05 +09:00
DongHyeonkaandClaude Opus 5 28dce83398 docs: SETUP 종류 설계·계획을 구현 결과와 맞춘다
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
2026-09-09 14:39:32 +09:00
DongHyeonkaandClaude Opus 5 7cd11a7b35 fix: 관계와 카탈로그가 환경 구성을 가리킬 수 있게 한다
계약의 종류 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
2026-09-09 14:32:55 +09:00
DongHyeonkaandClaude Opus 5 3af9be9e09 feat: 환경 구성(SETUP) 기록 종류를 더한다
다섯 종류는 전부 끝난 일을 남긴다. 없는 것은 읽는 사람이 자기 손으로 다시
하려면 무엇부터 하는가다. 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
2026-09-09 14:12:44 +09:00
DongHyeonka 3374f286be fix: 라우트 제목의 초점 링을 실제로 없앤다
앞 커밋이 로그인 제목의 파란 사각형을 고쳤다고 적었지만 배포된 화면에는 그대로 있었다.
두 가지를 잘못 봤다.

- 이 저장소의 `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 인지를 브라우저에서
직접 재고 확인했다.
2026-09-07 10:11:16 +09:00
DongHyeonka 6b8530e04e fix: Studio 로그인 화면을 이 사이트의 언어로 세운다
작성자가 처음 만나는 화면인데 사이트가 쓰지 않는 말을 쓰고 있었다 — 테두리를 두른 둥근
카드, 파란 채움 버튼, 파란 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` 를 묻게 한다.
2026-09-07 10:05:12 +09:00
DongHyeonka 2b2f4430dd fix: 주제 탭을 아래 묶음에 붙인다
급을 칩으로 낮추고 나니 이번에는 목록 위에 글자만 떠 있는 것처럼 보였다. 두 가지 때문이다 —
고른 것이 색으로만 달라 누를 수 있는 것으로 읽히지 않았고, 탭 줄과 목록 사이가 선 없이
30px 비어 있어 두 덩어리로 갈렸다.

- 고른 탭에 형태를 준다(알약). 색만 바꾸면 「진한 글자와 연한 글자」로 읽힌다. 밑줄은 쓰지
  않는다 — 주제가 스무 개면 밑줄 설 자리 스무 개가 함께 늘어선다.
- 묶음의 윗선을 목록이 아니라 패널이 갖고, 탭 줄이 그 선에 바로 얹힌다. 선이 목록에 있으면
  축 이름 줄만 선 위로 밀려 나가 탭과 한 덩어리처럼 보이고 정작 목록은 저 혼자 시작한다.
- 알약의 좌우 여백만큼 줄을 당겨, 첫 탭의 글자가 아래 목록의 왼쪽 끝과 한 줄로 선다.

탭이 데이터를 따른다는 것도 검사로 박는다. 화면에는 주제 이름도 개수도 상한도 적혀 있지
않지만, 그 사실은 코드를 읽어야만 알 수 있었다 — 주제 화면이 주제 셋을 코드에 적어 두고
그 셋만 열던 때가 있었으므로 물어볼 만한 것이다.
2026-09-02 11:16:10 +09:00
DongHyeonka 3bb724b1d0 fix: 주제 탭을 칩 크기로 줄이고 개수 상한을 없앤다
탭을 구역 제목 급(30px/650)으로 세웠다. 주제가 둘일 때는 그럴듯했지만 열 개, 스무 개가
되면 이름만으로 화면이 덮인다 — 여기서 하려는 말은 「이것이 이 구역의 제목이다」가 아니라
「고를 것이 이만큼 있다」이므로 급도 그쪽이어야 한다. 지금 무엇을 읽는지는 목록 바로 위의
축 이름과 「전체 보기」 줄이 말한다.

고른 탭의 파란 밑줄도 없앤다. 주제가 스무 개면 밑줄이 설 자리 스무 개가 함께 늘어선다.
고르지 않은 것은 색만 죽인다.

개수 상한도 없앤다. 상한은 주제마다 상세를 미리 받느라 둔 것이었는데, 그러면 상한 밖의
주제는 다시 「다른 주제 N개 보기」로 밀린다 — 이 구역이 없애려던 문제로 되돌아간다.
탭은 목록이 주는 전부이고, 상세는 고른 것만 그때 받는다. 요청은 목록 하나 + 처음 열린
주제 하나로 고정되고, 주제가 늘어도 그대로다.

받지 못한 주제는 그 자리에 남긴다. 홈이 두 읽기를 `Promise.all` 로 묶었을 때는 하나가
실패하면 나머지까지 통째로 사라져 흔적이 없었다.
2026-09-02 11:07:42 +09:00
DongHyeonka de4cb8b30b feat: 홈이 주제를 탭으로 나란히 세운다
홈은 주제 하나만 펴 두고 나머지는 비교 목록 밑 「다른 주제 N개 보기」 한 줄로 보냈다.
그 줄은 목록을 다 읽고 나서야 만나는 자리라 대개 지나쳤고, 그래서 JPA 주제는 홈에
있으면서도 없는 것과 같았다.

구역 제목이 서 있던 자리(「구조별로 알게 된 것」)를 주제 이름 탭이 대신한다. 무엇이 더
있는지가 목록을 읽기 전에 먼저 보이고, 탭을 고르면 그 주제의 축이 그대로 열린다 —
인증 경계면 SPA·Mediator·BFF·Forward-Auth, JPA면 그 주제의 조회 전략들이다.

- 축의 이름은 목록 바로 위로 내렸다. 제목 자리를 탭이 가져갔으니 「이 넷은 구조다」는
  목록에 붙어 있어야 짝이 보인다.
- 패널은 전부 그려 두고 감춘다. 상세는 이미 받아 온 것이라 탭을 눌러도 요청이 나가지
  않고, 페이지 내 검색이 감춘 주제까지 찾는다.
- 탭이 되는 주제 수에 상한을 둔다. 주제마다 상세 요청이 하나씩 나가므로, 주제가 늘어도
  홈의 요청 수는 정해져 있다.
- 「다른 주제」 줄은 축이 없어 탭이 되지 못한 주제만 받는다.

탭은 h2 가 아니지만 구역 제목의 자리를 물려받았으므로 `section-heading-rank` 가 그 급을
정본과 함께 묶는다.
2026-09-02 10:59:14 +09:00
DongHyeonka fe6b56a96c fix: 열리지 않는 주소를 링크로 그리지 않는다
「다음에 읽을 것」에 걸린 결정 링크가 404 였다. 주소는 서버가 게시할 때 만들어 저장한
문자열이라 화면 코드 어디에도 흔적이 없었고, 방문자만 그것을 만났다.

- `resolvesToPublicRoute` 가 route contract 에서 읽은 라우트 표에 주소를 맞춰 본다. 맞는
  라우트가 없는 줄은 관계 목록이 링크로 그리지 않는다.
- 결정 목록의 각 항목이 `slug` 를 element id 로 단다 — 결정의 공개 주소가 이 목록 위의
  앵커이므로, id(UUID)를 달면 다른 기록이 건 링크가 갈 곳을 잃는다.
- 앵커로 들어오면 그 결정까지 내려간다. 목록은 받아온 뒤에 그려지므로 브라우저의 기본
  앵커 이동만으로는 닿지 않는다.

주제 화면 셋을 더하면서 함께 늘려야 했던 것들도 여기서 맞춘다 — nginx 로 나가는 경로
패턴, 라우트마다 하나씩인 수동 접근성 증거, 그리고 그 둘을 세는 CI 게이트 기준값.
게이트 형상 digest 는 이전 gates.json 에서 옛 값(87a22f68…)을 먼저 재현한 뒤 새로 계산했다.
2026-09-02 09:54:51 +09:00
DongHyeonkaandClaude Opus 5 eedc90b674 fix: 프로필과 프로젝트의 문구를 사용자가 쓴 말로 바꾼다
「결론이 서는 조건」·「자리」·「프로젝트를 답니다」·「결정 순서로 읽는다」·「접근을 나눠
견주고」가 모두 번역투이거나 이 기록에서 쓰지 않는 말이었다. 사용자가 직접 적어 준 세 항목을
그대로 싣는다.

프로젝트 화면의 「이 프로젝트가 밝힌 것」은 「프로젝트를 통해 확인한 결과」로, 소개 문구의
「운영 가능한 설계로 연결합니다」는 「실제 운영에 적용할 수 있는 형태로 정리합니다」로 바꾼다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-02 08:48:26 +09:00
DongHyeonkaandClaude Opus 5 094e75519b fix: 편집기가 프로젝트 slug 를 목록 행에서 직접 읽는다
`publication.canonicalPath` 에서 뽑고 있었는데 그 칸은 서버가 한 번도 채우지 않아 늘 비어
있었다. 그래서 어떤 프로젝트를 골라도 다른 프로젝트의 질문까지 목록에 남았다 — KeyCloak 을
고르면 Liner 의 질문 다섯 건이 함께 나왔다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-02 01:47:16 +09:00
DongHyeonkaandClaude Opus 5 6e784eded4 fix: 편집기의 결정 목록을 살리고, 프로필 원칙을 이 기록의 말로 고친다
결정 조회가 500 이었다. `project_decision.consequences` 를 문자열 배열로 알고 읽었는데
실제로는 `{id, text, order}` 객체의 배열이다 — 작업본 저장 경로가 그렇게 쓰고, 그것을 읽는
`StudioJson.orderedTextFromJson` 이 이미 있었는데 보지 않고 새로 썼다.

그리고 한 칸의 실패가 옆 칸을 끌고 내려갔다. 편집기가 질문과 결정을 `Promise.all` 로 묶어
읽어서, 결정만 터지는데 멀쩡히 오던 질문 목록까지 「불러오지 못했습니다」가 됐다. 둘을
따로 읽는다.

프로젝트를 가려내는 slug 는 `publication.canonicalPath` 에서 나오는데 그 값은 게시된 적이
있어야 채워진다. 게시 전 프로젝트에서는 거르지 않는다 — 잘못 거르면 있는 질문이 사라져
보인다.

프로필의 원칙 세 줄은 「섞지 않습니다」·「함께 기록합니다」·「흩어지지 않게」처럼 무엇을
하는지 말하지 않는 동사로 끝나 있었다. 이 기록의 다른 글은 그렇게 쓰지 않는다 — Case 의
소제목은 「이 구조에서 감수한 것」처럼 무엇인지를 명사로 짚는다. 제목을 그 명사형으로,
설명을 이 사이트가 실제로 하는 일로 바꾼다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-02 01:26:59 +09:00
DongHyeonkaandClaude Opus 5 aca4f189d1 feat: 주제 목록 화면을 만들어 주 내비에 넣는다
주제로 가는 길이 기록의 breadcrumb 과 탐색의 묶음 제목뿐이었다. 주제가 이 기록의 뼈대인데
그 목록을 정면으로 보여 주는 자리가 없었고, 홈이 한 주제만 펼치던 동안 나머지는 최근
기록에 우연히 걸릴 때만 보였다.

목록의 각 줄은 이름·논지·축·기록 수를 싣는다. 이름은 무엇에 대한 것인지만 말하므로,
들어갈지 말지를 정하려면 그 주제가 무엇에 답하는지가 함께 있어야 한다. 그래서 계약의
`TopicListItem` 에 논지와 축을 더한다 — 그동안 이름과 개수뿐이었다.

홈의 「다른 주제」 줄은 목록으로 가는 한 줄로 줄인다. 주제가 늘면 옆으로 길어지던 자리다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-02 00:43:58 +09:00
DongHyeonkaandClaude Opus 5 69eabc7d6c fix: 축 화면에서 결론을 빼고, 홈에서 다른 주제로 갈 길을 낸다
축 화면이 요약과 결론을 함께 실었다. 이 화면이 답하는 것은 「이 접근이 무엇이고 그 기록이
어디 있나」이고, 무엇을 알게 됐는지는 주제 화면의 비교표가 네 축을 나란히 놓고 답한다 —
같은 문장을 두 자리에 두면 비교표를 볼 이유가 없어진다.

홈의 비교 구역은 기록이 가장 많은 주제 하나만 펼친다. 그래서 나머지 주제는 최근 기록에
우연히 걸릴 때만 보였고, 그 주제가 무엇을 견줬는지는 홈 어디에서도 닿을 수 없었다 —
JPA 주제가 실제로 그랬다. 「다른 주제」 한 줄을 둔다. 펼치지는 않는다; 견주는 자리는 한
번에 하나여야 읽힌다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-02 00:34:47 +09:00
DongHyeonkaandClaude Opus 5 a71c588d01 fix: 축 화면의 머리말을 문서 화면과 같은 것으로 맞춘다
머리말을 자기 것으로 새로 만들었더니 규칙을 하나도 못 받았다. breadcrumb 이 flex 도 gap 도
없어 「탐색/OAuth/OIDC 인증 경계」로 붙어 버렸고 — 주제 이름 안에도 슬래시가 있어 한
덩어리로 읽혔다 — 그 아래 kicker 가 끼어 있었다.

문서 머리말(`public-document-header`)을 그대로 쓴다. breadcrumb 은 「주제 / 축 이름」이고,
요약은 다른 문서와 같은 자리·같은 크기에 온다.

결론은 각주(12px)로 흘리고 있었다. 이 문장이 이 축의 값어치이므로 자기 블록을 준다 —
Case 가 결론을 스냅샷에 두는 것과 같은 시각 언어이되 한 단이다. `.document-snapshot` 은 두
칸 격자라 한 칸만 넣으면 글이 화면 반쪽에 갇힌다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 21:27:04 +09:00
DongHyeonkaandClaude Opus 5 68538f2e17 fix: 구역 제목의 급이 갈리던 것을 정본에 맞춘다
「구조별로 알게 된 것」만 26px·굵기 400 으로 나왔다. 형제 구역(「먼저 읽을 것」·「이 주제를
다룬 프로젝트」)은 30px·650 이라, 같은 화면에서 이 구역만 급이 낮아 디자인이 빠진 것처럼
보였다.

규칙이 없었던 게 아니라 절반만 있었다. 정본은 `.section-heading-row h2` 인데 그 안에
들어가지 않는 두 구역이 크기만 각자 적어 두어 굵기를 아무도 정하지 않았고, 그래서 기본값
400 으로 떨어졌다. 값을 정본과 맞추고, 나란히 서는 제목들이 다시 갈라지면 멈추는 검사를
둔다 — 굵기를 빼 보고 실제로 멈추는 것을 확인했다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 21:19:47 +09:00
DongHyeonkaandClaude Opus 5 67a549173d feat: 축에 자기 화면을 준다
주제 화면의 네 줄(SPA·Mediator·BFF·Forward-Auth)은 링크인데 눌러도 아무 일이 없었다.
축의 주소를 주제 화면 안의 앵커로 잡아 두어서, 정작 주제 화면에서는 그 링크가 자기 자신을
가리켰다 — 주소만 바뀌고 화면은 그대로였다.

축에 화면을 준다. 결론을 먼저 두고 그 아래 그 축에 걸린 기록만 모은다. 목록 조회에
`variant` 필터를 더해 `record_variant` 로 거른다 — 축 slug 는 주제 안에서만 유일하므로
주제까지 함께 맞춘다.

정적 어댑터는 축으로 거르면 빈 목록을 준다. 축은 사람이 Studio 에서 거는 값이라 픽스처가
지어낼 수 없고, 없는 것을 있는 척하면 이 어댑터로 그린 화면이 서버로 바꿨을 때 달라진다.

`RecordFilters` 가 포트와 정적 어댑터에 따로 있어, 포트에 필터가 늘어도 이쪽은 모르는
상태가 됐다 — 메서드 매개변수가 bivariant 라 `satisfies` 가 잡지 못한다. 하나로 합친다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 20:36:53 +09:00
DongHyeonkaandClaude Opus 5 344dadb17a fix: 구역 규칙이 제목까지 잡던 것을 행에만 건다
`.home-comparison a { display: grid; grid-template-columns: 200px … }` 는 비교 행을 위한
규칙인데 선택자가 구역 전체라 제목 안의 링크까지 잡았다. 제목이 200px 칸에 갇혀 두 줄로
접히고 행용 padding 까지 물려 h2 높이가 199px 이 됐다 — 디자인이 빠진 것처럼 보였지만
규칙이 샌 것이었다. 같은 이유로 주제 화면의 안내 문단도 행의 크기·색으로 덮여 있었다.

CSS 로 막는 것은 임시방편이라 구조도 바꾼다. 제목 안에 링크를 두지 않고, 주제로 가는 길은
아래 한 줄이 맡는다 — 최근 기록이 이미 쓰는 배치다. em-dash 로 두 가지 일을 한 줄에
욱여넣을 이유도 함께 없어진다.

제목의 말도 고친다. 「무엇을 견줬나」는 의문형 꼬리가 붙었고 「견주다」는 이 기록의 다른
문장에 쓰지 않는 낱말이다. 작성자가 Case 의 소제목에 쓰는 말은 「이 구조에서 감수한 것」
처럼 「~한 것」 명사형이라 그쪽에 맞춘다. 주제 화면도 같은 이름을 쓴다 — 같은 네 줄을 두
화면이 다른 이름으로 부르고 있었다.

같은 모양이 다른 구역 아홉 곳에도 있었다. 배치를 거는 규칙은 그 배치를 쓰는 요소까지
좁혀 적도록 51개를 고치고, 그 습관을 지키는 검사를 둔다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 20:24:15 +09:00
DongHyeonkaandClaude Opus 5 46e4e815a1 test: 편집기가 부르는 두 목록이 사라지면 먼저 멈추게 한다
계약에 있고 프론트가 부르는데 서버에 없어서 404 가 났다. 서버 쪽에도 같은 가드를 뒀다
(`ContractRouteCoverageTest`) — 양쪽에서 봐야 한쪽만 지웠을 때 잡힌다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 20:02:09 +09:00
DongHyeonkaandClaude Opus 5 7acde27f2e fix: Studio 가 못 읽은 것을 없는 것으로 그리지 않게 한다
홈 「지금 집중하는 것」 편집기는 열린 질문과 결정을 못 읽으면 빈 배열로 삼키고 「이
프로젝트에 열린 질문이 없습니다」라고 적었다. 실제로는 넷이 있었고 공개 사이트에도
나오고 있었다 — 작성자에게는 자기가 아직 쓰지 않은 것으로 보였다. 거짓말을 하느니 못
읽었다고 말한다.

작업본 인트로가 「Case, Reference, Question, Decision」이었다. 바로 아래 필터는 새
이름이라 한 화면에 두 벌이 있었다. 공개 프로젝트·프로필 문구도 같이 고친다.

관계 대상 select 를 종류별로 묶는다. 평면 목록은 문서가 늘수록 나빠지는데 25개에서
49개가 됐다 — 종류는 카탈로그가 이미 알려 주고 있었고 화면만 버리고 있었다. 이유 칸은
이제 공개 화면에 그대로 나가므로 한 줄 input 에서 여러 줄로 바꾼다.

본문에 코드·표·목록을 넣는 도구를 둔다. 주제 화면에 비교표를 두자고 정해 놓고도 그
표를 작성할 수단이 문법을 외우는 것뿐이었다.

인라인 코드 스타일이 세 컨테이너에 따로 있어 어디에도 속하지 않는 자리 — 문서 머리말의
요약 — 에서는 코드가 본문과 같은 민무늬로 나왔다. 그 칸에 이름을 준다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 19:59:42 +09:00
DongHyeonkaandClaude Opus 5 ffdeaa1e83 fix: 홈의 종류 배지도 목록과 같은 배지로 만든다
최근 기록의 종류 자리만 따로 굵은 검정으로 칠해 두어, 배지에 상태 구분(확인한 것·정리한
것·아직 모르는 것)이 생긴 뒤에도 홈에서는 넷이 똑같이 보였다. 같은 `.record-kind` 를 쓰게
하고 그 자리의 override 를 걷어낸다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 18:43:43 +09:00
DongHyeonkaandClaude Opus 5 db83228992 fix: 「먼저 읽을 것」을 종류마다 한 편으로 줄이고 나머지도 같은 순서로 둔다
종류마다 두 편씩 담았더니 일곱 줄이 되어, 순서가 아니라 또 하나의 목록이 됐다. 이 자리가
답하는 것은 무엇이 있나가 아니라 어디서부터 읽나다. 아래 나머지 목록도 같은 순서를
따른다 — 한 화면에서 순서가 두 번 바뀌면 순서로 읽히지 않는다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 18:40:08 +09:00
DongHyeonkaandClaude Opus 5 dc2fda7a5d fix: 종류 이름을 화면마다 하나로 맞추고, 읽는 순서를 기록에서 만든다
홈 한 화면에 종류 이름이 아홉 개 떠 있었다. 최근 기록 목록은 `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
2026-09-01 18:36:52 +09:00
DongHyeonkaandClaude Opus 5 88d841dc96 fix: 홈이 실제로 가장 많이 다룬 주제를 앞에 세운다
주석은 「가장 많이 다룬 주제를 고른다」인데 목록의 첫 항목을 쓰고 있었다. 순서는 서버가
정하므로, 기록 3편짜리 주제가 18편짜리를 제치고 홈에 올랐다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 17:55:30 +09:00
DongHyeonkaandClaude Opus 5 23efcf095c fix: 주제가 없는 기록이 죽은 링크를 달지 않게 한다
주제 없이 게시된 기록이 있는데, 화면이 그것을 모르고 `/topics/` 로 가는 이름 없는 링크를
만들고 있었다 — 문서 머리말의 breadcrumb 과 탐색의 「주제 없음」 묶음 둘 다. 프로젝트
조각은 처음부터 조건부였는데 주제 쪽만 아니었다.

관계 목록의 제목도 기본값으로 옮긴다. 부르는 쪽마다 적게 했더니 다섯 자리 중 둘만
고쳐졌고, 같은 목록이 화면에 따라 두 이름으로 나왔다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 17:46:56 +09:00
DongHyeonkaandClaude Opus 5 b89a54feb6 fix: 작업본 목록의 종류 필터에 개념을 넣고 이름을 맞춘다
필터가 종류를 손으로 나열하고 있어 개념이 통째로 빠져 있었다 — 개념 작업본은 만들 수는
있는데 걸러 볼 수가 없었다. 이름도 영문(`Case`, `Question`)이라 같은 화면 안의 배지와
어긋났고, 같은 문서가 한 화면에서 두 이름으로 보였다.

`Record<RecordKind, …>` 에서 뽑아 종류가 늘면 컴파일러가 빈 자리를 잡게 한다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 17:36:05 +09:00
DongHyeonkaandClaude Opus 5 3660404a12 fix: 관계 목록의 제목이 그 목록이 답하는 것을 말한다
「이 기록의 연결」은 무엇이 걸려 있는지를 말하고, 독자가 알고 싶은 것은 다음에 무엇을
읽는가다. 작성자가 관계마다 남긴 문장이 이제 그 아래 나오므로 제목도 그 문장이 답하는
질문에 맞춘다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 17:31:59 +09:00
DongHyeonkaandClaude Opus 5 197db749b9 fix: 새 화면의 chunk 이름을 표에 넣고, 빠뜨리면 먼저 멈추게 한다
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
2026-09-01 17:29:34 +09:00
DongHyeonkaandClaude Opus 5 77ef30420b fix: 모의 검증기가 개념을 아는 종류로 다룬다
유형별 칸 목록이 삼항 사슬이라 개념이 어디에도 없었다. 그래서 개념 작업본은 「알 수 없는
종류」로 거절되고 그 문서의 모든 칸이 「허용되지 않은 속성」이 됐다 — 모의 구성으로
개념을 편집하면 아무것도 저장되지 않았다는 뜻이다.

`Record<종류, …>` 로 두어 종류가 늘면 컴파일러가 빈 자리를 잡게 한다. `variantIds` 는
계약에서 `required` 가 아니므로 허용하되 요구하지는 않는다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 17:26:00 +09:00
DongHyeonkaandClaude Opus 5 882800568f fix: 주제로 가는 링크가 실제로 주제 화면에 닿게 한다
문서 머리말의 주제 링크는 탐색 필터(`/explore?topic=…`)를 가리키고 있었다. 주제 화면이
주제 셋만 열어 두어 나머지가 404 였기 때문에 우회한 것인데, 그 하드코딩이 없어졌으므로
이제 곧장 주제 화면으로 간다.

축의 주소도 실제로 있는 자리로 맞춘다. `/topics/{주제}/{축}` 이라 적어 두었는데 그런
화면이 없다 — 축은 주제 화면 안의 한 줄이므로 그 줄에 앵커를 달고 그것을 가리킨다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 17:22:57 +09:00
DongHyeonkaandClaude Opus 5 3510ec013f feat: 프로젝트 화면이 어디서부터 읽을지를 말한다
숫자 셋(기록 12 · 결정 4 · 활동 9)은 이 프로젝트가 얼마나 큰지는 말해도 어디서부터
읽어야 하는지는 말하지 않는다. 세는 자리를 처음 몇 편으로 바꾸고, 숫자는 각 목록으로
가는 줄에 남긴다.

「주요 주제」는 글자 목록이었다. 매퍼가 이름만 남기고 slug 를 버려서 그 주제로 갈 수가
없었는데, 계약은 처음부터 둘 다 주고 있었다.

논지 자리의 제목도 고친다 — 「프로젝트가 지키는 기준」이 아니라 이 프로젝트가 밝힌
것이고, 여러 문단으로 쓸 수 있으므로 산문으로 그린다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 17:19:32 +09:00
DongHyeonkaandClaude Opus 5 604ded5720 feat: 홈이 무엇을 견줬는지 먼저 말한다
홈은 「무엇을 만들었나」로 시작했다. 30초 안에 알아야 할 것은 무엇을 견줬고 무엇이
남았나인데, 그 답은 주제 화면까지 들어가야 있었다. 가장 많이 다룬 주제 하나를 앞에
세우고 축마다 무엇을 알게 됐는지를 나란히 둔다 — 요약을 쓰면 무엇인가만 말하고 무엇을
알게 됐는지는 말하지 않으므로 결론 칸을 읽는다.

종류별 입구에는 개념이 아예 없었고, 문서 머리말의 종류 링크는 삼항의 마지막 else 를 타
개념 문서에서 `/projects` 로 갔다. `/explore/concepts` 는 처음부터 열려 있었는데 그리로
가는 길이 세 화면 어디에도 없었다. 대응을 표 하나로 모은다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 17:17:14 +09:00
DongHyeonkaandClaude Opus 5 4da6d77c43 feat: 기록을 축에 걸고, 탐색을 주제로 묶는다
기록↔축 연결을 저장할 경로가 없었다. `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
2026-09-01 17:13:18 +09:00
DongHyeonkaandClaude Opus 5 3616502463 feat: 주제의 논지와 축을 Studio 에서 쓸 수 있게 한다
「주제·프로젝트」 화면은 주제를 만들고 지울 수만 있었다. 이름과 slug 말고는 쓸 자리가
없어, 주제가 답하는 질문(논지)도 축의 이름도 어디에도 적을 수 없었다 — 공개 주제
화면이 그 둘을 읽는데 쓸 곳이 없으니 늘 비어 있었다.

주제 편집 화면을 프로젝트 편집기와 같은 자리·같은 클래스로 둔다. 축(variant)은 주제
안의 접근/구조 하나다. 인증 경계라면 SPA·BFF·Mediator 가 각각 하나고, 각자 만들어 보고
무엇을 알게 됐는지가 다르다. 비교표가 읽는 것은 요약이 아니라 그 결론이라, 두 칸을
따로 둔다 — 기록의 요약 첫 줄을 잘라 쓰면 안 되는 자리다.

프로젝트에도 논지 칸을 둔다. 목적은 시작할 때 쓰는 글이고 논지는 끝나고 쓰는 글이다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-09-01 17:01:36 +09:00
DongHyeonkaandClaude Opus 5 15e6ea8f15 feat: 주제 화면을 계약에 잇고, 등록을 잊는 사고를 가드로 막는다
주제 화면은 주제 셋(`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
2026-09-01 16:57:24 +09:00
DongHyeonkaandClaude Opus 5 618a228eff fix: 관계의 묶음 이름과 작성자가 쓴 문장을 갈라 놓는다
관계 한 줄에 세 가지가 뭉쳐 있었다. 대상이 어떤 종류인지, 작성자가 왜 걸었는지,
대상이 무엇인지 — 셋 다 `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
2026-09-01 16:48:11 +09:00
DongHyeonkaandClaude Opus 5 af5a6bbf23 fix: 종류 이름을 기록의 톤에 맞는 말로 바꾼다
앞선 커밋의 「직접 해보니 · 다음에 쓸 기준」 은 기술 기록의 톤에 비해
가벼웠다. 역할은 그대로 말하되 문어체로 세운다:

  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
2026-09-01 16:06:54 +09:00
DongHyeonkaandClaude Opus 5 a6413d0301 feat: 문서 종류를 독자의 말로 바꾸고 미해결을 눈에 띄게 한다
이 저장소의 종류 이름은 글을 담아 둔 방식의 이름이었다 — 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
2026-09-01 15:19:47 +09:00
DongHyeonkaandClaude Opus 5 2b042829cf fix: 홈 초점의 질문·결정을 고른 프로젝트 것으로 좁힌다
「지금 집중하는 것」은 프로젝트·질문·결정 셋을 각각 고르는 구조였고, 고르는
목록이 전체였다. 그래서 프로젝트만 바꾸면 질문·결정은 이전 프로젝트 것이
그대로 남았다 — 홈에 프로젝트는 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
2026-09-01 15:02:06 +09:00
DongHyeonkaandClaude Opus 5 d835276296 fix: 개념 관계 라벨을 계약이 주는 이름에 맞추고 표를 계약에 묶는다
개념 화면에 `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
2026-09-01 14:42:29 +09:00
DongHyeonkaandClaude Opus 5 8996430d23 fix: 공개 개념 문서를 열 수 있게 한다
`/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
2026-09-01 14:37:39 +09:00
DongHyeonkaandClaude Opus 5 a3ed23e073 fix: 관계 요약이 화면까지 닿게 한다
라벨은 고쳤는데 요약이 여전히 비어 있었다. 값이 경계 세 곳을 지나며 사라진다:
평탄화가 담고(고침), 렌더 모델로 바꿀 때 버리고, 화면 목록으로 넘길 때 또
버렸다. 렌더 모델 계약(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
2026-08-31 11:10:15 +09:00
DongHyeonkaandClaude Opus 5 642afa878c fix: 관계 목록이 사람이 읽는 이름과 요약을 보여 준다
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
2026-08-31 11:04:42 +09:00
DongHyeonkaandClaude Opus 5 6429aee74e fix: 개념 삭제가 실제로 개념 경로로 나가게 한다
앞선 커밋은 게이트웨이를 고치지 못했다. 편집 스크립트가 중간에서 실패했는데
그 뒤 단계만 다시 돌리고 이 파일은 손대지 않은 채 넘어갔다. 배포된 번들에
옛 삼항이 그대로 남아 서버 로그에
`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
2026-08-31 10:55:18 +09:00
DongHyeonkaandClaude Opus 5 dec86bd1f2 fix: 개념 삭제가 질문 삭제로 떨어지던 것을 고친다
개념을 지우려 하면 「질문을 찾을 수 없습니다」가 났다. 세 가지가 겹쳤다.

게이트웨이가 종류를 삼항으로 이어 붙여, 마지막 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
2026-08-31 10:35:04 +09:00