docs: CLAUDE.md 4분할(매 세션 로드 1537→354줄), 워크플로 가짜 초록불 수정

## CLAUDE.md 분할
1537줄이라 (a) 사람이 검토 불가, (b) 공식 권장치(파일당 200줄) 7.7배
초과로 지침 준수도 자체가 저하, (c) 긴 파일 편집 시 에이전트 실수 증가.

  CLAUDE.md (39줄, 진입점)
  ├─ @.claude/conventions.md      언어/모델 관례 + 작업 방식
  ├─ @.claude/project-context.md  프로젝트 설명 + 문서 구조
  └─ @.claude/todos.md            지금 할 일
     .claude/session-summary.md   ← import 안 함(의도적, 온디맨드)

세션 히스토리 1231줄(전체의 80%)은 그 문서 스스로 "항상 읽을 필요 없음,
base/가 소스"라고 명시해온 색인이라 @import에서 뺐음. 내용 유실 없음
(1537→1647줄, 추가 헤더만큼 증가).

주의: @import는 컨텍스트를 줄이지 않음(전부 로드됨). 분할이 사는 건
사람 검토성 + 편집 정확도 + 파일 단위 자동생성 가능성.
CLAUDE.md 계열의 블록 HTML 주석은 주입 전 제거되므로 지시는 본문에 쓸 것.

## 워크플로 가짜 초록불 수정
첫 실측에서 감사 에이전트 6개 전원 실패했는데 converged:true가 나왔음
(전멸하면 fresh가 비어 "깨끗한 라운드"와 구분 불가). 감사 도구 최악의
실패 모드라 (1) 전멸이면 throw, (2) 반영 에이전트 실패 시 그 발견을
seen에서 빼 다음 라운드가 재시도하도록 수정.

## 부수
- 분할로 깨진 상호참조 20여 곳 정정(병렬 에이전트 3개).
  ref-plan.md:541의 사전 존재 오류(→ pre-implementation-audit 1-5)도 정정.
- doc-check.py: 새 파일 4개를 OURS에 등록(안 하면 깨진 참조가 WARN으로만
  잡힘), is_history()로 session-summary.md를 archive/와 같이 면제.
- doc-include-plan.md: 목적지가 통째로 생성되는 파일이 되면서 양방향
  마커 설계의 절반(목적지 마커)이 불필요해져 단방향 생성으로 단순화.

doc-check.py ERROR 0 유지.

미해결: session-summary.md 자동생성 미착수(91개 세션 파일 마커 삽입 필요),
orphan 인용 3건(modifier-plan.md:536, v1-compat-plan.md:50,
pre-implementation-audit.md:434 — 분할 이전부터 존재).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019HvEKn9f67kkx2nGLG8PsP

2026-08-16 01:35:02 +09:00

7.1 KiB

Raw Blame History

문서 stale 감소용 include 도구 — `doc-include.py` (가칭)

상태: research — 2026-08-14 세션에 아이디어 확정, [2026-08-16 갱신] CLAUDE.md 분할로 파일럿 설계가 단방향 생성으로 단순화됨(아래 "파일럿 범위" 참고). 구현 착수 전.

[2026-08-16] 이 문서의 원 설계에서 절반이 불필요해졌음. 원래는 원본에 , 인용처에  두 종류 마커를 두는 양방향 설계였는데, 같은 날 CLAUDE.md를 분할하면서 세션 히스토리가 독립 파일 (.claude/session-summary.md)이 됐음 — 목적지가 "손으로 쓴 파일 속 구간"이 아니라 통째로 생성되는 파일이 되면서 목적지 마커가 필요 없어졌다. 남는 건 원본 쪽 마커 + 단방향 생성기뿐. 아래 본문은 이 정정을 반영해 갱신했다.

배경

같은 날 진행된 코퍼스 전체 사실관계 감사(서브에이전트 4개 병렬)에서 실제 오류 20건을 찾아 고쳤는데, 대부분이 "같은 사실이 두 곳 이상에 적혀있다가 한쪽만 갱신됨" 패턴이었음(bind-system-plan.md 3단계 분할 후 다른 문서가 옛 줄번호를 가리키던 것 11곳 등). 이 프로젝트는 이미 doc-check.py(기계 검증기, ERROR/WARN 리포트)로 이 문제를 사후 탐지하고 있는데, 사용자가 사전 차단(애초에 중복 서술이 안 생기게)이 더 근본적이지 않겠냐고 제안 — "summary" 같은 블록을 원본 파일에 마커로 표시해두고, 인용하는 쪽은 그 마커 구간을 기계적으로 추출해 붙여넣는 도구를 만들면 정보의 관리 주체가 자연히 한 파일로 모인다는 아이디어.

선례 (재발명 아님을 확인)

