From 3e2c63e3d16031691f6d699b0db706de4667d0f6 Mon Sep 17 00:00:00 2001 From: qwreey Date: Fri, 14 Aug 2026 22:56:21 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EB=AC=B8=EC=84=9C=20stale=20=EA=B0=90?= =?UTF-8?q?=EC=86=8C=EC=9A=A9=20include=20=EB=8F=84=EA=B5=AC=20=EB=B0=B1?= =?UTF-8?q?=EB=A1=9C=EA=B7=B8=20=EC=8B=A0=EC=84=A4(doc-include.py)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 반복된 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 백로그·세션 히스토리 동기화. --- .claude/README.md | 1 + .claude/research/doc-include-plan.md | 101 ++++++++++++++++++ ...-14-14-corpus-audit-doc-include-backlog.md | 61 +++++++++++ CLAUDE.md | 20 ++++ 4 files changed, 183 insertions(+) create mode 100644 .claude/research/doc-include-plan.md create mode 100644 .claude/session/2026-08-14-14-corpus-audit-doc-include-backlog.md diff --git a/.claude/README.md b/.claude/README.md index 22fa83c..34c376b 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -77,6 +77,7 @@ | `debounce-throttle-plan.md` | **[2026-08-14 신설]** 시간 기반 전파 게이트 `Debounce`/`Throttle` — 사용자 요청("`Blocker`와 유사하게")으로 신설. 요지: (1) `Blocker`가 이미 쓰는 게이트 노드의 **릴리스 트리거만 타이머로 바꾼 것**이라 새 전파 메커니즘이 아님 — `Blocker` 구현(M3) 시점에 게이트를 공용으로 빼두는 게 쌈, (2) 무효화 채널만 만지므로 laziness 안 깨짐, (3) **Debounce/Throttle의 차이는 "신호가 창 타이머를 리셋하는가" 한 비트뿐** — 공개 생성자는 둘, 구현은 하나(초안의 lodash식 `maxWait` 공식엔 trailing 통과 직후 이중 발화 버그가 있었음), (4) 알고리즘은 quad-base + 주입 op 2개 `setTimeout(func, delay) -> Timeout`/`clearTimeout`(Roblox `task.delay`/`task.cancel`로 배선 — **인자 순서 반대라 주의**). `os.clock()`은 Luau 표준 라이브러리라 주입 대상 아님(단 절대 시각이 아니라 **diff 전용**), 취소 없는 엔진도 래핑+유효 플래그로 대응 가능, `Timeout`은 `{ __type_timeout: true, _native: any }`. **부수 성과**: 이 설계 중 `source-state-plan.md`의 무효화 dedup 서술이 `Observer` 계약과 모순되는 게 발견돼 base 전면 정정(`archive/invalidate-dedup-propagation-reversed.md`) | 하 — M0 안 막음(코어 계약 변경 없음), 다만 순수 슈가가 아니라 실제 기능 갭이라 `operator-sugar-plan.md`보다는 위. 의존은 M3(State)+백엔드 주입. 남은 열린 질문: 이름(Roblox 관용 debounce와 충돌)/값 지연 의미론/제어 핸들 `Flush`/`Time=0` 허용 | | `quad-recursive-acronym.md` | **[2026-08-14 신설]** GNU/WINE류로 `Quad`를 재귀 약어화하는 카피 브레인스토밍 — 설계 결정도 착수 게이팅도 아니고 나중에 README.md 헤딩 등에 쓸 캐치프레이즈 후보 모음. 자학 개그 방향(기각)과 지연평가/재귀·커링/펑터/클로저를 자랑하는 방향(채택 후보, 미확정) 정리 | 하 — 카피 소재, 설계 상의 필요 없음. 사용자가 최종 문구 고르면 반영 | | `v1-compat-plan.md` | v1 하위호환(compat) 레이어 — `quad-roblox-v1-compat` 패키지, v2→v1 단방향 브리지(`state:Observer()`+v1 프로퍼티 재대입), v2-in-v1/v1-in-v2 두 임베딩 방향의 기술 규칙까지 확정. quad2-try의 `quad-compat`은 빈 폴더로 실제 시도된 적 없었음을 확인 | 하 — Slot이 foreign Instance를 어떻게 다루는지만 Slot 코어 구현 시점까지 미결 | +| `doc-include-plan.md` | **[2026-08-14 신설]** 문서 stale 감소용 include 도구 `doc-include.py`(가칭) — 원본 파일에 `` 류 마커로 요약 구간을 표시해두면 인용하는 문서가 그 구간을 기계적으로 추출해 붙여넣게 하는 도구. `doc-check.py`(사후 탐지)와 짝을 이루는 사전 차단 장치. AsciiDoc tagged include/markdown-magic이 선례, build vs buy 검토 후 Python 표준 라이브러리로 직접 제작(~100줄) 채택. 파일럿은 `CLAUDE.md` 세션 히스토리 ← `.claude/session/*.md` 요약 마커부터(부작용 최소) | 하 — M0/설계 게이트와 무관한 메타 도구, 플랜만 초안, 사용자가 내일 다듬을 예정 | ## `archive/` — 완료됐거나 완전히 뒤집힌 것, 능동 참고 불필요 diff --git a/.claude/research/doc-include-plan.md b/.claude/research/doc-include-plan.md new file mode 100644 index 0000000..b1991c2 --- /dev/null +++ b/.claude/research/doc-include-plan.md @@ -0,0 +1,101 @@ +# 문서 stale 감소용 include 도구 — `doc-include.py` (가칭) + +**상태**: research — 2026-08-14 세션에 아이디어 확정, **플랜만 초안, 사용자가 +다듬을 예정(내일 처리)**. 구현 착수 전. + +## 배경 + +같은 날 진행된 코퍼스 전체 사실관계 감사(서브에이전트 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.md 세션 히스토리부터 + +사용자가 지목한 이유: 세션 히스토리 항목은 서로 독립적(과거 기록이라 +다른 문서가 그 문장을 인용하는 경우가 거의 없음)이라 이 도구가 버그가 +있어도 **부작용이 다른 곳으로 안 번짐** — 첫 적용 대상으로 가장 안전. + +- 지금 구조: `.claude/session/YYYY-MM-DD-NN-slug.md`에 세션 원문 전체가 + 있고, `CLAUDE.md`의 "세션 히스토리" 절엔 사람이 손으로 압축한 2~4줄 + 요약 + 링크가 별도로 적혀있음(둘이 물리적으로 분리된 텍스트라 한쪽만 + 갱신되면 어긋날 수 있음 — 실제로 아직 발생한 적은 없지만 구조적으로 + 가능한 상태). +- 적용 후: 각 세션 파일 안에 "이 요약이 CLAUDE.md에 들어갈 정본"이라고 + 표시하는 마커 블록을 신설(**새로 요약을 쓸 필요 없음** — 지금 + `CLAUDE.md`에 이미 있는 압축 요약을 그대로 그 블록 안으로 옮기면 됨). + `CLAUDE.md` 쪽엔 대응하는 include 마커만 남기고, `doc-include.py --write`가 + 두 마커 사이 콘텐츠를 세션 파일에서 가져와 채움. + +## 마커 문법 (초안 — 사용자가 확정할 것) + +``` +# 세션 파일(.claude/session/2026-08-14-14-....md) 안: + +**2026-08-14 열네 번째 세션 — ...** (`session/2026-08-14-14-....md`) +... 2~4줄 압축 요약 ... + + +# CLAUDE.md "세션 히스토리" 절 안: + +(doc-include.py --write가 여기를 원본 summary 블록 내용으로 갱신) + +``` + +## 열린 질문 (사용자가 다듬을 것) + +1. 마커 문법 자체(위 초안 확정 여부, id 네이밍 규칙 — 날짜+세션번호로 + 충분한지). +2. 기존 세션 항목 전부(13개+)에 마커를 소급 삽입할지, 아니면 다음 + 세션부터 신규 항목에만 적용하고 과거분은 그대로 둘지. +3. `--write` 실행 시점 — 수동(세션 마무리 시 사람이 실행) vs 커밋 훅. + 이 레포는 지금 CI가 없고 사람이 `doc-check.py`도 수동으로 돌리는 + 관례라 같은 패턴(수동 + 커밋 전 확인)이 자연스러워 보이지만 확정은 + 사용자 몫. +4. `--check` 실패를 `doc-check.py`의 ERROR로 편입할지 별도 스크립트로 + 둘지. +5. 파일럿이 성공하면 다음 확대 후보 — `.claude/README.md` 표의 "상태" + 요약을 각 `base/`/`research/` 문서 맨 위 `**상태**: ...` 줄에서 + 추출해오는 것(단, `luau-test/STATUS.md`처럼 이미 "폴더 구조 자체가 + 상태"인 곳은 include로 바꿀 필요 없음 — 그쪽은 이미 소스가 하나로 + 수렴된 상태라 적용 대상 아님). + +## 우선순위 + +하 — M0/설계 게이트와 무관한 메타 도구. 사용자가 플랜을 다듬은 뒤 착수 +시점 결정. diff --git a/.claude/session/2026-08-14-14-corpus-audit-doc-include-backlog.md b/.claude/session/2026-08-14-14-corpus-audit-doc-include-backlog.md new file mode 100644 index 0000000..c3f775c --- /dev/null +++ b/.claude/session/2026-08-14-14-corpus-audit-doc-include-backlog.md @@ -0,0 +1,61 @@ +# 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.md` 3단계 분할(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번에 반영. 구현 착수는 아직 안 함. diff --git a/CLAUDE.md b/CLAUDE.md index 529e830..1b324fe 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -270,6 +270,10 @@ modifier/Ref의 컴포넌트 경계 통과 방식) 논의도 2026-08-04 세션 거기도 반복 안 함 — 소스는 `research/debounce-throttle-plan.md` 12절). 5. 자율 작업 루프/스케줄 설정 여부는 사용자 결정 대기 중 (`HUMAN_TODO.md` 2번 항목). +6. **[신규 백로그, 2026-08-14 열네 번째 세션]** 문서 stale 감소용 include + 도구 `doc-include.py`(가칭, `doc-check.py`와 짝) — `research/ + doc-include-plan.md` 참고. 플랜만 초안, **사용자가 내일 다듬을 + 예정**. M0/설계 게이트와 무관. ## 세션 히스토리 @@ -1450,3 +1454,19 @@ v1) Did` 등)은 톤이 안 맞아 기각, 사용자가 실제로 내걸고 싶 지연평가·재귀/커링·펑터·일급 익명 클로저 방향으로 `Quad Unwinds, Applies, Defers` 등 4개 후보 정리 — `research/quad-recursive-acronym.md` 신설(나중에 README.md 헤딩 후보용), 최종 문구는 미확정. + +**2026-08-14 열네 번째 세션 — 코퍼스 전체 사실관계 감사, `doc-include.py` +백로그 신설** (`session/2026-08-14-14-corpus-audit-doc-include-backlog.md`) +서브에이전트 4개 병렬(base/research+reference/luau-test+audit/archive+root)로 +전 코퍼스 재감사 — `bind-system-plan.md` 3단계 분할 후 stale 참조 11곳, +`HUMAN_TODO.md`의 `canBound` 재도입 미반영, 날짜 없는 완결 주장 4건 등 +13개 파일 20건 수정, `doc-check.py` ERROR 0 유지(커밋 `f829487`). 이어 +사용자가 반복된 stale 원인(같은 사실이 여러 곳에 중복 서술)을 근본적으로 +줄이는 방법으로 마커 기반 include 도구(원본에 요약 구간을 마커로 표시, +인용 문서가 기계적으로 추출해 붙여넣음)를 제안 — AsciiDoc tagged +include/markdown-magic이 선례임을 확인 후 build-vs-buy 논의, 문제가 좁고 +기존 도구는 새 Node/npm 의존성을 들여온다는 이유로 **직접 제작**(Python, +`doc-check.py`와 짝) 채택. 오늘은 플랜만 `research/doc-include-plan.md`로 +작성 — 파일럿은 부작용이 가장 작은 CLAUDE.md 세션 히스토리부터, 마커 +문법·소급 적용 범위 등 열린 질문은 **사용자가 내일 직접 다듬기로 함**, +구현 착수 안 함.