quad/.claude/conventions.md

# 관례와 작업 방식

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

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

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

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

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

## 설계 원칙

- **⭐ 드문 오용이나 가상의 미래 요구까지 방어/최적화하려고 구조를 복잡하게
  만들지 않는다.** 실제로 관측된 문제(실측된 병목, 실제로 밟은 함정)에만
  구조를 쓴다. **[2026-08-16 명문화]** 이 원칙은 `base/modifier-plan.md`가
  `Apply` 체인 fast-path를 미루는 근거 등으로 **여러 문서가 이미 인용해왔지만
  정작 어디에도 적혀 있지 않았다** — 코퍼스 전체 grep과 `git log -S`로
  확인됨. 사용자가 세션 중 구두로 말한 게 옮겨적히지 않았을 가능성이 크다는
  사용자 본인 추정에 따라 여기 정식 관례로 승격(선택지 (a) 채택). 이 누락이
  아래 "사용자 발언을 인용할 때" 관례가 생긴 계기이기도 함.

## 작업 방식

- **소스코드를 많이 읽어야 하는 리서치는 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`.
- **⭐ [2026-08-16 실측] `@import`로 로드되는 파일(이 문서/`project-context.md`/
  `todos.md`)을 그 세션에 고쳐도 **그 세션의 컨텍스트엔 반영되지 않는다.**
  세션 시작 시점 버전이 그대로 남는다 — 4라운드 감사가 받은 임포트 블록이
  세션 시작 커밋과 정확히 일치했고(그 사이 7커밋), 메인 세션 자신의
  컨텍스트도 마찬가지였다. **그래서 이 문서를 고친 세션은 자기가 방금 쓴
  규칙을 컨텍스트에서 못 본다** — 고친 뒤에는 기억에 의존하지 말고 파일을
  직접 `Read`해서 따를 것. 다음 세션부터는 정상적으로 새 버전이 로드된다.
- **기계 점검 — `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 재설계] "핸드오버 준비하고 커밋해" 류 요청엔 되묻지 말고
  아래 감사 루프를 돌릴 것.** 단일 `quad-doc-auditor` 패스는 비결정적이라
  매번 다 잡는다는 보장이 없다는 게 사용자 지적 — 그래서 병렬 다회로 돌린다.
  **처음엔 이걸 Workflow(`quad-handover-audit.js`)로 만들어 픽스까지
  서브에이전트에 맡겼으나, 첫 실동에서 에이전트 67개·4.6M 토큰을 쓰고도
  수렴하지 못해 2026-08-16에 폐기**(원문은 `archive/`가 아니라 git 히스토리와
  `session/2026-08-16-02-*.md`에 있음). 폐기 이유는 셋 — (1) 토큰이 과하게
  갈림, (2) 파일별로 픽스 에이전트를 쪼개니 **그 에이전트들이 또 부정확한
  서술을 새로 만들어냄**, (3) 서브에이전트는 사용자에게 물을 수가 없어서
  판단이 필요한 항목이 그냥 임의 처리됨. 지금 절차:
  1. **`quad-doc-auditor`를 한 메시지에서 병렬 호출**(Agent 도구 직접 호출
     — Workflow 안 씀). **최소 2개, 변경 사항이 많으면 그만큼 늘릴 것** —
     사용자 지침(2026-08-16): "최소 2에, 변경 사항이 많아진다면 batch 수가
     늘어나는게 맞다고 봄". 감사자는 sonnet이라 패스당 비용이 낮고 역할이
     "빠르게 전체를 훑는 것"이라, 커버리지를 넓히는 쪽이 이득인 구조다
     (사실 검증은 상위 모델인 메인이 한다). 기준은 라이브 문서 몇 개가
     바뀌었나 — 두어 개 고친 정도면 2개, 설계 반전이나 문서 분할처럼
     코퍼스 전반을 건드린 변경이면 3~4개.
     **감사자 모델은 `sonnet` 유지 — haiku로 더 낮추지 말 것**(사용자
     판단, 2026-08-16). 실제로 이 감사가 잡아온 것들(재역전된 배너, 자기
     메모리의 stale 서술)은 문맥 추론이 꽤 들어간 발견이었다.
  2. **두 리포트를 메인 세션이 합쳐서 검토하고, 수정도 메인이 일괄로 한다.**
     픽스를 서브에이전트에 위임하지 말 것(위 (2)번 이유). 감사자는 읽기
     전용이고 발견만 리포트한다.
  3. **애매하면 임의로 정하지 말고 그 자리에서 사용자에게 보고할 것.**
     메인 세션은 사용자에게 물을 수 있다는 게 서브에이전트 대비 유일한
     강점이니 그걸 쓸 것(어떤 발견이 여기 해당하는지 판정 기준은
     `.claude/agents/quad-doc-auditor.md`의 "출력 형식" 절이 소스 — 여기서
     다시 나열하지 않음).
  4. **새 발견이 없는 라운드가 연속 2번 나올 때까지 1~2를 반복**(보통
     2~3라운드). **수렴 안 하면 조용히 멈추지 말고 사용자에게 보고할 것** —
     첫 실동이 실제로 6라운드를 소진하고도 수렴 못 했고(새 발견
     28→15→16→7→11→6, 단조 감소가 아니었음), 그때 조용히 끊으면
     "감사 통과"로 오독된다.
  5. `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에서
  베타 기능을 켜줘야 함).
- **⭐ [2026-08-16 신설] 사용자 발언을 근거로 인용할 때는 결론만 적지 말고
  "사용자가 무슨 논거로 그렇게 말했는지"까지 남길 것.** 문서에 **사용자
  확정**이라고만 적어두면 다음 세션이 그 결정을 재검토할 수도, 인접한
  새 문제에 적용할 수도 없다 — 근거가 없으면 그건 권위지 논거가 아니다.
  - **어디에 적나**: 논거 원문·대화 흐름은 `.claude/session/`의 그 세션
    파일에, 라이브 문서(`base/`/`research/`)는 결론 + 짧은 논거 + 그
    세션 파일 포인터를 적는다. 좋은 본보기는
    `base/component-composition-plan.md` §1의
    `**사용자 확정**("마법 안쓴다 그것도 동의함")` 패턴 — 사용자 어투
    그대로 짧게 인용하면 나중에 진위와 맥락을 다 되짚을 수 있다.
  - **원칙·규칙을 새로 세우는 발언이면 그 자리에서 이 문서(`conventions.md`)
    나 해당 `base/` 문서에 명문화할 것.** 안 그러면 나중 문서들이 출처
    없는 원칙을 인용하게 된다 — 위 "설계 원칙" 절의 첫 항목이 그 사례다
    (경위는 그 항목에만 적어둠, 여기서 반복하지 않음).
- **`SAFETY.md` 반드시 지킬 것** — (1) GitHub 등 외부 git 호스팅에 이 레포를
  push하지 말 것, 모델의 git 작업 공간은 사용자가 별도로 마련해줄 제한 계정
  (예: git.qwreey.moe) 전용으로 국한됨 — 그 계정/원격이 설정되기 전까지는
  **로컬 git 커밋까지만** 하고 원격 추가/푸시는 하지 말 것. (2) Roblox Studio는
  메인 계정이 아닌 별도 계정으로만 사용 — 로그인 계정 전환을 사용자가 안 해줬다면
  Studio 관련 작업(MCP 연결 등)을 진행하지 말고 대기.