qwreey
936e0766b7
- 이벤트 핸들러 self(Instance) 관습 비채택 확정 (Ref로 충분, Modifier 정적 flatten과의 충돌, quad-debug 추적성, 클로저 비용) - rbvm GC 패턴이 실물 검증됐다는 근거 보강 (lifecycle-pattern.md) - .claude 코퍼스 전체 stale 참조/모순 감사 및 정리 - Store:Emit(key) 확정 (Source 원천 한정, clone 불가 userdata 우선 근거) - :Compute(fn, previous) 확정 (무거운 파생 객체 재사용, full diff 필수) - state:Observer(fn) 확정 (children 배열에 직접 놓는 leaf 값, canExecute 게이팅) - Ref 일반화 확정 (범용 값 박스, 반복 재설정 가능, State와 달리 non-lazy) - CLAUDE.md 핸드오버 갱신 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
89 lines
5.9 KiB
Markdown
89 lines
5.9 KiB
Markdown
# 문서화 전략 계획 (뼈대만)
|
|
|
|
**상태**: 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 한정 설명으로 둘지, 다른 백엔드 구현자를
|
|
위한 일반 가이드로도 남길지는 미정.
|
|
- 어느 문서에 넣을지 — 퀵스타트? 위 1번 네이밍 컨벤션 문서와 마찬가지로
|
|
아직 미정.
|
|
|
|
## 다음 단계
|
|
|
|
셋 다 지금 당장 설계할 필요는 없음(`CLAUDE.md` "지금 할 일" 1번 —
|
|
구현 착수가 최우선). 사용자 판단이 필요한 것:
|
|
- 이걸 `.claude/question.md`/`CLAUDE.md`에 정식 백로그 항목으로 올릴지,
|
|
아니면 이 파일 하나로 충분한지.
|
|
- 착수 시점 — quad-debug처럼 "개발 상당 부분 끝난 뒤"로 볼지, 아니면
|
|
M1(스캐폴딩) 즈음부터 조금씩 곁들일지(네이밍 컨벤션은 특히 초기부터
|
|
적용하는 게 나중에 소급 적용하는 것보다 쌀 수 있음 — 검토 필요).
|