AI-readable 문서 설계 원칙

구조화된 포맷, 핵심 우선 밀도, 선언적 서술, 실행 가능성의 실전 가이드

핵심 요약

AI-readable을 넘어 agent-operable 문서를 만드는 5가지 원칙을 다룹니다.
메타데이터를 본문이 아닌 frontmatter로 분리하면 AI가 본문을 읽기 전에 관련성을 판단합니다.
"정보 가치 = 인사이트 ÷ 토큰"이므로, 범용 개념은 생략하고 프로젝트 고유 정보만 남깁니다.
절차적(how) 서술보다 선언적(what) 규칙을 AI가 더 정확히 따르고, 표와 목록이 산문보다 스캔하기 좋습니다.
실행 가능성을 위해 실행 명령, 위치 안내, 완료 조건, 실패 시 조치를 함께 제공합니다.

AI가 문서를 잘 활용하려면 사람이 읽기 편한 문서와는 다른 설계 원칙이 필요합니다. 이 장에서는 AI-readable을 넘어 agent-operable 문서의 5가지 핵심 원칙과 실전 적용법을 다룹니다.

원칙 1: 구조화된 포맷

AI는 자유 형식 산문보다 구조화된 데이터를 훨씬 정확하게 처리합니다.

Frontmatter로 메타데이터 분리

---
title: 사용자 인증 API
description: JWT 기반 인증/인가 시스템
version: v2.3
status: stable
owner: auth-team
last-reviewed: 2026-05-24
---

왜 frontmatter인가

AI 에이전트는 문서를 읽기 전에 메타데이터만으로 관련성을 판단합니다. frontmatter가 없으면 전체 본문을 읽어야 하니 토큰이 낭비됩니다.

Before/After

Before — 메타데이터가 본문에 섞임:

# 사용자 인증 API

이 문서는 auth-team이 관리하는 JWT 기반 인증 시스템에 대한
v2.3 문서입니다. 2026년 5월 24일에 마지막으로 검토되었습니다.
현재 안정 버전입니다.

After — 메타데이터가 frontmatter로 분리:

---
title: 사용자 인증 API
version: v2.3
status: stable
owner: auth-team
last-reviewed: 2026-05-24
---

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가 최신성을 판단 못함	날짜/버전 명시

원칙 5: 실행 가능성

에이전트가 문서를 읽은 뒤 무엇을 해야 하는지 알 수 있어야 합니다. 좋은 문서는 "설명"에서 멈추지 않고 실행 명령, 입력/출력 계약, 검증 기준을 함께 줍니다.

## 변경 절차

1. `src/api/orders.ts`를 수정한다.
2. `openapi/orders.yaml`을 함께 갱신한다.
3. 다음 검증을 실행한다.

