AI-readable 문서 설계 원칙
구조화된 포맷, 핵심 우선 밀도, 선언적 서술의 실전 가이드
AI가 문서를 효과적으로 활용하려면 사람이 읽기 편한 문서와는 다른 설계 원칙이 필요합니다. 이 장에서는 AI-readable 문서의 4가지 핵심 원칙과 실전 적용법을 다룹니다.
원칙 1: 구조화된 포맷
AI는 자유 형식 산문보다 구조화된 데이터를 훨씬 정확하게 처리합니다.
Frontmatter로 메타데이터 분리
---
title: 사용자 인증 API
description: JWT 기반 인증/인가 시스템
version: v2.3
status: stable
owner: auth-team
last-reviewed: 2026-03-15
---왜 frontmatter인가
AI 에이전트는 문서를 읽기 전에 메타데이터만으로 관련성을 판단합니다. frontmatter가 없으면 전체 본문을 읽어야 하고, 이는 토큰 낭비입니다.
Before/After
Before — 메타데이터가 본문에 섞임:
# 사용자 인증 API
이 문서는 auth-team이 관리하는 JWT 기반 인증 시스템에 대한
v2.3 문서입니다. 2026년 3월 15일에 마지막으로 검토되었습니다.
현재 안정 버전입니다.After — 메타데이터가 frontmatter로 분리:
---
title: 사용자 인증 API
version: v2.3
status: stable
owner: auth-team
---
JWT 기반 인증/인가 시스템의 API 레퍼런스입니다.원칙 2: 핵심 우선 정보 밀도
정보 가치 = 인사이트 ÷ 토큰
AI의 컨텍스트 윈도우는 유한합니다. 기본지식을 반복 설명하면 정작 중요한 프로젝트 고유 정보가 들어갈 공간이 줄어듭니다.
생략해야 할 것과 남겨야 할 것
| 생략 가능 (AI가 이미 알고 있음) | 반드시 남겨야 함 (프로젝트 고유) |
|---|---|
| REST API가 무엇인지 설명 | 이 프로젝트의 API 엔드포인트 목록 |
| Git 기본 사용법 | 이 프로젝트의 브랜치 전략과 커밋 컨벤션 |
| Docker 개념 설명 | 이 프로젝트의 Docker 설정과 환경변수 |
| TypeScript 문법 설명 | 이 프로젝트의 타입 컨벤션과 패턴 |
Before/After
Before — 기본지식 포함 (78 토큰):
## 환경변수 설정
환경변수는 운영체제에서 프로세스에 전달하는 키-값 쌍입니다.
Node.js에서는 process.env를 통해 접근할 수 있습니다.
이 프로젝트에서는 다음 환경변수를 사용합니다:
- DATABASE_URL: PostgreSQL 연결 문자열
- JWT_SECRET: 토큰 서명 키After — 핵심만 (32 토큰):
## 환경변수
| 변수 | 용도 | 예시 |
|---|---|---|
| DATABASE_URL | PostgreSQL 연결 | postgresql://user:pass@localhost:5432/db |
| JWT_SECRET | 토큰 서명 키 | (32자 이상 랜덤 문자열) |원칙 3: 선언적 서술
AI는 **"어떻게(how)"보다 "무엇을(what)"**으로 서술된 규칙을 더 정확하게 따릅니다.
Before/After
Before — 절차적 서술:
커밋 메시지를 작성할 때는 먼저 타입을 적고,
그 다음에 콜론을 붙인 뒤 공백을 하나 넣고,
변경 내용을 간략히 설명합니다.
타입은 feat, fix, docs 등이 있습니다.After — 선언적 규칙:
## 커밋 컨벤션
- 형식: `<type>: <description>`
- 허용 type: feat, fix, docs, refactor, test, chore
- description: 소문자 시작, 마침표 없음, 50자 이내
- 본문: 선택, 빈 줄 후 작성조건부 지시 패턴
## 파일 수정 규칙
- TypeScript 파일 수정 시: `yarn typecheck` 실행
- API 엔드포인트 변경 시: OpenAPI 스펙도 함께 갱신
- DB 스키마 변경 시: 마이그레이션 파일 생성 필수
- 테스트 없는 PR은 머지하지 않는다원칙 4: 탐색 가능한 구조
AI는 문서를 순차적으로 읽지 않습니다. 제목 계층으로 필요한 섹션을 찾아 점프합니다.
좋은 구조의 특징
- 요약이 상단에: 가장 중요한 정보가 먼저 나옴
- 계층적 제목: H2 → H3 → H4 순서로 정보를 세분화
- 앵커 가능한 제목: 구체적이고 고유한 제목 ("
설정" 보다 "PostgreSQL 연결 설정") - 표와 목록 활용: 산문보다 스캔하기 쉬운 형식
Anti-pattern 표
| Anti-pattern | 문제 | 대안 |
|---|---|---|
| 산문형 장문 | AI가 핵심을 추출하는 데 토큰 낭비 | 표, 목록, 코드 블록 사용 |
| 암묵적 맥락 의존 | "위에서 말한 것처럼"은 AI가 추적 못할 수 있음 | 명시적 참조 또는 반복 |
| 거대한 단일 문서 | 컨텍스트 윈도우 초과 위험 | 주제별 분리, 링크로 연결 |
| 이미지만으로 설명 | AI가 이미지 내 텍스트를 놓칠 수 있음 | 텍스트 대체(alt) 또는 병행 설명 |
| 중복 설명 | 토큰 낭비 + 버전 불일치 위험 | single source of truth + 링크 |
| 날짜 없는 정보 | AI가 최신성을 판단 못함 | 날짜/버전 명시 |
핵심 포맷별 설계 철학
llms.txt
사이트 전체를 AI가 이해하는 진입점입니다. 사이트맵처럼 동작하되, 각 페이지의 목적과 관계를 설명합니다.
# Project Name
> 프로젝트 한 줄 설명
## Docs
- [API Reference](/api): REST API 엔드포인트 목록
- [Architecture](/arch): 시스템 아키텍처와 설계 결정
- [Setup Guide](/setup): 개발 환경 설정 가이드CLAUDE.md / AGENTS.md
프로젝트의 규칙과 컨텍스트를 즉시 전달하는 문서입니다. AI 에이전트가 프로젝트에 진입할 때 가장 먼저 읽습니다.
핵심 설계 원칙:
- 프로젝트 개요를 첫 5줄 안에
- 명령어(빌드, 테스트, 린트)를 코드 블록으로
- 금지사항을 명시적으로
- 아키텍처를 간결하게
체크리스트
| 항목 | 확인 |
|---|---|
| 모든 문서에 frontmatter가 있는가 | ☐ |
| 기본지식 설명을 생략했는가 | ☐ |
| 규칙이 선언적으로 서술되었는가 | ☐ |
| 제목이 계층적이고 구체적인가 | ☐ |
| 표와 목록을 산문 대신 사용했는가 | ☐ |
| 하나의 문서가 하나의 주제를 다루는가 | ☐ |
| 날짜/버전 정보가 포함되어 있는가 | ☐ |
| 이미지에 텍스트 대체가 있는가 | ☐ |