현 상황

이전 Skill화 이후 Claude Code를 이용하여 자료 수집이 원활하게 진행되는지 확인을 진행 하였다. 결과는 만족할 정도로 템플릿을 잘 따라갔지만, 토큰 사용량이 어마어마하게 찍힌걸 발견 할 수 있었다. 이에 토큰 사용량이 왜 이렇게 많이 발생했는지 구조적인 검토와 개선방안을 생각해 적용해볼 예정이다.

원인 분석을 위해 AI와의 토론을 진행 하였다.

토큰원천

스킬/참조 문서 탐색

양식과 기준이 되는 규칙들을 이해하는데 사용하는 토큰으로 사실은 이미 인덱스 파일을 형성한 후, 프로세스별 참조 폴더를 분리해두었다. ( 하지만 AI의 판단에는 라우터의 존재가 없으므로 이를 만들어두는걸 추천했다. )

  1. 폴더/계층 별 토큰 수 확인하기 : 현재 토큰량을 기준으로 최적화 작업 이후 확인 용도
# 계층별 토큰 무게 측정 (4바이트 ≈ 1토큰 근사)
for d in prompts research/elements research/games research/genres research/signals templates; do
  B=$(cat $d/*.md 2>/dev/null | wc -c); echo "$d: ≈ $((B/4)) 토큰"
done
wc -c research/_index.md

토큰량

이제보니 프롬프트에 영어번역 + 한국어 본문이 중복으로 작성되어 있어 AI가 읽을 영어만 남겨두고 다시 한번 측정 했다.

토큰량2

  1. 라우터(지도) 추가 : 필요한 정보만 조회
## 읽기 지도 (무엇을 할 때 무엇만 읽는가)
| 상황 | 읽을 파일 (이것만) |
|---|---|
| 조사 주제 발굴 | prompts/0_scout.md |
| 카드 조사 | prompts/1_researcher.md |
| 카드 집필 | prompts/2_writer.md + templates/해당종류 1개 |
| 카드 검수 | prompts/3_validator.md |
| 다이제스트 반영 | prompts/4_updater.md |
| Unity 구현 지시 | prompts/5_developer.md |
| 기획/스펙 작성 | prompts/6_planner.md |
| QA 판정 | prompts/7_qa.md |
| 기존 카드 확인 | research/_index.md 먼저 → 필요한 카드 최대 2장 |
| 카드 형식 오류 | templates/해당종류 1개 (전체 templates 열람 금지)

## 읽기 규율 (토큰 예산)
1. 위 지도에 없는 파일은 열지 않는다. 단계당 프롬프트 1개만 읽는다.
2. 카드 확인은 반드시 _index.md부터. 본문 열람은 작업당 최대 2장.
3. research/ 하위 폴더를 통째로 여는 것 금지 (ls는 허용, cat 전체 금지).
  1. 읽는 방식 수정 : 현재 카드 전체를 읽기 보다 용도에 맞춰 특정 절만 읽게하여 토큰을 줄이는 방식
위의 CLAUDE.md 에 추가
| 여러 카드의 특정 절만 필요 (궁합, 빈칸 등) | tools/read_section.py <카드들> "<절 제목>" — 전체 열람 금지 |
| 절 제목은 표준 사전의 문자열 그대로 | 변형 제목 발견 시 lint로 잡아 수정 (임의 추측 금지) |

웹 검색

사실 현재 웹 검색에 대하여 제한을 두지 않았기에 제일 많은 소비로 예상이 되는 구간이다. 이에 여러가지 방안을 추천받고 적용하기로 하였다.

  1. 최적의 검색 횟수 적용하기

시뮬레이션

  • 기본 3회에 필요사항(핵심슬롯) 검토 후 추가 1회 가능하도록 조절
  1. 조사를 서브에이전트에게 위임하여 세션(토큰량) 조절

처방전

  • 검색한 원문을 요약해 토큰을 압축하여 전달

  • 검색 전 이미 아는 정보는 DB를 통해 낮은 코스트로 읽어오기

기존 카드 참조

카드 작성 및 업데이트 과정에서 필요한 토큰으로 위의 마지막 방식과 조금씩 공유되는 해결법이 존재한다. 기존 MD 파일의 경우 index를 통해 참조가 가능하지만, 각자의 유사성을 판단하기 위해 추가로 토큰이 소모되게 된다. 이에 사용되는 토큰을 줄이기 위해 벡터(위치)를 이용해 데이터들을 정리해주는 PostgreSQL을 도입하려한다.

  1. 벡터 위치(유사도)를 측정해줄 도구

    • 로컬 AI를 통해 계산하도록 스크립트 형식으로 만들었다. ( Python 형식 AI 초안으로 테스트 예정 )

  2. 클라우드 서비스 선정

    • 무료 플랜 및 조회율이 높지않은 걸 고려하여 Neon의 PostgreSQL 클라우드 서버를 사용하기로 했다.

  3. 구현 방법 설계

    • 현재 md 파일 구조로 된 파일/폴더를 유지하되, PostgreSQL로 미러링을 하는 형태로 진행하려한다.

    • 자료 수집 후 Github Pull Request를 통해 자동으로 PostgreSQL에 올려 연동되도록 구현

    • 현재 파일 구조의 인간이 보기에 좋은 가독성 및 AI 친화적인 PostgreSQL의 장점을 둘다 살릴 수 있다고 생각하였다.

한줄 평

  • 다음 프로세스에 PostgreSQL을 통해 토큰 사용량이 최적화된 채로 기능 구현이 되었으면 좋겠다.