# task-1388.1 완료 보고서: 토큰 소모 절감 방안 v2

## S - Situation
대용량 파일(server.py 228KB, CampaignView.js 88KB, dispatch.py 64KB)로 인해 에이전트 세션이 반복적으로 토큰 초과로 터지고 있다. 최근 4건의 작업(task-1373.1~1384.1)이 이 문제로 실패했으며, $2.55 비용 초과와 3시간 39분 낭비 사례가 발생했다.

## C - Complication
기존 dispatch.py의 file-size-check는 WARNING 로그만 출력하여 팀이 무시하고 전체 읽기를 시도했다. 참조 파일 총 크기 한도가 없었고, 대용량 파일의 요약 파일도 없어 에이전트가 매번 원본 전체를 읽어야 했다.

## Q - Question
대용량 파일을 분할하고, 토큰 보호 로직을 강화하여 세션 터짐을 방지할 수 있는가?

## A - Answer
5개 방면에서 개선을 실행하여 토큰 소모를 대폭 절감했다:
1. CampaignView.js: 1265줄 → 234줄 (81% 감축, 3개 파일로 분할)
2. server.py: 5271줄 → 2474줄 (53% 감축, data_loader.py + helpers.py 분리)
3. dispatch.py: 참조 파일 총 크기 50KB 한도 적용, 70% 사전경고, 요약파일 우선 읽기 지침 삽입
4. 대용량 파일 자동 요약 생성 스크립트(generate_file_summaries.py) + 즉시 3개 요약 생성
5. 태스크 설계 규칙 문서화

pytest 149건(dispatch) + 228건(dashboard) = 377건 통과, 테스트 회귀 0건.

## 산출물 목록

### 생성 파일
- `/home/jay/workspace/dashboard/components/CampaignViewUtils.js` (52줄) — 유틸리티 함수 4개
- `/home/jay/workspace/dashboard/components/CampaignSections.js` (1063줄) — 서브컴포넌트 4개
- `/home/jay/workspace/dashboard/data_loader.py` (2434줄) — DataLoader 클래스 추출
- `/home/jay/workspace/dashboard/helpers.py` (410줄) — 독립 헬퍼 함수 추출
- `/home/jay/workspace/dashboard/__init__.py` (0줄) — 패키지 인식용
- `/home/jay/workspace/scripts/generate_file_summaries.py` (약 300줄) — 요약 자동 생성 스크립트
- `/home/jay/workspace/dashboard/server.py.summary.md` — server.py 구조 요약
- `/home/jay/workspace/dashboard/data_loader.py.summary.md` — data_loader.py 구조 요약
- `/home/jay/workspace/dispatch.py.summary.md` — dispatch.py 구조 요약
- `/home/jay/workspace/teams/dev1/token-savings/top20-large-files.md` — 대용량 파일 TOP 20 리스트
- `/home/jay/workspace/teams/dev1/token-savings/task-design-rules.md` — 태스크 설계 규칙 문서

### 수정 파일
- `/home/jay/workspace/dashboard/components/CampaignView.js` (1265줄 → 234줄)
- `/home/jay/workspace/dashboard/server.py` (5271줄 → 2474줄)
- `/home/jay/workspace/dashboard/index.html` (script 태그 2개 추가)
- `/home/jay/workspace/dispatch.py` (_check_referenced_file_sizes 강화 + 프롬프트 삽입 강화)

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **dashboard/__init__.py 미존재** — Pyright가 dashboard 패키지를 인식하지 못함 → 빈 __init__.py 생성
2. **ALLOWED_RECORD_DIRS re-export 누락** — helpers.py로 이동 후 server.py에서 re-export 안 됨 → import에 추가
3. **server.py 미사용 import** — timedelta, timezone이 DataLoader와 함께 이동해야 했으나 남아있음 → 제거

### 범위 외 미해결 (1건)
1. **기존 테스트 실패 10건** — 범위 외 사유: data-dependent/system-dependent pre-existing 실패. git stash로 원본 코드 대비 동일 실패 확인.

## 테스트 결과

### dispatch.py 테스트
- `tests/test_dispatch.py`: **149건 전체 PASS**

### dashboard 테스트
- `dashboard/test_server.py` + `dashboard/tests/`: **228건 PASS, 10건 FAIL (pre-existing)**
- 테스트 회귀: **0건**

### Pre-existing 실패 상세
- ⚠️ 기존 테스트 실패 10건 (본 작업 범위 외):
  - TestGetProjectClassifiedTasks::test_fixed_project_order (data-dependent)
  - TestGetSystemStatus (3건, system-dependent)
  - TestGetCompositeTasks (4건, data-dependent — git stash로 원본 동일 실패 확인)
  - TestSafeReadRecord (2건, data files not found)

## 모델 사용 기록
- 팀원: 아르고스 / 작업 내용: TOP 20 대용량 파일 조사 / 사용 모델: haiku / 정당성: 단순 파일 스캔+리스트 생성
- 팀원: 이리스 / 작업 내용: CampaignView.js 분할 / 사용 모델: sonnet / 정당성: -
- 팀원: 불칸 / 작업 내용: server.py DataLoader 분할 / 사용 모델: sonnet / 정당성: -
- 팀원: 불칸 / 작업 내용: dispatch.py 강화 + 요약 생성 스크립트 / 사용 모델: sonnet / 정당성: -
- 팀원: 아테나 / 작업 내용: 태스크 설계 규칙 문서 / 사용 모델: sonnet / 정당성: -