지식기반 (KB) & 내부 위키
검색 + AI RAG에 최적화된 KB 설계
지식기반(KB)은 AI RAG(Retrieval-Augmented Generation) 시스템의 핵심 데이터 소스입니다. KB가 잘 설계되어 있으면 AI는 정확한 정보를 찾아 답변하고, 그렇지 않으면 관련 없는 문서를 참조합니다.
왜 KB 구조가 AI 시대에 중요한가
RAG 시스템은 질문과 관련된 문서를 벡터 검색으로 찾습니다. 이때 문서 단위가 크면(예: 100페이지 Confluence), 관련 없는 내용도 함께 가져와 답변 품질이 떨어집니다. 반대로, 작은 단위의 잘 태그된 문서는 정확한 검색과 답변을 가능하게 합니다.
Atomic Documentation 원칙
1주제 = 1문서
거대한 문서를 작은 단위로 분리합니다. 각 문서는 하나의 주제만 다루고, 다른 주제는 링크합니다.
| 기존 (Monolithic) | AI-optimized (Atomic) |
|---|---|
| "개발 가이드" 100페이지 1개 | 환경 설정, API 사용법, 배포 등 20개 문서 |
| 찾고 싶은 내용이 문서 중간에 | 제목만 보고 원하는 문서 특정 |
| RAG가 전체를 가져옴 | RAG가 필요한 문서만 가져옴 |
메타데이터 설계
모든 KB 문서에 frontmatter 메타데이터를 추가합니다. AI가 문서를 분류, 필터, 검색하는 핵심입니다.
---
title: PostgreSQL 연결 설정
description: 개발/스테이징/프로덕션 환경별 DB 연결 설정 가이드
category: infrastructure/database
tags: [postgresql, database, connection, environment]
status: current # current | outdated | archived
created: 2026-01-15
updated: 2026-03-20
author: infra-team
related:
- /docs/env-variables
- /docs/db-migration
---필수 메타데이터 필드
| 필드 | 용도 | AI 활용 |
|---|---|---|
title | 문서 제목 | 검색 매칭, 목록 표시 |
description | 한 줄 요약 | 관련성 판단, 검색 스니펫 |
category | 분류 경로 | 필터링, 계층 탐색 |
tags | 키워드 | 유사 문서 탐색, 검색 확장 |
status | 문서 상태 | 최신 문서 우선, 만료 문서 제외 |
updated | 마지막 수정일 | 최신성 판단 |
related | 관련 문서 | 추가 컨텍스트 탐색 |
Single Source of Truth
같은 정보가 여러 문서에 중복되면 버전 불일치가 발생합니다.
원칙:
- 정보는 한 곳에만 작성
- 다른 곳에서는 링크로 참조
- "복사-붙여넣기" 대신 "참조" 원칙
## 환경변수 설정
환경변수 목록은 [환경변수 레퍼런스](/docs/env-variables)를 참조하세요.Before/After
Before — 거대한 Confluence 페이지:
[개발 가이드] (120페이지)
├── 환경 설정 (페이지 내 섹션)
├── API 사용법 (페이지 내 섹션)
├── 배포 방법 (페이지 내 섹션)
├── 트러블슈팅 (페이지 내 섹션)
└── 팀 컨벤션 (페이지 내 섹션)After — Atomic KB:
docs/
├── setup/
│ ├── local-dev.md (frontmatter + 태그)
│ ├── staging.md
│ └── production.md
├── api/
│ ├── auth.md
│ ├── users.md
│ └── payments.md
├── deploy/
│ ├── ci-cd.md
│ └── rollback.md
└── troubleshooting/
├── db-connection.md
└── memory-leak.md관계 그래프
문서 간 관계를 related 필드로 명시하면, AI가 관련 문서를 추가로 탐색할 수 있습니다.
템플릿: KB 문서
---
title: [문서 제목]
description: [한 줄 요약]
category: [대분류/소분류]
tags: [태그1, 태그2, 태그3]
status: current
created: [YYYY-MM-DD]
updated: [YYYY-MM-DD]
author: [작성자/팀]
related:
- [관련 문서 경로 1]
- [관련 문서 경로 2]
---
## 개요
[이 문서가 다루는 내용 2-3문장]
## [핵심 내용]
[구조화된 내용 — 표, 목록, 코드 블록]
## 참고
- [관련 문서](링크)
- [외부 참조](링크)AI가 실패하는 패턴
| 실수 | AI가 실패하는 이유 | 수정 방법 |
|---|---|---|
| 하나의 문서에 5개 주제 | RAG가 관련 없는 내용도 가져옴 | 1주제 = 1문서 (atomic) |
| frontmatter 없음 | AI가 문서 분류/필터 불가 | title, tags, category, status 필수 |
| 같은 내용이 3곳에 중복 | 버전 불일치 발생 → AI가 모순된 정보 전달 | single source of truth + 링크 |
| status 관리 안 함 | AI가 outdated 문서를 최신으로 답변 | status: current/outdated/archived |
AI 프롬프트 예시
다음 Confluence 페이지를 atomic KB 문서들로 분리해줘.
원칙:
- 1주제 = 1문서
- 각 문서에 frontmatter (title, description, category, tags, status, related)
- 문서 간 참조는 링크로
- 중복 내용 제거, single source of truth
원본 페이지:
[붙여넣기]체크리스트
| 항목 | 확인 |
|---|---|
| 모든 문서가 1주제 = 1문서 원칙을 따르는가 | ☐ |
| 모든 문서에 frontmatter 메타데이터가 있는가 | ☐ |
| category와 tags가 일관적인 체계를 따르는가 | ☐ |
| status가 관리되고 있는가 (current/outdated/archived) | ☐ |
| 중복 내용 없이 링크로 참조하는가 | ☐ |
| related 필드로 문서 간 관계가 연결되어 있는가 | ☐ |
| updated 날짜가 실제 수정일과 일치하는가 | ☐ |