quad/.claude/conventions.md

# 관례와 작업 방식

이 파일은 루트 `CLAUDE.md`가 `@import` 하므로 **매 세션 컨텍스트에 로드된다**
— 늘리기 전에 "정말 매 세션 필요한가"를 따질 것. 세션마다 필요하진 않은
상세는 `.claude/` 아래 개별 문서로.

<!-- 참고: CLAUDE.md 계열 파일의 블록 HTML 주석은 컨텍스트 주입 전에 제거된다.
     즉 여기 주석으로 쓴 것은 에이전트가 못 본다 — 지시는 반드시 본문에 쓸 것. -->

## 언어/모델 관례 (기존 메모, 유지)

사용자는 한국 유저임을 유의해. 사용자가 보게 될 것은 한국어로 띄워주는 게
좋아. 너가 보는 것들(코드 주석 등)은 원하는 언어여도 되는 것(가장 성능이 좋을
영어를 쓰든 그래도 됨, 예를 들어 이 문서도 영어여도 무방하지만 지금은
한국어로 유지). 사용자가 검토해야 하는 것(plan, backlog 등)은 한국어로 써.
코드 안 주석은 공식성을 유지하기 위해 굳이 한국어일 필요 없음, 영어 가능.

또 토큰 맥싱에 유의해 — 아주 작은 테스크라 충분히 작은 모델이 쓸 수 있으면
haiku, 일반 작업은 sonnet. 특히 소스코드를 많이 읽어야 하는 리서치는 메인
컨텍스트를 부패시키니 Agent로 위임할 것(아래 "작업 방식" 참고).

## 작업 방식

- **소스코드를 많이 읽어야 하는 리서치는 Agent(Explore)로 위임** — 메인
  컨텍스트 보호. 이미 완료된 v1/rbvm/tbox/Fusion/Vide 리서치 결과는
  `.claude/base/`에 정리되어 있으니 중복 조사하지 말고 먼저 그걸 볼 것.
- **병렬화 가능한 작업은 Agent 여러 개를 한 메시지에 동시 호출.** 서로 독립적인
  파일/주제를 다루는 리서치나 구현 조사, 또는 서로 다른 문서 파일을 고치는
  문서 정리 작업이 여기 해당(단, 같은 파일을 동시에 고치는 에이전트를 병렬로
  띄우지 말 것 — 충돌함).
- **크리티컬한 설계 결정은 구현으로 밀어붙이지 말고 plan을 research/에 남긴 채
  연기.** 사용자는 Lua/Roblox 엔진을 깊이 아는 사람 — 근거와 선택지를 문서에
  정리해두면 사용자가 깨어있을 때 훑어보고 답해줄 것. `.claude/question.md`에
  반드시 반영.
- **작업이 끝나면(또는 방향이 바뀌면) 항상 자기 문서화** — 완료된 걸 다시
  조사하게 되는 재작업을 막기 위함. `.claude/base/`로 승격, `.claude/qa-request/`로
  이동, 또는 문서 자체를 갱신. code-docker/webmanager의 `.claude/` 관리 방식이
  좋은 예시(`.claude/initreq/code-docker/webmanager/.claude/README.md` 참고).
- **⭐ 중대 변경 핸드오버 체크리스트 — 확정된 결정을 뒤집거나 문서를
  쪼갤 때 반드시 이 순서를 밟을 것.** 2026-08-13 일곱/여덟 번째 세션에
  6+6라운드 수동 감사로 55건을 찾았는데, **거의 전부가 "변경한 세션이
  그 자리에서 안 한 일"이 나중에 stale로 쌓인 것**이었음. 감사로 뒤늦게
  줍지 말고 바꾸는 그 순간에 닫을 것:
  1. **`python3 .claude/tools/doc-check.py`를 돌릴 것**(아래 항목 참고) —
     ERROR 0을 유지한 채로 커밋. 이게 규율 대부분을 기계가 대신함.
  2. **바꾼 주장을 부정당하는 *본문 문장*을 grep으로 전수 찾을 것**(또는
     `.claude/agents/quad-doc-auditor.md`로 위임 — 아래 항목 참고, 신선한
     맥락에서 도는 서브에이전트가 이 항목을 실제로 더 잘 잡아왔음).
     헤더에 정정 배너만 달고 본문 bullet을 안 고치는 게 가장 잦은 실패 —
     실제로 `CLAUDE.md`가 "스파이크를 아직 안 돌려봄"이라고 서술한 채
     한 라운드를 통과했음. **배너를 달았으면 그 배너가 부정하는 문장을
     같은 커밋에서 고쳤는지 확인.**
  3. **뒤집힌 원문은 `archive/`로 옮기고 포인터만 남길 것** — 본문에
     "히스토리로만 보존"이라며 두면 구현자가 앞에서부터 읽다가 그
     "확정"을 그대로 믿음(`slot-plan.md`에서 실제로 발생).
  4. **개수·목록·상태는 소스를 하나만 둘 것.** "20개 중 19개", "4개
     문서", "남은 건 X뿐" 류는 두 곳 이상에 적는 순간 반드시 갈라짐 —
     한 곳(예: `luau-test/STATUS.md`, 폴더 구조)을 소스로 하고 나머지는
     가리키기만.
  5. **시한부 주장엔 날짜를 붙일 것.** "아직 안 돌려봄"이 아니라
     "[2026-08-09 기준] 아직 안 돌려봄" — 날짜가 있으면 다음 세션이
     의심할 수 있지만, 없으면 영원히 현재형으로 읽힘.
  6. **인덱스 레이어 3개를 같이 갱신**: `.claude/README.md`(색인),
     `question.md`(사용자가 답할 것만), 루트 `ROADMAP.md`/`HUMAN_TODO.md`.
