3.5.3 LLM Wiki 상황별 구축 가이드

1편에서 지형을 보고 2편에서 방식을 비교했다면, 이제 실제로 어떻게 구축할지 결정하고 행동한다. 의사결정 트리, 권장 구성 3단계, 즉시 적용 가능한 설정 스니펫을 제공한다. 업데이트: 2026-05-14

---

핵심 요약

구분	내용
📖 정의	위키 성격에 맞는 LLM 친화 구성을 단계적으로 도입하기 위한 실전 가이드
💡 핵심	최소 구성(진입점 + 지침 파일 + 작성 컨벤션)부터 시작 → 필요할 때 RAG·MCP·GraphRAG 추가
🎯 대상	자신의 위키에 어떤 방식을 어떤 순서로 적용할지 결정해야 하는 사람
⚠️ 주의	한 번에 다 도입하지 마라. 기본 → 표준 → 고급 순서로 점진 적용

---

문서 탐색

이전	다음
3.5.2 방식별 상세 비교	—

---

목차

1. 의사결정 트리 — 어떤 조합을 선택할까
2. 권장 구성 — 기본 / 표준 / 고급
3. Obsidian + Quartz 사용자를 위한 실전 절차
4. 핵심 설정 스니펫
5. 구현 체크리스트
6. 흔히 빠지는 함정

---

1. 의사결정 트리 — 어떤 조합을 선택할까

flowchart TD
    Start["위키 구축 시작"]
    Q1{"위키 규모?"}
    Q2{"공개 여부?"}
    Q3{"주 사용 에이전트?"}
    Q4{"팀 협업 필요?"}

    Start --> Q1
    Q1 -->|"~500 파일"| Q3
    Q1 -->|"500~5000"| Q2
    Q1 -->|"5000+ 파일"| GraphRAG["GraphRAG/LightRAG<br/>+ Markdown+RAG<br/>+ AGENTS.md"]

    Q3 -->|"Claude Desktop<br/>(데스크톱)"| Personal1["Karpathy 패턴<br/>+ CLAUDE.md<br/>+ filesystem MCP"]
    Q3 -->|"Cursor·Continue<br/>(IDE)"| Personal2["AGENTS.md<br/>+ Markdown 컨벤션<br/>+ llms.txt"]
    Q3 -->|"웹 LLM<br/>(ChatGPT 등)"| Personal3["llms.txt<br/>+ Markdown 컨벤션<br/>(공개 사이트)"]

    Q2 -->|"공개"| Q4
    Q2 -->|"비공개"| Team1["Markdown + RAG<br/>+ AGENTS.md<br/>+ MCP 연계"]

    Q4 -->|"예"| Team2["Mintlify/Docusaurus<br/>+ llms.txt 자동 생성<br/>+ AGENTS.md"]
    Q4 -->|"아니오"| Personal2

빠른 판별표

상황	권장 조합	우선 적용
개인 Obsidian + Claude Desktop	Karpathy + CLAUDE.md + filesystem MCP	CLAUDE.md → MCP → 폴더 재구성
개인 Quartz 공개 wiki (현재 사용자 케이스)	AGENTS.md + llms.txt + Markdown 컨벤션 강화	AGENTS.md → frontmatter 점검 → llms.txt
팀 비공개 wiki (Notion/Confluence)	Markdown + RAG + AGENTS.md	RAG 인덱싱 → 메타데이터 정비
공개 docs 사이트	Mintlify/Docusaurus + llms.txt 자동 생성	정적 사이트 마이그레이션 → llms.txt
대규모 기업 KB	GraphRAG + Markdown + RAG + AGENTS.md	단계적 인덱싱

---

2. 권장 구성 — 기본 / 표준 / 고급

위키 운영 성숙도에 따라 3단계로 나눈다. 처음부터 모두 도입하지 말고 기본 → 표준 → 고급 순으로 누적한다.

Level 1 — 기본 (1일 안에 적용)

최소한 갖춰야 할 구성. 비용 0, 인프라 0.

