qwreey-bot/quad
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
quad/.claude/conventions.md
qwreey 298dac2510
docs: 감사 툴링 재시작 검증 + 핸드오버 감사 첫 실동(수렴 실패), 인용 3건 정정 
전 세션이 "재시작해야만 확인 가능"으로 남긴 3건을 전부 닫음:
- @import 3개(conventions/project-context/todos) 실제 로드 확인
- quad-doc-auditor 레지스트리 등록 확인(전 세션 전멸은 .claude/agents/가
  세션 도중 생긴 디렉토리였던 탓)
- frontmatter model: sonnet 반영 확인(트랜스크립트에 claude-sonnet-5 기록,
  워크플로에 opts.model 명시 불필요)

정의 파일은 세션 시작 시점 스냅샷으로 고정된다는 것을 1차 증거로 확정 —
quad-handover-audit이 실제 실행한 스크립트가 세션 시작 시점 상태와 바이트
단위로 동일했고 같은 세션의 편집은 반영 0. 에이전트 정의도 동일.
정의를 고쳤으면 재시작 뒤에 감사를 돌릴 것(안 그러면 거짓 초록불).
전 세션 감사가 남긴 긴 가설 배너(80줄)를 검증된 것만 남겨 압축.

quad-handover-audit 첫 실동: 에이전트 67개/6라운드, 수렴 실패
(새 발견 28→15→16→7→11→6, 라운드5에서 되레 증가). MAX_ROUNDS와
"연속 dry 2회" 조건 재검토 필요 — 결과 자체는 위 스냅샷 문제로 옛
스크립트가 돈 것이라 재시작 후 재실동 대상.

감사가 잡은 것 반영: slot-plan.md 정정 배너가 그 뒤 재역전(retract=언마운트)을
놓치고 있던 것, "spikes 44개"(실제 48개) 류 하드코딩 개수의 단일 소스화,
doc-check.py docstring이 검사 심각도를 실제 코드와 다르게 서술하던 것 등.

인용 출처 3건 재분류 — 2건은 인용 대상만 틀린 것이라 실제 소스로 재조준
(v1-compat-plan.md→component-composition-plan.md+store-plan.md,
pre-implementation-audit.md→ROADMAP.md). 진짜 출처가 없는 1건
(modifier-plan.md:536)만 question.md 3번으로 올려 사용자 판단 대기.

워크플로 개선: 반환값에 findings 추가(커밋 전 diff 리뷰 근거),
totalFindingsFixed→findingsSentToFix 개명(과대계상), 반영 에이전트 sonnet 명시.

.claude/agent-memory/는 의도적으로 커밋 제외(추적 여부는 사용자 판단).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-16 03:02:33 +09:00

9.4 KiB
Raw Blame History

관례와 작업 방식

이 파일은 루트 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 연결 등)을 진행하지 말고 대기.