- **기계 점검 — `python3 .claude/tools/doc-check.py`.** 깨진 파일/절
  참조, README 색인 누락, 날짜 없는 시한부 주장, 미반영 배너를 한 번에
  훑음. **커밋 전에 돌리는 게 기본** — 수동 감사에서 나온 발견의 대부분이
  이걸로 잡히는 종류였고, 실제로 여덟 번째 세션에 문서를 쪼개면서 잘못
  옮긴 참조를 이 스크립트가 잡아냈음. ERROR는 고치고, WARN은 판단이
  필요한 것(절 제목을 의역해 인용한 관례 등)이라 늘 0일 필요는 없음.
- **[2026-08-16 도입] `.claude/agents/quad-doc-auditor.md` 서브에이전트 —
  위 체크리스트 2~4번(본문 문장 grep, archive 이전, 개수/목록 단일화)을
  신선한 맥락에서 대신 수행.** 읽기 전용, 발견만 리포트(직접 수정 안 함).
  **`.claude/base`/`.claude/research`/이 문서/`.claude/todos.md` 등 라이브
  문서에 중대한 변경이 있은 뒤, 특히 커밋 전에 돌리는 게 기본** — 지난
  세션들에서 "변경한 세션 자신의
  self-audit은 자기가 뭘 안 건드렸는지 몰라서 놓친다"는 패턴이 반복
  확인됐고(세션 히스토리 7·8·10·11차 등), 이걸 매번 즉흥적으로 프롬프트
  짜는 대신 고정 정의로 옮긴 것. **아주 큰 변경**(설계 반전 규모)엔 이걸로
  대체하지 말고 `/code-review`(diff 기반)와 사용자의 직접 diff 검토를
  병행할 것 — 이 서브에이전트는 diff가 아니라 코퍼스 전체의 정합성만 봄.
- **[2026-08-16 도입] "핸드오버 준비하고 커밋해" 류 요청엔 되묻지 말고
  `.claude/workflows/quad-handover-audit.js`(Workflow 이름
  `quad-handover-audit`)를 먼저 돌릴 것.** 단일 `quad-doc-auditor` 패스는
  비결정적이라 매번 다 잡는다는 보장이 없다는 게 사용자 지적 — 이 워크플로는
  라운드마다 `quad-doc-auditor`를 병렬로 여러 번 돌리고 새 발견을 파일별로
  즉시 반영한 뒤, **새 발견이 없는 라운드가 연속으로 나올 때까지** 반복해
  수렴시킨다(라운드당 패스 수·수렴 조건·최대 라운드는 튜닝 대상 상수라
  여기 숫자를 적지 않음 — 소스는 `.claude/workflows/quad-handover-audit.js`
  상단). 사용자가 정확성을 시간보다 우선한다고
  명시했으므로 기본 워크플로 크기 가이드라인(15 에이전트 이하)을 의도적으로
  넘을 수 있음 — 이 워크플로 자체가 그 예외 대상. Workflow는 백그라운드로
  돌고 완료 시 알림이 오므로, 호출 직후 대화를 막지 말고 진행 상황만
  알린 뒤 알림을 기다릴 것. 알림이 오면 `python3 .claude/tools/doc-check.py`로
  ERROR 0을 최종 확인한 뒤 평소 커밋 절차(git status/diff 검토, 메시지 작성)로
  넘어갈 것 — **실제 `git commit`은 이 워크플로 안이 아니라 항상 메인 세션이
  직접 함**(커밋 전 diff 재검토는 대화형 맥락이 필요해서 워크플로에 위임 안 함).
- **문서가 쌓이면서 모순/중복/stale 마커가 생기기 쉬움 — 주기적으로 감사할
  것.** 다만 위 체크리스트+`doc-check.py`+`quad-doc-auditor`가 자리잡으면
  이 감사는 "기계도 서브에이전트도 못 보는 것"(설계 자체의 자기모순, 의사코드
  손 트레이싱)에만 집중하면 됨. 2026-08-04 세션에 실제로 전체 `.claude/`
  코퍼스에서 이런 문제가 다수 발견되어 정리함(`.claude/session-summary.md` 참고) —
  여러 라운드에 걸쳐 같은 문서를 계속 고치다 보면 "정정됨" 표시가 원래
  문장에 안 반영되고 방치되는 패턴이 반복되니, 큰 방향 전환이 있을 때마다
  관련 문서 전체를 훑어 확인할 것.
- **Roblox Studio MCP 연결 시 주의**: Studio는 잘 죽는 편 — 죽었을 때 살리려고
  위험한 명령을 반복 시도하지 말 것. 그런 상황이면 MCP 없이 할 수 있는 작업만
  하거나 대기. 연결 방법은 `HUMAN_TODO.md` 1번 항목 참고(사용자가 Studio에서
  베타 기능을 켜줘야 함).
- **`SAFETY.md` 반드시 지킬 것** — (1) GitHub 등 외부 git 호스팅에 이 레포를
  push하지 말 것, 모델의 git 작업 공간은 사용자가 별도로 마련해줄 제한 계정
  (예: git.qwreey.moe) 전용으로 국한됨 — 그 계정/원격이 설정되기 전까지는
  **로컬 git 커밋까지만** 하고 원격 추가/푸시는 하지 말 것. (2) Roblox Studio는
  메인 계정이 아닌 별도 계정으로만 사용 — 로그인 계정 전환을 사용자가 안 해줬다면
  Studio 관련 작업(MCP 연결 등)을 진행하지 말고 대기.