[LLM Wiki 설계] Markdown 지식베이스 구조와 llms.txt 활용법

안녕하세요. 재아군의 관찰인생입니다.

오늘은 LLM Wiki 설계을 주제로 정리해보겠습니다. LLM Wiki를 만들겠다고 마음먹어도 바로 막히는 지점이 있습니다. 문서를 어떤 단위로 쪼갤지, 파일명은 어떻게 지을지, llms.txt는 어디에 둘지, 원문과 요약을 어떻게 나눌지가 애매합니다.

이 글은 AI 에이전트와 개발 도구가 문서를 읽고 활용하는 시대에, 우리가 지식베이스를 어떻게 설계해야 하는지에 초점을 맞춥니다.

핵심 요약: LLM Wiki 설계의 핵심은 사람이 관리하기 쉬우면서도 LLM이 안정적으로 읽을 수 있는 문서 계약을 만드는 것입니다.

1. LLM Wiki 설계의 기본 단위

가장 중요한 기준은 한 파일이 하나의 질문에 답할 수 있어야 한다는 점입니다. 너무 긴 문서는 검색과 요약이 흔들리고, 너무 짧은 문서는 맥락이 부족합니다.

개념, 도구, 절차, 의사결정, 사례를 파일 유형으로 나누면 관리가 쉬워집니다. 각 유형마다 필요한 속성과 헤딩이 달라야 합니다.

구성	역할	실무 의미
concept	개념 정의와 배경	정의, 왜 중요한가, 관련 개념
tool	도구 사용법	설치, 설정, 예시, 오류
decision	팀의 판단 기록	배경, 선택지, 결정, 근거
playbook	반복 작업 절차	목표, 단계, 체크리스트

2. Markdown과 frontmatter 규칙

Markdown은 LLM이 읽기 쉬운 형식입니다. 여기에 frontmatter를 붙이면 문서의 상태, 출처, 주제, 업데이트 날짜를 기계적으로 해석할 수 있습니다.

이 흐름을 이해하면 LLM Wiki가 단순 문서 모음과 어떻게 다른지 분명해집니다. 문서가 많아지는 것이 아니라, LLM이 재사용할 수 있는 지식 단위가 늘어나는 것이 목표입니다.

3. llms.txt는 어떤 역할을 하는가?

llms.txt는 사이트나 문서 저장소의 루트에 두는 Markdown 파일로, LLM에게 중요한 문서 목록과 읽는 순서를 알려주는 지도 역할을 합니다. 2026년 기준 강제 표준은 아니지만 문서 플랫폼과 개발자 도구에서 빠르게 채택되고 있습니다.

중요한 점은 llms.txt 하나로 모든 문제가 해결되지 않는다는 것입니다. llms.txt는 입구이고, 실제 품질은 연결된 Markdown 문서의 구조와 최신성에서 결정됩니다.

---
type: concept
status: stable
topic: documentation
updated: 2026-05-15
source:
confidence: medium
---

# llms.txt

## 한 줄 요약
LLM이 읽을 핵심 문서 목록을 제공하는 Markdown 기반 문서 지도입니다.

4. llms-full.txt와 문서 묶음 전략

짧은 컨텍스트에는 llms.txt가 유용하고, 긴 컨텍스트 모델이나 오프라인 분석에는 llms-full.txt 같은 전체 문서 묶음이 유용합니다. 단, 전체 묶음은 오래된 내용이 섞이기 쉬우므로 생성 시점과 범위를 명확히 적어야 합니다.

1. 수집 단계에서는 원문과 출처를 보존합니다.
2. 정리 단계에서는 요약과 판단을 분리합니다.
3. 검토 단계에서는 오래된 정보와 불확실한 정보를 표시합니다.
4. 활용 단계에서는 Claude Code나 Codex가 읽을 수 있는 문서로 제공합니다.

LLM Wiki 설계 운영 아키텍처

LLM Wiki 설계을 실제로 운영하려면 문서 저장소 하나만으로는 부족합니다. 원문을 수집하는 영역, 검토된 지식을 보관하는 영역, AI가 읽을 인덱스 영역, 외부에 공개할 문서 영역을 나누어야 합니다.

이 구분이 없으면 모든 자료가 하나의 폴더에 섞이고, 시간이 지날수록 AI가 최신 문서와 오래된 메모를 구분하지 못합니다. 결국 hallucination을 줄이려고 만든 지식베이스가 오히려 불확실한 컨텍스트를 공급하는 문제가 생깁니다.

층	역할	점검 질문
Raw source	원문·링크·클립 보관	출처와 수집일이 남아 있는가?
Curated wiki	검토된 요약과 개념 정리	사람이 읽어도 독립적으로 이해되는가?
Index	LLM이 읽을 경로 안내	중요 문서와 읽는 순서가 명확한가?
Output	블로그·문서·코드 작업에 사용	실제 결과물로 이어지는가?

