VitePress 컨벤션

이 장에서 얻는 것

• 이 책에 새 챕터를 추가하거나 기존 챕터를 개정할 때 따라야 하는 규약 전체
• 출처·비공식 자료·논쟁 주제를 다루는 표기법

왜 문제가 되는가

여러 사람이(또는 여러 세션의 AI가) 수십 개 챕터를 쓰면 형식·표기·출처 규율이 금방 흩어진다. 규약을 문서화해 두지 않으면 챕터마다 품질이 들쭉날쭉해지고, 독자는 어떤 수치를 믿어야 할지 알 수 없게 된다.

핵심 개념

챕터 공통 골격

모든 본문 챕터(index.md와 부록 제외)는 아래 골격을 따른다:

---
title: <한국어 제목>
description: <한 문장 요약 — YAML 특수문자 금지>
outline: [2, 3]
---

# <한국어 제목>

::: tip 이 장에서 얻는 것
- <결정할 수 있게 되는 것>
- <계측할 수 있게 되는 것>
:::

## 왜 문제가 되는가
## 핵심 개념
## 결정 표
## 실패 모드
## 안티패턴
## 계측 (SLI)
## 체크리스트
## 참고

"실패 모드" 표와 "체크리스트"는 모든 챕터 필수다. 개념만 있고 이 둘이 없는 챕터는 미완성으로 간주한다.

언어·표기 규칙

• 본문은 한국어. 기술 용어(prompt caching, KV cache, context rot 등)는 영어 원문 유지 — 억지 번역 금지.
• 파일명·디렉터리는 ASCII만.
• 독자를 초심자로 대하지 않는다 — Kubernetes/IAM/OAuth/벡터 검색 기본기는 전제.
• 분량 목표: 챕터당 1,500~4,000 단어.

출처 규율

• 모든 수치에 출처 URL을 붙인다. 출처가 없으면 그 수치를 쓰지 않는다.
• 벤더 주장은 사실처럼 쓰지 않고 "~라고 주장한다" 또는 벤더 표기.
• 비공식 출처(개인 블로그·커뮤니티) 기반 서술에는 아래 블록을 붙인다:

> ⚠️ 비공식 출처 기반 — 공식 문서 교차확인 필요

• 논쟁 중인 주제는 양쪽 입장을 병기하고 아래 컨테이너로 감싼다:

::: warning 미정착 영역
...
:::

• 확인되지 않은 기능·수치·제품명은 만들지 않는다. 모르면 "확인 필요"라고 쓴다.

정본(canonical) 챕터 원칙

같은 수치·개념이 여러 챕터에 필요하면 정본 챕터 하나를 정하고 나머지는 링크한다. 예:

정본 챕터	담당 수치/개념
프롬프트 캐싱 기초	캐시 가격 배수·TTL·최소 토큰
평가 하니스	p^n 에러 복합 표
Context rot	컨텍스트 길이별 성능 저하 연구 수치
검색 평가	recall@20 > 3% 전환 임계치
6대 통증점	전환 임계치 표 전체·실행 로드맵

다이어그램·코드

• 다이어그램은 Mermaid 코드 블록(````mermaid) 우선, 무거운 도해만 docs/public/` SVG.
• 코드 스니펫에는 언어 태그를 붙인다(라인번호는 전역 설정으로 자동).
• ❌/✅ 대조 예시는 안티패턴 섹션 또는 핵심 개념에서 적극 활용.

실패 모드

증상	근본 원인	확인 방법	해결
같은 수치가 챕터마다 다르게 인용됨	정본 원칙 미준수 — 각자 리서치해 다른 시점 값 인용	수치 grep으로 중복 확인	정본 챕터 지정 후 나머지는 링크로 대체
챕터 형식이 제각각	골격 미준수	"실패 모드"/"체크리스트" 섹션 존재 여부 grep	골격 템플릿으로 재정렬
출처 링크가 시간이 지나 죽음	외부 URL의 수명	주기적 링크 체커 실행	아카이브 링크 병기 또는 갱신

안티패턴

• ❌ 인접 챕터의 내용을 복붙해 중복 서술 → ✅ 정본 챕터로 링크하고 역할 분담을 명시.
• ❌ 리서치 시점을 안 밝히고 "최신" 수치 인용 → ✅ 가격·쿼터류는 확인 시점을 명시하고 공식 페이지 링크.

체크리스트 (새 챕터 추가 시)

• [ ] 골격 8개 섹션이 모두 있다(특히 실패 모드 표·체크리스트)
• [ ] 모든 수치에 출처 URL이 있다
• [ ] 비공식 출처·미정착 영역 표기를 적용했다
• [ ] 겹치는 수치는 정본 챕터로 링크했다
• [ ] config.ts 사이드바에 추가하고 빌드가 통과한다

참고

• VitePress 설정 — 빌드·설정 골격
• 용어집 — 용어의 정본 챕터 매핑