# 문서를 자료로 바꾸기

> **이 장에서 배우는 것**
> 문서 파일을 에이전트가 다룰 수 있는 형태로 바꾸는 법, 그리고 원본과 사본의
> 관계.
>
> **파일 형식과 인코딩이 낯설다면** [데이터의 형태](/guide/it-data-formats)를 먼저 보세요.

## 문제 — 문서는 그냥은 못 읽습니다

작업 폴더에 PDF와 엑셀이 쌓여 있어도 에이전트가 바로 다루지 못합니다.
[환각을 줄이는 근본 방법](/guide/ai-hallucination)이 "자료를 주고 그 안에서
답하게 하는 것"인데, **자료가 읽히는 형태여야** 그게 됩니다.

## 텍스트 사본을 만듭니다

문서 옆에 **마크다운 사본**을 나란히 놓습니다.

```
사업계획서.pdf
사업계획서.pdf.md      ← 이게 사본
```

이름이 `사업계획서.md`가 아니라 **`사업계획서.pdf.md`**인 게 중요합니다. 원본
이름을 통째로 유지하기 때문에 **어느 파일에서 나온 사본인지** 이름만 보고
압니다.

## 대상은 네 가지

| 확장자 | |
|---|---|
| `pdf` | 문서·보고서·제안서 |
| `docx` | 워드 |
| `xlsx` | 엑셀 |
| `pptx` | 파워포인트 |

**이 넷만 됩니다.** 확장자로 판단하므로 이름이 정확해야 합니다.

## PDF와 나머지는 다릅니다

여기가 자주 놓치는 부분입니다.

```mermaid
graph TD
  A["원본 문서"] --> B{"어떤 종류?"}
  B -->|"PDF"| C["사본은 보조<br/>표·그림은 원본을 봐야"]
  B -->|"docx · xlsx · pptx"| D["사본이 전부<br/>원본은 못 읽음"]
```

| | PDF | docx · xlsx · pptx |
|---|---|---|
| 원본을 직접 읽나 | **읽습니다** (쪽 범위로) | 못 읽습니다 |
| 사본의 역할 | **보조** — 검색·요약용 | **전부** |
| 표·그림 | 원본을 봐야 정확 | 사본에 담긴 만큼만 |

> **PDF는 사본으로 찾고 원본으로 확인하세요.** 사본에서 "3장에 매출 표가 있다"를
> 찾은 뒤, 그 표의 정확한 숫자는 원본 3장을 읽게 하는 것이 맞습니다.
> **엑셀은 사본이 전부**라 사본이 부실하면 그걸로 끝입니다 — 중요한 수치는
> 사람이 확인해야 합니다.

![탐색기 탭에서 폴더의 파일을 보고, 문서에서](/guide-assets/ht-explorer.png)

탐색기 탭에서 폴더의 파일을 보고, 문서에서 텍스트 사본을 만들 수 있습니다.

## 언제 만들어지나

| 계기 | 범위 |
|---|---|
| 파일을 올릴 때 | 올린 것들만 |
| 파일에서 직접 지정 | 그 파일 하나 |

**폴더를 통째로 훑지 않는 게 기본**입니다. 하위까지 다 뒤지면 관계없는 문서까지
전부 변환되고, 큰 폴더에서는 그게 오래 걸립니다.

이미 사본이 있고 원본이 안 바뀌었으면 **다시 만들지 않습니다.** 강제로 다시
만들 수도 있습니다 — 원본을 고쳤는데 사본이 옛것일 때 씁니다.

## 파일 검색

사본이 생기면 **내용으로 찾을 수 있습니다.**

```
"작년 계약서 중에 손해배상 상한이 없는 것 찾아줘"
```

원본 PDF만 있으면 이런 요청이 안 됩니다. 사본이 있어야 검색이 걸립니다.

> **문서를 많이 다루는 작업 폴더라면 사본 만들기가 첫 단계입니다.** 이걸 안 하고
> 요약을 시키면 매번 파일을 통째로 읽느라 [컨텍스트가
> 찹니다](/guide/ai-context-overflow).

## 실무 흐름

문서가 많은 폴더의 전형적인 순서입니다.

