Files
tech-log-frontend/docs/reviews/2026-09-09-editor-design-proposal.md
T
DongHyeonkaandClaude Opus 5 fe1f23520e feat: 기록마다 이 조사의 어디쯤인지를 제목 아래에 세운다
이 사이트의 차별점은 "기록 하나에 아무 데서나 들어와도 그 결론을 만든 맥락의 사슬을
잃지 않는다"는 것이다. 그런데 그 사슬이 화면에서는 제목 위 얇은 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
2026-09-15 20:03:01 +09:00

20 KiB
Raw Blame History

글 쓰는 화면 설계안 — 원고·판면·자료

  • 일시: 2026-09-09
  • 대상: /studio/documents/:id/edit (Case·Question·Reference·Concept·Decision 공용 편집기)
  • 측정 문서: c1158754… Collection Fetch Join Pagination의 In-memory Paging (본문 2,707자, Asset 27개)
  • 선행 문서: 2026-09-09-studio-public-ux-review.md

1. 진단 — 세 가지가 각자 다른 곳을 본다

1.1 쓰는 글자와 읽는 글자가 다르다

폰트 크기 / 줄간 한글 1자 폭 한 줄 자수
편집 상자 IBM Plex Mono 13px / 20.15px 11.96px 52자
즉시 미리보기 Pretendard 21px / 34.02px 18.15px 21자
실제 공개 페이지 Pretendard 21px / 34.02px 18.15px 43자

세 판면이 전부 다르다. 세 가지가 따라온다.

하나. 편집 상자에서 한 줄인 문장이 미리보기에서 2.5줄이 된다. 줄바꿈 위치, 문단 덩어리, 호흡 — 글 쓰면서 만드는 것 중 어느 것도 오른쪽에 그대로 나타나지 않는다. 오른쪽은 "방금 쓴 글"이 아니라 "방금 쓴 글의 다른 판본"이다.

둘. 미리보기(21자)가 공개(43자)와도 다르다. 「즉시 미리보기」라는 이름이 사실이 아니다. 실제로 어떻게 보일지는 게시해 봐야 안다.

셋. IBM Plex Mono에는 한글 글리프가 없다. 편집 상자의 한글은 폴백 폰트로 떨어진다. 한 상자 안에서 라틴 문자는 모노, 한글은 다른 폰트로 렌더된다. 자간·기준선이 어긋난다.

덧붙여 52자/줄은 한국어 산문 편집에 너무 길다. 한글 본문의 적정 측정폭은 25~40자다. 줄 끝에서 다음 줄 머리로 눈이 되돌아오는 거리가 길어 오독이 생긴다. 반대로 미리보기의 21자는 너무 짧아 문단이 세로로 늘어진다. 셋 중 유일하게 제대로 된 판면은 공개 페이지(43자)다. 정작 그건 쓸 때 볼 수 없다.

1.2 스크롤이 셋이다

한 화면에 독립된 스크롤 컨텍스트가 세 개 있다.

컨텍스트 내용 높이 보이는 높이 숨겨진 비율
페이지 6,075px 900px 85%
textarea.studio-markdown-field 1,833px 628px 66%
section.studio-editor-preview 9,799px 852px 91%

셋은 서로 연결돼 있지 않다. 지금 쓰는 문단의 결과를 보려면 세 번째 스크롤바를 따로 굴려야 한다. 미리보기는 position: sticky; top: 28px이라 화면에는 늘 있지만, 늘 문서 맨 위를 보여준다. 본문 y=3,802 지점을 편집하는 동안 오른쪽은 제목과 첫 문단을 비추고 있다.

실측: scrollY = 3110일 때

  • 본문 상자는 630px 중 208px만 화면에 남는다 (커서 위치가 안 보인다)
  • 미리보기는 검증 기록 / JPA 피드 조회 성능 / … / Collection Fetch Join Pagination의 In-memory Paging — 문서 첫머리

1.3 Asset은 이름표 27장이다