항목	작업	효과
루트 지침 파일	저장소 루트에 AGENTS.md 작성	코딩 에이전트 세션마다 자동 로드
Claude 심링크	CLAUDE.md → AGENTS.md 심링크	Claude Code도 동일 지침 적용
frontmatter 점검	모든 .md에 title, description, date, tags	청크 분리 후에도 정체성 유지
H1 규칙	문서당 H1 한 개, H2/H3 계층 일관성	RAG 청크 품질, LLM 파싱 정확도
약어 풀어쓰기	첫 등장 시 MCP(Model Context Protocol)	LLM 컨텍스트 자체 완결성

Level 2 — 표준 (1주 안에 적용)

위키가 어느 정도 자리잡았을 때 추가하는 구성.

항목	작업	효과
llms.txt 발행	정적 사이트 빌드 시 자동 생성 또는 수동 작성	외부 AI 에이전트 진입점 제공
폴더별 index.md	각 폴더에 index.md 또는 진입 파일	위키 탐색 구조 명확화
wikilink 정비	명시적 링크로 통일 ([[파일명|표시]])	LLM이 따라가는 링크 그래프
MCP 연결	Claude Desktop에 filesystem MCP 추가	에이전트가 위키 read/write
log.md	변경 이력을 누적 기록	에이전트 작업 추적·감사

Level 3 — 고급 (필요 시)

규모가 커지거나 특수 요구가 생겼을 때 추가한다.

항목	작업	효과
RAG 인덱싱	Markdown → 벡터 DB (Chroma·LanceDB)	대규모 검색·챗봇
GraphRAG / LightRAG	엔티티·관계 추출 → 지식 그래프	다중 hop 추론
obsidian-mcp-server	Obsidian vault 전용 MCP	백링크·태그 API 활용
자동 Lint 에이전트	Karpathy 패턴 — 중복·stale 점검	위키 건강도 유지
세분화 규칙	.cursor/rules/*.mdc	Cursor 사용 시 글롭별 규칙

---

3. Obsidian + Quartz 사용자를 위한 실전 절차

사용자 케이스(Obsidian vault + Quartz 정적 사이트 + AI/MCP 자료 정리)에 맞춘 단계별 절차다.

Step 1 — vault 루트에 AGENTS.md 작성 (30분)

vault 루트(또는 Quartz의 content/ 루트)에 AGENTS.md를 작성한다. 핵심 설정 스니펫 참조.

Step 2 — frontmatter 일괄 점검 (1~2시간)

기존 문서들의 frontmatter를 점검한다. 누락된 필드 추가:

---
title: 문서 제목
description: 한 줄 요약
date: 2026-05-14
tags: [태그1, 태그2]
---

description 필드는 RAG 청크 메타데이터로 자주 활용되니 빠뜨리지 않는다.

Step 3 — Claude Desktop에 filesystem MCP 연결 (30분)

%APPDATA%\Claude\claude_desktop_config.json 편집:

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "E:\\OneDrive\\3.code\\obsidian\\quartz\\quartz\\content"
      ]
    }
  }
}

재시작 후 Claude Desktop에서 vault 파일을 직접 read/write 가능.

Step 4 — Quartz에 llms.txt 발행 (선택, 1시간)

Quartz는 기본적으로 llms.txt 자동 생성 기능이 없으므로 빌드 후 후처리 스크립트를 추가하거나 수동 작성한다.

// quartz/plugins/emitters/llmsTxt.js (커스텀 emitter)
import { glob } from "glob";
import fs from "fs/promises";
 
export const LlmsTxt = () => ({
  name: "LlmsTxt",
  async emit({ argv }) {
    const files = await glob("**/*.md", { cwd: argv.directory });
    const lines = ["# 내 지식 위키", "", "> AI/LLM/MCP 관련 학습 노트 모음", "", "## 문서"];
    for (const f of files) {
      const slug = f.replace(/\.md$/, "");
      lines.push(`- [${slug}](https://example.com/${slug}.md)`);
    }
    await fs.writeFile(`${argv.output}/llms.txt`, lines.join("\n"));
    return ["llms.txt"];
  },
});

