# dispatch 프롬프트 토큰 최적화 스펙

**작업 ID**: task-285.1
**작성일**: 2026-03-06
**작성자**: 오딘 (개발2팀장)

## 1. 도입 배경

LangSmith CLI Skills의 **Progressive Disclosure(점진적 공개)** 패턴:
- 필요한 스킬만 동적 로딩하여 토큰 낭비 방지
- Claude Code Sonnet 4.6 기준 17% → 92% 성능 향상 달성
- 참고: https://blog.langchain.com/langsmith-cli-skills/

우리 시스템에서 이미 성공한 사례:
- dev3 팀: GLM-WORKFLOW.md 외부 파일 참조로 프롬프트 720자까지 경량화

## 2. 문제 분석

dev1/dev2 `_build_direct_prompt()` 프롬프트 구성 (변경 전 2,254자):
- 팀장 신원 + 작업 지시: ~200자 (동적, 필수)
- 코워크 섹션 (`_build_cowork_section()`): ~400자 (정적 보일러플레이트)
- 워크플로우 7단계: ~800자 (정적 보일러플레이트)
- 작업 규칙: ~300자 (정적 보일러플레이트)
- QC 검증: ~200자 (이미 파일 참조로 경량화)

**정적 보일러플레이트 ~1,500자가 매 위임마다 반복** → 토큰 낭비

## 3. 채택 방안

### 미팅 결과 (2026-03-06)
참석: 오딘(진행), 토르(백엔드), 미미르(UX/UI), 헤임달(테스터)

**방안 A 만장일치 채택**: 보일러플레이트를 DIRECT-WORKFLOW.md로 분리, 프롬프트에 파일 경로 + 최소 변수만 전달

기각된 대안:
- 방안 B (작업 유형별 템플릿): 유지보수 오버헤드 증가, 실질 절감 효과 제한적
- 방안 C (CLAUDE.md 사전 탑재): 매 호출마다 로드되므로 토큰 절감이 아닌 단순 이동

## 4. 구현 결과

### 전후 비교

| 팀 | 변경 전 | 변경 후 | 절감율 |
|----|---------|---------|--------|
| dev1-team | 2,258자 (~564토큰) | 536자 (~134토큰) | **76.3%** |
| dev2-team | 2,254자 (~563토큰) | 532자 (~133토큰) | **76.4%** |
| dev3-team | 720자 (~180토큰) | 720자 (~180토큰) | 변경 없음 |

**목표 50% 절감을 크게 초과 달성 (76%)**

### 수정 파일
1. `/home/jay/workspace/prompts/team_prompts.py` — `_build_direct_prompt()` 경량화
2. `/home/jay/workspace/prompts/DIRECT-WORKFLOW.md` — 신규 생성 (워크플로우 가이드)
3. `/home/jay/workspace/prompts/test_team_prompts.py` — 테스트 업데이트 + 3개 신규 테스트

### 구조 변화
```
변경 전:
  build_prompt() → _build_direct_prompt() [인라인 2,254자]
                 → _build_glm_prompt() [GLM-WORKFLOW.md 참조 720자]

변경 후:
  build_prompt() → _build_direct_prompt() [DIRECT-WORKFLOW.md 참조 532자]
                 → _build_glm_prompt() [GLM-WORKFLOW.md 참조 720자]
```

## 5. 테스트 결과

- 기존 11개 테스트: 모두 통과
- 신규 3개 테스트: 모두 통과
  - `test_direct_workflow_file_exists`: DIRECT-WORKFLOW.md 파일 존재 확인
  - `test_prompt_size_reduction`: dev1/dev2 프롬프트 1,500자 이하 확인
  - `test_placeholder_variables`: 필수 변수 5개 포함 확인
- 일치성 검증: dispatch.py/orchestrator.py 동일 프롬프트 생성 확인

## 6. LangSmith 패턴 도입 현황

| LangSmith 패턴 | 우리 시스템 대응 | 상태 |
|----------------|-----------------|------|
| Progressive Disclosure | DIRECT-WORKFLOW.md / GLM-WORKFLOW.md 외부 참조 | **이번 작업에서 도입** |
| trace (트레이싱) | task-timer.py + 보고서 시스템 | 기존 운영 중 |
| dataset (데이터셋) | - | 향후 과제 |
| evaluator (평가) | QC-RULES.md + 마아트 독립 검증 | 기존 운영 중, 자동화 향후 과제 |

## 7. 위험/주의사항

1. DIRECT-WORKFLOW.md 파일이 삭제/이동되면 팀장이 워크플로우를 참조할 수 없음 → `test_direct_workflow_file_exists` 테스트로 방지
2. 플레이스홀더 변수가 누락되면 팀장이 잘못된 명령 실행 가능 → `test_placeholder_variables` 테스트로 방지
3. 기존 인라인 방식 대비 팀장이 1회 추가 파일 읽기 필요 → 경미한 오버헤드, 토큰 절감 대비 무시 가능