만들어보고서야 안 만들어도 된다는 걸 알았다 — AI용 문서 지도를 만들고 그날 버린 기록

📝 한줄 요약

AI에게 문서 전체를 안 읽히려고 "지도"(문서 목차 파일)를 만들었다. 하루 만에 9개를 만들고, 시험하고, 전부 지웠다. 검색 명령 한 줄이 0.068초에 같은 일을 하고 있었기 때문이다. 그런데 지도를 버리고도 "필요한 부분만 골라 읽는 방식"은 살아남았다 — 만들어봤기 때문에 그 둘이 다른 문제라는 걸 알 수 있었다.

바쁘시면 이것만 읽어도 돼요:

• 조사에서 "이런 도구 있다"고 나온 것 중 절반이 빈 껍데기였다 (설치는 되는데 실행 파일이 없음)
• 직접 만들어보니 핵심 기능은 정규식 다섯 줄. 유료 API가 필요한 건 그 위의 부가 기능이었다
• 전체 문서로 지도를 만드니 36만 토큰 — 애초에 한 번에 못 준다는 걸 만들고 나서 알았다
• 만든 지도를 AI에게 주고 시험했더니 절반만 맞혔다. 실패한 쪽이 더 중요한 정보였다
• 결국 검색 명령 한 줄에 밀려 폐기. 그런데 방식 자체는 따로 검증해서 살렸다 — 정확도 같고 읽은 양 절반
• 교훈 하나: 도구가 필요한가와 방식이 맞는가는 다른 질문이다. 섞으면 방식까지 같이 버린다

🎯 이런 분들께 도움돼요

• AI에게 자기 문서·메모를 읽히는 구조를 만들려는 분
• 지식 관리 시스템(PKM)에 AI를 붙여보려다 "뭘 만들어야 하지?"에서 멈춘 분
• 조사해서 도구를 고르는 단계에서 시간을 많이 쓰는 분

😫 문제 상황 (Before)

전날(1편) 문서를 필요할 때만 층층이 열리는 구조로 바꾸기로 설계를 끝냈다. 색인을 먼저 보여주고, AI가 거기서 필요한 문서만 골라 펴게 하는 방식이다.

설계는 끝났는데 실물이 없었다. 그래서 "지도"를 만들기로 했다. 각 프로젝트마다 문서 목록 + 그 안의 제목 + 몇 번째 줄인지를 담은 파일. AI가 그것만 보고 "3번 항목이 필요하네, 14번째 줄부터 읽자" 할 수 있게.

문제는 그걸 만들어야 하는지조차 확신이 없었다는 것이다. 이미 만들어진 도구가 있을 수도 있고, 만들어도 쓸모없을 수도 있었다.

🛠️ 사용한 도구

• Claude Code (Opus) — 조사·제작·검증 전부
• 검증 방법: 같은 AI를 별도로 띄워서(헤드리스) 문제를 풀게 하고 채점

🔧 작업 과정

조사에선 "이미 도구가 있다"고 했다

먼저 남들은 뭘 쓰는지 찾아봤다. 두 개가 나왔다.

하나는 ast-outline — 소개가 이랬다. "AI 코딩 에이전트가 파일 전체를 읽는 대신 필요한 것만 뽑게 한다. 마크다운도 지원." 내가 만들려던 그거였다.

또 하나는 PageIndex — "마크다운에서 계층 트리를 생성. 마크다운은 제목 계층이 명시적이라 PDF보다 빠르고 정확."

둘 다 딱 맞아 보였다. 여기서 멈췄으면 "도구 있으니 쓰자"로 끝났을 거다.

✅ 확인법: 설치해서 실행해봤다.

절반이 빈 껍데기였다

ast-outline  → 설치는 되는데 실행 파일이 없음. 설명란도 비어 있음 (이름만 선점한 상태)
PageIndex    → 설치되는 건 클라우드 서비스 접속용. 유료 API 키가 있어야 함

PageIndex는 공식 문서에 적힌 코드가 설치본에 아예 없었다. GitHub 원본을 직접 받아서야 돌아갔다.

✅ 확인법: 실행 파일 목록이 비어 있음 / import 실패 후 설치된 파일 목록 확인

그런데 그렇게 고생해서 돌린 결과물이 이거였다.

