2026-10-25 목록의 자리, TIL, 문서 지도, 코드의 자리, 문서 전체 정합성

(← 2026-10-25-02-site-tags-figures) 같은 날 세 번째 세션이다. inbox 여덟 항목(“1. 일하는 방식”)을 처리하고, 링크 공유 그림을 로고로 바꾸고, 문서 전체의 정합성을 검토했다. 세션 중간에 매듭(중간 마무리)을 지었다.

inbox 원문

메인테이너가 매듭 때 “옮기고 지움”을 골라 원문을 그대로 옮기고 inbox에서 지웠다.

1. 일하는 방식

  • 아키텍처 결정 기록 (ADR)을 atelier/adr/README로
  • 결정 기록 (DR)을 atelier/decisions/README로
  • 세션 기록 목록을 atelier/sessions/README로
  • 구성에 위 문서들의 링크
  • 문서 지도를 구조를 이해하기 쉽게 만들어주세요.
  • tech-notes (기술 노트) ← “홍월이 학습한 것”이라는 느낌이 아니라 AriadenNSD의 “고유한 기술”이라는 느낌이 듭니다. 오해하기 딱 좋네요. 바꿀 후보를 추천해주세요.
  • MVP 직전입니다. src/ 구조를 어떻게 할 것인지 결정해야합니다. 배포 대상이 다양한 것을 고려합시다. 제안해주세요.
  • site/는 문서를 배포하기 위함이지요? 앱을 배포하기 위해서는 어떤 디렉토리가 필요한가요?

