qwreey
540c142969
CLAUDE.md 관례대로 세션 로그 신설 + 압축 요약 추가. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Y6hzeUi5QdLPEk69B6cXFa
83 lines
5 KiB
Markdown
83 lines
5 KiB
Markdown
# 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 반영과 같은 패스).
|