{"doc_name": "2026-08-04", "structure": [
  {"title": "1차 — 감지기 6개도 낡는 거 아니야?", "line_num": 5},
  {"title": "3차 — 메모리에 넣는 게 소용 있어?", "line_num": 14},
  ...

제목이랑 몇 번째 줄인지. 그게 전부였다. 원문 13,031자가 2,219자로 줄긴 했다.

그래서 직접 만들었다 — 다섯 줄

마크다운은 제목 앞에 #이 붙는다. 그러니 #으로 시작하는 줄만 골라 모으면 그게 목차다. 실제로 핵심은 정규식 한 줄이었고, 우리 규칙(한글 파일명, 문서 머리의 정보칸, 계획 문서 문법)에 맞추는 게 나머지였다.

PageIndex의 진짜 값어치는 그 위에 있었다 — 각 항목에 요약을 붙여주는 것. 그건 유료 API를 부른다. 그리고 원래 PDF용으로 만든 도구라 우리한테 필요 없는 짐이 잔뜩 딸려왔다.

✅ 확인법: 직접 만든 것과 PageIndex 결과가 같은 제목·같은 줄번호를 뱉는지 대조

전체로 만들어보니 애초에 불가능했다

전 문서에 돌렸더니 이랬다.

문서 1,769개 / 제목 19,641개
지도 크기 72만자 = 약 36만 토큰

한 번에 줄 수 있는 양이 아니었다. 게다가 무게의 75%가 남의 것이었다 — 참고하려고 받아둔 남의 프로젝트 하나가 43만자를 차지하고 있었고, 정작 내가 매일 만지는 문서는 전체의 0.5%였다.

그래서 각 프로젝트 문서 머리에 붙여둔 상태값(진행중·운영·잠듦 같은 것)으로 걸렀다. 지금 굴리는 것만 남기니 6.2만자. 프로젝트별로 쪼개면 대부분 1만자 이하였다.

✅ 확인법: 폴더별 크기를 표로 뽑아 어디가 무거운지 확인 → 상위 두 개가 전체의 75%

만든 지도를 AI에게 주고 시험했다

9개 프로젝트에 지도가 생겼다. 이제 진짜 질문 — 이게 쓸모가 있나?

별도로 AI를 띄워서 지도 파일만 읽게 하고 물었다. 다른 파일은 못 열게 막고.

그 지도만 보고 답해:
'PowerShell BOM 때문에 파서가 죽은 사고'가 어느 파일 몇 번째 줄쯤에 기록돼 있을 것 같나?
못 찾겠으면 '못찾음'이라고만 답해라.

답은 "못찾음"이었다.

공정한 시험이었는지 확인하려고 다른 질문을 했다.

그 지도만 보고: '이 프로젝트의 최종 목표'가 적힌 파일과 줄번호를 답해라.

이번엔 정확히 맞혔다. 00_전체그림.md:7.

차이가 뭐였냐면 — 실패한 질문의 그 내용은 제목이 ⓪ 백업 실물 가동인 절 안에 있었다. 제목만 봐선 그 안에 그 얘기가 있는 줄 몰랐던 것이다.

✅ 확인법: 정답을 내가 알고 있으니 채점 가능. 두 문제의 성패가 갈린 지점을 비교

그리고 한마디에 전부 지웠다

여기까지 왔을 때 이런 말을 들었다.

지도 파일이 왜 필요한지 잘 모르겠고, 그냥 마크다운 문서에 따라서 순차적으로
제목을 먼저 훑고 필요하면 더 깊이 들어가는 식으로 해주면 되는 거 아니야?
그거는 파일이 아니라 지침에서 하거나, 기계적으로 강제하면 되는 거 아닌가?

재봤다. 검색 명령으로 제목만 뽑는 데 0.068초. 프로젝트 전체 87개 제목을 훑는 데 0.049초.

미리 만들어둔 지도는 문서가 바뀌면 낡는다. 검색은 늘 최신이다.

지도 파일 9개와 생성기를 지웠다. 같은 이유로, 그 전에 세웠던 백과사전식 색인(어떤 단어가 어디에 몇 번 나오는지) 계획도 접었다. 검색으로 "BOM"을 찾는 데 0.9초, 정확한 줄까지 나왔다.

종이책 뒤에 색인이 붙는 이유는 종이엔 검색이 없어서였다. 우린 있다.

✅ 확인법: 같은 결과를 뽑는 데 걸린 시간을 직접 측정(time)

그런데 더 근본적인 질문이 왔다

근데 이걸 하기 전에, 우선 제목부터 순차적으로 읽었을 때
과연 AI가 더 잘 파악할까? 오히려 더 놓치는 거 아닐까?

맞는 걱정이었다. 그날 나는 실제로 그 실수를 했다 — 긴 기록에서 한 구절만 뽑아 읽고 목적을 잘못 이해해서, 며칠간 엉뚱한 방향으로 작업하고 있었다.

지도가 필요 없다는 건 확인했지만, 방식 자체가 나은지는 안 재봤던 것이다.

그래서 실험했다. 같은 문서(251줄), 같은 질문 3개, 두 가지 방식으로.

• A: 문서를 통째로 읽고 답하기
• B: 제목만 먼저 훑고, 필요한 절만 골라 읽고 답하기

질문 중 하나는 일부러 어렵게 냈다. "이 문서에 AI가 사용자 발화를 오독한 사례가 나오나?" — 그 내용은 여러 절에 흩어져 있고, "오독"이라는 단어로 검색해도 안 나온다.

정확도는 같고 읽은 양은 절반. 어려운 문제도 제목을 보고 그 절을 골라 읽어서 맞혔다.

✅ 확인법: 같은 질문·같은 문서로 두 번 돌려 답을 채점하고, 읽은 줄 수를 세게 함

✅ 결과 (After)

Before vs After

하루 종일 만들고 남은 것

파일로 남은 건 없다. 대신 세 가지를 알게 됐다.

1. 지도 파일은 필요 없다 — 검색이 더 빠르고 늘 최신이다
2. 방식은 유효하다 — 정확도 손해 없이 읽는 양이 절반
3. 되는 조건이 있다 — 제목이 내용을 대표할 때만. 제목이 껍데기면 통째로 읽을 수밖에 없다

3번이 제일 값졌다. 다음에 할 일이 "장치 만들기"에서 "제목 잘 쓰기"로 바뀌었기 때문이다. 실제로 내 할 일 목록 파일은 제목이 다음 / 마일스톤 / 이슈 / 한 일 네 개뿐이라 안에 뭐가 있는지 하나도 안 보인다. 거기부터 손보면 된다.

💬 이 과정에서 배운 AI 활용 팁

효과적이었던 것

1. 조사 결과는 돌려보기 전엔 확정이 아니다. "마크다운 지원 CLI"가 빈 껍데기였고, "설치 한 줄"이 유료 서비스 접속용이었다. 둘 다 소개글만 보면 완벽했다.
2. 만들기 전에 대상부터 재본다. 지도를 다 만들고 나서야 36만 토큰이라 못 준다는 걸 알았다. 먼저 쟀으면 범위를 좁혀서 시작했을 것이다.
3. 판정 기준을 먼저 정하고 시험한다. "쓸모 있나?"는 채점이 안 된다. "이 질문에 답하나?"는 채점이 된다. 정답을 내가 아는 질문을 골라야 한다.
4. 실패한 시험이 더 많은 걸 알려준다. 지도가 못 맞힌 질문 하나가 "제목이 내용을 대표해야 한다"는 조건을 드러냈다. 성공한 질문에선 안 나왔을 정보다.

이렇게 하면 안 돼요

1. "도구가 필요한가"와 "방식이 맞는가"를 섞지 마세요. 지도 파일이 필요 없다는 결론에서 멈췄으면, 방식까지 같이 버릴 뻔했다. 따로 재보니 방식은 살아 있었다.
2. 만들었다는 이유로 붙잡지 마세요. 하루를 썼어도 검색 한 줄이 더 나으면 지우는 게 맞다. 안 지우면 그때부터 그 파일을 관리해야 한다.
3. "안 만들어도 되겠지"로 건너뛰지도 마세요. 만들어봤기 때문에 필요 없다는 걸 안 것이다. 안 만들었으면 계속 "지도가 없어서 안 되나 보다" 했을 것이다.

🌍 다른 업무에 적용한다면?

• 자동화 도구를 고르기 전에 처리할 대상부터 세보기. 개수·용량을 재면 후보 절반이 저절로 걸러진다
• AI에게 긴 자료를 줄 때 목차를 먼저 주고 필요한 부분만 지정하기. 자료를 통째로 붙여넣는 것보다 정확도 손해가 없다
• 회의록·업무일지 제목을 내용이 드러나게 쓰기. 나중에 찾을 때 목차만 봐도 되는지가 여기서 갈린다

🚀 앞으로의 계획

장치를 더 만드는 대신 문서 제목부터 손본다. 할 일 목록 파일에 완료된 항목이 12개나 섞여 있고(미완은 8개), 한 항목이 400자까지 늘어난 상태다. 정리하면 그게 곧 "필요한 부분만 읽는 구조"를 만드는 일이기도 하다.

그리고 그 구조가 다시 무너지지 않게 기계가 검사하게 만들 생각이다. 규칙은 이미 있는데 안 지켜진 상태라, 규칙을 한 줄 더 쓰는 건 답이 아니라는 걸 이미 여러 번 확인했다.

📋 재사용 가능한 프롬프트

프롬프트 1: 도구를 고르기 전에 대상부터 재기

이 작업을 위한 도구를 고르기 전에, 처리할 대상부터 실측해줘. [대상 폴더/파일]의 개수·용량·종류별 분포를 표로 보여주고, 그 수치가 도구 선택을 바꾸는 지점이 있으면 짚어줘. 재보기 전에는 도구를 추천하지 마.

프롬프트 2: 만든 것이 쓸모 있는지 채점하기

방금 만든 [결과물]이 실제로 쓸모 있는지 시험하려고 해. 내가 정답을 아는 질문 3개를 낼 테니, 너는 [결과물]만 보고 답해. 다른 파일은 열지 마. 모르겠으면 '못찾음'이라고만 답해. — 질문 중 하나는 일부러 어려운 걸 넣으세요. 실패한 질문이 조건을 드러냅니다

프롬프트 3: 두 방식 비교하기

같은 자료·같은 질문으로 두 방식을 비교해줘. A안: [방식 1]로 답하기 B안: [방식 2]로 답하기 각각의 정답 여부와 읽은 분량(줄 수)을 같이 보고해줘.

아루나의 다른 프로젝트가 궁금하다면 → aluna-site.vercel.app