quad/.claude/research/documentation-plan.md

문서화 전략 계획 (뼈대만)

상태: research — 매우 초기. research/debug-tooling-plan.md 논의 (2026-08-06) 도중 파생된 두 아이디어를 별도로 트래킹할 가치가 있다고 판단해 뼈대만 기록해둠. 세부 설계는 없음, 착수 시점도 미정 — 사용자가 "간단히 plan 작성은 하는 게 맞을 듯, 아주 뼈대만 있는 것이라 할지라도 적어줄 필요는 있겠다"고 판단해서 만든 문서. 같은 날 후속 세션에서 이벤트 핸들링 self 관습 논의가 확정되며 3번 항목이 추가됨. 별도 세션 (날짜 미상, 다음 세션이 채워 넣을 것)에서 전체 문서 사이트 구조 논의가 추가돼 0번 항목으로 들어감.

0. 전체 문서 사이트 구조 — 3축 + 백엔드별 트랙 분리 (확정, 착수는 여전히 후순위)

축 구조 확정: 초심자(getting started, 전반적 패턴을 실행 가능한 예제로) / api(레퍼런스, 노출 표면 전부를 빠르게 훑어보기 용) / 심화(왜 quad가 그렇게 설계됐는지 기술적 근거, 최적화·대규모 코드베이스 관리 관심자용) 3축으로 관리. Diátaxis 프레임워크(tutorial/reference/ explanation)와 사실상 동형 — 검증된 패턴이라 그대로 채택. 원래 4분면인 Diátaxis의 "how-to guides"(태스크 지향 레시피)에 해당하는 콘텐츠는 별도 축을 새로 만들지 않고 초심자 트랙 안에 녹이기로 함(아래 "초심자 스코프" 참고, 2번 항목의 "Store 부작용 패턴" 문서가 대표 사례).

초심자 문서 스코프 — "core loop 완주에 필요한 최소 집합만": 프리미티브(Source/State/Modifier 등)와 그 주요 파생 데이터 입력값 정도는 처음부터 가르치기 쉬움(quad엔 가상 DOM이 없어서 개념 자체가 단순함). 반면 Compute의 previous 인자, Observer, Store :Emit, 이벤트 store-bind, Slot 형제 순서 같은 건 "필요해지면 찾아보는" 것으로 api/심화에 위임 — 처음부터 노출하면 core loop이 흐려짐. 로블록스 스크립팅 유저 간 실력 편차가 큰 문제는, 초심자 트랙 자체를 짧고 선형으로 유지하면서 각 개념 옆에 api/심화로 새는 링크를 촘촘히 박아두는 방식으로 대응 — "쉬운 버전/어려운 버전"을 따로 쓰지 않고 한 문서 안에 탈출구를 많이 두는 쪽.

초심자 문서에 quad-base/quad-roblox 분리를 노출하지 않기로 확정: 지금은 백엔드가 quad-roblox 하나뿐이라, 초심자에게 "이건 base 프리미티브, 이건 roblox 전용"이라고 구분해서 가르치면 실행도 안 해본 추상 개념부터 마주치게 됨 — 대신 Source/State/Modifier 등을 전부 구체적인 Roblox 코드(Frame 만들기 등) 안에서 자연스럽게 등장시키고, 엔진 무관하다는 사실은 각주 정도로만 언급. 이 구분이 실제로 값어치를 하는 곳은 (a) api 문서 — 패키지별로 quad-base 페이지/quad-roblox 페이지를 나눠 "이 함수가 어디서 왔는지" 룩업 가능하게, (b) 심화 문서 — base/roblox를 왜 쪼갰는지 설계 근거 자체가 콘텐츠.

백엔드별 튜토리얼은 필요해질 때 추가 — 지금 설계 불필요: 초심자 문서는 메이저 버전업이나 개명 수준이 아니면 거의 안 바뀌는 성격이라, 나중에 quad-web/love2d 등 실제로 다른 백엔드가 분리되어 나올 때 그 사용자들을 위한 튜토리얼을 그때 가서 추가하면 됨 — 이벤트 핸들링 모델도 다르고 Tween처럼 아예 없는 백엔드도 있을 수 있어 지금 추상 개념을 먼저 가르치려 하면 없는 공통분모를 억지로 만드는 셈이라 오히려 나쁨. 즉 초심자 트랙은 백엔드별로 완전히 분리된 트랙(지금은 quad-roblox 하나)으로 구조화하고, "quad 코어가 뭔지"는 심화에서만 다룸.

착수 시점: 위 1~3번 항목과 동일하게 지금 당장 설계/작성할 필요는 없음(.claude/todos.md 1번 — 구현 착수가 최우선). 이 0번 항목은 "만약 시작한다면 이런 구조로"에 대한 합의이지, 착수 신호는 아님.

