CLAUDE-CODE의 토큰을 절약하기 - tasks.md의 문서 구조 개편

이 글은 제 경험기를 GPT와 함께 작성한 글임을 밝힙니다.

Case Study

Token Limit로 막힌 2,000+라인 태스크 파일을 구조화해 76.1% 토큰 절감한 방법

Executive Summary

• 문제: 단일 tasks.md(2,247라인)를 모델에 로딩할 때 token limit exceed로 AI 워크플로우 불능 상태 발생.
• 해결: 마스터 인덱스(180라인) + 6개 전문 파일 + 완료 아카이브로 정보 아키텍처 재설계.
• 성과(정량)
  • 평균 토큰 사용량 76.1% 절감 (42,000 → 10,100)
  • 응답 시간 평균 75% 단축 (질의 유형별 73~83%)
  • 탐색 시간 70% 단축, 개발 효율성 4배
  • API 비용 연간 $8,731 절감, 개발 시간 절감 ROI 연간 ~$80,000
• 성과(정성)
  • 개발자 만족도 및 정보 적합성 유의미 개선(예: 정보 적합성 3.1/5 → 4.6/5, +48%)

---

1) 문제 정의: 단일 파일 + Token Limit의 복합 병목

• 단일 파일 규모: 2,247 라인, 추정 38k~42k tokens.
• 구성 혼재: 완료·진행·계획·결제·보안·메타데이터가 한 문서에 공존 → 컨텍스트 노이즈 급증.
• 직접 영향
  • 모델 호출 시 token limit exceed → AI 기반 검색/요약/연결 자동화 중단.
  • 사람 입장에서도 원하는 태스크를 찾기 위해 분 단위 탐색이 상시 발생.
  • 협업(병렬 편집·책임 분리)과 진행률 가시성 모두 저하.

---

2) 설계 원칙: Separation of Concerns + 선택적 로딩

핵심은 “파일을 자르는 것”이 아니라 “컨텍스트를 설계”하는 것입니다.

1. 도메인 중심 분류(Domain-Driven Organization)
   • 태스크를 기능적 도메인 기준으로 재배치(코어 개발, 결제/구독, 품질/국제화, 인프라/보안, 프로젝트 운영, 미래 확장).
2. 계층적 참조(Hierarchical References)
   • 마스터 인덱스(180라인) = 한눈에 조망 + 내비게이션 허브.
   • 세부 작업은 전문화 파일에서만 읽음 → 선택적 로딩.
3. 스마트 참조(Smart Referencing)
   • 일반 질의는 인덱스만, 특정 업무는 인덱스 + 해당 1개 파일, 완료 검토는 아카이브만.

---

3) 최종 구조: 인덱스 + 전문 파일 + 아카이브

/development
├─ tasks.md                         # Master Index (180 lines)
├─ completed-tasks-archive.md       # 완료 아카이브 (371 lines, 23건)
└─ /current-tasks
   ├─ 01-core-development.md        # 260 lines
   ├─ 02-payments-subscriptions.md  # 273 lines
   ├─ 03-quality-testing.md         # 227 lines
   ├─ 04-infrastructure-security.md # 259 lines
   ├─ 05-project-management.md      # 221 lines
   └─ 06-future-expansion.md        # 262 lines

---

4) 구현 프로세스(Phase별)

Phase 1: 분석/분류

• wc -l, grep -c 등으로 라인·섹션·태스크 정량 진단
• 완료 23, 진행 15, 계획 25, 메타데이터 247+ 라인
• 교차 관심사(Cross-cutting) 식별 → Primary 배치 + Cross-reference

Phase 2: 구조화/분리

• Master Index 초안 작성
• 전문 파일 6종 생성, 파일명/순서 규칙화

Phase 3: 완료 아카이브

• 완료 23건을 독립 파일로 이동
• 활성 컨텍스트에서 완료 이력 제거 → 현재 작업의 신선도 유지

---

5) 성과(정량): 토큰·응답·비용·시간

5.1 토큰 절감

• Before: 질의 유형 무관 42,000 tokens 평균
• After(평균 10,100 tokens, 가중 평균)
  • 일반 현황(40%): 2,800
  • 도메인 작업(35%): 7,300
  • 우선순위 확인(15%): 800
  • 종합 분석(10%): 11,800
• 절감률: 76.1%

5.2 응답 시간(실측)

• 단순 질의: 1525s → 35s (75~83%↓)
• 복합 분석: 3550s → 812s (76~77%↓)
• 도메인 특정: 2030s → 58s (73~75%↓)

5.3 API 비용 절감(예시)

• 가격: $15 / 1M tokens
• Before: $31.50/day
• After : $7.58/day
• 연간 절감: ~$8,731

5.4 개발 시간 ROI(예시)

• 연간 ~$80,000 절감 (탐색 시간 단축 기반)

---

6) 성과(정성)

• 정보 적합성: 3.1/5 → 4.6/5 (+48%)
• 태스크 발견 만족도: 4.2/5 → 4.8/5 (+14%)
• 컨텍스트 전환 스트레스: 3.8/5 → 2.1/5 (–45%)
• 체감 생산성: 3.5/5 → 4.7/5 (+34%)
• 투명성: 완료 23건 vs 진행 항목 명확 구분

---

7) 통합 가이드

• 일반 질의: 인덱스만 로딩
• 특정 업무: 인덱스 + 해당 파일
• 우선순위 확인: 인덱스 부분만
• 완료 검토: 아카이브만
• Prompt/에이전트 룰: 인덱스→파일 선택적 로딩

---

8) 도전과 극복

• 경계 모호 → Primary+Cross-ref 규칙 확립
• 정보 중복 → Essential Duplication 최소화
• 팀 적응 기간 → 2~3주 온보딩 가이드
• 초기 혼란 → 인덱스 상단 “파일 결정표” 제공
• 파일 동기화 → 리뷰 시 인덱스 무결성 확인

---

9) 재현 체크리스트

• Week 1: 진단 (라인 수·태스크 수 분석)
• Week 2: 도메인 그룹핑
• Week 3~4: 파일화 & 인덱싱
• Month 2: 운영 정착 & 리뷰 자동화

---

10) 요약 인사이트

• 엔지니어: Token limit은 입력 제약이자 설계 요구사항.
• PM/리더: 문서 구조 최적화는 ROI를 만들어내는 전략적 행위.

---

부록 A. 시나리오별 절감률

• 일반 현황: 42,000 → 2,800 (–93.3%)
• 도메인 작업: 42,000 → 7,300 (–82.6%)
• 완료 검토: 42,000 → 6,500 (–84.5%)
• 종합 분석: 42,000 → 11,800 (–71.9%)

부록 B. 파일/라인 요약

• 인덱스 180 / 아카이브 371 / 전문 6개(227~273, 평균 250±)
• 활성 태스크: 진행 15 / 계획 25 / 완료 23

 

 

https://velog.io/@bernoyoun/CLAUDE-CODE%EC%9D%98-%ED%86%A0%ED%81%B0%EC%9D%84-%EC%A0%88%EC%95%BD%ED%95%98%EA%B8%B0-tasks.md%EC%9D%98-%EB%AC%B8%EC%84%9C-%EA%B5%AC%EC%A1%B0-%EA%B0%9C%ED%8E%B8

CLAUDE-CODE의 토큰을 절약하기 - tasks.md의 문서 구조 개편

 

조금 가벼워진 글은 VELOG에 올라갑니다.