AsciiDoc tagged region include — // tag::x[] ... // end::x[]로 구간 표시, include::file.adoc[tag=x]로 다른 문서가 그 구간만 당겨옴. 사용자가 제안한 --#summary-start/--#summary-end 아이디어의 원조 격.
markdown-magic(JS) — HTML 주석 마커()로 README 등에 다른 파일 내용을 주입, 재실행하면 갱신. Markdown 생태계에서 가장 가까운 기존 도구.
Obsidian/Roam/Logseq의 block transclusion(![[file#^blockid]]) — 빌드 스텝 없이 렌더 시점에 라이브로 당겨옴. stale이 구조적으로 원천 차단되는 더 강한 버전이지만 이 프로젝트는 정적 .md 파일이 소스라 뷰어 종속적인 이 방식은 안 맞음.

Build vs Buy 판단 — 직접 제작 채택

필요한 기능이 좁음: 마커 사이 텍스트를 원본에서 읽어 대상에 갱신 삽입 + 재실행해도 안정적(idempotent) + --check 모드로 어긋나면 실패. 정규식 몇 개 + 파일 I/O가 전부라 100줄 내외로 충분.
기존 도구(markdown-magic 등)를 쓰면 이 레포에 없던 Node/npm 툴체인이 새로 들어옴 — 지금 유일한 도구인 doc-check.py가 Python 표준 라이브러리만 쓰는 의존성 0 스크립트라는 관례와 어긋남. 프로젝트가 얻는 이득(TOC 생성, 배지 삽입 등 우리가 안 쓸 기능들)에 비해 대가가 큼.
마커 문법을 이 코퍼스 관례(한국어, doc-check.py의 ERROR/WARN 리포팅 스타일)에 맞춰 직접 정하고 싶으므로, 외부 도구 설정 파일로 끼워 맞추는 것보다 직접 짜는 쪽이 코드도 적고 통제도 쉬움.

결론: .claude/tools/doc-check.py와 짝을 이루는 doc-include.py를 Python 표준 라이브러리만으로 신설. --write(갱신 삽입)/--check(어긋나면 ERROR, doc-check.py 파이프라인에 편입) 두 모드.

파일럿 범위 — `.claude/session-summary.md` 전체 생성

사용자가 지목한 이유: 세션 히스토리 항목은 서로 독립적(과거 기록이라 다른 문서가 그 문장을 인용하는 경우가 거의 없음)이라 이 도구가 버그가 있어도 부작용이 다른 곳으로 안 번짐 — 첫 적용 대상으로 가장 안전.

[2026-08-16 기준] 지금 구조: .claude/session/YYYY-MM-DD-NN-slug.md에 세션 원문 전체가 있고, .claude/session-summary.md(CLAUDE.md 분할 전엔 CLAUDE.md의 "세션 히스토리" 절이었음)에 사람이 손으로 압축한 2~4줄 요약 + 링크가 별도 텍스트로 적혀있음 — 한쪽만 갱신되면 어긋날 수 있는 구조.
적용 후: 각 세션 파일 안에 "이게 이 세션의 정본 요약"이라고 표시하는 마커 블록을 신설(새로 요약을 쓸 필요 없음 — 지금 session-summary.md에 이미 있는 압축 요약을 그대로 그 블록 안으로 옮기면 됨). 생성기가 세션 파일들을 파일명 순으로 훑어 마커 블록을 모아 session-summary.md를 통째로 다시 씀. 그 시점부터 session-summary.md는 직접 편집 금지 대상이 되고(파일 상단에 그렇게 명시), 요약을 고치려면 세션 파일을 고침.

왜 목적지 마커가 필요 없어졌나

원안은 목적지(CLAUDE.md)가 손으로 관리되는 파일이라, 그 안의 특정 구간만 골라 갱신하려고  마커가 필요했음. 분할 후엔 목적지가 파일 통째로 파생 데이터라 "어디를 갱신할지"를 표시할 이유가 없음 — 파일 전체를 덮어쓰면 됨. 부품이 절반으로 줄고, "목적지 마커가 손실되면?" 같은 실패 모드도 같이 사라짐.

마커 문법 (초안 — 사용자가 확정할 것)

# 세션 파일(.claude/session/2026-08-14-14-....md) 안:
<!--#summary-->
**2026-08-14 열네 번째 세션 — ...** (`session/2026-08-14-14-....md`)
... 2~4줄 압축 요약 ...
<!--#/summary-->

session-summary.md 쪽엔 마커가 없음 — 생성기가 헤더 + 각 세션 블록을 파일명 순으로 이어 붙여 전체를 씀. id도 불필요해짐(파일명이 곧 순서이자 식별자).

열린 질문 (사용자가 다듬을 것)

마커 문법 자체(위 초안 확정 여부, id 네이밍 규칙 — 날짜+세션번호로 충분한지).
기존 세션 항목 전부(13개+)에 마커를 소급 삽입할지, 아니면 다음 세션부터 신규 항목에만 적용하고 과거분은 그대로 둘지.
--write 실행 시점 — 수동(세션 마무리 시 사람이 실행) vs 커밋 훅. 이 레포는 지금 CI가 없고 사람이 doc-check.py도 수동으로 돌리는 관례라 같은 패턴(수동 + 커밋 전 확인)이 자연스러워 보이지만 확정은 사용자 몫.
--check 실패를 doc-check.py의 ERROR로 편입할지 별도 스크립트로 둘지.
파일럿이 성공하면 다음 확대 후보 — .claude/README.md 표의 "상태" 요약을 각 base//research/ 문서 맨 위 **상태**: ... 줄에서 추출해오는 것(단, luau-test/STATUS.md처럼 이미 "폴더 구조 자체가 상태"인 곳은 include로 바꿀 필요 없음 — 그쪽은 이미 소스가 하나로 수렴된 상태라 적용 대상 아님).

우선순위

하 — M0/설계 게이트와 무관한 메타 도구. 사용자가 플랜을 다듬은 뒤 착수 시점 결정.

7.1 KiB Raw Blame History

문서 stale 감소용 include 도구 — doc-include.py (가칭)

배경