qwreey
3e2c63e3d1
반복된 stale 문제(같은 사실이 여러 곳에 중복 서술)를 근본적으로 줄이는 방법으로 마커 기반 include 도구를 논의 — AsciiDoc tagged include/ markdown-magic 선례 확인 후 build-vs-buy 검토, doc-check.py와 짝인 Python 직접 제작 채택. research/doc-include-plan.md에 플랜 초안(마커 문법, CLAUDE.md 세션 히스토리 파일럿 범위, 열린 질문) 작성 — 세부는 사용자가 다듬을 예정, 구현 착수는 안 함. README.md 색인/CLAUDE.md 백로그·세션 히스토리 동기화.
4 KiB
2026-08-14 열네 번째 세션 — 코퍼스 전체 사실관계 감사 + doc-include.py 백로그 신설
사용자 요청("전체 내용 감사해줘, 서브에이전트 써도 좋아")으로 .claude/
코퍼스 전체를 대상으로 사실관계 감사 진행.
1. 기계 점검 + 서브에이전트 4개 병렬 감사
python3 .claude/tools/doc-check.py 선실행(ERROR 0, WARN 85 — 대부분
"절 제목 의역 인용" 정상 관례). 이어서 base/, research+reference/,
luau-test+audit/, archive+root 네 영역으로 나눠 general-purpose 서브에이전트
4개를 병렬로 띄워 각자 독립적으로 감사·직접 수정하게 함(같은 파일을
동시에 건드리지 않도록 영역 분리, CLAUDE.md 자체는 제외해 어시스턴트가
직접 처리).
결과: 13개 파일에 걸쳐 실제 오류 20건 수정.
- 가장 큰 원인:
bind-system-plan.md3단계 분할(1238→203줄, 9차/14차 세션) 이후research/·reference/문서 11곳이 여전히 옛 줄번호나 이관된 내용을 옛 파일로 가리키던 것 —source-state-plan.md/event-plan.md/dispatch-core-plan.md/archive/ quad2-try-research-findings-rejected.md등 실제 위치로 정정. HUMAN_TODO.md가 이중 바인딩 게이트를 "canExecute하나"로 서술 중이었으나 열한 번째 세션의canBound재도입이 반영 안 돼 있던 것 정정.architecture.md/blocker-plan.md/component-composition-plan.md/debug-tooling-plan.md의 "남은 건 X뿐" 류 날짜 없는 완결 주장 4건에[YYYY-MM-DD 기준]날짜 태그 추가(git log로 유추).luau-test/·archive/·.claude/README.md·ROADMAP.md·question.md·HUMAN_TODO.md·SAFETY.md는 감사 결과 이상 없음 확인(agent 보고).- 어시스턴트가 CLAUDE.md 자체도 직접 대조(
bind-system-plan.md의 "확정된 것" 절 존재 여부, 최근 승격 파일 실존 여부 등) — 이상 없음.
doc-check.py ERROR 0 유지, 커밋 완료(f829487).
2. State 노드 남발 줄이는 법 — 탐색 질문
기존 확정 설계에서 이미 있는 절제 수단 세 가지를 정리해 답변: (1)
:With(a,b,c) 가변인자로 한 호출에 의존성 몰아넣기, (2) 이미 다른 이유로
노드를 만드는 자리면 :Compute(fn, ...) trailing-args로 공짜로 의존성만
얹기(단 호출문 로컬 안에서만 무료), (3) 재사용되는 파생 로직은
:Apply(factory)로 감싼 콤비네이터를 한 번만 만들어 재사용. 근본
원칙은 "관측해야 실체화된다"(source-state-plan.md) — 반응성이 실제로
필요 없는 값은 State로 안 감싸는 것. 새 설계 결정 아님, 기존 문서
인용 답변.
3. 문서 stale 감소 방안 논의 → doc-include.py 백로그 신설
사용자가 "요약 부분을 특정 파일에서 마커로 표시해두고, 인용하는 문서가
그 구간을 기계적으로 추출해 붙여넣는 도구를 만들면 안 되냐"고 제안(선례
있는지도 질문). 어시스턴트가 AsciiDoc tagged region include / markdown-magic
/ Obsidian block transclusion을 선례로 확인, 이 코퍼스엔 아직 없음을
확인. 사용자가 "직접 만들지 vs 기존 걸 가져다 쓸지"를 재질문 —
build-vs-buy 판단으로 직접 제작 채택을 권고(문제가 좁아 100줄 내외로
충분, 기존 JS 도구는 Node/npm 툴체인을 새로 들여옴 — doc-check.py가
Python 의존성 0이라는 관례와 어긋남, 마커 문법을 코퍼스 관례에 맞춰
직접 정하는 게 더 간단).
사용자가 동의, 오늘은 플랜만 작성하고 세부는 내일 사용자가 직접
다듬기로 함 — 파일럿 범위는 CLAUDE.md 세션 히스토리부터(다른 문서가
그 문장을 인용하는 경우가 거의 없어 부작용이 가장 작다는 사용자 판단).
research/doc-include-plan.md 신설(마커 문법 초안, 파일럿 범위, 열린
질문 5개, 우선순위 하) — .claude/README.md research 표, CLAUDE.md
"지금 할 일" 6번에 반영. 구현 착수는 아직 안 함.