/studio/documents/:id/edit의 본문에 Asset 삽입 패널 (문서 y=4,460, 높이 1,321px):

  • Asset 27개가 전부 텍스트 이름 pill로 나열된다. 썸네일 0개.
  • 이름이 <의미>-<8자리 해시> 구조다. 해시만 다른 동명 항목이 나란히 있다.
ap4-edge-trust-architecture-8125e9e8   ap4-edge-trust-architecture-1a916e10
ap3-bff-session-flow-1b005e15          ap3-bff-session-flow-a8dfff6f
ap2-mediator-handoff-flow-efe7039c     ap2-mediator-handoff-flow-8c2a6f8f

같은 그림의 다른 버전인지, 아예 다른 그림인지 이 화면에서는 알 방법이 없다. screenshot-from-2026-08-21-18-04-49-72f1f9c6 처럼 파일명이 그대로 올라온 것도 섞여 있다.

  • pill 27개마다 옆에 삭제 버튼이 붙어 있다. 삽입하려고 여는 목록에 영구 삭제가 27번. (확인 절차는 없다 — 선행 리뷰 B3)
  • 본문 상자(y 3,8024,432)와 이 패널(y 4,460)은 900px 뷰포트에 같이 담기지 않는다. 커서를 놓고 목록으로 내려가면 커서가 안 보이고, 목록을 보며 고르면 본문이 안 보인다.

삽입 결과는 본문에 이렇게 들어간다.

:::evidence key="batch-fetch-in-clause-cb44066a" alt="조회 코드, Hibernate 세션, feed_items,
highlights 네 참여자 사이에서 부모 페이징이 먼저 일어나고 그다음 자식 IN 배치 조회가
일어나는 순서도." caption=" " zoom="true"
:::

한 줄 270자. 52자/줄 상자에서 5~6줄을 차지하며 문장 흐름을 끊는다. alt를 성실하게 쓴 건 좋은 습관인데, 그 성실함이 원고를 망가뜨리는 구조다. caption=" " — 캡션을 안 쓰려고 공백 하나를 넣은 흔적도 남아 있다.

1.4 왜 이렇게 됐나 — 폼이 스키마를 그대로 비춘다

편집 화면은 데이터 모델을 1:1로 옮긴 CRUD 폼이다. Case = 문제 / 결론 / 검증환경 / 재현조건 / 마지막검증일 / 본문. 각 필드에 라벨 하나, textarea 하나. 선언 순서대로 세로로 쌓고, 폭도 무게도 같게.

이건 데이터를 입력하는 화면의 문법이지, 글을 쓰는 화면의 문법이 아니다. 세 가지가 깨진다.

하나 — 「지금 어디인가」가 없다. Question 문서 실측 7,540px에 textarea 21개. 전부 같은 크기, 같은 테두리, 같은 배경. 확인한 사실 2와 선택지 4를 눈으로 구별할 수 없다. 목차도 접기도 앵커도 없다. 문서를 하나의 형태로 볼 방법이 없다.

둘 — 메타데이터와 산문이 같은 격이다. 마지막 검증일(날짜 하나)과 본문(2,707자의 논증)이 둘 다 "라벨 붙은 입력칸"이다. 하나는 3초, 하나는 3시간이 드는 일인데 같은 옷을 입고 있다.

셋 — 고도(altitude)가 하나뿐이다. 글쓰기 도구에는 두 개의 고도가 있어야 한다.

  • 구조 고도 — 문서를 형태로 본다. 어떤 섹션이 있고, 뭐가 비었고, 근거가 어디 붙었는지. 계획하고, 재배치하고, 완성도를 점검할 때 쓴다.
  • 원고 고도 — 한 대목에 집중한다. 넓은 판면, 편한 글자.

현재 편집기는 이 둘 사이의 쓸모없는 중간에 갇혀 있다. 전체를 보기엔 7,540px이라 형태가 안 보이고, 쓰기엔 13px 모노 상자가 내용의 66%를 가린다.


