서론

「문서나 지식을 AI에게 읽히고 싶다」는 니즈가 급격히 증가했습니다. Claude Code와 같은 에이전트에게 리포지토리(Repository) 전체를 전달하거나, RAG의 지식 베이스로 입력하거나, 사내 Wiki를 그대로 참조하게 하는 등 용도는 다양하지만, 그 과정에서 반드시 마주하게 되는 질문이 있습니다.

디렉터리가 깔끔하게 정리되어 있고

index.md

도 존재하는 리포지토리와, Obsidian처럼 태그가 지정된 플랫(Flat)한 Markdown 군. AI에게는 어느 쪽이 「더 빠르고, 저렴하고, 정확하게」 컨텍스트(Context)를 인식할 수 있을까요?

결론부터 말씀드리겠습니다.

AI 에이전트에게 「탐색」을 시킨다면 → 계층 구조 + index.md 가 유리 (빠르고, 저렴하며, 헤매지 않음)
RAG (벡터 검색)로 「끌어온다면」 → 태그 (메타데이터)는 강력한 무기가 됨
베스트는 둘 다 취하는 것: 디렉터리로 구조를 잡고, frontmatter의 태그로 메타데이터를 갖게 함

이 기사에서는 왜 그런 결과가 나오는지 「AI가 어떻게 리포지토리를 읽는지」라는 메커니즘부터 해설하고, 실례와 비교표, 그리고 오늘부터 바로 사용할 수 있는 설계 지침까지 정리합니다.

애초에 AI는 두 가지 「읽기 방식」을 한다

비교의 전제로서, AI가 리포지토리를 인식하는 방법은 크게 두 가지로 나뉩니다. 이 부분을 혼동하면 논의가 어긋나게 됩니다.

1. 에이전트형 (탐색해서 읽기)

Claude Code, Cursor, Devin과 같은 코딩 에이전트는 인간 엔지니어와 마찬가지로 파일 트리(File Tree)를 따라 움직입니다.

ls / glob으로 파일 목록을 확인
↓
디렉터리명·파일명으로부터 「어디를 봐야 할지」 추측
...

이때 소비되는 것은 「읽은 파일의 토큰(Token)」입니다. 즉, 불필요한 파일을 열지 않게 할수록 더 저렴하고 빨라집니다.

2. RAG형 (사전에 Embedding하여 가져오기)

문서를 청크(Chunk) 단위로 분할하고, 임베딩(Embedding)하여 벡터 DB에 넣어둔 뒤, 질문 시 유사한 청크를 끌어오는 방식입니다.

모든 문서를 청크 분할 → Embedding → Vector DB
↓
질문을 Embedding → 유사 검색 → 히트한 청크만 LLM에 전달

이 방식에서는 디렉터리 구조 그 자체보다 청크의 의미적인 덩어리와 메타데이터 (태그)를 통한 필터링이 효과적입니다.

이 「두 가지 방식」을 염두에 두면, 어떤 형식이 유리한지는 용도에 따라 달라진다는 것을 알 수 있습니다.

「계층 구조 + index.md」 형식의 강점

Next.js나 Kubernetes의 공식 문서, 혹은 Diátaxis를 따른 docs 디렉터리를 떠올려 보세요.

docs/
├── index.md # 전체 지도 (목차 + 개요)
├── getting-started/
...

왜 에이전트에게 강한가

디렉터리명이 최강의 메타데이터: guides/authentication.md는 열어보기 전부터 내용을 추측할 수 있습니다. 에이전트는 「불필요한 파일을 열지 않겠다」는 판단을 할 수 있습니다.
지도로서의 역할: 최상위의 index.md가 지도가 됩니다. index.md를 단 한 장 읽는 것만으로 전체상을 파악할 수 있습니다. 이는 수백 토큰으로 전체 맵을 얻는 것을 의미하며, 비용이 극적으로 저렴합니다.
헤딩 계층이 그대로 컨텍스트가 됨: ## / ### 구조는 RAG에서 청크를 분할했을 때 「브레드크럼 (이 청크는 어느 장의 이야기인가)」으로서 부여하기 쉽습니다.

비용의 이미지

100개의 파일이 있는 리포지토리를 탐색시킬 경우:

index.md 있음: index.md (약 500토큰) → 목적 파일 2~3개만 read. 합계 수천 토큰.
index.md 없음·플랫함: 우선 모든 파일을 ls로 확인하고, 감을 잡기 위해 관련 있어 보이는 파일을 하나씩 전부 read. 수만 토큰으로 불어날 수도 있음.

에이전트 운용에서는 이 차이가 곧바로 요금과 대기 시간이 됩니다.

「Obsidian 형식 (태그 + 링크)」의 강점과 약점

Obsidian이나 Foam 스타일은 플랫하게 나열된 .md 파일에 frontmatter의 태그와 **[[wikilink]]**를 사용하여 의미적인 연결성을 부여합니다.

---

tags: [auth, security, backend]
aliases: ["認証", "ログイン"]
...

강점

• 태그는 RAG의 메타데이터 필터와 궁합이 매우 좋음: tags: [auth]는 그대로 벡터 DB(Vector DB)의 메타데이터가 되어, "인증 카테고리만으로 검색"과 같은 하이브리드 검색(Hybrid Search)을 실현할 수 있습니다. 이는 계층 구조만으로는 가지기 어려운 정보입니다.
• 링크가 지식 그래프(Knowledge Graph)가 됨: [[...]]의 연관성은 Graph RAG(관련 노드를 따라가며 문맥을 보강하는 기법)의 재료가 될 수 있습니다.
• 1토픽 1파일의 입도(Granularity): 제텔카스텐(Zettelkasten) 방식으로 입도가 일정하면, 청크(Chunk) 분할이 깔끔하게 이루어져 임베딩(Embedding)의 정확도를 높이기 쉽습니다.

약점 (에이전트에게는 불리해지기 쉬움)

• 링크 해결의 비용: Obsidian 앱은 링크를 해결하여 그래프를 그리지만, Claude Code 등은 [[wikilink]]를 AI에게는 단순한 텍스트로 취급합니다. 에이전트는 링크 대상을 스스로 grep 하여 찾아야만 합니다. 인간을 위한 편리한 기능이 에이전트에게는 불필요한 검색 비용이 됩니다.
• 플랫한 구조는 "지도"가 없음: 모든 파일이 1계층으로 나열되면 ls 결과가 거대한 리스트가 되어, 어떤 파일을 열어야 할지 추측하기 어렵습니다. 파일명이 2024-03-15.md와 같은 날짜라면 최악입니다.
• 태그는 파일을 열지 않으면 읽을 수 없음: 디렉터리 이름은 ls만으로 볼 수 있지만, frontmatter의 태그는 각 파일을 읽어야(read) 알 수 있습니다. 탐색형 작업에서는 비용이 많이 듭니다.

즉, Obsidian 형식은 RAG 전처리를 제대로 구축한다는 전제 하에는 빛을 발하지만, "그대로 에이전트에게 전달하는" 용도로는 계층 구조에 한 수 밀린다는 것이 실태입니다.

비교표

관점	계층 구조 + index.md	Obsidian 형식 (태그 + 링크)
컨텍스트 정확성 (에이전트)	◎ 디렉터리 이름으로 의도가 명확함	△ 플랫하여 길을 잃기 쉬움
...

대략적으로 말하자면, 탐색형은 디렉터리, 검색형은 태그가 효과적이라는 역할 분담이 존재합니다.

그럼 어떻게 만들어야 할까? —— 두 마리 토끼를 잡는 실전 레시피

현실적인 최적해는 "둘 중 하나"가 아니라 "겹치는 것"입니다.

1. 최상단에 "AI용 지도"를 한 장 둔다

README.md나 index.md, 그리고 AI 에이전트를 위해서는 CLAUDE.md(Claude Code용)나 llms.txt(Jeremy Howard/Answer.AI가 제안한, 사이트 구조를 LLM에 전달하기 위한 제안 포맷)를 준비합니다. 여기에 "무엇이 어디에 있는지"를 수백 토큰 내외로 적어두는 것만으로도 에이전트의 초기 동작 비용을 급격히 줄일 수 있습니다.

llms.txt

# 이 리포지토리의 가이드
- `guides/` : 구현 가이드
- `reference/` : API 레퍼런스
...

2. 디렉터리로 "구조"를 갖춘다

