왜 문서화가 변해야 하는가

문서화의 오래된 공식

지난 수십 년간 기술 문서화의 공식은 단순했다.

사람이 작성하고 → 문서에 담기고 → 사람이 읽는다.

이 공식은 놀라울 정도로 오랫동안 유효했다. Wiki, Confluence, Notion, GitBook — 도구는 바뀌었지만 패러다임은 동일했다. 문서의 독자는 항상 사람이었고, 문서의 가치는 사람이 얼마나 빠르게 이해하느냐로 측정되었다.

그런데 2024~2025년, 무언가 근본적으로 달라졌다.

새로운 등식: AI ↔ 문서 ↔ 사람

2025년 현재, 문서의 소비자는 더 이상 사람만이 아니다. Claude Code, GitHub Copilot, Cursor, Codex 같은 AI 에이전트가 코드베이스와 문서를 직접 읽고 해석한다. 이들이 문서를 소비하는 방식은 사람과 근본적으로 다르다.

핵심 전환

문서의 독자가 사람 1명에서 사람 + AI 에이전트 N개로 바뀌었다. 문서 하나의 ROI가 구조적으로 변했다.

달라진 것들

항목	과거	현재
문서 독자	팀원, 신규 입사자	팀원 + AI 에이전트 + 외부 LLM
읽기 방식	순차적 스캔, 검색	토큰 단위 파싱, 전체 컨텍스트 로딩
문서 포맷	자유 산문, 스크린샷	구조화된 텍스트, 코드 블록, 메타데이터
업데이트 주기	분기/반기 (혹은 방치)	AI가 변경 감지 후 제안
품질 검증	리뷰어 1~2명	AI 교차 검증 + 사람 최종 확인

"기본 지식은 AI에게" — 문서에 모든 걸 담을 필요 없다

전통적인 문서화 접근법은 자기 완결성을 추구했다. "이 문서만 읽으면 모든 걸 알 수 있어야 한다"는 원칙. 이것이 문서를 비대하게 만든 핵심 원인이다.

예시: API 인증 문서

기존 방식 — 모든 배경 지식을 문서에 포함:

## API 인증

### JWT란?
JSON Web Token(JWT)은 RFC 7519에 정의된 개방형 표준으로,
당사자 간에 정보를 JSON 객체로 안전하게 전송하기 위한
컴팩트하고 독립적인 방법을 정의합니다.

JWT는 세 부분으로 구성됩니다:
1. Header: 토큰 유형과 서명 알고리즘
2. Payload: 클레임(claims) 데이터
3. Signature: 검증용 서명

### OAuth 2.0이란?
OAuth 2.0은 인가(authorization) 프레임워크로...
(50줄의 배경 설명 계속)

### 우리 API의 인증
Bearer 토큰을 Authorization 헤더에 포함하세요.

새로운 방식 — 기본 지식은 AI에게 맡기고 핵심만:

## API 인증

Bearer 토큰을 `Authorization` 헤더에 포함한다.

- 토큰 발급: `POST /auth/token` (client_credentials grant)
- 만료: 1시간, 갱신 불가 — 재발급 필요
- Rate limit: 토큰당 100 req/min

> JWT, OAuth 2.0 기본 개념은 AI 어시스턴트에게 질문하세요.

주의

"기본 지식은 AI에게"가 프로젝트 고유 맥락까지 생략하라는 의미는 아니다. AI가 알 수 없는 것 — 내부 규칙, 아키텍처 결정 이유, 비즈니스 로직 — 은 반드시 문서화해야 한다.

무엇을 남기고 무엇을 생략할 것인가

문서에 남겨야 할 것	AI에게 맡길 수 있는 것
프로젝트 고유 아키텍처 결정	범용 기술 개념 설명
내부 코딩 컨벤션	언어/프레임워크 기본 문법
비즈니스 로직과 이유(Why)	라이브러리 API 레퍼런스
배포/운영 환경 고유 설정	일반적인 트러블슈팅
팀 간 합의사항, 인터페이스 계약	디자인 패턴 설명