```
1. 문서를 작업 폴더에 모은다
2. 사본을 만든다
3. 사본으로 검색해 관련 문서를 좁힌다
4. 좁혀진 것만 자세히 읽힌다
5. 결과를 확인한다 (특히 숫자)
```

**3번이 핵심입니다.** 100개 문서를 다 읽히는 게 아니라 3개로 좁힌 뒤 읽힙니다.
[도구가 많아질 때](/guide/mcp-too-many-tools)와 같은 원리입니다 — **후보를 줄이는
것이 정확도를 올립니다.**

## git과의 관계

작업 폴더가 저장소이면 **무엇을 버전 관리할지** 정해야 합니다.

| 대상 | 관리 | 왜 |
|---|---|---|
| 원본 문서 | 경우에 따라 | 큽니다. 자주 안 바뀌면 넣어도 됨 |
| **텍스트 사본** | **넣는 쪽 권장** | 작고, 변경 이력이 의미 있음 |
| 생성한 이미지·음성 | **제외** | 이진 파일이 저장소를 불립니다 |

사본을 넣어두면 **문서가 언제 어떻게 바뀌었는지** 이력으로 보입니다. PDF는
바뀌어도 차이를 못 보지만 마크다운은 보입니다.

### 커밋 메시지

에이전트에게 커밋을 맡기면 **이 저장소에서 의미 있는 단어**를 골라 제목을
씁니다. 파일 이름을 전수 조사해서, 너무 흔한 이름은 무시하고 실제로 영역을
가리키는 이름을 씁니다.

> 프레임워크 상용구 목록을 관리하는 대신 저장소에 직접 물어보는 방식입니다 —
> 파일 상당수가 가진 이름은 그 자체로 상용구이기 때문입니다.

## 조심할 것

### 사본이 낡습니다

원본을 고쳤는데 사본이 옛것이면 **에이전트가 옛 내용을 자신 있게 말합니다.**
원본을 바꾸면 사본도 다시 만드세요.

### 표와 숫자는 확인하세요

문서 변환에서 표는 가장 잘 깨지는 부분입니다. **금액·날짜·수량이 걸린
판단이라면 원본을 확인**해야 합니다. [조심할 것](/guide/ai-cautions)의 "숫자는
반드시 확인"이 여기 그대로 적용됩니다.

### 민감 문서를 그냥 올리지 마세요

작업 폴더에 넣는 순간 [그 폴더 범위가 에이전트의 활동
범위](/guide/ht-working-directory)입니다. 시스템을
[Connect에 등록](/guide/cn-systems)했다면 워크스페이스 멤버도 닿습니다.

```
□ 이 문서가 이 폴더에 있어도 되나
□ 개인정보가 포함돼 있지 않나
□ 사본까지 만들어 검색에 걸려도 되나
```

---

## 확인

**1. 사본 이름이 `보고서.md`가 아니라 `보고서.pdf.md`인 이유는?**

<details>
<summary>답</summary>

**원본 이름을 통째로 유지해 어느 파일에서 나온 사본인지 이름만 보고 알기
위해서**입니다. 확장자를 떼면 `보고서.docx`와 `보고서.pdf`의 사본이 충돌합니다.
</details>

**2. PDF와 엑셀에서 사본의 역할이 어떻게 다릅니까?**

<details>
<summary>답</summary>

**PDF는 원본을 쪽 범위로 직접 읽을 수 있어 사본이 검색·요약용 보조**이지만,
**docx·xlsx·pptx는 원본을 못 읽어 사본이 전부**입니다. 그래서 엑셀은 사본이
부실하면 그걸로 끝이라 중요한 수치는 사람이 확인해야 합니다.
</details>

**3. 문서가 많은 폴더에서 사본을 먼저 만드는 이유는?**

<details>
<summary>답</summary>

**검색으로 후보를 좁힌 뒤 읽히기 위해서**입니다. 100개를 다 읽히면 컨텍스트가
차고 정확도도 떨어집니다. 좁히는 것이 정확도를 올립니다.
</details>

---

지금까지 본 것을 하나로 잇습니다 → [사례 — 콘텐츠 공장](/guide/ht-case-factory)