quad/.claude/session/2026-08-13-09-structure-and-guardrails.md

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