# 태스크 설계 규칙: 토큰 소모 절감 가이드

---

| 항목 | 내용 |
|---|---|
| 생성일 | 2026-04-04 |
| 버전 | v1.0 |
| 관련 태스크 | task-1373.1, task-1382.1, task-1383.1, task-1384.1 |
| 작성자 | 아테나 (UX/UI 디자이너) |

---

## 왜 이 문서가 필요한가?

**실제로 터진 사례들:**

- **task-1384.1**: `server.py` 단 하나(222KB)를 통째로 읽다가 Claude Max 한도 초과. 비용 $2.55, 49턴 소모 후 강제 종료.
- **task-1373.1**: `CampaignView.js`(86KB) + `strategy.md`(46KB) + `creative-specs.md`(33KB) 세 파일을 한 세션에 참조 → 토큰 초과.
- **task-1382.1**: `channel-*.md` 파일 4개(33~45KB씩)를 순차 읽기 → 3시간 39분 작업 후 터짐. 결과물 없음.
- **task-1383.1**: `CampaignView.js`(86KB) 하나만으로도 토큰 초과.

비유하자면, 에이전트에게 "도서관 전체를 외워"라고 시키는 것과 같습니다. 책 목차(요약 파일)만 보고 필요한 챕터만 펼치도록 태스크를 설계해야 합니다.

---

## 1. 기본 원칙

| 규칙 | 기준 |
|---|---|
| 한 세션 참조 파일 총 크기 | **50KB 이내** |
| 개별 파일 크기 | 25KB 초과 시 offset/limit 필수 |
| 한 번 Read에 읽는 줄 수 | **200줄 이내** |

이 세 가지 숫자를 기억하세요: **50 / 25 / 200**

---

## 2. 대용량 파일 처리 규칙

### 2.1 요약 파일 우선 참조

대용량 파일에는 반드시 `*.summary.md` 요약 파일이 함께 존재합니다.
에이전트는 원본 파일을 곧바로 열지 않고, **요약 파일을 먼저 읽어 필요한 구간을 파악**한 뒤 원본의 해당 부분만 읽어야 합니다.

```
[작업 흐름]
요약 파일 확인 → 필요한 라인 범위 파악 → 원본 offset/limit 읽기
```

예시:
- `server.py` 필요 시 → `server.py.summary.md` 먼저 읽기
- 요약에서 "인증 로직: 450~600줄" 확인 → `Read(server.py, offset=450, limit=150)`

### 2.2 offset/limit 필수 패턴

```python
# 올바른 방법
Read(file_path="server.py", offset=100, limit=200)

# 잘못된 방법
Read(file_path="server.py")  # 전체 5271줄 읽기 시도 → 토큰 폭탄
```

200줄씩 나눠 읽으면 5271줄 파일도 안전하게 처리할 수 있습니다.
필요한 부분만 읽는 것이 핵심입니다.

### 2.3 "읽지 마세요" 패턴

태스크 파일(task-*.md)에 명시적으로 읽기 금지를 지정합니다:

```markdown
## 참조 파일 주의
- server.py: 전체 읽기 금지. server.py.summary.md를 먼저 참조할 것
- CampaignView.js: 분할 완료. CampaignView.js + CampaignSections.js 개별 참조
- channel-*.md: 한 세션에 2개 이하로 제한
```

에이전트가 규칙을 스스로 판단하도록 기대하지 마세요.
**태스크 파일에 명시해야** 지킵니다.

---

## 3. 태스크 설계 체크리스트

태스크 파일(task-*.md) 작성 전, 아래 항목을 모두 확인하세요.

- [ ] 참조 파일 총 크기가 50KB 이내인가?
- [ ] 25KB 초과 파일에 offset/limit 사용 지시가 명시되어 있는가?
- [ ] 대용량 파일의 `*.summary.md` 요약 파일이 존재하는가?
- [ ] `channel-*.md` 등 유사 계열 파일을 한 세션에 2개 이하로 제한했는가?
- [ ] 리서치와 구현이 분리되어 있는가? (한 태스크에 둘 다 포함 금지)

마지막 항목이 중요합니다. "조사하고 코드도 짜줘"는 세션을 두 배로 키웁니다.
리서치 태스크와 구현 태스크는 반드시 별도 태스크로 쪼개세요.

---

## 4. 파일 크기 기준표

| 크기 구간 | 추정 토큰 | 위험도 | 처리 방법 |
|---|---|---|---|
| ~10KB | ~4,000 | LOW | 전체 읽기 허용 |
| 10~25KB | 4,000~10,000 | MED | 주의, 가급적 분할 |
| 25~50KB | 10,000~20,000 | HIGH | offset/limit 필수 |
| 50KB+ | 20,000+ | CRITICAL | 요약 파일 우선 + 분할 읽기 |

> **기억법**: 25KB = 10,000토큰 = 위험 신호. 이 선을 넘으면 반드시 나눠 읽어야 합니다.

---

## 5. 실행된 개선 사항 (2026-04-04)

이 문서가 작성되기 직전, 아래 조치들이 실행되었습니다:

| 파일 | 변경 내용 |
|---|---|
| `CampaignView.js` | 1265줄 → 234줄로 감소. `CampaignSections.js`, `CampaignViewUtils.js`로 분할 |
| `server.py` | 5271줄 → 2474줄로 감소. `data_loader.py`, `helpers.py`로 분할 |
| `dispatch.py` | 참조 파일 총 크기 한도 50KB 적용, 프롬프트 경고 강화 |
| 신규 도입 | 대용량 파일 자동 요약 생성 스크립트 `generate_file_summaries.py` |

이 조치들은 위기 대응입니다. 앞으로는 파일이 커지기 **전에** 분할을 계획해야 합니다.

---

## 6. 유지 관리

- **신규 파일**: 25KB 이상 파일이 생성될 때마다 `*.summary.md`도 함께 생성
- **정기 갱신**: TOP 20 대용량 파일 리스트(`top20-large-files.md`) 매월 갱신
- **분기 감사**: 분기별 파일 크기 감사 실행. 50KB 초과 파일은 즉시 분할 검토
- **태스크 리뷰**: 새 태스크 파일 작성 시 3번 체크리스트를 의무 통과

---

> 이 규칙은 에이전트를 제약하는 것이 아니라, 에이전트가 끝까지 작업을 완수할 수 있도록 보호하는 장치입니다.
> 토큰 초과로 터지면 지금까지의 작업이 모두 사라집니다. 작게 나눠야 멀리 갑니다.