docs: CLAUDE.md 4분할(매 세션 로드 1537→354줄), 워크플로 가짜 초록불 수정

## CLAUDE.md 분할
1537줄이라 (a) 사람이 검토 불가, (b) 공식 권장치(파일당 200줄) 7.7배
초과로 지침 준수도 자체가 저하, (c) 긴 파일 편집 시 에이전트 실수 증가.

  CLAUDE.md (39줄, 진입점)
  ├─ @.claude/conventions.md      언어/모델 관례 + 작업 방식
  ├─ @.claude/project-context.md  프로젝트 설명 + 문서 구조
  └─ @.claude/todos.md            지금 할 일
     .claude/session-summary.md   ← import 안 함(의도적, 온디맨드)

세션 히스토리 1231줄(전체의 80%)은 그 문서 스스로 "항상 읽을 필요 없음,
base/가 소스"라고 명시해온 색인이라 @import에서 뺐음. 내용 유실 없음
(1537→1647줄, 추가 헤더만큼 증가).

주의: @import는 컨텍스트를 줄이지 않음(전부 로드됨). 분할이 사는 건
사람 검토성 + 편집 정확도 + 파일 단위 자동생성 가능성.
CLAUDE.md 계열의 블록 HTML 주석은 주입 전 제거되므로 지시는 본문에 쓸 것.

## 워크플로 가짜 초록불 수정
첫 실측에서 감사 에이전트 6개 전원 실패했는데 converged:true가 나왔음
(전멸하면 fresh가 비어 "깨끗한 라운드"와 구분 불가). 감사 도구 최악의
실패 모드라 (1) 전멸이면 throw, (2) 반영 에이전트 실패 시 그 발견을
seen에서 빼 다음 라운드가 재시도하도록 수정.

## 부수
- 분할로 깨진 상호참조 20여 곳 정정(병렬 에이전트 3개).
  ref-plan.md:541의 사전 존재 오류(→ pre-implementation-audit 1-5)도 정정.
- doc-check.py: 새 파일 4개를 OURS에 등록(안 하면 깨진 참조가 WARN으로만
  잡힘), is_history()로 session-summary.md를 archive/와 같이 면제.
- doc-include-plan.md: 목적지가 통째로 생성되는 파일이 되면서 양방향
  마커 설계의 절반(목적지 마커)이 불필요해져 단방향 생성으로 단순화.

doc-check.py ERROR 0 유지.

미해결: session-summary.md 자동생성 미착수(91개 세션 파일 마커 삽입 필요),
orphan 인용 3건(modifier-plan.md:536, v1-compat-plan.md:50,
pre-implementation-audit.md:434 — 분할 이전부터 존재).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019HvEKn9f67kkx2nGLG8PsP

2026-08-16 01:35:02 +09:00

9.3 KiB

Raw Blame History

지금 할 일 (우선순위순)

루트 CLAUDE.md가 @import 하는 파일. 가장 자주 바뀜 — 해소된 항목은 미루지 말고 그 자리에서 지우고, 개수·목록은 여기 적지 말고 소스를 가리킬 것 (.claude/question.md, luau-test/STATUS.md 등).

⭐ M0 착수를 막는 결정은 이제 없음 (2026-08-14 열한 번째 세션 기준). question.md의 최우선 항목이 전부 비었음 — 0-Y(:Compute lazy 핸들 계약)는 13차 세션에, 0-Z(Attribute 이름 소유권)와 0-A(재디스패치 하강 diff)는 14차 세션에, 0-B(dispose 시그니처/범위)는 2026-08-14 열 번째 세션에 확정·base/ 반영 완료. 0-W(같은 Ref 이중 배치, M8 구현 세부만 막던 항목)도 2026-08-14 열한 번째 세션에 해소 — 선택지 (a) 채택(즉시 error), 메커니즘은 새 Relate 없이 bindLifetime/unbindLifetime 재사용(base/ref-plan.md "이중 배치 방지" 절). 부수 결정으로 canBound가 canExecute와 별도 진입점으로 재도입됨(2026-08-14 다섯 번째 세션에 하나로 합쳤던 걸 부분적으로 되짚음 — "이미 묶여 있는가"(bound 문맥)와 "지금 발화해도 되는가" (execute 문맥)는 판정 로직은 공유해도 호출부의 질문이 다르다는 사용자 지적, base/lifecycle-pattern.md의 "canBound vs canExecute" 절). question.md엔 이제 "결정 대기" 절 자체가 없음(비어서 헤딩째로 삭제).

