문서 토큰 효율화 — 이슈

2026-09-13 ▶ → 🎨. A·B가 다 끝나 🎨(문서관계도 압축)만 남았다. 이슈 #18은 결과 수치를 댓글로 남기고 닫았다.

배경

클라이언트 담당이 이슈 #18에 문서 토큰 효율화 권고를 남겼다(2026-08-15). 요지는 둘이다 — 트리거(읽히는 횟수)부터 보고, 스킬은 전문 로드되니 요지는 남기고 설명만 밖으로 뺀다. 클라 쪽(clean-code-style 분할 · Agent 로그 INDEX 압축 · 스킬 트리거 정비)은 이미 적용됐다.

2026-09-13에 서버·기획 쪽 대상을 다시 재 보니 하나도 처리되지 않았고, 하나는 오히려 커졌다.

우선순위는 이슈와 다르게 잡는다. tasks/README.md는 T-0XX가 언급될 때마다 task-reader가 통째로 여는 파일이라, 지금은 저장소에서 가장 자주 읽히는 큰 파일이다. 이슈에서는 3순위였지만 여기서는 1순위로 올린다.

할 일

A. 1순위 — 자주 읽히는 것

• [x] tasks/README.md 압축 ✅ 2026-09-13 — 36.9KB → 12.8KB (−65%). 이력 메모 26.8KB는 [archive/순서 메모 이력.md](/tasks/순서 메모 이력)로 내렸고, 살아 있던 사실 두 건은 T-002·T-029 파일로 옮겼다. 행마다 한 줄 + 짧은 괄호 메모로. 2026-09-05의 표 셋 구조는 유지한다 (가르는 축이 의도된 설계다). 표 밖의 긴 설명·순서 메모는 별도 절로 내리거나 일감 파일로 옮긴다. 목표는 이슈 3-2절 실측(−49%) 수준
• [x] game-design-reference 하이브리드 분할 ✅ 2026-09-13 — 11.9KB → 8.7KB, 상세는 전파 상세.md(4.4KB). 트리거·"읽지 않아도 되는 경우"는 이미 정비돼 있었다. 분량의 절반인 "재귀 전파" 장(109~183행) 을 같은 폴더 전파 상세.md로 빼고, SKILL.md에는 규칙 요지(표 한 줄)와 "판단이 서면 열지 않아도 된다" 문장만 남긴다
• [x] excel-table-creator 하이브리드 분할 ✅ 2026-09-13 — 9.5KB → 6.7KB, 상세는 컬럼 레퍼런스.md(4.7KB). 절차·하드 규칙·체크리스트는 SKILL.md에 남기고, 마커 행 구조·시트 병합·Ref·Description·Enum 시트 레퍼런스를 컬럼 레퍼런스.md로 뺀다

B. 2순위 — GameDesign/design/

• [x] 게임기획코어.md 상단에 7개 장 앵커 목차 추가 ✅ 2026-09-13 — T-003 세션이 유휴일 때 넣고 목차 hunk만 커밋했다. 내용이 안 바뀌므로 갱신일은 올리지 않았다(올리면 참조 문서 15곳에 역전 경고). 규범·배경 분리는 하지 않는다 — 최상위 진입점을 쪼개면 링크 16곳과 클라 참조가 흔들리고, 테스트 단계라 수치가 자주 바뀐다
• [x] research/ · proposals/ 를 GameDesign/CLAUDE.md 폴더 표에 완결된 기록 — 평소 열지 않는다로 표시 ✅ 2026-09-13. 기획평가.md는 제외했다 — 갱신일이 계속 오르는 살아 있는 리뷰이고 전파 그래프(바뀌면 갱신)에 들어 있어 완결 기록이 아니다

C. 🎨 후순위

• [ ] 🎨 문서관계도.md INDEX 압축 — 자동 로드되지 않는 문서라 급하지 않다

완료 조건

A·B가 끝나고, 각 대상의 한 번에 읽히는 양(발동 시 로드되는 파일 크기)이 이슈 시점 대비 줄었음을 wc -c로 확인해 이 파일에 적는다. 이슈 #18에 결과 수치를 댓글로 남기고 닫는다.

총량이 느는 것은 정상이다 — 아끼는 것은 디스크가 아니라 컨텍스트다(이슈 2절).

막고 있는 것 / 선행 일감

• 없음. 문서만 건드린다.
• ⚠️ tasks/README.md 압축은 워크트리가 없을 때 한다 — INDEX는 워크트리마다 충돌하는 파일이다.

관련 커밋

• e2aedf1 — 일감 등록
• 62f37ad — INDEX 압축 (36.9KB → 12.8KB) · 이력 메모를 보관으로
• 275619a — 공용 스킬 2개 분할 (11.9 → 8.7KB · 9.5 → 6.7KB)
• 19ada90 — research·proposals 완결 기록 표시
• ddb4b13 — 게임기획코어 앵커 목차

참고

• 이슈 #18 — 권고 원문과 클라 쪽 실측
• 6db1867 · 09f66b4 — 클라 쪽에서 같은 방법을 적용한 커밋