Step 5 — 작업 로그(log.md) 시작 (선택)

Karpathy 패턴을 차용. vault 루트에 log.md를 두고 에이전트가 변경할 때마다 한 줄 추가하도록 AGENTS.md에 지시한다.

---

4. 핵심 설정 스니펫

AGENTS.md 템플릿 (개인 wiki용)

# AGENTS.md
 
이 저장소는 개인 학습용 Obsidian + Quartz 위키다.
 
## 폴더 구조
 
- `content/1. ai/` — AI 관련 학습 노트
  - `1.overview/` — 개념 입문
  - `2.basic/` — 기본 도구 사용법
  - `3.advanced/` — 심화 주제
- `content/99. etc/` — 기타
- `content/personalSetting/` — 개인 설정·메타 문서
 
## 파일 네이밍 규칙
 
- 모든 `.md` 파일은 `{인덱스}.camelCase.md` 형식
  - 예: `3.5.1.llmWikiLandscape.md`
- 인덱스는 폴더 위계를 반영 (3.advanced/5. llm_wiki/ → 3.5.x)
 
## 문서 작성 규칙
 
- frontmatter 필수: `title`, `description`, `date`, `tags`
- 한국어 본문, 코드·고유명사는 원문 유지
- 말투: 설명체 (`~된다`, `~한다`)
- Mermaid 다이어그램: 방향 TD/TB만 사용, 노드 줄바꿈은 `<br/>`
- Wikilinks: `[[파일명|표시텍스트]]` (테이블 안에서는 `[[파일명\|표시]]`)
- 각 문서 끝에 "문서 탐색" 테이블과 "참고 자료" 섹션
 
## 에이전트가 할 일
 
1. **Ingest**: 사용자가 자료 URL이나 raw 메모를 주면 적합한 폴더에 구조화된 문서로 저장
2. **Query**: 질문 시 관련 wiki 문서를 검색·참조해 답변
3. **Lint**: 요청 시 중복·stale 문서를 리포트
 
## Don't
 
- 기존 문서를 통째로 덮어쓰지 말 것 (Edit 도구 우선)
- 사용자 확인 없이 폴더 구조 변경 금지
- `git push` 자동 실행 금지

Claude Desktop MCP 설정 (Windows)

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "E:\\OneDrive\\3.code\\obsidian\\quartz\\quartz\\content"
      ]
    }
  }
}

llms.txt 수동 작성 예시

# 내 AI 학습 위키
 
> Obsidian + Quartz로 운영하는 개인 AI/LLM/MCP 학습 노트다.
 
## 핵심 주제
 