콘텐츠 분류 완료(2026-08-06): 위 3축을 실제로 뭘로 채울지 .claude/base/*.md 전체 + 관련 research/*.md(tween-plan, ui-shorthand-plan)를 초심자/api/심화/skip으로 서베이한 결과는 research/documentation-content-map.md 참고 — 초심자 core loop 목차 초안, 파일별 상세 분류, 심화 전용 신설 콘텐츠 후보(14개 에세이 소재), 아직 미확정이라 문서화 보류해야 할 항목까지 정리됨. api 항목은 간략 설명 + 심화로 "더 알아보기" 링크를 다는 패턴(사용자 확정)도 그 문서에 반영.

4번째 축 신설 — quadnomicon(2026-08-06, 같은 세션 후속): 콘텐츠 분류 중 "심화"로 분류하기엔 성격이 다른 두 갈래가 섞여 있는 게 드러남 — (a) Fusion/Vide 내부 구현 비교, 다른 프레임워크 선례 조사처럼 "quad를 깊게 이해해 최적화하려는 사용자"가 아니라 "비슷한 프레임워크를 직접 설계/포크 하려는 엔지니어"를 위한 콘텐츠, (b) 세션별 정정 이력/조사 원자료처럼 애초에 공개 문서화 대상이 아닌 내부 설계사. (b)는 새 티어도 필요 없이 그냥 .claude/ 내부 설계 기록으로 남고 절대 publish 안 함(Rust로 치면 rust-lang/rfcs 저장소처럼 raw 상태로만 존재). (a) 중 잘 다듬은 소수만 Rustonomicon 패러디 이름 quadnomicon으로 새 4번째 축에 publish — 독자층은 quad 사용자가 아니라 프레임워크 설계 자체에 관심 있는 엔지니어. 이름은 사용자가 여러 후보(quadnomicon/심해/해구/흑마법서) 중 직접 확정.

GC처럼 quad 고유 내용은 아니지만 배경지식 자체가 깊은 주제 처리 방침: 새 티어를 안 만들고, "quad가 GC를 어떻게 활용하는가"(quad 고유)는 심화에 그대로 남기되 "GC란 무엇인가" 자체는 자체 튜토리얼을 쓰지 않고 외부 좋은 자료로 링크 처리하는 쪽으로 방침 확정 — 안 그러면 문서 프로젝트가 일반 프로그래밍 교육 쪽으로 스코프 크리프될 위험이 있다는 판단.

1. UI 요소 네이밍 컨벤션 문서

배경: quad-debug 논의 중 사용자가 직접 겪은 pain point로 드러남 — Roblox가 Play 중 라이브 UI 편집 도구를 꺼버려서 실제 화면의 UI 요소 위치를 찾으려면 Explorer를 계속 펼치고 접어야 하는데, quad로 만든 요소는 보통 이름을 잘 안 지정해서 특히 힘들다는 지적(debug-tooling-plan.md "핵심 설계 방향" 8번, Element Inspector로 부분 완화 예정이지만 근본적으로는 좋은 네이밍 습관이 있어야 함).

뼈대(아직 설계 아님, 물음표만):

• 어떤 단위에 이름을 붙이게 유도할까 — 모든 Frame? 컴포넌트 루트만?
• 자동 이름 부여 옵션이 있으면 좋을까(예: 컴포넌트 함수 이름을 기본 Name으로 쓰는 관례 — 있으면 편하지만 매직에 가까워 "마법 안 쓴다" 원칙과 긴장 있을 수 있음, 검토 필요).[정정: 인용 위치 정정 — architecture.md 2번(함수형 vs OOP 논의)이 아니라 base/component-composition-plan.md §1("컴포넌트 = 그냥 함수, '자기 store 자동 소유' 매직은 폐기")의 사용자 확정 "마법 안쓴다 그것도 동의함" 발언이 근거임]
• 어디에 문서화할까 — 퀵스타트 튜토리얼? 별도 스타일 가이드? 린트 규칙으로 강제할까(과한 선택지, 참고만)?

구체적으로 결정된 하위 규칙 하나(2026-08-06): quad가 내부적으로 자동 생성하는 helper Instance(예: base/ui-shorthand-plan.md의 UICorner/UIPadding/UIScale 숏핸드가 만드는 자식)는 _나 QUAD_ 같은 접두어를 붙여 Explorer에서 직접 볼 때 사용자가 만든 것과 헷갈리지 않게 함 — v1의 _quad_round류 네이밍 재사용(research/debug-tooling-plan.md "핵심 설계 방향" 9번과도 연결, 플러그인이 Explorer 선택을 자기 트리와 동기화할 때도 이 구분이 필요함). 이건 "사용자가 자기 컴포넌트에 이름을 잘 붙이게 유도"하는 위 물음표들과는 별개로 이미 결정된 사항.

2. Store 부작용을 게임 시스템에서 깔끔하게 쓰는 패턴 문서

배경: quad의 Store는 부작용 허용이 기본 설계(base/architecture.md, base/store-plan.md에서 확정)인데, 실제 게임 개발(스킬, 쿨타임, 재화 같은 도메인 상태를 담당하는 store, 부분별 모듈화 등)에서 이 자유도를 깔끔한 패턴으로 쓰는 법이 아직 문서화 안 됨 — 사용자 원 발언: "원래 의도했던 편한 부작용 허용을 좀더 더럽지 않은 패턴으로 수행하는 방법도 적절한 문서화 계획이 있어야겠습니다".

뼈대(아직 설계 아님, 물음표만):

• 예제 도메인으로 스킬/쿨타임/재화 같은 흔한 게임 시스템을 다룰 것으로 보임 — 실제 예제 코드까지 만들지, 원칙만 서술할지 미정.
• base/purity-and-effects-plan.md(컴포넌트 "이식성" 경고)와는 성격이 다름 — 그쪽은 "이러면 재사용성이 깨진다"는 경고 문서고, 이건 "그래도 부작용을 쓸 거면 이렇게 하면 덜 지저분하다"는 처방 문서. 둘을 같은 문서에 합칠지 분리할지는 미정.
• 안티패턴 vs 권장 패턴 대조 형식이 적당할지, 다른 형식이 나을지도 미정.

3. 권장 이벤트 핸들링 패턴 문서 (2026-08-06 추가)

배경: 이벤트 핸들러가 self(Instance)를 받지 않기로 확정된 결정 (base/event-plan.md "이벤트 핸들러는 self(Instance)를 받지 않는다" 절)의 근거가 꽤 비직관적임 — v1을 써본 사용자는 self가 없어진 걸 보고 "왜 없어졌지, 불편한데"라고 느낄 수 있어서 근거까지 같이 문서화할 가치가 있음.

뼈대(아직 설계 아님, 물음표만):

• **"왜 thin wrapper를 안 주는가"**를 설명하는 절 — 메모리 낭비(클로저 래핑 비용)와 오버엔지니어링(Modifier 정적 flatten과 경쟁하는 두 번째 쓰기 경로, KV 핸들러 분기 비용)이 핵심 논거. base/event-plan.md의 결정문을 그대로 요약하면 될 듯.
• 권장 이벤트 핸들링 패턴 자체 — Instance가 필요하면 Ref로 캡쳐해서 쓰는 예제, Store/Source를 만들고 State로 파이핑되는 초기점을 바꿔가며 반응형을 구현하는 게 더 일관된 흐름이라는 사용자 원 논지를 코드 예제로 보여주는 게 좋아 보임.
• 일반화된 원칙("엔진이 네이티브로 콜백에 뭘 주든 그대로 호출해줘도 무방하다")을 quad-roblox 한정 설명으로 둘지, 다른 백엔드 구현자를 위한 일반 가이드로도 남길지는 미정.
• 조건부 이벤트 처리 — 기본 패턴 vs store-bind, 대조해서 보여줄 것 (2026-08-06 추가). "핸들러 하나 계속 연결 + 내부에서 store.enabled:Get() 분기"가 기본 권장 패턴이고, 이벤트 store-bind(false로 disconnect, event-plan.md "이벤트도 store-bind 가능" 절)는 고빈도 신호나 로직 자체가 바뀌는 드문 케이스를 위한 부차적 옵션이라는 점을 코드 대조로 보여줄 것 — quad가 미는 디자인은 전자, 후자는 "이럴 수도 있다" 정도로만 소개.
• 어느 문서에 넣을지 — 퀵스타트? 위 1번 네이밍 컨벤션 문서와 마찬가지로 아직 미정.

4. 심화 문서 소재 후보 (누적, 2026-08-06 추가)

설계 논의 중 "이건 왜 이렇게 안 했는가/이렇게 했는가" 식으로 나온 세세한 근거들 중, 나중에 0번 항목의 "심화" 축에 넣을 만한 것들을 누적 기록. 지금 당장 문서를 쓰라는 뜻 아님 — 원 결정문은 각 base/ 문서에 이미 있으므로 여기선 소재 제목과 위치만 남김:

• 왜 State 체인을 Modifier처럼 플래튼하지 않는가 — 결정문은 base/source-state-plan.md "왜 State 체인을 Modifier처럼 플래튼하지 않는가" 절. State의 정의가 "캐싱하는 존재"라 다이아몬드 파생에서 캐시 공유를 잃으면 previous 메커니즘이 막으려던 중복 계산 문제가 재발한다는 게 핵심 논거.

다음 단계

셋 다 지금 당장 설계할 필요는 없음(.claude/todos.md 1번 — 구현 착수가 최우선). 사용자 판단이 필요한 것:

• 이걸 .claude/question.md/.claude/todos.md에 정식 백로그 항목으로 올릴지, 아니면 이 파일 하나로 충분한지.
• 착수 시점 — quad-debug처럼 "개발 상당 부분 끝난 뒤"로 볼지, 아니면 M1(스캐폴딩) 즈음부터 조금씩 곁들일지(네이밍 컨벤션은 특히 초기부터 적용하는 게 나중에 소급 적용하는 것보다 쌀 수 있음 — 검토 필요).