AI가 문서를 소비하는 방식

AI 에이전트가 문서를 어떻게 읽는지 이해하면, 문서를 어떻게 써야 하는지가 명확해진다.

토큰 경제학

LLM은 텍스트를 토큰 단위로 처리한다. 한국어의 경우 대략 한 글자가 1~2토큰에 해당한다.

컨텍스트 윈도우 크기 (2025년 기준):
- Claude Sonnet 4:   200K 토큰 (~책 3~4권)
- Claude Opus 4:     200K~1M 토큰 (확장 사고 모드)
- GPT-4.1:           1M 토큰
- Gemini 2.5 Pro:    1M 토큰

토큰 = 비용 + 시간

토큰이 많을수록 API 비용이 올라가고, 응답 지연이 증가한다. 같은 정보를 더 적은 토큰으로 전달하는 문서가 경제적으로 우월하다.

파싱 특성

AI 에이전트는 다음과 같이 문서를 처리한다:

전체 로딩: 파일 단위로 컨텍스트에 로딩 (사람처럼 훑어보기 불가)
구조 인식: Markdown 제목(#, ##), 코드 블록(```), 표, 리스트를 구조적으로 파싱
메타데이터 활용: frontmatter, 파일명, 디렉토리 구조에서 의미 추출
중복 비효율: 같은 내용이 반복되면 토큰만 낭비하고 정보량은 동일

AI 에이전트의 문서 접근 경로

CLAUDE.md / AGENTS.md          ← 프로젝트 진입점
    ↓
디렉토리 구조 탐색              ← 파일명/폴더명으로 관련성 판단
    ↓
파일 내용 읽기                  ← 구조화된 섹션에서 필요한 부분 추출
    ↓
코드와 문서 교차 참조           ← 실제 구현과 문서 일치 여부 확인

문서화 ROI의 구조적 변화

AI 에이전트 시대에 문서화의 투자 대비 효과가 어떻게 달라졌는지 비교한다.

Before: 전통적 문서화 ROI

항목	수치
작성 시간	4~8시간/문서
독자 수	팀원 5~20명
읽히는 빈도	온보딩 시 1~2회
유지보수	수동 (대부분 방치)
실질 ROI	낮음 — 작성 후 빠르게 노후화

After: AI-aware 문서화 ROI

항목	수치
작성 시간	1~3시간/문서 (AI 협업)
독자 수	팀원 + AI 에이전트 (사실상 무제한)
읽히는 빈도	AI가 매 작업마다 참조 (일 수십~수백 회)
유지보수	AI가 불일치 감지 → 업데이트 제안
실질 ROI	높음 — AI 생산성에 직결

복리 효과

잘 구조화된 CLAUDE.md 하나가 팀의 모든 AI 에이전트 세션에서 반복적으로 참조된다. 문서 1회 작성 → AI N회 활용. 이것이 문서화의 복리 효과다.

새로운 문서 형식의 등장

2024~2025년, AI 에이전트를 위한 새로운 문서 형식들이 등장했다.

CLAUDE.md

Claude Code가 프로젝트 진입 시 자동으로 읽는 파일. 프로젝트의 "정신 모델"을 AI에게 전달한다.

# CLAUDE.md

## 프로젝트 개요
Yarn 4 모노레포, Next.js 16 기반 문서 사이트

## 명령어
yarn dev      # 개발 서버
yarn build    # 프로덕션 빌드
yarn lint     # 린트 검사

## 아키텍처 결정
- Fumadocs 기반 문서 시스템
- 한국어 콘텐츠 전용
- Orama 검색 엔진 + 한국어 bigram 토크나이저

## 금지 사항
- 커밋/푸시는 명시적 요청 시에만
- .next/, dist/ 등 생성 파일 편집 금지

AGENTS.md

AI 에이전트의 행동 지침. CLAUDE.md보다 더 구체적인 규칙을 정의한다.

llms.txt

웹사이트의 robots.txt에 해당하는 LLM 버전. 사이트 구조와 주요 콘텐츠를 AI에게 안내한다.

# llms.txt

> 이 사이트는 reopt KB 문서 모음입니다.

## 주요 섹션
- /company: 회사 정보
- /engineering: 엔지니어링 가이드
- /operations: 운영 매뉴얼

## 상세 문서
- [아키텍처 개요](/engineering/architecture)
- [배포 프로세스](/operations/deploy)

새로운 원칙 요약

AI 에이전트 시대의 문서화 3대 원칙:

1. 핵심 밀도 (Information Density)

정보 가치 = 고유 인사이트 / 소비 토큰 수

같은 정보를 전달하면서 토큰을 줄이는 것이 핵심이다. 장황한 설명 대신 정확한 한 줄이 더 가치 있다.

2. 구조화 (Structured Format)

AI는 자유 산문보다 구조화된 포맷을 훨씬 정확하게 파싱한다.

Markdown 제목 계층 (# → ## → ###)
코드 블록 (언어 태그 포함)
표 (비교, 목록)
frontmatter (메타데이터)
리스트 (순서/비순서)

3. 기계 가독성 (Machine Readability)

사람에게 아름다운 문서와 AI에게 유용한 문서는 다를 수 있다.

사람에게 좋은 것	AI에게 좋은 것
스크린샷, GIF	텍스트 설명, 코드 블록
은유와 비유	직접적이고 선언적인 서술
감성적 도입부	즉시 핵심 정보
컬러풀한 다이어그램	Mermaid 텍스트 다이어그램
PDF, Figma 링크	Markdown, 구조화된 텍스트

균형이 중요하다

AI 가독성만 추구하면 사람이 읽기 어려운 문서가 된다. 사람과 AI 모두에게 잘 작동하는 문서를 목표로 해야 한다. 다행히 잘 구조화된 Markdown은 양쪽 모두에게 효과적이다.

이 핸드북의 방향

이 핸드북은 세 가지 질문에 답한다:

설계: AI가 잘 읽는 문서는 어떤 구조인가? → Ch2
프로세스: AI와 함께 문서를 쓰는 워크플로우는? → Ch3
실전: CLAUDE.md, AGENTS.md는 어떻게 설계하는가? → Ch4~6

다음 챕터에서는 AI-readable 문서 설계의 구체적인 원칙과 패턴을 다룬다.

문서화의 오래된 공식

지난 수십 년간 기술 문서화의 공식은 단순했다.

사람이 작성하고 → 문서에 담기고 → 사람이 읽는다.

그런데 2024~2025년, 무언가 근본적으로 달라졌다.

새로운 등식: AI ↔ 문서 ↔ 사람

핵심 전환

문서의 독자가 사람 1명에서 사람 + AI 에이전트 N개로 바뀌었다. 문서 하나의 ROI가 구조적으로 변했다.

달라진 것들

항목	과거	현재
문서 독자	팀원, 신규 입사자	팀원 + AI 에이전트 + 외부 LLM
읽기 방식	순차적 스캔, 검색	토큰 단위 파싱, 전체 컨텍스트 로딩
문서 포맷	자유 산문, 스크린샷	구조화된 텍스트, 코드 블록, 메타데이터
업데이트 주기	분기/반기 (혹은 방치)	AI가 변경 감지 후 제안
품질 검증	리뷰어 1~2명	AI 교차 검증 + 사람 최종 확인

"기본 지식은 AI에게" — 문서에 모든 걸 담을 필요 없다

예시: API 인증 문서

기존 방식 — 모든 배경 지식을 문서에 포함:

## API 인증

### JWT란?
JSON Web Token(JWT)은 RFC 7519에 정의된 개방형 표준으로,
당사자 간에 정보를 JSON 객체로 안전하게 전송하기 위한
컴팩트하고 독립적인 방법을 정의합니다.

JWT는 세 부분으로 구성됩니다:
1. Header: 토큰 유형과 서명 알고리즘
2. Payload: 클레임(claims) 데이터
3. Signature: 검증용 서명

### OAuth 2.0이란?
OAuth 2.0은 인가(authorization) 프레임워크로...
(50줄의 배경 설명 계속)

### 우리 API의 인증
Bearer 토큰을 Authorization 헤더에 포함하세요.

새로운 방식 — 기본 지식은 AI에게 맡기고 핵심만:

## API 인증

Bearer 토큰을 `Authorization` 헤더에 포함한다.

- 토큰 발급: `POST /auth/token` (client_credentials grant)
- 만료: 1시간, 갱신 불가 — 재발급 필요
- Rate limit: 토큰당 100 req/min

> JWT, OAuth 2.0 기본 개념은 AI 어시스턴트에게 질문하세요.

주의

무엇을 남기고 무엇을 생략할 것인가

문서에 남겨야 할 것	AI에게 맡길 수 있는 것
프로젝트 고유 아키텍처 결정	범용 기술 개념 설명
내부 코딩 컨벤션	언어/프레임워크 기본 문법
비즈니스 로직과 이유(Why)	라이브러리 API 레퍼런스
배포/운영 환경 고유 설정	일반적인 트러블슈팅
팀 간 합의사항, 인터페이스 계약	디자인 패턴 설명

AI가 문서를 소비하는 방식

AI 에이전트가 문서를 어떻게 읽는지 이해하면, 문서를 어떻게 써야 하는지가 명확해진다.

토큰 경제학

LLM은 텍스트를 토큰 단위로 처리한다. 한국어의 경우 대략 한 글자가 1~2토큰에 해당한다.

컨텍스트 윈도우 크기 (2025년 기준):
- Claude Sonnet 4:   200K 토큰 (~책 3~4권)
- Claude Opus 4:     200K~1M 토큰 (확장 사고 모드)
- GPT-4.1:           1M 토큰
- Gemini 2.5 Pro:    1M 토큰

토큰 = 비용 + 시간

토큰이 많을수록 API 비용이 올라가고, 응답 지연이 증가한다. 같은 정보를 더 적은 토큰으로 전달하는 문서가 경제적으로 우월하다.

파싱 특성

AI 에이전트는 다음과 같이 문서를 처리한다:

전체 로딩: 파일 단위로 컨텍스트에 로딩 (사람처럼 훑어보기 불가)
구조 인식: Markdown 제목(#, ##), 코드 블록(```), 표, 리스트를 구조적으로 파싱
메타데이터 활용: frontmatter, 파일명, 디렉토리 구조에서 의미 추출
중복 비효율: 같은 내용이 반복되면 토큰만 낭비하고 정보량은 동일

AI 에이전트의 문서 접근 경로

CLAUDE.md / AGENTS.md          ← 프로젝트 진입점
    ↓
디렉토리 구조 탐색              ← 파일명/폴더명으로 관련성 판단
    ↓
파일 내용 읽기                  ← 구조화된 섹션에서 필요한 부분 추출
    ↓
코드와 문서 교차 참조           ← 실제 구현과 문서 일치 여부 확인

문서화 ROI의 구조적 변화

AI 에이전트 시대에 문서화의 투자 대비 효과가 어떻게 달라졌는지 비교한다.

Before: 전통적 문서화 ROI

항목	수치
작성 시간	4~8시간/문서
독자 수	팀원 5~20명
읽히는 빈도	온보딩 시 1~2회
유지보수	수동 (대부분 방치)
실질 ROI	낮음 — 작성 후 빠르게 노후화

After: AI-aware 문서화 ROI

항목	수치
작성 시간	1~3시간/문서 (AI 협업)
독자 수	팀원 + AI 에이전트 (사실상 무제한)
읽히는 빈도	AI가 매 작업마다 참조 (일 수십~수백 회)
유지보수	AI가 불일치 감지 → 업데이트 제안
실질 ROI	높음 — AI 생산성에 직결

복리 효과

잘 구조화된 CLAUDE.md 하나가 팀의 모든 AI 에이전트 세션에서 반복적으로 참조된다. 문서 1회 작성 → AI N회 활용. 이것이 문서화의 복리 효과다.

새로운 문서 형식의 등장

2024~2025년, AI 에이전트를 위한 새로운 문서 형식들이 등장했다.

CLAUDE.md

Claude Code가 프로젝트 진입 시 자동으로 읽는 파일. 프로젝트의 "정신 모델"을 AI에게 전달한다.

# CLAUDE.md

## 프로젝트 개요
Yarn 4 모노레포, Next.js 16 기반 문서 사이트

## 명령어
yarn dev      # 개발 서버
yarn build    # 프로덕션 빌드
yarn lint     # 린트 검사

## 아키텍처 결정
- Fumadocs 기반 문서 시스템
- 한국어 콘텐츠 전용
- Orama 검색 엔진 + 한국어 bigram 토크나이저

## 금지 사항
- 커밋/푸시는 명시적 요청 시에만
- .next/, dist/ 등 생성 파일 편집 금지

AGENTS.md

AI 에이전트의 행동 지침. CLAUDE.md보다 더 구체적인 규칙을 정의한다.

llms.txt

웹사이트의 robots.txt에 해당하는 LLM 버전. 사이트 구조와 주요 콘텐츠를 AI에게 안내한다.

# llms.txt

> 이 사이트는 reopt KB 문서 모음입니다.

## 주요 섹션
- /company: 회사 정보
- /engineering: 엔지니어링 가이드
- /operations: 운영 매뉴얼

## 상세 문서
- [아키텍처 개요](/engineering/architecture)
- [배포 프로세스](/operations/deploy)

새로운 원칙 요약

AI 에이전트 시대의 문서화 3대 원칙:

1. 핵심 밀도 (Information Density)

정보 가치 = 고유 인사이트 / 소비 토큰 수

같은 정보를 전달하면서 토큰을 줄이는 것이 핵심이다. 장황한 설명 대신 정확한 한 줄이 더 가치 있다.

2. 구조화 (Structured Format)

AI는 자유 산문보다 구조화된 포맷을 훨씬 정확하게 파싱한다.

Markdown 제목 계층 (# → ## → ###)
코드 블록 (언어 태그 포함)
표 (비교, 목록)
frontmatter (메타데이터)
리스트 (순서/비순서)

3. 기계 가독성 (Machine Readability)

사람에게 아름다운 문서와 AI에게 유용한 문서는 다를 수 있다.

사람에게 좋은 것	AI에게 좋은 것
스크린샷, GIF	텍스트 설명, 코드 블록
은유와 비유	직접적이고 선언적인 서술
감성적 도입부	즉시 핵심 정보
컬러풀한 다이어그램	Mermaid 텍스트 다이어그램
PDF, Figma 링크	Markdown, 구조화된 텍스트

균형이 중요하다

이 핸드북의 방향

이 핸드북은 세 가지 질문에 답한다:

설계: AI가 잘 읽는 문서는 어떤 구조인가? → Ch2
프로세스: AI와 함께 문서를 쓰는 워크플로우는? → Ch3
실전: CLAUDE.md, AGENTS.md는 어떻게 설계하는가? → Ch4~6

다음 챕터에서는 AI-readable 문서 설계의 구체적인 원칙과 패턴을 다룬다.

왜 문서화가 변해야 하는가

목차

왜 문서화가 변해야 하는가

목차