- [MCP란 무엇인가](https://my-wiki.example.com/3.1.1.whatIsMCP.md)
- [Harness Engineering](https://my-wiki.example.com/3.3.1.whatIsHarness.md)
- [LLM Wiki 지형도](https://my-wiki.example.com/3.5.1.llmWikiLandscape.md)
 
## 옵션
 
- [전체 문서 (Quartz)](https://my-wiki.example.com/)

MarkdownHeaderTextSplitter (RAG 인덱싱 시)

Vanilla JS / Node.js 예시:

import fs from "fs/promises";
import path from "path";
 
function splitByHeaders(markdown) {
  const lines = markdown.split("\n");
  const chunks = [];
  let current = { headers: {}, content: [] };
 
  for (const line of lines) {
    const match = line.match(/^(#{1,3})\s+(.+)$/);
    if (match) {
      if (current.content.length) {
        chunks.push({ ...current, content: current.content.join("\n") });
      }
      const level = match[1].length;
      const text = match[2].trim();
      const headers = { ...current.headers };
      Object.keys(headers).forEach(k => {
        if (Number(k) >= level) delete headers[k];
      });
      headers[level] = text;
      current = { headers, content: [line] };
    } else {
      current.content.push(line);
    }
  }
  if (current.content.length) {
    chunks.push({ ...current, content: current.content.join("\n") });
  }
  return chunks;
}
 
const md = await fs.readFile("wiki/topic-a.md", "utf-8");
const chunks = splitByHeaders(md);
// 각 chunk = { headers: {1:"...",2:"..."}, content: "..." }

---

5. 구현 체크리스트

항목	확인 방법	통과 기준
AGENTS.md 존재	저장소 루트에 파일 확인	1~3K 토큰, 폴더 구조·규칙·금지사항 명시
CLAUDE.md 연결	ls -la CLAUDE.md (심링크 확인)	AGENTS.md를 가리키는 심링크 또는 복사본
frontmatter 완비	임의 10개 파일 샘플 점검	4개 필수 필드(title/description/date/tags) 모두 존재
H1 규칙	grep -c "^# " *.md	모든 파일에서 H1이 정확히 1개
wikilink 정비	깨진 wikilink 검사 도구	깨진 링크 0건
llms.txt 발행	사이트 루트 fetch	HTTP 200, 마크다운 링크 트리
MCP 연결	Claude Desktop → 도구 목록	read_file, write_file 등 노출
Mermaid 방향	grep "graph LR" *.md	0건 (TD/TB만 사용)
약어 정의	임의 문서 검토	첫 등장 시 풀어쓰기 적용
참고 자료 섹션	모든 문서 말미 점검	URL 포함 참고 자료 섹션 존재

---

6. 흔히 빠지는 함정

함정	영향	대처
AGENTS.md를 너무 길게 작성	매 세션 컨텍스트 낭비, 에이전트가 무시	1~3K 토큰 이내, 디테일은 docs/에 분리
frontmatter description 누락	RAG 메타데이터 빈약, 청크 정체성 약화	1~2문장 요약 필수
Mermaid graph LR 사용	Quartz 렌더링 시 가로 다이어그램이 페이지 깨짐	항상 TD/TB
노드 텍스트에 \n 사용	Mermaid 파싱 실패	<br/> 사용
wikilink 대신 상대 경로	LLM이 링크 그래프 못 따라감	[[파일명|표시]] 통일
모든 방식을 한 번에 도입	운영 부담, stale 가속화	Level 1 → 2 → 3 점진 적용
stale 문서 방치	LLM이 옛 정보를 사실로 답변	정기 Lint(에이전트 실행), date 갱신
llms.txt 자동 동기화 안 함	사이트 구조 변경 후 깨진 링크 누적	빌드 파이프라인에 자동 생성 통합
MCP write 권한 무제한	에이전트 실수로 파일 손상	읽기 전용 MCP 또는 git으로 백업
CLAUDE.md와 AGENTS.md 중복 작성	두 파일 간 drift 발생	심링크로 단일 진실 소스

---

마치며

LLM 친화 위키의 본질은 **“에이전트도 독자로 인정하는 글쓰기”**다. 표준 파일(llms.txt, AGENTS.md), 메타데이터(frontmatter), 청크 친화 구조(H1/H2/H3 계층), 에이전트 채널(MCP)은 모두 이 인식에서 출발한다.

처음부터 완벽한 인프라를 구축할 필요는 없다. Level 1(기본 구성)만으로도 LLM과의 협업 품질이 즉시 향상된다. 위키가 자라면서 Level 2·3을 점진적으로 추가한다.

---

문서 탐색

이전	다음
3.5.2 방식별 상세 비교	—

---

참고 자료

• agents.md — AGENTS.md 표준 사이트
• BuildBetter.ai: AGENTS.md Complete Guide for Engineering Teams 2026
• llmstxt.org — llms.txt 사양
• Mintlify: Real llms.txt examples
• Karpathy LLM Wiki Gist
• Anthropic: Claude Code best practices
• Anthropic: filesystem MCP server (GitHub)
• cyanheads/obsidian-mcp-server
• Quartz 공식 문서
• LangChain MarkdownHeaderTextSplitter
• Fern: How to write LLM-friendly documentation
• Apify: Optimizing content for LLMs