qwreey
bc0a8b9f5f
- research/debug-tooling-plan.md 신설: 런타임 디버깅 플러그인 quad-debug 설계 — BindableEvent/Function이 Studio 플러그인↔Play 중 게임 경계를 넘는지 실측 검증 완료, 채널 위치/페이로드 제약/UUID 기반 on-demand compute/Element Inspector/Explorer-플러그인 트리 동기화까지 정리 - research/ui-shorthand-plan.md 신설: v1 Corner/PaddingAll/Scale 인라인 숏핸드 조사, quad-v2 포팅 확정(RoundSize만 네이티브 UICorner로 대체돼 불필요), quad-roblox 코어 직접 포함 원칙 확정 - research/documentation-plan.md 신설: UI 네이밍 컨벤션 + Store 부작용을 게임 시스템에서 쓰는 패턴 문서화 뼈대 - base/bind-system-plan.md: Attribute 특수 키 타입 파라미터화 신규 논의 추가 - base/modifier-plan.md, README.md, question.md, ROADMAP.md, CLAUDE.md: 위 신규 문서 색인/요약 반영 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
4.1 KiB
문서화 전략 계획 (뼈대만)
상태: research — 매우 초기. research/debug-tooling-plan.md 논의
(2026-08-06) 도중 파생된 두 아이디어를 별도로 트래킹할 가치가 있다고
판단해 뼈대만 기록해둠. 세부 설계는 없음, 착수 시점도 미정 — 사용자가
"간단히 plan 작성은 하는 게 맞을 듯, 아주 뼈대만 있는 것이라 할지라도
적어줄 필요는 있겠다"고 판단해서 만든 문서.
1. UI 요소 네이밍 컨벤션 문서
배경: quad-debug 논의 중 사용자가 직접 겪은 pain point로 드러남 —
Roblox가 Play 중 라이브 UI 편집 도구를 꺼버려서 실제 화면의 UI 요소
위치를 찾으려면 Explorer를 계속 펼치고 접어야 하는데, quad로 만든 요소는
보통 이름을 잘 안 지정해서 특히 힘들다는 지적(debug-tooling-plan.md
"핵심 설계 방향" 8번, Element Inspector로 부분 완화 예정이지만 근본적으로는
좋은 네이밍 습관이 있어야 함).
뼈대(아직 설계 아님, 물음표만):
- 어떤 단위에 이름을 붙이게 유도할까 — 모든 Frame? 컴포넌트 루트만?
- 자동 이름 부여 옵션이 있으면 좋을까(예: 컴포넌트 함수 이름을 기본
Name으로 쓰는 관례 — 있으면 편하지만 매직에 가까워architecture.md2번의 "마법 안 쓴다" 원칙과 긴장 있을 수 있음, 검토 필요). - 어디에 문서화할까 — 퀵스타트 튜토리얼? 별도 스타일 가이드? 린트 규칙으로 강제할까(과한 선택지, 참고만)?
구체적으로 결정된 하위 규칙 하나(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 권장 패턴 대조 형식이 적당할지, 다른 형식이 나을지도 미정.
다음 단계
둘 다 지금 당장 설계할 필요는 없음(CLAUDE.md "지금 할 일" 1번 —
구현 착수가 최우선). 사용자 판단이 필요한 것:
- 이걸
.claude/question.md/CLAUDE.md에 정식 백로그 항목으로 올릴지, 아니면 이 파일 하나로 충분한지. - 착수 시점 — quad-debug처럼 "개발 상당 부분 끝난 뒤"로 볼지, 아니면 M1(스캐폴딩) 즈음부터 조금씩 곁들일지(네이밍 컨벤션은 특히 초기부터 적용하는 게 나중에 소급 적용하는 것보다 쌀 수 있음 — 검토 필요).