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은 바로 답하기로 했다(메인테이너: “좋습니다”).
한 일
- 목록을 각 폴더로 (inbox 1~4). ADR · DR · 세션 기록의 목록을
atelier/README.md의 절에서 README, README, README로 옮기고, 작업 공간의 구성 표에서 링크했다. CLAUDE.md의 “목록을 갱신한다” 규칙도 새 자리로 고쳤다. 사이트에서는 폴더의 README가 폴더 첫 페이지가 된다. tech-notes/→til/(inbox 6). 메인테이너가 고르는 창에서 “til + 풀어 쓴 제목”을 골랐다. 폴더와 태그를til로, 제목은 “Today I Learned (TIL)“. 사이트 주소는/til/. 이어서 메인테이너가 “til도 주제별로 분류할 수 있나요?”라고 물어 “목록만 묶기”를 골랐다: index의 노트 목록을 주제 여섯(브라우저, 그림과 글자, 설계와 기술 선택, 배포 대상, git과 GitHub, 오픈소스 운영)으로 묶었고 파일은 그대로 두었다.- 문서 지도 (inbox 5). 시안 M31에서 메인테이너가 D1 1번(흐름 그림 + 폴더별 표)을 골랐다. 문서 지도를 Mermaid 흐름 그림과 폴더마다의 표(문서 · 답하는 질문 · 상태 · 바뀌는 때)로 다시 썼다. 상세 설계 표를 지도 안으로 합쳤다.
- 코드의 자리 (inbox 7). 시안 M32에서 메인테이너가 S1 2번(코드는 모두
src/아래, Claude의 추천은 1번 맨 위apps/·packages/), S2 1번(core는 패키지 하나, 안을 폴더로), S3 1번(Obsidian의manifest.json사본은 저장소 맨 위)을 골랐다 → ADR-0036. ADR-0002의 이후 변경, 아키텍처 3장, backlog의 테스트 전략 항목에 반영했다. - 앱 배포 폴더 (inbox 8). 대화로 답했다:
site/는 문서 사이트의 설정이다. 앱은 배포 폴더를 커밋하지 않는다. 빌드 결과dist/는.gitignore하고 Actions가 내보낸다(웹은 Pages의/app/, 데스크톱과 Obsidian은 GitHub Releases). → build-output-and-releases - 링크 공유 그림. 메인테이너: “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)]] - 문서 전체의 정합성 검토. 메인테이너: “전체 문서의 정합성을 검토해주세요. 심지어 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의 “확인해 주세요”에 적었다. 정할 것 하나(글자 폭 측정의 우선순위)는 “정해 주세요”에
- 매듭. 메인테이너가 “일단 중간 마무리. 중간 마무리를 일컫는 용어를 추천해주세요”라고 했고, 고르는 창에서 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