개인용이라면 이 구조를 폴더 네 개로만 시작해도 충분합니다. 팀용이라면 문서 소유자, 리뷰 주기, 폐기 기준까지 함께 정의해야 안정적으로 유지됩니다.

5. LLM Wiki 폴더 구조 예시

초기 구조는 복잡하지 않아도 됩니다. 중요한 것은 문서 유형별로 분리하고, 각 폴더에 index 문서를 두는 것입니다.

중요한 것은 모든 도구를 한 번에 붙이지 않는 것입니다. Markdown 문서 구조가 먼저 안정되어야 RAG, MCP, llms.txt, AI 코드 도구가 제대로 힘을 발휘합니다.

6. AI가 읽기 좋은 헤딩과 링크

헤딩은 질문형 또는 작업형으로 작성하는 편이 좋습니다. '설정'보다 'Claude Code에서 Notion MCP를 설정하는 방법'처럼 목적이 드러나는 헤딩이 LLM에게 더 좋습니다.

docs 폴더를 LLM Wiki로 재구성하기 위한 llms.txt 초안을 만들어줘.
필수 문서와 선택 문서를 나누고,
각 링크 옆에 LLM이 읽어야 하는 이유를 한 문장으로 적어줘.

프롬프트에는 항상 범위와 출력 위치를 명시하는 것이 좋습니다. ‘전체를 알아서 정리해줘’보다 ‘보고서를 먼저 만들고, 수정은 승인 후 진행해줘’가 훨씬 안전합니다.

프롬프트를 쓸 때 넣어야 할 제약

• 읽을 폴더와 제외할 폴더를 명시합니다.
• 결과를 어디에 저장할지 파일 경로를 지정합니다.
• 기존 파일을 수정하지 말고 보고서부터 만들라고 지시합니다.
• 출처가 불명확한 내용은 추정이라고 표시하게 합니다.
• 문서 삭제·이동·대량 치환은 별도 승인 후 진행하게 합니다.

이 제약들은 답변을 느리게 만드는 장치가 아니라, 지식베이스를 오래 운영하기 위한 안전장치입니다. 특히 개인 위키가 아니라 팀 위키라면 AI가 만든 변경 사항을 리뷰하는 절차가 반드시 필요합니다.

7. 설계 글의 결론

LLM Wiki 설계는 검색엔진 최적화와 비슷하지만 대상이 사람만은 아닙니다. 사람, 검색, LLM, 에이전트가 모두 이해할 수 있는 문서 구조를 만드는 작업입니다.

• 원문과 요약을 섞지 않습니다.
• 출처와 업데이트 날짜를 남깁니다.
• AI가 만든 내용을 사람 검토 없이 기준 문서로 승격하지 않습니다.
• 공개 가능한 문서와 개인용 문서를 분리합니다.
• 지식베이스가 커질수록 인덱스와 오래된 문서 정리를 우선합니다.

LLM Wiki 설계 실패 사례와 복구 방법

가장 흔한 실패는 자료를 너무 많이 넣는 것입니다. LLM Wiki는 저장소가 아니라 정리된 지식층이기 때문에, 무분별한 클리핑과 자동 요약을 계속 쌓으면 검색 품질이 오히려 떨어집니다.

두 번째 실패는 오래된 문서를 폐기하지 않는 것입니다. AI는 오래된 문서도 그럴듯하게 참고할 수 있으므로, deprecated, draft, verified 같은 상태값을 두고 최신 기준 문서와 구분해야 합니다.

실패 패턴	증상	복구 방법
원문만 계속 저장	검색 결과가 길고 산만함	요약 노트와 기준 문서를 분리
상태값 없음	초안과 확정 문서가 섞임	status 필드를 추가
출처 누락	검증이 불가능함	source와 updated 필수화
AI 대량 수정	링크와 문맥이 깨짐	Git 커밋 후 작은 범위로 수정

복구할 때는 모든 것을 한 번에 정리하려고 하지 말고, 가장 자주 쓰는 주제 10개부터 기준 문서로 승격하는 것이 좋습니다. 작은 성공 루프가 생기면 나머지 자료도 자연스럽게 정리됩니다.

마무리: LLM Wiki 설계은 AI 시대 문서 구조의 핵심입니다

LLM Wiki 설계은 단순히 문서를 예쁘게 정리하는 작업이 아닙니다. 사람이 읽고, AI가 찾고, 에이전트가 활용할 수 있는 형태로 지식을 재구성하는 일입니다.

작게 시작하려면 오늘 다룬 구조 중 하나만 고르면 됩니다. 하나의 폴더, 하나의 index 문서, 하나의 정리 프롬프트만 있어도 LLM Wiki는 시작할 수 있습니다.

참고 자료

• llms.txt reference
• Bright Data LLM-Friendly References
• txt-llms documentation

LLM Wiki 설계 시리즈의 다음 단계는 실제 문서 저장소를 만들고, AI가 읽을 수 있는 인덱스와 검토 루틴을 붙이는 것입니다.