diff --git a/.claude/session/2026-08-13-09-structure-and-guardrails.md b/.claude/session/2026-08-13-09-structure-and-guardrails.md new file mode 100644 index 0000000..5fbb63c --- /dev/null +++ b/.claude/session/2026-08-13-09-structure-and-guardrails.md @@ -0,0 +1,83 @@ +# 2026-08-13 아홉 번째 세션 — 구조 재편(luau-test/bind-system/question) + 재발 방지 도구 + +## 배경 + +직전 세션(8차 감사)이 끝난 뒤 사용자가 네 가지를 한 번에 요청 — 앞의 셋은 +**"사람이 읽을 수 없는 문서"** 라는 같은 뿌리의 문제이고, 넷째는 그 뿌리를 +없애는 방법에 대한 질문: + +1. `luau-test/`가 평평해서 "지금 볼 게 뭔지" 못 고르겠음 → 상태별 폴더로 +2. `bind-system-plan.md`가 3000줄이라 검토 불가 + 한 곳 실수의 파급이 큼 + → 쪼개도 되는지 판단 요청("이대로 둬야 해요?") +3. `question.md`에 해결된 게 많아 필터가 안 됨 → archive로 +4. **"이런 깊은 감사를 재발 방지하는 방법이 있나"** + +## 1. `luau-test/` — 폴더가 곧 상태 + +파일 21개를 4폴더로: `review-required/`(1, 사람 결정) / +`rewrite-required/`(3, 스파이크 코드가 깨짐) / `not-run/`(1+헬퍼, Studio 전용) / +`done/`(15). STATUS.md를 폴더 구조 그대로 재작성하고 **"파일을 옮기는 게 곧 +상태 갱신"** 을 규칙으로 명시. + +부수적으로 중요한 결정: 폴더가 상태라 파일이 옮겨 다니므로 **다른 문서는 +경로가 아니라 파일명으로 참조**하도록 6곳 정규화 — 안 그러면 상태를 바꿀 +때마다 링크가 깨져 stale이 또 쌓임. + +## 2. `bind-system-plan.md` 분할 — "쪼개되 반만, 나머지는 0-Z 반영과 같이" + +**판단**: 쪼개는 게 맞음. 근거는 사용자가 든 것 그대로(검토 불가 + 파급) 이고, +반대 근거였던 "인바운드 참조 253개"는 실측해보니 절 이름까지 지목한 건 +60곳뿐이라 감당 가능. + +다만 **전부 쪼개지는 않음**. 남은 두 덩어리(디스패치 코어 ~1000줄, 반응형 +코어 ~950줄)는 `question.md` 0-Z가 정해지면 **어차피 전면 재작성 대상**이라, +지금 옮기면 같은 텍스트를 두 번 만지고 인바운드 참조(~37곳)도 두 번 고쳐야 +함. 재작성하는 그 패스에서 파일을 가르는 게 총 변경량과 실수 위험이 모두 +작음 — `dispatch-redispatch-diff-plan.md` 6절에 그 지시를 넣어뒀음. + +**1단계(완료, 2989 → 2263줄)**: `ref-plan.md`(509) / `event-plan.md`(103, +사용자가 직접 지목) / `brand-plan.md`(137). 전부 **순수 이동, 결정 불변**. +이벤트 *네이밍* 관례만 인스턴스 생성과 한 절에 섞여 있어 쪼개면 양쪽이 +반토막 나므로 원위치 유지(그 사실을 `event-plan.md` 헤더에 명시). + +## 3. `question.md` — 사용자가 답할 것만 (525 → 279줄) + +`archive/question-resolved.md`에 분리 직전 전문을 보존하고, 본문은 +⭐최우선 2건(0-Y/0-Z) → 결정 대기 2건 → 용어 미확정 6건 → 낮은 우선순위 +5건만 남김. 통째로 해소된 옛 "0번(추가 프리미티브)"/"2번(구현 착수 직전 +감사)"과 맨 아래 확정 요약표(README와 중복)는 archive로. +**"항목을 해소하면 여기서 지우고 archive로 옮길 것"** 을 상단에 명시 — +이게 없으면 같은 문제가 다시 쌓임. + +인바운드 참조 보호를 위해 절 번호 1/3은 헤딩에 유지하고, 없어진 0번/2번을 +가리키던 2곳은 실제 원본으로 재지정. + +## 4. 재발 방지 — 규율 문서가 아니라 검사기 + +**진단**: 7·8차 감사에서 찾은 55건이 거의 전부 "변경한 세션이 그 자리에서 +안 한 일"이었고, 그중 상당수가 grep으로 잡히는 기계적 종류. 사람/에이전트의 +성실성에 기대는 규칙을 하나 더 쓰는 건 이미 실패한 방법(CLAUDE.md엔 이미 +"주기적으로 감사할 것"이 있었음). + +**`.claude/tools/doc-check.py` 신설** — 라이브 문서 61개에 대해 깨진 파일/절 +참조, README 색인 누락, 날짜 없는 시한부 주장, 미반영 배너를 한 번에 검사. +오탐 제거에 공을 들임(아직 없는 소스 트리 `.luau`, 읽기 전용 `initreq/`, +외부 문서명은 ERROR에서 제외 — 처음 돌렸을 때 232건이 나와 쓸모없었고, +정밀화 후 ERROR 1 / WARN 58로 수렴). + +**검사기가 같은 세션 안에서 실효를 증명함**: bind-system-plan.md를 쪼개며 +"이중 바인딩 금지" 절 참조 4곳을 `ref-plan.md`로 옮겼는데, 그 절은 실제로는 +Observer/Effect 쪽이라 **이동 대상이 아니었음** — 사람 눈으로는 못 잡았을 +실수를 스크립트가 즉시 잡아내 되돌림. 이 한 건이 도구의 존재 이유를 그대로 +보여줌. + +**CLAUDE.md에 중대 변경 핸드오버 체크리스트 6단계 명문화**: +doc-check 실행 → **부정당한 본문 문장 전수 grep**(배너만 달고 본문 방치가 +최다 실패 패턴) → 뒤집힌 원문은 archive로 → 개수/상태는 소스 하나만 → +시한부 주장엔 날짜 → 인덱스 레이어 3개 동시 갱신. + +## 남은 것 + +- `doc-check.py` WARN 58건 중 절 참조 불일치 51건은 대부분 "절 제목을 의역해 + 인용"한 관례라 판단이 필요 — 급하지 않지만 훑어서 진짜 깨진 것만 고칠 것. +- `bind-system-plan.md` 2단계 분할(0-Z 반영과 같은 패스). diff --git a/CLAUDE.md b/CLAUDE.md index 3ceb764..93daf7e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1003,3 +1003,20 @@ Slot 언마운트 전환 미반영 6곳. 뒤집힌 "폐기, 옮기지 않음 + p 달면 그 배너가 부정하는 *본문 문장*까지 같은 커밋에서 고쳤는지 확인할 것, (2) 영역 분할 감사는 "아무 영역에도 안 속한 파일"을 통째로 빠뜨리므로 레포 루트 파일 목록으로 커버리지를 먼저 체크할 것. + +**2026-08-13 아홉 번째 세션 — 구조 재편(luau-test/bind-system/question) + 재발 방지 도구** +(`session/2026-08-13-09-structure-and-guardrails.md`) +"사람이 읽을 수 없는 문서" 문제를 사용자가 세 건 지적하고 재발 방지법을 물음. +(1) `luau-test/`를 **상태별 폴더**로 재편(`done`/`review-required`/ +`rewrite-required`/`not-run`, 폴더 이동이 곧 상태 갱신 — 그래서 다른 문서는 +경로 아닌 **파일명**으로 참조하도록 정규화). (2) `bind-system-plan.md` +**1단계 분할**(2989→2263줄, `ref-plan.md`/`event-plan.md`/`brand-plan.md`로 +순수 이동) — 남은 디스패치·반응형 코어는 0-Z 반영 때 **어차피 전면 재작성** +대상이라 그 패스에서 같이 가르는 게 총 변경량·위험이 작다고 판단해 의도적 +연기(`dispatch-redispatch-diff-plan.md` 6절에 지시). (3) `question.md`를 +**사용자가 답할 것만**으로 축소(525→279줄, 해소분은 +`archive/question-resolved.md`). (4) 재발 방지는 규율 문서가 아니라 +**검사기**로 — `.claude/tools/doc-check.py` 신설(깨진 파일/절 참조, 색인 +누락, 날짜 없는 시한부 주장, 미반영 배너). **같은 세션에 실효 증명**: 분할 +중 "이중 바인딩 금지" 절 참조 4곳을 잘못 옮긴 걸 스크립트가 잡아내 되돌림. +CLAUDE.md "작업 방식"에 중대 변경 핸드오버 체크리스트 6단계도 명문화.