quad/.claude/conventions.md

관례와 작업 방식

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

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

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

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

설계 원칙

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

문서 표기 규약

doc-check.py는 정규식으로 정적·결정론적으로 판정한다 — 표기가 흔들리면 검사가 열거형으로 비대해지거나 아예 무력화된다. "예상 가능한 범위"를 컨벤션으로 미리 좁혀두는 게 정규식을 늘리는 것보다 싸다는 게 사용자 판단(2026-08-16, "형식이 많이 왔다 갔다 하면 문제가 커져", "가장 비용이 쌈"). 근거가 된 실측과 논의 원문은 session/2026-08-16-03-doc-check-section-convention.md.

컨벤션이 규정으로 값을 하는 범위는 "도구가 잡은 걸 표준 마커로 잠재우는" 검사뿐이다. "위험한 문장을 먼저 찾아내야 하는" 검사(시한부 주장 탐지 등)는 표현을 열거하는 수밖에 없다 — 정규식은 날짜를 안 붙인 문장을 찾을 수 없기 때문. 그 잔여가 quad-doc-auditor의 몫이고 앞으로도 그렇다.

• ⭐ [2026-08-16 신설] 절 인용 규약 — 절 제목은 의역하지 말고 원문에서 잘라 쓸 것. `<파일>.md`의 "절 제목" 형태로 인용할 때(예시의 <파일>은 자리표시자 — 실제 파일명처럼 적으면 doc-check.py가 깨진 참조로 잡는다):
  • # 헤딩: 제목의 연속된 부분문자열이면 됨(줄여 쓰기 허용, 말 바꾸기 금지).
  • **볼드** 절: 이 코퍼스가 하위 절로 쓰는 형태. 절로 인정되는 건 빈 줄 다음에 오는 볼드와 리스트 항목(- /1. /> ) 머리의 볼드뿐이다 — 문단이 줄바꿈되며 우연히 줄머리에 걸린 강조는 절이 아니다. 인용은 제목 앞부분부터 잘라 쓸 것. 볼드는 단순 강조와 구분이 안 되고 # 헤딩보다 압도적으로 흔해서(실측 수치는 session/2026-08-16-03-doc-check-section-convention.md), 중간 조각 인용까지 허용하면 무관한 강조에 우연히 걸려 검사가 조용히 통과하는 쪽으로 무력화된다.
  • 큰따옴표가 든 제목은 앞부분만 인용할 것 — 인용 문법 자체가 "..."라 안쪽 따옴표가 문법을 깬다.
  • ⚠️ 태그로 닫히는 볼드는 절로 인식되지 않는다. - **[해소됨, …]** 실제 제목 — 본문…처럼 볼드가 상태 태그에서 끝나고 진짜 제목이 볼드 밖 평문으로 나오면(archive/question-resolved.md가 이 형태), 검사기는 "[해소됨, …]"만 절 제목으로 본다. 그런 항목을 가리킬 땐 큰따옴표 인용을 쓰지 말고 백틱으로 쓸 것. 새로 쓸 땐 태그와 제목을 한 볼드 스팬 안에 넣을 것 — **[해소됨, …] 실제 제목**. 절 참조가 ERROR로 승격됐으므로, 이걸 모르고 규약대로 큰따옴표 인용을 하면 실재하는 서술인데도 커밋이 막힌다.
  • 선두 장식(⚠️/⭐), 백틱, 선두 상태·날짜 태그([2026-08-16 신설], [해소됨, …])는 붙이든 빼든 무관(양쪽에서 똑같이 벗겨내고 비교). 태그는 제목의 일부가 아니다 — 시간이 지나면 내용이 바뀌는 메타 표시라 거기에 인용을 묶으면 태그가 갱신될 때마다 참조가 깨진다. 인용은 태그 뒤 실제 제목부터 잘라 쓰는 걸 권장.
  • 줄바꿈에 걸쳐 인용해도 무관(공백을 무시하고 비교). 다만 인용이 160자를 넘으면 검사 자체가 안 걸리니 길게 늘어뜨리지 말 것.
  • blockquote(> ) 안에서는 인용을 줄바꿈에 걸치지 말 것 — 다음 줄의 > 마커가 인용문 안으로 딸려 들어가 매칭이 깨진다. 실제로 이 세션에 ROADMAP.md에서 그 마커를 지우다 blockquote를 통째로 망가뜨릴 뻔했다.
  • 절 제목을 문장에 끼울 땐 "…" 뒤에 절을 붙일 것("패키지 경계" 절이 세운 원칙처럼). 제목을 명사구 자리에 그대로 넣으면 원문에서 잘라 쓴 제목이 문장과 안 맞아 문법이 깨진다 — 이 세션에 실제로 여러 건 냈다.
  • 용어를 인용할 땐 이 형태를 쓰지 말 것 — `<파일>.md`의 "cleanup" 처럼 쓰면 절 인용과 문법이 같아서 구분이 안 된다(실제로 base/lifecycle-pattern.md가 effect-plan.md의 용어 cleanup을 이 형태로 인용해 오탐을 냈었고, 이 규약을 세우면서 같이 고쳤다). 용어는 따옴표 없이 쓰거나 문장을 바꿀 것.
  • 제외 대상: initreq/를 가리키는 인용(읽기 전용 외부 원본이라 절 구조가 없음 — raw-userinput.md는 스스로 "정리가 없는 생각의 흐름"이라 밝힘), 그리고 archive/·session-summary.md가 하는 인용(히스토리 문서).
  • 왜 지금 정하나: 예전엔 "절 제목을 의역해 인용하는 관례"가 있어서 이 검사가 영원히 WARN에 묶여 있었다. 의역을 금지하면 ERROR로 승격돼 절 참조 rot이 커밋 게이트에 걸린다 — bind-system-plan.md 분할 때 20곳이 이 사각지대로 샜던 실패 모드다. [2026-08-16] 불일치를 0으로 만들고 깨끗하게 도는 걸 확인한 뒤 ERROR로 승격 완료 — 이제 의역 인용은 커밋 게이트에서 막힌다.
