qwreey-bot/quad
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
quad/ROADMAP.md
qwreey 4b839b09e1
문서 사이트 구조/quadnomicon 신설, 프레임워크 정직 비교, Source가 State를 만족하는 서브타입 재구성 
세 갈래 작업:

1. 문서 사이트 구조 확정(초심자/api/심화 3축 + quadnomicon 4번째 축) —
   research/documentation-plan.md 0번 항목, research/documentation-content-map.md
   신설(초심자 core loop 목차 초안, 파일별 분류, 심화 에세이 후보 15개).

2. quad vs Fusion/Vide/react-lua 정직 비교 — research/framework-comparison-findings.md
   신설. 3개 에이전트가 실제 소스(Fusion/Vide 로컬 클론)+웹 리서치(react-lua)로
   검증. quad 강점(Slot 단일 마운트 가드, 열린 우선순위 축, 명시적 의존성,
   다이아몬드 dedup)과 고칠 만한 약점 식별.

3. Source가 State를 구조적으로 만족하는 서브타입으로 재구성(핵심 변경) —
   store.key 타입 문제(레코드 타입 읽기/쓰기 비대칭)를 풀다가 StoreSource
   프록시 설계(2026-08-04 확정분)를 완전히 대체:
   - Source<T>가 State<T>를 구조적으로 만족(단방향 호환), Store는
     "이름 붙은 Source 모음"으로 단순화 — 별도 wrapper 생성/캐싱 불필요
   - store.key = value(__newindex) 폐기 → store.key:Set(value)
   - Store:Emit(key) → source:Emit()
   - base/store-semantics.md에 새 절로 반영, bind-system-plan.md/
     component-composition-plan.md/architecture.md 정정
   - ROADMAP.md M0에 Luau 솔버 검증 항목 추가(재귀 타입 조합)
   - 폐기된 StoreSource 원문은 archive/store-source-proxy-reversed.md에
     역전 이유·신구 비교와 함께 보존(quadnomicon 소재 후보)

전체 코퍼스 stale 참조 재점검: architecture.md 요약절, README.md 승격 누락,
Modifier UB 규칙 확장 등 발견해서 수정.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-06 21:29:56 +09:00

6.4 KiB
Raw Blame History

ROADMAP.md

quad-v2 구현 단계 실행 계획. 설계 근거/아키텍처 자체는 여기 안 옮겨적음 — .claude/base/가 소스, 여긴 순서와 진행 상황만. 마일스톤 시작할 때 체크박스를 세분화해서 늘려도 되고, 끝나면 체크만 하면 됨 — 살아있는 문서.

2026-08-04 세션에 준비만 해둔 상태 — 아직 M0도 시작 안 함. 다음 세션은 바로 M0부터.

M0 — 스켈레톤 + 기술검증 (스파이크, "진짜" 마일스톤 아님)

최종 소스 트리를 그대로 만들기 전에, 지금까지 추론만으로 확정하고 실제 Luau 코드로 부딪혀본 적 없는 세 가지를 던지는 코드로 검증하는 단계 — .claude/base/ 감사에서 나온 결론(2026-08-04). 여기서 뭔가 어긋나면 architecture.md/bind-system-plan.md 등을 이 시점에 고치는 게 정상 — 실패가 아니라 이 단계의 목적.

  • Store/State push-invalidate → pull-recompute propagation을 실제로 짜보기(다이아몬드 의존성 케이스 포함 — 이미 invalid면 전파 중단되는지)
  • Source가 State를 구조적으로 만족하는 제네릭 타입(:Compute<U>(self: Source<T>, ...) -> State<U>류, self 타이핑 + State 참조 혼합)이 Luau 솔버에서 안전하게 추론되는지 확인(2026-08-06 후속 세션, base/store-semantics.md "Source가 State를 만족함" 절 — State<T>가 Source를 참조하지 않는 단방향 의존으로 두면 위험한 상호 재귀는 피할 수 있어 보이나 실제 검증 전엔 확정 아님)
  • process/retract 재귀 재-process 디스패치를 실제로 짜보기(store-bind 핸들러 하나 + isHandlable 우선순위 스캔 포함)
  • props.Modifier/props.Ref named-parameter로 받는 컴포넌트 하나 작성, export type Params = {...}로 타입 체크되는지 확인 (component-composition-plan.md 최종 결론 1번)
  • 위 과정에서 소스 트리/메커니즘 문서에 고칠 부분이 생기면 그 자리에서 .claude/base/ 갱신

통과 기준: 세 개 다 Luau에서 자연스럽게 짜이는 게 확인되면 M1 진행. 안 되면 여기서 관련 base/ 문서부터 고치고 재시도.

