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.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-semantics.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 핸들러 분기 비용)이 핵심 논거. `bind-system-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/bind-system-plan.md` "왜 State 체인을 Modifier처럼 플래튼하지
  않는가" 절. State의 정의가 "캐싱하는 존재"라 다이아몬드 파생에서
  캐시 공유를 잃으면 `previous` 메커니즘이 막으려던 중복 계산 문제가
  재발한다는 게 핵심 논거.

## 다음 단계

셋 다 지금 당장 설계할 필요는 없음(`CLAUDE.md` "지금 할 일" 1번 —
구현 착수가 최우선). 사용자 판단이 필요한 것:
- 이걸 `.claude/question.md`/`CLAUDE.md`에 정식 백로그 항목으로 올릴지,
  아니면 이 파일 하나로 충분한지.
- 착수 시점 — quad-debug처럼 "개발 상당 부분 끝난 뒤"로 볼지, 아니면
  M1(스캐폴딩) 즈음부터 조금씩 곁들일지(네이밍 컨벤션은 특히 초기부터
  적용하는 게 나중에 소급 적용하는 것보다 쌀 수 있음 — 검토 필요).