# 관례와 작업 방식 이 파일은 루트 `CLAUDE.md`가 `@import` 하므로 **매 세션 컨텍스트에 로드된다** — 늘리기 전에 "정말 매 세션 필요한가"를 따질 것. 세션마다 필요하진 않은 상세는 `.claude/` 아래 개별 문서로. ## 언어/모델 관례 (기존 메모, 유지) 사용자는 한국 유저임을 유의해. 사용자가 보게 될 것은 한국어로 띄워주는 게 좋아. 너가 보는 것들(코드 주석 등)은 원하는 언어여도 되는 것(가장 성능이 좋을 영어를 쓰든 그래도 됨, 예를 들어 이 문서도 영어여도 무방하지만 지금은 한국어로 유지). 사용자가 검토해야 하는 것(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 연결 등)을 진행하지 말고 대기.