2. 「텍스트 상자 말고 다른 방식」— 선택지는 셋이다

방식 대표 이 제품에서
A 블록 에디터 Notion, Craft 스키마와 충돌. / 메뉴는 다른 제품의 어휘
B 마크다운 + 인라인 렌더 Obsidian Live Preview, Typora 권장
C 위지윅 Google Docs 마크다운 소스를 잃는다. 이 저자에겐 손해

C를 버리는 이유. 이 저자는 :::evidence, GFM 표, EXPLAIN 출력, 코드 펜스를 직접 쓴다. 소스 접근을 뺏으면 지금 쓰는 글을 못 쓰게 된다.

A를 버리는 이유. 문서 종류마다 스키마가 정해져 있다(Case는 문제·결론·환경·재현·본문). 블록 에디터는 "무엇이든 놓을 수 있다"는 전제 위에 서는데, 이 제품의 가치는 그 반대다 — 정해진 칸을 채우게 하는 것이 이 도구의 존재 이유다. 또 이 사이트의 디자인 언어는 타이포로만 말하는 절제된 문법인데, / 메뉴와 블록 핸들은 다른 제품의 시각 어휘를 들여온다.

B를 고르는 이유. 소스는 마크다운 그대로 두되, 소스를 읽을 만하게 만든다. 그러면 오른쪽 미리보기의 필요 자체가 줄어들고, 스크롤 동기화 문제가 사라진다. 동기화를 잘 하는 것보다 동기화가 필요 없게 만드는 것이 우아하다.


3. 세 방향

방향 A — 「한 장의 원고」

논지. 편집기가 곧 문서다. 폼도 미리보기도 없고, 타이핑해 넣는 한 장의 지면만 있다.

  • 스키마 필드가 원고 흐름 안의 유형 있는 블록이 된다. 읽는 순서 그대로, 게시될 모습 그대로.
  • 미리보기 패널 없음 — 미리볼 것이 없으니까. 편집면 = 게시면.
  • 근거 이미지는 들어갈 자리에 실제 그림으로 놓인다.
  • slug·Topic·Project·검증일은 흐름에서 빠져 접히는 머리말로.
  • 서명 인터랙션: /가 이 문서 종류에 남은 스키마 칸만 보여준다. 폼 없이 구조가 지켜진다.
  • 배제: 좌우 분할, 마크다운 소스, 미리보기.
  • 위험: 가장 크다. 마크다운 소스를 잃는다. 블록당 「소스 보기」로 완화해야 한다.

방향 B — 「원고와 판면」