• ⭐ [2026-08-16 신설] 세션은 산문 서수 말고 파일 ID로 지칭할 것. 지금 코퍼스엔 한글 서수("열세 번째 세션") / N차 / N번째가 다 섞여 있고(정확한 분포는 세는 범위에 따라 달라지므로 여기 숫자로 못 박지 않음), 같은 세션을 다른 이름으로 부르는 사례가 한 파일 안에도 있다 (base/tween-plan.md가 같은 2026-08-13 13차를 "13차 세션"과 "열세 번째 세션" 두 표기로). 이건 스타일 취향이 아니라 grep을 감사 도구로 못 쓰게 만드는 문제다 — "13차 세션에 뭘 정했나"를 찾으면 절반을 놓친다. 앞으로는 `session/YYYY-MM-DD-NN-slug.md` 형태의 파일 ID로 쓸 것. doc-check.py가 이 참조를 이미 검증하므로(없는 세션을 인용하면 깨진 파일 참조로 잡힘) 새 코드도 필요 없다. 기존 표기는 일괄 치환하지 말 것 — 그 파일을 만질 때 같이 고친다.
• [2026-08-16 검토 후 보류] 날짜 마커 라벨([YYYY-MM-DD 신설/정정/기준…])의 어휘는 닫지 않는다. 날짜 리터럴 자체는 강제 장치 없이도 이미 100% 균일해서(실측은 세션 파일) 고칠 게 없고, 라벨 쪽은 사용자 판단대로 기계 검사 대상이 아니라 읽는 쪽 판단 재료다 — "에이전트가 순서 섞였을 때 최신의, 옳은 요소 선택에 도움이 되는 정보에 가깝지 이게 warn을 만들지는 못할듯". 어휘를 닫아도 검사가 하나도 안 생기므로 안 한다. 같이 묶여 있던 DATED 앵커 좁히기(±3줄 아무 날짜 → 같은 줄 마커)만은 유일하게 WARN을 만드는 항목이라 성격이 다르지만, 지금 그 위음성이 아프다는 증거가 없어 함께 보류 — 아프면 그때 한다("실제로 관측된 문제에만 구조를 쓴다" 원칙 그대로).

작업 방식

• 소스코드를 많이 읽어야 하는 리서치는 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)을 그 세션에 고쳐도 그 세션의 컨텍스트엔 반영되지 않는다. 세션 시작 시점 버전이 그대로 남는다 — session/2026-08-16-02-audit-tooling-verification-and-first-real-run.md 세션의 4라운드 감사가 받은 임포트 블록이 세션 시작 커밋과 정확히 일치했고(그 사이 7커밋), 메인 세션 자신의 컨텍스트도 마찬가지였다. 그래서 이 문서를 고친 세션은 자기가 방금 쓴 규칙을 컨텍스트에서 못 본다 — 고친 뒤에는 기억에 의존하지 말고 파일을 직접 Read해서 따를 것. 다음 세션부터는 정상적으로 새 버전이 로드된다.
• 기계 점검 — python3 .claude/tools/doc-check.py. 깨진 파일/절 참조, README 색인 누락, 날짜 없는 시한부 주장, 미반영 배너를 한 번에 훑음. 커밋 전에 돌리는 게 기본 — 수동 감사에서 나온 발견의 대부분이 이걸로 잡히는 종류였고, 실제로 여덟 번째 세션에 문서를 쪼개면서 잘못 옮긴 참조를 이 스크립트가 잡아냈음. ERROR는 고치고, WARN은 판단이 필요한 것이라 늘 0일 필요는 없음. [2026-08-16 정정] 예전엔 여기 "절 제목을 의역해 인용한 관례"를 WARN이 0일 수 없는 대표 사유로 적어뒀는데, 위 "절 인용 규약"으로 의역 인용은 관례가 아니라 고칠 대상이 됐다 — 절 참조는 이제 WARN이 아니라 ERROR다(승격 완료).
• [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 연결 등)을 진행하지 말고 대기.