\`\`\`bash
pnpm test orders
pnpm openapi:check
\`\`\`

완료 조건:
- 모든 테스트 통과
- OpenAPI diff에 breaking change 없음
- 변경 내용이 `docs/api/orders.md`에 반영됨

실행 가능성을 높이는 요소

요소	예시
실행 명령	`pnpm typecheck`, `pnpm test api`
위치 안내	`src/api/`, `docs/api/`, `openapi/**`
완료 조건	"테스트 통과", "schema diff 없음"
실패 시 조치	"마이그레이션 실패 시 rollback runbook 참고"
참조 표면	Skill, MCP Resource, runbook 링크

핵심 포맷별 설계 철학

llms.txt

사이트 전체를 AI가 이해하기 쉽게 안내하는 Markdown 색인 제안입니다. 사이트맵처럼 URL만 나열하지 않고, 각 페이지의 목적과 관계까지 설명합니다. 다만 크롤링이나 검색 노출을 보장하는 공식 표준처럼 다루면 안 됩니다.

# Project Name
> 프로젝트 한 줄 설명

## Docs
- [API Reference](/api): REST API 엔드포인트 목록
- [Architecture](/arch): 시스템 아키텍처와 설계 결정
- [Setup Guide](/setup): 개발 환경 설정 가이드

CLAUDE.md / AGENTS.md

프로젝트의 규칙과 컨텍스트를 즉시 전달하는 문서입니다. AI 에이전트가 프로젝트에 진입할 때 가장 먼저 읽습니다.

핵심 설계 원칙:

프로젝트 개요를 첫 5줄 안에
명령어(빌드, 테스트, 린트)를 코드 블록으로
금지사항을 명시적으로
아키텍처를 간결하게
긴 절차는 Skill 또는 runbook으로 분리

Skills / MCP Resources

긴 절차와 레퍼런스를 시작 지침에 다 넣으면 컨텍스트가 낭비됩니다. 반복 절차는 Skill로, 최신 외부 컨텍스트는 MCP Resource로 빼냅니다.

AGENTS.md          -> 항상 필요한 짧은 규칙
Skill             -> 필요할 때 실행하는 절차
MCP Resource      -> 필요할 때 가져오는 최신 문서/스키마

체크리스트

항목	확인
모든 문서에 frontmatter가 있는가	☐
기본지식 설명을 생략했는가	☐
규칙이 선언적으로 서술되었는가	☐
제목이 계층적이고 구체적인가	☐
표와 목록을 산문 대신 사용했는가	☐
하나의 문서가 하나의 주제를 다루는가	☐
날짜/버전 정보가 포함되어 있는가	☐
이미지에 텍스트 대체가 있는가	☐
실행 명령과 완료 조건이 있는가	☐
긴 절차와 레퍼런스를 Skill/MCP로 분리했는가	☐

핵심 요약

AI-readable을 넘어 agent-operable 문서를 만드는 5가지 원칙을 다룹니다.
메타데이터를 본문이 아닌 frontmatter로 분리하면 AI가 본문을 읽기 전에 관련성을 판단합니다.
"정보 가치 = 인사이트 ÷ 토큰"이므로, 범용 개념은 생략하고 프로젝트 고유 정보만 남깁니다.
절차적(how) 서술보다 선언적(what) 규칙을 AI가 더 정확히 따르고, 표와 목록이 산문보다 스캔하기 좋습니다.
실행 가능성을 위해 실행 명령, 위치 안내, 완료 조건, 실패 시 조치를 함께 제공합니다.

원칙 1: 구조화된 포맷

AI는 자유 형식 산문보다 구조화된 데이터를 훨씬 정확하게 처리합니다.

Frontmatter로 메타데이터 분리

---
title: 사용자 인증 API
description: JWT 기반 인증/인가 시스템
version: v2.3
status: stable
owner: auth-team
last-reviewed: 2026-05-24
---

왜 frontmatter인가

AI 에이전트는 문서를 읽기 전에 메타데이터만으로 관련성을 판단합니다. frontmatter가 없으면 전체 본문을 읽어야 하니 토큰이 낭비됩니다.

Before/After

Before — 메타데이터가 본문에 섞임:

# 사용자 인증 API

이 문서는 auth-team이 관리하는 JWT 기반 인증 시스템에 대한
v2.3 문서입니다. 2026년 5월 24일에 마지막으로 검토되었습니다.
현재 안정 버전입니다.

After — 메타데이터가 frontmatter로 분리:

---
title: 사용자 인증 API
version: v2.3
status: stable
owner: auth-team
last-reviewed: 2026-05-24
---

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가 최신성을 판단 못함	날짜/버전 명시

원칙 5: 실행 가능성

## 변경 절차

1. `src/api/orders.ts`를 수정한다.
2. `openapi/orders.yaml`을 함께 갱신한다.
3. 다음 검증을 실행한다.

\`\`\`bash
pnpm test orders
pnpm openapi:check
\`\`\`

완료 조건:
- 모든 테스트 통과
- OpenAPI diff에 breaking change 없음
- 변경 내용이 `docs/api/orders.md`에 반영됨

실행 가능성을 높이는 요소

요소	예시
실행 명령	`pnpm typecheck`, `pnpm test api`
위치 안내	`src/api/`, `docs/api/`, `openapi/**`
완료 조건	"테스트 통과", "schema diff 없음"
실패 시 조치	"마이그레이션 실패 시 rollback runbook 참고"
참조 표면	Skill, MCP Resource, runbook 링크

핵심 포맷별 설계 철학

llms.txt

# Project Name
> 프로젝트 한 줄 설명

## Docs
- [API Reference](/api): REST API 엔드포인트 목록
- [Architecture](/arch): 시스템 아키텍처와 설계 결정
- [Setup Guide](/setup): 개발 환경 설정 가이드

CLAUDE.md / AGENTS.md

프로젝트의 규칙과 컨텍스트를 즉시 전달하는 문서입니다. AI 에이전트가 프로젝트에 진입할 때 가장 먼저 읽습니다.

핵심 설계 원칙:

프로젝트 개요를 첫 5줄 안에
명령어(빌드, 테스트, 린트)를 코드 블록으로
금지사항을 명시적으로
아키텍처를 간결하게
긴 절차는 Skill 또는 runbook으로 분리

Skills / MCP Resources

긴 절차와 레퍼런스를 시작 지침에 다 넣으면 컨텍스트가 낭비됩니다. 반복 절차는 Skill로, 최신 외부 컨텍스트는 MCP Resource로 빼냅니다.

AGENTS.md          -> 항상 필요한 짧은 규칙
Skill             -> 필요할 때 실행하는 절차
MCP Resource      -> 필요할 때 가져오는 최신 문서/스키마

체크리스트

항목	확인
모든 문서에 frontmatter가 있는가	☐
기본지식 설명을 생략했는가	☐
규칙이 선언적으로 서술되었는가	☐
제목이 계층적이고 구체적인가	☐
표와 목록을 산문 대신 사용했는가	☐
하나의 문서가 하나의 주제를 다루는가	☐
날짜/버전 정보가 포함되어 있는가	☐
이미지에 텍스트 대체가 있는가	☐
실행 명령과 완료 조건이 있는가	☐
긴 절차와 레퍼런스를 Skill/MCP로 분리했는가	☐

On this page

AI-readable 문서 설계 원칙

On this page