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

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

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

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(예: research/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/bind-system-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, bind-system-plan.md "이벤트도 store-bind 가능" 절)는 고빈도 신호나 로직 자체가 바뀌는 드문 케이스를 위한 부차적 옵션이라는 점을 코드 대조로 보여줄 것 — quad가 미는 디자인은 전자, 후자는 "이럴 수도 있다" 정도로만 소개.
• 어느 문서에 넣을지 — 퀵스타트? 위 1번 네이밍 컨벤션 문서와 마찬가지로 아직 미정.

다음 단계

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

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