# Budgeted Reads (예산 읽기)

*파일을 개요, 섹션, 줄 범위, 전체로 읽되, 예산에 맞춰 단계적으로 낮춥니다.*

> **Budgeted Reads**는 토큰 예산으로 재는 읽기입니다. 같은 파일을 개요, 섹션, 줄 범위, 전문까지 서로 다른 수준의 상세도로 읽을 수 있습니다. 에이전트는 “N토큰 안에 들어가는 가장 좋은 뷰”를 요청하고, 정확한 원본을 가리키는 증거 포인터를 돌려받습니다.

**AN-08** · 적합성 수준: L2 Memory · 그룹: 지식

## 해결하려는 문제

에이전트는 컨텍스트를 파일 전체와 반복되는 읽기에 소모하고, 순진한 RAG 청킹은 구조를 잃습니다. 모델은 이미 `grep`, `tail`, 줄 단위 읽기에 능합니다. Cursor는 너무 긴 도구 출력을 파일에 써서 에이전트가 필요할 때 읽게 하며, MCP 도구를 호출한 실행에서 도구 설명의 [동적 탐색](https://cursor.com/blog/dynamic-context-discovery)으로 전체 토큰을 46.9% 줄였습니다.

그래서 문제는 “또 하나의 검색 시스템을 만드는 것”이 아니라, 파일 위의 읽기에 **예산이 있고 검사할 수 있는** 계약을 주는 것입니다.

## 동작 방식

- **파일이 먼저입니다.** 표준 읽기(줄 범위 포함)는 항상 쓸 수 있으며, Budgeted Reads는 그 위의 선택적인 확장일 뿐 파일 시스템을 대체하지 않습니다.
- **결정론적 개요(무료):** Markdown의 제목 트리, 코드 심볼(tree-sitter), JSON과 YAML의 키, CSV의 헤더와 행 수. LLM이 필요 없습니다.
- **예산과 품질 저하.** 요청에는 `budget_tokens`가 담기며, 맞지 않으면 **조용히 잘라 내는 대신** 더 거친 뷰로 낮춥니다. 응답은 실제 뷰, 토큰 수, `generated` 여부를 밝힙니다.
- **검색은 스니펫과 포인터를 돌려줍니다.** 파일 전체가 아닙니다.
- **증거 포인터:** `nas://<node>/<tree>/<path>@<commit>#L12-L18`. 안정적이며 커밋에 대해 검증할 수 있고, `dereference`는 정확한 내용을 돌려줍니다.
- **지난번 이후 바뀐 것:** 파일 전체 대신 두 커밋 사이의 diff를 돌려줍니다.
- **선택적인 LLM 요약 계층:** 캐시로서 `generated: true`와 오래됨 표시를 붙입니다.

## 작게 시작하기

- `nas_read` 말고는 아무것도 더하지 마세요. 에이전트가 `rg`와 `sed -n`으로 예전 방식대로 읽게 둡니다.
- 그다음에 Markdown과 코드를 위한 작은 개요 도구를 더합니다.
- 증거 포인터는 “path@commit#line”으로 시작하세요. 새 서비스는 필요 없습니다.

## 인터페이스 스케치

설명을 위한 예시입니다. 필드 이름은 명세 v0.3 이전에 바뀔 수 있습니다.

*POST /v1/files/read*

```http
POST /v1/files/read
{ "path": "/agents/cleo/memory/notes/customer-acme.md",
  "view": "outline", "budget_tokens": 400 }

200 OK
{ "view": "outline", "tokens": 212, "generated": false, "truncated": false,
  "content": "# Acme\n## Renewal (L12-L18)\n## Contacts (L19-L31)\n## Open issues (L32-L40)",
  "evidence": [
    { "pointer": "nas://home-box/agents/cleo/memory/notes/customer-acme.md@9f2c1de#L1-L40" }
  ] }
```

## 명세가 요구하는 것

- 응답은 실제로 돌려준 뷰와 토큰 수를 밝혀야 하며, 생성형 뷰에는 표시를 해야 합니다.
- 예산이 너무 작으면 NAS는 더 거친 뷰로 낮춰야 하며, 조용히 잘라 내서는 안 됩니다.
- 표준 파일 읽기(범위 포함)는 계속 쓸 수 있어야 합니다.
- 증거 포인터는 커밋에 대해 검증할 수 있어야 합니다.
- 검색은 기본적으로 파일 전체가 아니라 스니펫과 포인터를 돌려주어야 합니다.

## 빌려 온 것과 새로운 것

점진적 공개와 grep은 그 자체로 새롭지 않습니다. **새로운 것은** 예산과 증거 포인터를 **스토리지 계층의 읽기 계약**으로 만들어 답을 검사할 수 있게 한 것입니다. 한 문장에서 출발해 그 근거가 된 커밋의 줄까지 되짚어 갈 수 있습니다.

- [Cursor: dynamic context discovery](https://cursor.com/blog/dynamic-context-discovery)
- [Agent Skills (progressive disclosure)](https://agentskills.io/specification)
- [Letta Context Repositories](https://www.letta.com/blog/context-repositories/)
- [RAPTOR](https://arxiv.org/abs/2401.18059)

## 솔직한 한계

- 토크나이저는 모델마다 다르므로 토큰 수는 추정치입니다.
- 클라이언트가 채택해야만 작동합니다.
- 요약은 낡거나 틀릴 수 있으므로 캐시일 뿐이며 항상 표시합니다.

## 열린 질문

- 서로 다른 모델 토크나이저 사이의 예산 오차는 어떻게 다뤄야 하는가?
- 요약의 품질은 어떻게 평가하는가?

## 자주 묻는 질문

### RAG와는 어떻게 다른가요?

RAG는 질문과 가장 가까운 스니펫을 돌려줍니다. Budgeted Reads는 이미 알고 있는 객체에 대해 독자가 상세도를 고르게 하고, 예산이 모자라면 정직하게 품질을 낮추며, 검증할 수 있는 포인터를 줍니다. 둘은 겹쳐 쓸 수 있습니다. 검색 결과도 예산 뷰로 돌려받을 수 있습니다.

### 파일을 읽으려면 꼭 써야 하나요?

아닙니다. 마운트와 Git은 언제나 평범한 파일을 줍니다. Budgeted Reads는 토큰에 신경 쓰는 에이전트를 위한 선택적인 읽기입니다.

### 증거 포인터가 “지어낸 인용”을 막아 주나요?

인용을 검사할 수 있게 합니다. 포인터는 한 커밋의 특정 줄을 가리키고 그 콘텐츠 해시를 검증할 수 있습니다. 모델이 무언가를 지어내는 것을 막지는 못하지만, “인용한 구절이 실제로 있는가?”를 기계가 검사할 수 있는 문제로 바꿉니다.

## 관련 개념

- [Agent Memory (에이전트 메모리)](https://agentnas.com/ko/concepts/agent-memory/): 읽고 고칠 수 있는 노트가 진실입니다. 인덱스는 버려도 되는 캐시입니다.
- [Agent Home (에이전트 홈)](https://agentnas.com/ko/concepts/agent-home/): 역할마다 하나씩, 이력이 있는 디렉터리. 가지고 떠날 수 있는 평범한 파일.
- [Flight Recorder (플라이트 레코더)](https://agentnas.com/ko/concepts/flight-recorder/): 실행마다 하나, 해시로 연결되며 읽은 것까지 담는 기록.

---

표준 URL: https://agentnas.com/ko/concepts/budgeted-reads/
최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0