(위 원문의 atelier/README#… 링크는 이 세션에서 그 절을 옮겨 지금은 깨져 있다. 그때의 글이라 그대로 둔다.)

진행 순서는 1~4 → 6 → 5 → 7로 하고 8은 바로 답하기로 했다(메인테이너: “좋습니다”).

한 일

  1. 목록을 각 폴더로 (inbox 1~4). ADR · DR · 세션 기록의 목록을 atelier/README.md의 절에서 README, README, README로 옮기고, 작업 공간의 구성 표에서 링크했다. CLAUDE.md의 “목록을 갱신한다” 규칙도 새 자리로 고쳤다. 사이트에서는 폴더의 README가 폴더 첫 페이지가 된다.
  2. tech-notes/ → til/ (inbox 6). 메인테이너가 고르는 창에서 “til + 풀어 쓴 제목”을 골랐다. 폴더와 태그를 til로, 제목은 “Today I Learned (TIL)“. 사이트 주소는 /til/. 이어서 메인테이너가 “til도 주제별로 분류할 수 있나요?”라고 물어 “목록만 묶기”를 골랐다: index의 노트 목록을 주제 여섯(브라우저, 그림과 글자, 설계와 기술 선택, 배포 대상, git과 GitHub, 오픈소스 운영)으로 묶었고 파일은 그대로 두었다.
  3. 문서 지도 (inbox 5). 시안 M31에서 메인테이너가 D1 1번(흐름 그림 + 폴더별 표)을 골랐다. 문서 지도를 Mermaid 흐름 그림과 폴더마다의 표(문서 · 답하는 질문 · 상태 · 바뀌는 때)로 다시 썼다. 상세 설계 표를 지도 안으로 합쳤다.
  4. 코드의 자리 (inbox 7). 시안 M32에서 메인테이너가 S1 2번(코드는 모두 src/ 아래, Claude의 추천은 1번 맨 위 apps/ · packages/), S2 1번(core는 패키지 하나, 안을 폴더로), S3 1번(Obsidian의 manifest.json 사본은 저장소 맨 위)을 골랐다 → ADR-0036. ADR-0002의 이후 변경, 아키텍처 3장, backlog의 테스트 전략 항목에 반영했다.
  5. 앱 배포 폴더 (inbox 8). 대화로 답했다: site/는 문서 사이트의 설정이다. 앱은 배포 폴더를 커밋하지 않는다. 빌드 결과 dist/는 .gitignore하고 Actions가 내보낸다(웹은 Pages의 /app/, 데스크톱과 Obsidian은 GitHub Releases). → build-output-and-releases
  6. 링크 공유 그림. 메인테이너: “github page를 facebook에 링크를 공유했는데 대표이미지가 Quartz로 나옵니다. 우리는 로고도 있는데!!” Quartz가 모든 페이지의 og:image로 쓰는 static/og-image.png에 Quartz의 그림이 있었다. 로고와 문자 로고로 1200×630 그림을 만드는 site/make-og-image.mjs를 쓰고, 빌드가 site/og-image.png를 그 자리에 복사하게 했다. push 뒤 페이스북 공유 디버거에서 다시 스크랩하자 로고가 나왔다(메인테이너: “페이스북에 로고가 잘 나옵니다”). → DR-0013 이후 변경, [[github-pages-site#링크를-공유하면-보이는-그림-ogimage|링크를 공유하면 보이는 그림 (og:image)]]
  7. 문서 전체의 정합성 검토. 메인테이너: “전체 문서의 정합성을 검토해주세요. 심지어 README에 배포 대상이 현행화 안 되어있네요. 이런것들이 전체 문서에 많이 있을 것 같군요.” 문서를 네 묶음(첫 화면 · 색인, 요구사항 · UX, 아키텍처 · 설계, 작업 공간 · TIL)으로 나눠 동시에 검토하고, 파일이 겹치지 않게 나눠 고쳤다(52개 파일). 주로 고친 것:
    • 배포 대상을 셋으로 적은 곳(README, CLAUDE.md, 아키텍처의 제약, 요구사항의 호환성)을 일곱으로
    • 이미 정한 것이 미결정으로 남은 곳(글꼴 D2Coding, 네임스페이스, MVP의 Case · For, v0 파일)
    • 문서끼리 어긋난 곳: 파일 형식 예시의 palette(모델은 theme), 설정에 빠진 headStyle, undo를 쌓는 쪽(명령이 아니라 editor), 호출 블록의 점선, 용어집의 Case · 갈래, 키 표의 빠진 키
    • 승인 ADR · DR의 “이후 변경” 누락(ADR-0002 · 0003 · 0005 · 0007 · 0012, DR-0005), DR 열 개의 옛 번호가 새 번호로 잘못 바뀌어 있던 것
    • 규칙 위반: docs/의 이력 문장 · 날짜 꼬리표 · 확인 요청(아키텍처 8장 → outbox), 글 속의 #P1 태그, 상세 설계 문서의 제목과 H1이 다른 것
    • 작업 공간: status의 지나온 경과를 지우고 지금 상태만, 끝난 항목과 중복, 깨진 링크, 남은 tech-notes
    • 뜻에 닿는 고침과 남겨 둔 것은 outbox의 “확인해 주세요”에 적었다. 정할 것 하나(글자 폭 측정의 우선순위)는 “정해 주세요”에
  8. 매듭. 메인테이너가 “일단 중간 마무리. 중간 마무리를 일컫는 용어를 추천해주세요”라고 했고, 고르는 창에서 Claude의 추천 매듭을 골랐다. CLAUDE.md의 “세션 끝날 때 할 일”에 적었다.

결정

  • ADR-0036: 코드는 src/ 아래의 pnpm 모노레포, core는 패키지 하나, Obsidian의 manifest.json 사본은 저장소 맨 위
  • tech-notes/ → til/(Today I Learned), 목록은 주제 여섯으로
  • 문서 지도는 흐름 그림 + 폴더별 표(M31)
  • 세션 중간의 정리는 “매듭”이라고 부른다

발견한 것

  • ADR을 DR로 옮길 때(2026-10-17) 바꾸기를 한꺼번에 하면서, DR 열 개의 “이후 변경”에 있던 옛 ADR 번호까지 새 DR 번호로 바뀌어 있었다. 일주일 동안 아무도 몰랐다. 한꺼번에 바꾼 뒤에는 바뀐 줄을 훑어봐야 한다.
  • 정합성 검토에서 고친 곳의 많은 수가 “한 사실이 여러 문서에 따로 적혀 있어서” 생겼다(배포 대상의 수, 프로토타입의 판 번호, 남은 물음의 목록). “한 항목은 한 곳에만”을 지키지 못한 곳이다.
  • Windows에서 Python으로 파일을 쓸 때 newline을 정하지 않으면 줄 끝이 CRLF가 된다. 커밋 전에 LF로 되돌렸다(.gitattributes가 eol=lf).

다음 할 일

  • 레이아웃 설계 02-layout의 1단계 → 이번과 다음 세션에 할 것
  • outbox의 새 항목: 글자 폭 측정의 우선순위(정해 주세요), 정합성 검토의 고침과 이 세션의 다른 확인들(확인해 주세요) → outbox