M1 — 실제 스캐폴딩

  • quad-base/, quad-roblox/ 폴더 + 각 wally.toml
  • 루트 default.project.json, .luaurc(architecture.md "구현 착수: 소스 트리 구조 확정" 절 그대로)
  • quad-base용 최소 mock 테스트 하네스(Vide test/mock.luau 선례, 순수 luau CLI, architecture.md "테스트 전략" 절 참고)
  • 이 시점부터 .claude/qa-request//.claude/archive/ 폴더 실사용 시작

M2 — 디스패치 엔진

  • Dispatch/init.luau(process/retract 엔진, isHandlable 우선순위 스캔)
  • Handler.luau(핸들러 계약 타입)
  • mock 대상 테스트

M3 — Store/State/Source

  • Source.luau/State.luau/Store.luau
  • store.key dot-access 타입 추론 확인
  • mock 대상 테스트

M4 — 첫 end-to-end 반응형 업데이트

  • Dispatch/StoreBind.luau(재귀 재실행 로직, 엔진 무관)
  • mock 대상으로 "store 값 바꾸면 process가 다시 호출된다" 확인

M5 — quad-roblox 최소 프로바이더

  • RobloxFactory.luau(BaseModule 뮤테이션, 재호출 가드)
  • DI/init.luau(제네릭 생성자 + ~25개 정적 필드)
  • Handlers/Property.luau, Handlers/InstanceChild.luau
  • 실제 Roblox에서 첫 Frame{...} 렌더 확인 — Studio 작업이라 HUMAN_TODO.md 1번(계정 분리) 먼저 되어야 진행 가능, SAFETY.md 준수

M6 — Slot

  • "여러 Slot이 형제로 섞일 때 순서 보장" 열린 질문 확인(slot-plan.md) — Roblox 단일 백엔드로는 급하지 않으면 스킵하고 진행 가능
  • base Dispatch/Slot.luau(추상 재조정) + quad-roblox Handlers/Slot.luau (실제 Parent 조작)

M7 — Modifier

  • flatten-before-dispatch, immutable table.clone 체이닝
  • Modifier.Merge(가칭)
  • State<Modifier> 조합 타입 차단 확인(modifier-plan.md 7번, UB 확정)

M8 — Ref

  • CreatedRef 메커니즘(숫자 슬롯 참가자)
  • LifetimeHandle 인터페이스 + quad-roblox 실제 구현(Instance 생존 확인)
  • PerInstanceState 인터페이스 + quad-roblox 실제 구현(weak-keyed table)

M9 — 컴포넌트 합성 레이어

  • 플레인 함수 컴포넌트 관례 문서화/예제
  • props.Modifier/props.Ref 전달 관례를 정식 컴포넌트로 검증(M0 스파이크를 정식화)

M10 — Event / Attribute / Tag

  • Handlers/Event.luau(ReflectionService 기반 자동 판별)
  • Handlers/Attribute.luau
  • Handlers/Tag.luau(CollectionService)

M11 — Tween

  • research/tween-plan.md 남은 옵션 이름 확정(구조는 이미 확정)
  • Handlers/Tween.luau(높은 우선순위 store-bind 핸들러, 기본 오버라이드 Cancel)

특정 마일스톤에 안 묶이고 병행 가능

  • 용어 정리 스윕 — State/DI/PerInstanceState/Slot 등 (.claude/question.md 1번), 최종 이름 확정되는 대로 아무 시점에나
  • 각 마일스톤 완료 시 .claude/qa-request//.claude/archive/에 기록, 필요하면 CLAUDE.md "최근 세션 요약"도 갱신

백로그 (스코프 밖 — 필요성이 실제로 드러나면 그때 설계)

  • research/existing-instance-bind-plan.md — Modifier 정적 flatten과 긴장 관계 있음, 재검토 시 그 문서부터 다시 볼 것
  • 범용 렌더 디버깅 도구로서의 quad-mock(Tween mock 등 동적 동작 포함, M1의 quad-base 테스트용 mock과는 별개)
  • quad-debug/quad-debug-roblox-plugin — 실물 Instance→코드 위치 역추적 Studio 플러그인(research/debug-tooling-plan.md). 위 quad-mock과 목적이 다름(오프라인 검증 vs 실시간 라이브 관찰) — 단 trace 이벤트 스키마를 공유할 여지는 있음, 그 문서 참고. M2/M3/M5 구현 시 훅 확장 지점만 고려해두면 이 항목 자체는 지금 착수 불필요.
  • v1 마이그레이션 가이드 + objectListClass.__newIndex 오타 기능 재현 테스트
  • Slot 형제 순서 보장(다중 백엔드 관점) — Roblox만이면 급하지 않음