M0 착수 전 반드시 읽을 것 — 이 두 개는 "결정"이 아니라 "구현 규약"이라 여전히 유효:
- base/typing-limits.md(0-Y의 산물) — 핵심은 "파생 State를 만드는 자리마다 결과 타입을 명시 주석으로 바인딩" + 7번 설계 체크리스트. 재귀 제네릭이 자기를 다른 타입 인자로 반환하면 Luau가 타입 안전성을 에러 없이 조용히 잃는 상위 한계라 quad 쪽에서 우회하지 않기로 확정(RFC relax-recursive-type-restriction 수혜 대기, 추적 luau-lang/luau#2380). 실측 근거는 audit/type-recursion-issue/.
- base/dispatch-core-plan.md(0-A/0-Z의 산물, 14차 세션에 bind-system-plan.md에서 분리 신설) — 재디스패치가 "철거 후 재구축"이 아니라 하강 diff임, retractFrom은 3-인자, 클로저 인자는 nil이거나 같은 핸들러가 처리할 값(타입 보장), HANDLER_PRIORITY_FALLBACK, "base가 소유하는 핸들러와 주입되는 엔진 op"(addTag/removeTag/ setAttribute). Handler 작성 체크리스트 8개를 새 핸들러 짜기 전에 훑을 것 — 지난 세션들에서 실제로 반복된 실수 목록임.
해소 전 원문은 archive/question-resolved.md(0-Y/0-Z/0-A 절), 뒤집힌 옛 재디스패치 모델 전문은 archive/dispatch-hintvalue-model-reversed.md.
구현 시작 — 루트 ROADMAP.md의 M0부터. 설계 단계는 2026-08-04 로드맵 인수인계 라운드로 종료. research/pre-implementation-audit.md 우선순위1은 2026-08-12 열일곱 번째 세션에 마지막 넷(1-3/1-4/1-10/1-11)까지 전부 해소되어 11개 전원 완료. [14차 세션 기준] 0-Y/0-Z/0-A까지 전부 해소돼 설계 게이트는 남아있지 않음 — 착수 전 읽을 것은 위 0번의 두 문서(typing-limits.md/dispatch-core-plan.md)뿐이고, 스파이크 상태는 아래 그대로:
- .claude/luau-test/(2026-08-09 신설, 2026-08-13 기준 20개) 스파이크 결과 — [2026-08-13 여섯 번째 세션에 첫 실측 완료, 대부분 닫힘]. 상태의 소스는 항상 .claude/luau-test/STATUS.md(pass / 사람 결정 필요 / 스파이크 깨짐 / 미실행, 폴더 구조 자체가 상태) — 몇 개가 지금 어느 폴더에 있는지는 여기서 나열 안 함(04/05/10/13/15/16/19가 여러 세션에 걸쳐 재설계로 rewrite-required/에 들고나며 이 문단의 나열이 매번 stale해지는 패턴이 반복됐음, 최근엔 8차 세션의 "emit은 항상 전파" 정정으로 05도 합류). 실행 결과 상세는 .claude/audit/luau-test-first-run-2026-08-13.md. 첫 실측 요지만 (역사적 사실 — 이후 변동은 위처럼 STATUS.md가 소스):
  - 런타임 12개 전원 통과(01~07/11/17/18/19/20, crash 0 / FAIL 0) — 특히 07이 연쇄 GC를, 18이 두-Relate 상호 순환 미해제를 실측 확정해 GC-native 아키텍처의 핵심 전제가 검증됨. 04는 같은 세션 감사가 찾은 chains:SetStrong 순서 버그를 음성 대조군으로 재현.
  - 타입 쪽에서 하나가 걸렸었음 → 그게 구 0-Y, [13차 세션] 해소(Luau 현 한계로 확정, base/typing-limits.md). 나머지 타입 스파이크는 판정 완료(08/09 통과, 12는 실패지만 문서가 이미 fallback으로 예비해둔 결과라 설계 영향 없음, 14는 부분). 지금 M0 착수를 막는 설계 결정은 없고, 0-Y/0-A가 남긴 규약 (base/typing-limits.md/base/dispatch-core-plan.md)은 착수 전 필독.
용어 정리 — 1차 제안 이후 대부분 확정, 소수만 남음. 최신 소스는 .claude/question.md 1번(개수 반복 안 함, 항목 추가/해소될 때마다 여기가 stale해지는 패턴이 반복됐어서). [2026-08-13 정정] State는 2026-08-12 스무 번째 세션에 현재 이름 그대로 유지로 이미 확정됐음(이 목록이 "위험도 높음, 1순위 open"으로 stale하게 남아있던 걸 발견해 수정) — 아직 진짜로 열려있는 것만 짚으면: DI→D(1순위), Slot(2순위), canExecute(3순위 — isAlive는 검토 후 기각, can 계열 접두 유지 방향으로 기울었으나 구체 대안 미정), Brand(3순위), Tag/Added/ Removed/Merged(3순위), Attribute/AttributeKey(3순위).
[2026-08-14 세션에 해소] 오래 열려 있던 "이미 생성된 인스턴스 재바인드"는 기각되어 archive/existing-instance-bind-rejected.md로 이전됨 — 더 이상 상의할 스코프 항목이 아님.
[백로그] 범용 렌더 디버깅 도구 quad-mock(Tween mock 등 동적 동작 지원, M0 mock 테스트 하네스와는 별개), 런타임 디버깅 플러그인 quad-debug(Studio 플러그인, 실물 Instance→코드 위치 역추적 — 채널 실현 가능성은 실측 검증 완료, 세부 API 이름만 남음), 문서 사이트 전체 구조(초심자/api/심화/quadnomicon 4축 + 콘텐츠 맵), Operator 콤비네이터 슈가(Sum/Product/Not/비트연산 등 :Compute/:Apply용 — 메커니즘은 확정, 네임스페이스 이름만 미정, 구현은 순수 슈가라 맨 마지막), 컴포넌트 에러 격리 유틸 Fallback/Traceback([2026-08-14 세션, 설계 확정 — research/에서 base/fallback-plan.md로 승격] pcall 기반 Fallback과 xpcall+debug.traceback 기반 Traceback으로 분리, err: any 확정, 패키지·이름 전부 확정 — 설계만 끝났을 뿐 구현 우선순위는 그대로 맨 뒤), 생명주기 훅 OnCreated/OnRendered/OnDestroyed([2026-08-14 아홉 번째 세션, research/에서 base/lifecycle-hooks-plan.md로 승격] 각각 PreRef/PostRef/Effect를 반환하는 순수 팩토리 함수 슈가 — OnRendered도 채택 확정, 그게 얹히는 PostRef 프리미티브 자체는 슈가가 아니라 디스패치 코어라 ROADMAP M8에서 PreRef와 같이 구현됨 (백로그가 아님, base/ref-plan.md의 "PostRef" 절). 훅 슈가 셋만 후순위) — 전부 "quad 개발 상당 부분 끝난 뒤"로 사용자가 못박은 후순위. 상세는 .claude/README.md의 base/ 표(fallback-plan.md/ lifecycle-hooks-plan.md)와 research/ 표 (debug-tooling-plan.md/documentation-plan.md/ documentation-content-map.md/framework-comparison-findings.md/ operator-sugar-plan.md). [2026-08-14 추가, 성격이 다름] 시간 기반 전파 게이트 Debounce/Throttle(research/debounce-throttle-plan.md)도 백로그이긴 하나 위 항목들과 달리 사용자가 직접 요청한 실제 기능 갭이고 순수 슈가가 아님 — M0/M3를 막지는 않지만, M3에서 Blocker를 구현할 때 게이티드 노드를 공용 Gate로 빼두는 것만은 그 시점에 해야 함(따로 하면 같은 설계를 두 번 함). 주입 op 2개(setTimeout/clearTimeout)가 백엔드 팩토리 표면에 추가될 예정이라는 것도 M1 설계 시 인지. 설계는 네 라운드로 대부분 확정됐고 남은 열린 질문은 question.md 3번(개수는 거기도 반복 안 함 — 소스는 research/debounce-throttle-plan.md 12절).
자율 작업 루프/스케줄 설정 여부는 사용자 결정 대기 중 (HUMAN_TODO.md 2번 항목).
[신규 백로그, 2026-08-14 열네 번째 세션] 문서 stale 감소용 include 도구 doc-include.py(가칭, doc-check.py와 짝) — research/ doc-include-plan.md 참고. 플랜만 초안, 사용자가 내일 다듬을 예정. M0/설계 게이트와 무관.

9.3 KiB Raw Blame History

지금 할 일 (우선순위순)

9.3 KiB

Raw Blame History