# 대용량 파일 관리 가이드라인

최종 업데이트: 2026-03-27
작성: 이쉬첼 (프론트엔드 개발자)

---

## 1. 파일 크기 제한 기준

- 권장 최대: 10,000 토큰 (약 25,000 바이트)
- 경고 수준: 5,000~10,000 토큰 → 분리 검토 필요
- 위험 수준: 10,000 토큰 초과 → 즉시 분리 조치 필요

토큰 추정 방법: 파일 바이트 수 ÷ 2.5 = 대략적 토큰 수

---

## 2. 큰 파일 작성 시 원칙

### 2-1. 3레이어 구조 적용

모든 문서는 "목차 → 요약 → 상세" 순으로 구성한다.

- 목차: 파일 상단에 위치. 전체 섹션 링크 포함.
- 요약: 각 섹션의 핵심을 3줄 이내로 압축.
- 상세: 구체적 내용, 코드 예시, 데이터 등.

에이전트가 파일을 읽을 때 목차만 확인해도 필요 섹션을 파악할 수 있어야 한다.

### 2-2. 파일 유형별 분리 원칙

상시 참조용 (SKILL.md 또는 메인 문서):
- 에이전트가 매 작업마다 읽는 핵심 규칙만 포함
- 목표 크기: 5,000 토큰 이하
- 세부 절차, 예시 코드는 포함하지 않음

필요 시 참조용 (SKILL-REF.md 또는 -ref.md 접미사):
- 상세 절차, 엣지 케이스, 고급 옵션
- 에이전트가 특정 작업 시에만 읽음

운영 데이터 (SKILL-OPS.md 또는 -ops.md 접미사):
- 런타임 상태, 설정값, 실행 이력
- 자주 갱신되는 데이터

코드 예시 (examples/ 디렉토리):
- 3개 이상의 코드 블록이 있으면 별도 파일로 분리
- 경로 예시: skills/my-skill/examples/basic-usage.md

---

## 3. Read tool 사용 가이드

### 3-1. 대용량 파일 읽기 절차

1단계: 파일 구조 파악 (처음 100줄만 읽기)
- offset 미지정, limit=100 으로 읽어 목차와 구조 확인

2단계: 필요 섹션 위치 파악
- 목차의 줄 번호 또는 섹션 헤딩으로 위치 추정

3단계: 해당 섹션만 읽기
- offset=시작줄, limit=필요한 줄 수 지정

### 3-2. 규칙 요약

- 10,000 토큰 초과 파일은 반드시 offset/limit 파라미터 사용
- 전체 파일 읽기(offset/limit 미지정)는 5,000 토큰 이하 파일에만 허용
- 파일 구조를 먼저 파악(head 100줄)한 후 필요 부분만 읽기
- 같은 파일을 반복 읽는 경우, 읽은 내용을 대화 컨텍스트에 보존

### 3-3. 잘못된 패턴 vs 올바른 패턴

잘못된 패턴:
- 50,000B 파일을 offset/limit 없이 한 번에 읽기
- 필요한 섹션이 중간에 있는데 전체를 읽기
- 동일 파일을 여러 번 전체 읽기

올바른 패턴:
- 먼저 limit=100으로 구조 파악
- 목차에서 필요 섹션 줄 번호 확인
- offset=해당줄, limit=200 등으로 좁게 읽기

---

## 4. 새 문서 작성 시 체크리스트

작성 완료 후 아래 항목을 모두 확인한다.

- [ ] 파일 크기가 25,000 바이트(약 10,000 토큰) 미만인가?
- [ ] 독립적으로 분리 가능한 섹션(코드 예시, 운영 데이터, 상세 절차)이 있는가?
  - 있다면 별도 파일(-ref.md, -ops.md, examples/)로 분리
- [ ] 코드 예시가 3개 이상이면 examples/ 파일로 분리했는가?
- [ ] 파일 상단에 목차가 있는가?
- [ ] 각 섹션에 3줄 이내 요약이 포함되어 있는가?
- [ ] 파일 유형(상시/필요시/운영)에 맞는 내용만 담겨 있는가?

---

## 5. 기존 대용량 파일 처리 절차

1. large-files-inventory.md 에서 대상 파일 확인
2. 팽창 원인 분석 (코드 블록 과다 / 섹션 비대화 / 데이터 누적 등)
3. 분리 계획 수립: 어떤 섹션을 어떤 파일로 분리할지 결정
4. 메인 파일에 분리된 파일 링크 추가
5. 원본 파일에서 이전된 섹션 제거
6. 크기 재측정 및 인벤토리 업데이트

---

## 참고: 토큰/바이트 빠른 환산표

- 5,000 토큰 ≈ 12,500 바이트 (권장 범위)
- 10,000 토큰 ≈ 25,000 바이트 (상한선)
- 15,000 토큰 ≈ 37,500 바이트 (위험)
- 20,000 토큰 ≈ 50,000 바이트 (심각)