LLM은 전체 파일을 읽을 필요가 없다
출처: Dev.to
코딩 에이전트는 사양, 설계 문서, 그리고 긴 README를 매일 읽습니다. 대부분은 몇 섹션만 필요하지만, 전체 파일을 컨텍스트에 로드합니다.
‘그냥 파일 읽기’의 숨겨진 비용
Here’s a scenario that plays out constantly. You ask your agent to check the error handling section of a 5,000‑line API spec. The agent opens the file, reads all 5,000 lines into its context window, finds the 80 lines it needs, and answers your question.
The result is correct. But the agent also consumed a large number of tokens on the 4,920 lines it didn’t need. Repeat this for every file read in a session, and the waste compounds fast.
The cost isn’t just tokens. A context window stuffed with irrelevant content makes the agent’s answers worse.
사람들이 다르게 하는 일
When a human picks up a 300‑page technical book, they don’t read cover to cover to find the chapter on authentication. They flip to the table of contents, scan the chapter titles, and jump to page 47. LLMs can do the same thing.
마크다운은 이미 구조화되어 있다
Markdown documents have a built‑in structure: headings. A # Title followed by ## Section A followed by ### Subsection A.1 creates a hierarchy that mirrors a book’s table of contents.
Split a Markdown file at heading boundaries, and you get a natural “table of contents + sections” structure. Each heading starts a new section, the heading text becomes the index entry, and the section number becomes the address.
This is the idea behind md2idx, a CLI tool.
md2idx 사용 방법
md2idx는 마크다운 파일을 두 개의 필드를 가진 JSON으로 변환합니다:
index: 번호가 붙은 목차이며 각 줄은 0. API Specification 형식이다.
sections: 헤딩당 하나의 원본 Markdown 문자열이 들어 있는 평탄한 배열.
$ npx md2idx spec.md | jq -r '.index'
# 0. API Specification
## 1. Authentication
## 2. Endpoints
### 3. GET /users
### 4. POST /users
## 5. Error Handling
## 6. Rate LimitingEnter fullscreen mode
Exit fullscreen mode
The serial numbers match the array indices. To read the Error Handling section:
$ npx md2idx spec.md | jq -r '.sections[5]'
## Error Handling
When a request fails, the API returns a JSON error object with... (just the content of that one section)Enter fullscreen mode
Exit fullscreen mode
To read a heading and all its children together:
$ npx md2idx spec.md | jq -r '.sections[2:5][]'
# Endpoints, GET /users, and POST /users — all 3 sectionsEnter fullscreen mode
Exit fullscreen mode
For a 5,000‑line spec where the agent needs 2 sections, context usage goes from ~5,000 lines to ~100 lines (20‑line index + 80 lines of content). Depending on the document and which sections are needed, the reduction is typically 80–98%.
The output is designed to work with jq. One‑line JSON by default (pipe‑friendly), --pretty for formatted output. Reads from a file argument or stdin.
왜 단순히 grep만 사용하지 않을까?
grep -nE '^{1,6} ' spec.md 를 이용하면 헤딩 리스트를 얻을 수 있습니다. 간단한 경우에 한해 충분합니다. 하지만 md2idx는 grep이 해결할 수 없는 문제를 다루고 있습니다:
-
섹션 본문 추출: grep은 헤딩 라인만 반환합니다. 본문을 얻으려면 줄 범위를 계산하고 Read 도구에 오프셋/리미트 사용해야 합니다. md2idx는
jq '.sections[N]'만으로 해결됩니다. -
세텍스 헤딩 (
===/---): grep의#패턴에 보이지 않음 -
#이 코드 펜스 안에 있으면: grep은 잘못된 양을 반환합니다. md2idx는 펜스 블록을 건너뜁니다. -
인라인 마크업: grep은
[link](url)등 그대로 포함합니다. md2idx는 인덱스에서는 마크업을 제거하지만 섹션 내용에는 유지합니다.
Claude 코드 스킬로 자동화
With the md2idx- read skill, the agent autonomously handles everything from fetching the index to selecting sections.
-
The agent checks the file size and, if large, calls md2idx to fetch the index
-
It reads the index and identifies which sections are relevant to the current task
-
It retrieves only those sections via
jqslicing
If more sections are needed, it goes back to step 3 (the index is already in context)
# install the skill
gh skill install oubakiou/md2idx md2idx- read --agent claude- code --scope project
# or with npx
npx skills add oubakiou/md2idx --skill md2idx- read --agent claude- code --yesEnter fullscreen mode
Exit fullscreen mode
Once installed, the agent uses the skill proactively whenever it encounters a large Markdown file. No manual invocation needed — it reads the index first, picks sections, and skips the rest.
A fallback is included. If md2idx isn’t available (network‑restricted environments, permission issues), it falls back to grep for headings and Read tool with offset/limit. Less accurate, but functional.
지금 바로 시도해 보기
# read the index of any Markdown file
npx md2idx README.md | jq -r '.index'
# grab a specific section by number
npx md2idx README.md | jq -r '.sections[2]'
# search within a section
npx md2idx data.md | jq -r '.sections[4]' | grep Tokyo
# global install
npm install -g md2idxmd2idx는 외부 의존성이 전혀 없으며, 마크다운 AST 파서가 아닌 자체 라인 스캐너입니다. ATX 헤딩 (# 스타일), 세텍스 헤딩 (=== / --- 밑줄), 코드 펜스 건너뛰기, 인라인 마크업 제거를 지원합니다.
md2idx는 MIT 라이선스로 전체 오픈 소스이며, LLM 에이전트가 전체 큰 Markdown 파일을 읽을 때 사용해 보세요:
-
npm →
npx md2idx your-file.md | jq -r '.index' -
클로드 코드 스킬 →
gh skill install oubakiou/md2idx md2idx- read
에이전트 워크플로우에서 사용해 보셨다면 어떻게 됐는지 듣고 싶어요 — 아래에 댓글을 달거나 깃허브 이슈 만들기.