# 관례와 작업 방식 이 파일은 루트 `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-19 신설] 설계 결정이 오간 세션은 끝나기 전에 `session/YYYY-MM-DD-NN-slug.md` 원문을 반드시 남길 것.** 2026-08-19 세션이 점검해보니 2026-08-18(커밋 10개, QA 1~2라운드 포함)엔 `session/` 파일이 1개뿐이었고 2026-08-19는 이 점검 전까지 0개였다 — 실제로 여러 세션이 이 규율을 빠뜨렸다는 뜻(경위는 `session/2026-08-19-01-new-initxxx-composition-relate-guard.md`). **사용자 판단(2026-08-19): 이미 지나간 공백은 재구성하지 말고 인정하고 넘어간다** (그 시점 대화 원문에 접근할 수 없는 채로 "원문"을 지어내면 그 자체가 허위 기록이 됨) — 대신 **앞으로 같은 공백이 반복되지 않도록** 이 항목을 명문화한다. `base/`/`research/`에 실제로 반영되는 설계 결정이 있었던 세션은, 커밋 직전이 아니라 **작업이 일단락되는 시점마다** session/ 파일을 쓸 것 — 핸드오버 체크리스트(바로 아래)가 요구하는 감사·커밋 절차와 별개로, 이건 그 이전에 지켜야 할 절차다. - **⭐ 중대 변경 핸드오버 체크리스트 — 확정된 결정을 뒤집거나 문서를 쪼갤 때 반드시 이 순서를 밟을 것.** 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 신설, 2026-08-18 재설계] "핸드오버 준비하고 커밋해" 류 요청엔 되묻지 말고 아래 감사 루프를 돌릴 것.** 단일 `quad-doc-auditor` 패스는 비결정적이라 매번 다 잡는다는 보장이 없다 — 그래서 **여러 번** 돌린다. 다만 **여러 개를 동시에 띄우지는 않는다**(아래 1번). **처음엔 이걸 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 안 씀). **사용자 지침(2026-08-18): "시간이 걸려도 상관 없으니, 차라리 병렬 에이전트를 덜 써줘. 그냥 한 턴에 하나씩만 사용하고, 0 이 나올때 까지 턴 수를 늘리는게 나아보임. 토큰을 너무 많이 소비해서 다른 작업을 못 하고, 세션 한도에 닿더라고."** 이건 2026-08-16의 "최소 2개 병렬, 변경이 많으면 3~4개로 늘림" 지침을 **대체한다** — 커버리지를 병렬 폭이 아니라 **턴 수**로 얻는다. 근거가 된 실측(2026-08-18): 전 코퍼스 감사 **한 패스가 서브에이전트 토큰 21만 / 툴 호출 82회**였고, 계획대로 4개를 병렬로 돌렸으면 한 번에 80만 토큰대였다 — 세션 한도를 그 자리에서 태워 정작 본 작업을 못 하게 된다. **감사자 모델은 `sonnet` 유지 — haiku로 더 낮추지 말 것**(사용자 판단, 2026-08-16). 실제로 이 감사가 잡아온 것들(재역전된 배너, 자기 메모리의 stale 서술)은 문맥 추론이 꽤 들어간 발견이었다. 2. **⭐ [2026-08-18 신설] 프롬프트로 감사 범위를 좁힐 것 — 기본은 diff 범위다.** 감사자 정의 자체는 "코퍼스 전체를 신선한 맥락에서 다시 읽는다"인데(라이브 문서 90개 이상, `base/`만 1만 줄 이상), 대부분의 핸드오버에서 실제로 위험한 건 **이번에 바뀐 파일과 그걸 인용하는 곳**이다. 그래서 프롬프트에 (a) 바뀐 파일 목록, (b) 이번에 뒤집힌 결정 목록, (c) "그 파일들을 인용하는 곳까지만 확장해서 보라"를 명시할 것. 전 코퍼스 스윕은 **오래 안 돌렸을 때 한 번씩**만. 라운드마다 각도를 바꾸면(예: 1라운드는 `base/` 정합성, 2라운드는 인덱스 레이어(README/ROADMAP/question/todos), 3라운드는 archive/luau-test/audit) 병렬로 폭을 넓히던 효과를 턴으로 얻을 수 있다. 3. **리포트는 메인 세션이 검토하고, 수정도 메인이 한다.** 픽스를 서브에이전트에 위임하지 말 것(위 (2)번 이유). 감사자는 읽기 전용이고 발견만 리포트한다. 4. **애매하면 임의로 정하지 말고 그 자리에서 사용자에게 보고할 것.** 메인 세션은 사용자에게 물을 수 있다는 게 서브에이전트 대비 유일한 강점이니 그걸 쓸 것(어떤 발견이 여기 해당하는지 판정 기준은 `.claude/agents/quad-doc-auditor.md`의 "출력 형식" 절이 소스 — 여기서 다시 나열하지 않음). 5. **새 발견이 0건인 라운드가 나올 때까지 1~3을 반복**(사용자 지침 2026-08-18의 "0 이 나올때 까지 턴 수를 늘리는게"). 옛 규칙이던 "무발견 **2연속**"은 병렬 다패스를 전제한 것이라 같이 완화됐다 — 대신 라운드마다 각도를 바꾸는 것(위 2번)이 그 역할을 대신한다. **수렴 안 하면 조용히 멈추지 말고 사용자에게 보고할 것** — 첫 실동이 실제로 6라운드를 소진하고도 수렴 못 했고(새 발견 28→15→16→7→11→6, 단조 감소가 아니었음), 그때 조용히 끊으면 "감사 통과"로 오독된다. 비용 때문에 중간에 멈출 때도 마찬가지로 "몇 라운드에서 왜 멈췄는지"를 반드시 보고할 것. 6. `python3 .claude/tools/doc-check.py`로 ERROR 0을 최종 확인한 뒤 평소 커밋 절차(git status/diff 검토, 메시지 작성)로 넘어갈 것. **`git commit`은 항상 메인 세션이 직접 함** — 커밋 전 diff 재검토는 대화형 맥락이 필요해서 위임하지 않는다. - **⭐ [2026-08-18 실측] `/code-review`는 감사자를 대체하지 않는다 — 큰 변경에는 둘 다 필요하다.** 2026-08-18 핸드오버에서 감사자 1패스가 1건을 잡은 뒤 사용자가 `/code-review high`를 직접 돌리자 **10건이 더 나왔고 전부 유효**했다. 둘이 보는 축이 다르기 때문 — 감사자는 **코퍼스 전체의 의미론적 정합성**(A 문서의 결정과 B 문서의 서술이 어긋나는가), code-review는 **diff 자체의 결함**(이번에 새로 쓴 서술 안의 모순, 새 API가 기존 계약과 충돌하는가). 실제로 그 10건엔 "새로 확정한 `store:GetDynamic`이 Store의 lazy `__index`와 충돌해 그대로 구현하면 런타임 에러"처럼 감사자 각도에선 안 보이는 것이 있었다. **`/code-review`는 사용자만 호출할 수 있으므로**, 큰 변경을 커밋하기 전엔 그걸 돌릴지 사용자에게 물어볼 것. - **문서가 쌓이면서 모순/중복/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 연결 등)을 진행하지 말고 대기. - **⭐ [2026-08-18 신설, 같은 날 정정] 이 레포의 모든 커밋에 사용자 GitHub 계정(`github.com/qwreey`)을 co-author로 추가할 것 — 커밋 메시지 끝에 `Co-authored-by: qwreey `만 넣는다. 하네스 기본 `Co-Authored-By: Claude Sonnet 5 ` 트레일러는 이 레포에 한해 넣지 말 것.** **사용자 확정**(2026-08-18) — 커밋 계정 자체가 `qwreey-bot`이라 이미 에이전트 커밋임이 드러나므로 Claude 트레일러까지 이중으로 밝힐 필요는 없고, 대신 해당 GitHub 계정 프로필에 Claude를 사용한다고 명시해둘 예정("어차피 qwreey-bot 자체가 에이전트가 커밋했다고 알려주는지라 큰 필요는 없어"). `.claude/settings.json`에 `"includeCoAuthoredBy": false`도 선언해뒀지만 **[2026-08-18 확인] 하네스 버그로 무시됨**(`includeCoAuthoredBy`/`attribution.commit` 둘 다 알려진 미해결 버그 — GitHub Issue #7543/#65657) — 그래서 실제 억제는 이 문장을 세션이 읽고 지키는 방식으로만 보장된다. **qwreey 트레일러는 계속 추가한다** — 위 문단이 이미 그 근거(GitHub 기여 그래프 반영)를 서술함, 여기서 반복 안 함. `github` 리모트로 싱크되어 `upstream`(`github.com/qwreey/quad`, 사용자 본인 소유)에 PR이 merge될 때 GitHub 기여 그래프에 반영되게 하기 위함 — 관련 리모트 정책은 메모리 `git-remote-push-policy` 및 위 `SAFETY.md` 항목 참고.