논지. 두 판을 남기되 하나의 기구로 묶는다. 왼쪽은 원고, 오른쪽은 판면, 둘은 위치에 대해 절대 어긋나지 않는다.

  • 픽셀 비율이 아니라 블록 경계(## 헤딩, 지시문 블록) 기준의 양방향 스크롤 동기화.
  • 지금 커서가 있는 블록을 양쪽에서 같이 강조.
  • 본문 textarea의 고정 높이를 없애 내용만큼 자라게 한다 → 스크롤 컨텍스트 3개가 2개로.
  • 근거는 원고 쪽에서도 270자 지시문이 아니라 카드로 보인다.
  • 서명 인터랙션: 미리보기가 교정쇄다. 오른쪽 문단을 클릭하면 왼쪽 커서가 그 자리로 간다.
  • 배제: 위지윅. 마크다운이 계속 정본이다.
  • 위험: 동기화 구현이 까다롭다. 그리고 아래 4.2에서 보듯 1440px에서는 양쪽을 동시에 제대로 못 놓는다.

방향 C — 「작업대」

논지. 문서는 섹션의 더미다. 한 번에 한 섹션을 전폭으로 다루고, 전체 형태는 레일이 갖는다.

  • 왼쪽 레일: 문서의 구조 — 모든 섹션(스키마 + ##), 채움 상태, 분량, 근거 개수. 1.4에서 없다고 한 「지금 어디인가」가 여기 산다.
  • 가운데: 한 섹션만. 649px 칸이 아니라 720px 판면에 17px.
  • 오른쪽: 기본은 없음. 미리보기는 가운데를 대체하는 토글.
  • 근거: 쓰는 영역 하단에 상주하는 자료 선반. 썸네일, 이 문서의 주제 것부터.
  • 서명 인터랙션: 선반에서 본문으로 끌어 놓으면 지시문이 대신 쓰이고 썸네일이 그 자리에 남는다.
  • 배제: 문서 전체를 한눈에 보기, 상시 좌우 분할.
  • 위험: 문서를 통으로 사고하는 사람은 한 섹션씩 보는 걸 답답해한다. 레일이 강해야 성립한다.

4. 권고 — B의 척추에 C의 두 기관, A의 근거 표현

세 개를 평균 내지 않는다. B의 구조적 결정(마크다운 정본 + 위치가 어긋나지 않는 두 면)을 뼈대로 삼고, C의 레일과 자료 선반, A의 인라인 근거 렌더링을 가져온다.

이유는 브리프에 있다.

  • 이 저자는 표·코드·EXPLAIN 출력·다이어그램이 섞인 측정 기반 산문을 쓴다. 마크다운이 정본이어야 한다 (A 탈락)
  • 호소한 불편은 셋 — ①미리보기가 따로 논다 ②자료가 뭐가 있는지 모르겠다 ③그냥 상자다. ①은 B, ②는 C의 선반, ③은 메타데이터와 산문의 고도를 나누는 것으로 풀린다
  • 사이트의 디자인 언어가 절제된 타이포다. 블록 에디터의 어휘를 들이면 제품이 둘로 쪼개진다

4.1 판면 — 쓰는 글자를 읽는 글자에 맞춘다

산문 편집:   Pretendard 17px / 1.75 (29.75px),  측정폭 620~660px  →  34~36자/줄
코드·지시문: IBM Plex Mono 13px / 1.55         (지금 값 유지)

픽셀이 아니라 자수를 맞춘다. 공개는 21px·43자다. 편집을 21px로 하면 화면에 안 담기고, 13px 모노를 유지하면 52자로 벌어진다. 17px·34~36자면 줄바꿈 감각이 공개로 이전된다 — 한 문장이 편집에서 2줄이면 공개에서도 2줄이다. 이게 지금 없는 것이다.

부수 효과로 한글 폴백 문제가 사라진다. 산문에서 모노를 걷어내면 한 상자 안에 폰트가 하나만 남는다.

4.2 상시 좌우 분할을 포기한다

미리보기를 공개와 같은 43자/줄로 맞추려면 21px × 18.15px × 43자 = 780px가 필요하다. 현재 미리보기 패널은 656px, 그 안의 본문은 399px다.

1440px 화면에서:  편집 620 + 간격 40 + 미리보기 780 = 1440   → 좌우 여백 0

1440px에서는 양쪽을 동시에 제대로 놓을 수 없다. 지금 오른쪽이 21자/줄인 건 그래서다. 반쪽짜리 미리보기를 붙잡고 있으면 이 계산은 영원히 안 맞는다.

그래서:

지금 제안
기본 편집 649 + 미리보기 656 (상시) 편집 단일 판, 660px 판면 중앙
확인 오른쪽 21자/줄 축소판 전폭 미리보기 토글 (Ctrl+/), 공개와 픽셀 동일
근거·표·코드 오른쪽에서만 확인 그 자리에서 인라인 렌더

핵심은 마지막 줄이다. 소스로 읽을 수 있는 것(산문)은 소스로 읽고, 소스로 읽을 수 없는 것(이미지·표·코드 하이라이팅)만 그 자리에서 결과로 보여준다. 그러면 스크롤 동기화라는 문제가 존재하지 않게 된다. 볼 것이 이미 거기 있으니까.

동시에 스크롤 컨텍스트가 3개에서 1개로 준다 — textarea 고정 높이 제거, 미리보기 패널 제거. 페이지 하나만 구르면 된다.

1920px 이상에서는 B의 원안대로 좌우 분할을 켤 수 있다. 780px 미리보기가 들어가니까. 다만 기본값은 아니다 — 기본이 예외 상황에 맞춰지면 안 된다.

4.3 자료 — 이름표 27장을 그림으로 바꾼다

# 문제 처방
1 썸네일 0개, 해시 이름 27개 96×72 썸네일 격자. 27개면 4열 × 7행 — 한 화면에 다 들어온다
2 …-8125e9e8 / …-1a916e10 구별 불가 표시 이름을 사람 말로. Edge 신뢰 구조 · v2. 해시는 상세에만
3 27개 중 이 문서와 관련된 건 3~4개 정렬을 이 문서의 주제·프로젝트 → 최근 업로드 → 전체로. 상단에 「이 주제에서 쓰인 것」 묶음
4 패널이 본문에서 658px 아래 커서 자리에서 여는 인라인 팝오버 (툴바 그림 또는 /그림). 스크롤 이동 0
5 삽입 목록에 삭제 27개 삭제를 목록에서 뺀다. 자료 관리는 /studio/assets에서만 (그리고 그 화면을 nav에 넣는다 — 선행 리뷰 B2)
6 삽입 결과가 270자 지시문 본문에 썸네일 + 캡션 카드. alt·caption·zoom은 카드를 눌러 편집. 「소스 보기」로 원문 확인
7 caption=" " 같은 잔재 카드 편집기에서 캡션 비우면 속성 자체를 안 쓴다

6번이 특히 중요하다. 지금 구조는 성실한 alt가 원고를 망가뜨린다. 카드로 빼면 접근성 텍스트를 길게 쓸수록 좋아지기만 한다.

4번의 서명 인터랙션은 C에서 가져온다 — 선반에서 본문으로 끌어 놓기. 놓은 자리에 지시문이 쓰이고 썸네일이 남는다. 「어디에 넣을지」와 「무엇을 넣을지」를 한 동작으로 합친다.

4.4 정보 배치 — 스키마 폼을 원고로

메타데이터를 흐름에서 뺀다. 제목·slug·요약·Topic·Project·관계는 접히는 머리말 한 줄로. 처음 만들 때만 펼쳐지고, 그다음부터는 JPA 피드 조회 성능 · Liner N+1문제 · 관계 3 + 「펼치기」. 지금은 이것들이 본문 위 1,900px을 차지한다.

Case의 기록 필드를 카드 하나로 묶는다. 문제·결론·검증 환경·재현 조건·마지막 검증일을 2열 「기록 카드」로. 지금은 세로 스택으로 1,240px. 카드로 묶으면 600px 안에 들어가고, 무엇보다 이 다섯이 한 덩어리라는 사실이 보인다. 지금은 본문과 같은 격의 낱개 칸들이다.

본문이 첫 화면의 주인이 된다. 현재 900px 중 530px을 지나야 첫 입력칸이 나온다 (문서 편집 + 문서 제목 + DOCUMENT + 기본 정보). 문서 제목은 한 화면에 세 번 나온다 — 부제, 제목 입력칸, 미리보기. 머리말을 접고 나면 첫 화면에서 바로 본문이다.

반복 그룹을 행으로. Question의 확인한 사실·가정·남은 미지수·제약·검토한 선택지는 지금 항목 하나가 textarea 1개 + 버튼 3개 ≈ 190px, 17개가 쌓여 있다 (버튼만 51개). → 한 줄 요약 행 + 클릭하면 인라인으로 펼쳐지는 편집. 재정렬은 드래그 핸들 하나로. 버튼 51개가 핸들 17개로 준다.

왼쪽 레일 — 「지금 어디인가」. 스키마 섹션 + 본문 ## 헤딩의 목차. 각 항목에 채움 상태(빈칸/작성 중/완료), 분량, 근거 개수.

지금 하단 바에 이렇게 적혀 있다.

게시를 누르면 채워야 할 칸을 그 자리에 표시합니다.

누르기 전에 보여야 한다. 레일이 그 일을 한다. 이 사이트에는 이미 공개 상세 페이지에 sticky 목차 구현이 있다 (position: sticky; top: 28px, 정상 동작). 새로 만들 것이 아니라 옮겨 오면 된다.

4.5 되돌릴 수 없는 것

선행 리뷰 M1과 이어진다. 저장(rgb 90,93,100 / 600)과 게시(rgb 23,24,27 / 700)의 차이가 회색 한 단계와 굵기 100뿐이다. 같은 16px, 같은 92×44 박스, 배경 없음.

타이포로만 격을 나누는 방향(studio.css:60-67)은 유지할 만하다. 다만 되돌릴 수 없는 동작은 위계가 아니라 절차로 구분한다. 게시는 확인 단계를 거치게 하고, 그 단계에서 무엇이 공개되는지 보여준다 — 이미 /publish 화면이 그 일을 하도록 만들어져 있다. 편집기의 게시 버튼은 그 화면으로 가는 링크면 충분하다.


5. 실행 순서

측정된 불편을 큰 것부터, 위험이 낮은 것부터.

1단계 — 판면 (1~2일, 위험 낮음)

  1. 산문 편집 폰트를 Pretendard 17px / 1.75, 판면 620~660px로 (4.1)
  2. 코드·지시문만 IBM Plex Mono 13px 유지
  3. 본문 textarea 고정 높이 제거 → 내용 높이만큼 성장 (스크롤 컨텍스트 3 → 2)

이것만으로 「52자 vs 21자」와 「66% 숨김」이 사라진다. 코드는 CSS 수준이다.

2단계 — 자료 (3~5일) 4. 자료 목록을 썸네일 격자로, 표시 이름을 사람 말로 (4.3 #1, #2) 5. 삽입 목록에서 삭제 제거, /studio/assets를 nav에 추가 (4.3 #5) 6. 이 문서의 주제·프로젝트 우선 정렬 (4.3 #3)

3단계 — 배치 (1주) 7. 메타데이터 머리말 접기 (4.4) 8. Case 기록 카드 2열 묶음 (4.4) 9. 왼쪽 목차 레일 — 공개 상세 페이지 구현 이식 (4.4) 10. 반복 그룹을 행 + 인라인 편집 + 드래그 핸들 (4.4)

4단계 — 원고와 판면 (2주) 11. 상시 좌우 분할 해제, 전폭 미리보기 토글 Ctrl+/ (4.2) 12. 근거·표·코드 인라인 렌더 (4.2, 4.3 #6) 13. 커서 자리 자료 팝오버 + 끌어 놓기 삽입 (4.3 #4) 14. 1920px 이상에서만 좌우 분할 옵션 (4.2)


6. 측정 근거

편집 상자   IBM Plex Mono 13px/20.15px, 폭 649px, 한글 11.96px/자 → 52자
미리보기    Pretendard 21px/34.02px, 본문 폭 399px → 21자
공개 페이지  Pretendard 21px/34.02px, 본문 폭 790px → 43자

스크롤 컨텍스트
  document                          6,075 / 900   (85% 숨김)
  textarea.studio-markdown-field    1,833 / 628   (66% 숨김)
  section.studio-editor-preview     9,799 / 852   (91% 숨김)

편집기 세로 좌표 (문서 기준)
  본문 textarea      y 3,802  h 630
  Asset 삽입 패널     y 4,460  h 1,321
  → 900px 뷰포트에 동시 수용 불가. scrollY 3,110에서 본문 208/630px만 노출

Asset 27개 · 썸네일 0 · 삭제 버튼 27
  해시만 다른 동명 3쌍 확인
  evidence 지시문 1개 = 270자 (52자/줄 상자에서 5~6줄)

스크린샷: w-editor-asset-reality.png (ai-design-harness 루트) — 위 사실이 한 화면에 다 있다.