# 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 반영과 같은 패스).