의미 있는 디렉터리 이름을 붙이고, 각 디렉터리에 index.md(개요 + 하위 파일 링크)를 둡니다. 이것이 에이전트의 탐색 비용을 낮추고 속도를 높여줍니다.

3. frontmatter로 "메타데이터"를 갖춘다

Obsidian의 장점을 흡수합니다. 디렉터리 구조를 깨뜨리지 않으면서, 각 파일의 상단에 태그를 붙입니다.

---
title: "인증 설계"
tags: [auth, security, backend]
...

이렇게 하면 RAG에 올릴 때 메타데이터 필터가 작동합니다. 구조(디렉터리)와 메타데이터(태그)는 배타적인 것이 아니라 양립할 수 있다는 점이 핵심입니다.

4. 링크는 AI에게 친화적인 형태로

[[wikilink]]보다 에이전트가 따라가기 쉬운 상대 경로의 일반 링크([인증 설계](./auth.md))를 병용하면 인간과 AI 모두에게 친절합니다. Obsidian은 Wikilink와 표준 Markdown 링크를 모두 지원하므로, 설정에서 표준 링크 위주로 구성해 두면 유연하게 대처할 수 있습니다.

실제 사례 및 도구로 확인하기

"어느 쪽이 옳은가"는 기존의 성공 사례를 보면 답을 찾을 수 있습니다.

• llms.txt: 그야말로 「AI에게 사이트/리포지토리 구조를 전달하기」 위한 계층적인 지도 포맷입니다. 평면적인 태그가 아니라, **구조화된 목차 (Table of Contents)**를 밀고 있다는 점이 시사적입니다.
• Dendron: Obsidian 스타일의 Markdown 지식 도구이지만, project.backend.auth와 같은 계층적 명명 (Hierarchical Naming) 방식을 채택하고 있습니다. 평면적인 지식 관리 도구조차 AI/검색성을 의식하면 계층 구조로 기울게 된다는 좋은 사례입니다.
• Repomix / gitingest: 리포지토리를 하나의 텍스트로 묶어 LLM에 전달하는 도구입니다. 여기서도 디렉토리 트리 (Directory Tree)를 서두에 출력합니다. 구조야말로 컨텍스트 (Context)의 토대라는 것을 알 수 있습니다.
• PARA / Diátaxis: 인간을 위한 정보 정리법이지만, 모두 「역할에 따라 디렉토리를 나눈다」는 발상을 공유합니다. AI에게도 이러한 구분은 그대로 컨텍스트 (Context)의 힌트가 됩니다.

한편, 태그의 가치도 명확합니다. **하이브리드 검색 (Hybrid Search, 벡터 + 메타데이터 필터)**은 최근 RAG의 정석이며, tags는 그 필터 조건으로서 직접적으로 작용합니다. 태그를 버릴 필요는 전혀 없습니다.

요약

목적이 만약…	추천 방식
Claude Code 등에 리포지토리 탐색을 맡기고 싶다면	계층 구조 + index.md (+ CLAUDE.md / llms.txt)
RAG의 지식 베이스로 만들고 싶다면	계층 구조 + frontmatter 태그 (하이브리드 검색 전제)
인간과 AI가 모두 사용하는 사내 지식	둘 다 적용 (디렉토리 구조 + 태그 + 표준 링크)

• 에이전트 (Agent)는 「인간과 마찬가지로 트리를 따라 이동」하므로, 디렉토리 이름과 index.md가 최강의 컨텍스트 (Context) 힌트가 되어 빠르고, 저렴하며, 정확합니다.
• Obsidian의 태그나 링크는 RAG의 메타데이터 (Metadata)로서는 매우 우수하지만, 평면 구조나 위키링크 (Wikilink)는 에이전트가 그대로 탐색하기에는 비용이 많이 듭니다.
• 따라서 대립시키지 말고, 구조는 디렉토리로, 의미는 태그로 겹쳐서 사용하는 것이 2026년 시점의 베스트 프랙티스 (Best Practice)입니다.

「AI 친화적인 리포지토리」는 결국 「신입 엔지니어에게 친화적인 리포지토리」와 거의 같습니다. 지도가 있고, 이름만으로 내용을 알 수 있으며, 길을 잃지 않습니다.

당신의 리포지토리는 지금, AI 에이전트가 가장 먼저 펼쳐볼 지도 한 장을 가지고 있습니까?

참고 링크

Discussion