README & 온보딩 문서

AI 시대에는 README 하나로 사람과 AI를 모두 만족시키기 어렵습니다. llms.txt는 AI의 진입점, README는 사람의 진입점으로 역할을 분리하면 양쪽 모두 효과적입니다.

왜 역할 분리가 필요한가

	사람이 원하는 것	AI가 원하는 것
첫 인상	프로젝트가 뭔지 한눈에	문서 구조와 위치 목록
시작 방법	설치/실행 스텝바이스텝	명령어 코드 블록
상세 정보	스크린샷, 데모 GIF	파일 경로, API 스키마
탐색 방법	목차 링크 클릭	전체 문서 인덱스

llms.txt: AI의 진입점

llms.txt는 사이트/프로젝트 전체를 AI가 이해하는 색인입니다. robots.txt가 크롤러를 위한 것처럼, llms.txt는 LLM을 위한 것입니다.

llms.txt 구조

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

## Docs
- [Getting Started](/docs/setup): 설치와 초기 설정
- [API Reference](/docs/api): REST API 엔드포인트 목록
- [Architecture](/docs/arch): 시스템 아키텍처와 ADR

## Optional
- [Contributing](/CONTRIBUTING.md): 기여 가이드
- [Changelog](/CHANGELOG.md): 변경 이력

llms.txt 표준

llms.txt는 아직 공식 표준은 아니지만, 빠르게 채택되고 있습니다. AI 에이전트와 RAG 시스템이 프로젝트를 이해하는 첫 번째 파일로 활용합니다.

README: 사람의 진입점

AI 시대의 README는 간결해져야 합니다. 기존에 README에 담던 상세 설명은 별도 문서로 분리하고, README는 핵심만 남깁니다.

간결한 README 구조

# Project Name

[뱃지: CI, 버전, 라이선스]

한 줄 설명.

## Quick Start

\`\`\`bash
npm install
npm run dev
\`\`\`

## Documentation

- [Setup Guide](docs/setup.md)
- [API Reference](docs/api.md)
- [Contributing](CONTRIBUTING.md)

## License

MIT

Before/After

Before — 모든 것이 담긴 거대한 README (200줄+):

# My Project

이 프로젝트는 TypeScript와 Next.js로 만든 ...
(20줄의 설명)

## Prerequisites
Node.js가 필요합니다. Node.js는 JavaScript 런타임으로...
(10줄의 기본지식 설명)

## Installation
(20줄의 설치 과정)

## Configuration
(30줄의 환경변수 설명)

## API Documentation
(50줄의 API 설명)

## Architecture
(30줄의 아키텍처 설명)

## Contributing
(20줄의 기여 가이드)

After — 3파일 분리:

파일	대상	내용	크기
`llms.txt`	AI	문서 색인, 경로, 한 줄 설명	~20줄
`README.md`	사람	한 줄 설명, Quick Start, 문서 링크	~30줄
`CLAUDE.md`	AI 에이전트	명령어, 아키텍처, 규칙, 금지사항	~50줄

템플릿: llms.txt

# [프로젝트명]
> [한 줄 설명]

## Docs
- [Setup](/docs/setup): [설명]
- [API](/docs/api): [설명]
- [Architecture](/docs/arch): [설명]

## Optional
- [Changelog](/CHANGELOG.md): [설명]
- [Contributing](/CONTRIBUTING.md): [설명]

실전 예시: 모노레포 프로젝트의 llms.txt

# reopt-kb
> Yarn 4 Workspaces + Turborepo 기반 문서 사이트 모노레포

## Docs
- [KB App](/apps/kb): 메인 지식기반 문서 사이트 (Fumadocs + Next.js)
- [Handbook App](/apps/handbook): 핸드북 사이트 (book-style content)
- [MCP Server](/apps/kb-mcp): MCP 검색 서버 (TypeScript)

## Architecture
- [CLAUDE.md](/CLAUDE.md): 프로젝트 규칙과 아키텍처 개요
- [AGENTS.md](/AGENTS.md): AI 에이전트용 프로젝트 네비게이션

## Development
- [Setup](/docs/setup): 개발 환경 설정 (yarn install → yarn dev)
- [Content Guide](/docs/content): MDX 문서 작성 가이드

## Optional
- [Changelog](/CHANGELOG.md): 변경 이력
- [Contributing](/CONTRIBUTING.md): 기여 가이드

실제 프로젝트에 적용하기

위 예시에서 각 링크는 실제 존재하는 파일을 가리킵니다. llms.txt를 작성한 후 모든 링크가 유효한지 반드시 확인하세요.

llms.txt 자동 검증

# llms.txt의 모든 링크 유효성 검사 (간단 스크립트)
grep -oP '\(/[^)]+\)' llms.txt | tr -d '()' | while read path; do
  if [ ! -e ".${path}" ]; then
    echo "❌ 존재하지 않는 경로: ${path}"
  fi
done

AI가 실패하는 패턴

실수	AI가 실패하는 이유	수정 방법
README에 모든 정보를 담음	AI가 200줄+ 문서에서 핵심을 놓침	llms.txt + README + CLAUDE.md 분리
llms.txt 없이 README만 제공	AI가 프로젝트 문서 구조를 파악 못함	llms.txt로 문서 색인 제공
설치 과정을 산문으로 설명	AI가 실행할 명령어를 추출 못함	Quick Start를 코드 블록으로

AI 프롬프트 예시

이 프로젝트의 구조를 분석해서 llms.txt를 생성해줘.

규칙:
- 프로젝트명과 한 줄 설명으로 시작
- 문서 파일들의 경로와 한 줄 설명을 나열
- 필수 문서(Docs)와 선택 문서(Optional)를 분리
- 경로는 실제 파일이 있는 경로만 포함

체크리스트

항목	확인
llms.txt가 프로젝트 루트에 있는가	☐
llms.txt의 모든 링크가 실제 파일을 가리키는가	☐
README가 30줄 이내로 간결한가	☐
README에 Quick Start가 코드 블록으로 있는가	☐
상세 문서가 별도 파일로 분리되었는가	☐
CLAUDE.md/AGENTS.md가 별도로 존재하는가	☐

왜 역할 분리가 필요한가

	사람이 원하는 것	AI가 원하는 것
첫 인상	프로젝트가 뭔지 한눈에	문서 구조와 위치 목록
시작 방법	설치/실행 스텝바이스텝	명령어 코드 블록
상세 정보	스크린샷, 데모 GIF	파일 경로, API 스키마
탐색 방법	목차 링크 클릭	전체 문서 인덱스

llms.txt: AI의 진입점

llms.txt는 사이트/프로젝트 전체를 AI가 이해하는 색인입니다. robots.txt가 크롤러를 위한 것처럼, llms.txt는 LLM을 위한 것입니다.

llms.txt 구조

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

## Docs
- [Getting Started](/docs/setup): 설치와 초기 설정
- [API Reference](/docs/api): REST API 엔드포인트 목록
- [Architecture](/docs/arch): 시스템 아키텍처와 ADR

## Optional
- [Contributing](/CONTRIBUTING.md): 기여 가이드
- [Changelog](/CHANGELOG.md): 변경 이력

llms.txt 표준

llms.txt는 아직 공식 표준은 아니지만, 빠르게 채택되고 있습니다. AI 에이전트와 RAG 시스템이 프로젝트를 이해하는 첫 번째 파일로 활용합니다.

README: 사람의 진입점

AI 시대의 README는 간결해져야 합니다. 기존에 README에 담던 상세 설명은 별도 문서로 분리하고, README는 핵심만 남깁니다.

간결한 README 구조

# Project Name

[뱃지: CI, 버전, 라이선스]

한 줄 설명.

## Quick Start

\`\`\`bash
npm install
npm run dev
\`\`\`

## Documentation

- [Setup Guide](docs/setup.md)
- [API Reference](docs/api.md)
- [Contributing](CONTRIBUTING.md)

## License

MIT

Before/After

Before — 모든 것이 담긴 거대한 README (200줄+):

# My Project

이 프로젝트는 TypeScript와 Next.js로 만든 ...
(20줄의 설명)

## Prerequisites
Node.js가 필요합니다. Node.js는 JavaScript 런타임으로...
(10줄의 기본지식 설명)

## Installation
(20줄의 설치 과정)

## Configuration
(30줄의 환경변수 설명)

## API Documentation
(50줄의 API 설명)

## Architecture
(30줄의 아키텍처 설명)

## Contributing
(20줄의 기여 가이드)

After — 3파일 분리:

파일	대상	내용	크기
`llms.txt`	AI	문서 색인, 경로, 한 줄 설명	~20줄
`README.md`	사람	한 줄 설명, Quick Start, 문서 링크	~30줄
`CLAUDE.md`	AI 에이전트	명령어, 아키텍처, 규칙, 금지사항	~50줄

템플릿: llms.txt

# [프로젝트명]
> [한 줄 설명]

## Docs
- [Setup](/docs/setup): [설명]
- [API](/docs/api): [설명]
- [Architecture](/docs/arch): [설명]

## Optional
- [Changelog](/CHANGELOG.md): [설명]
- [Contributing](/CONTRIBUTING.md): [설명]

실전 예시: 모노레포 프로젝트의 llms.txt

# reopt-kb
> Yarn 4 Workspaces + Turborepo 기반 문서 사이트 모노레포

## Docs
- [KB App](/apps/kb): 메인 지식기반 문서 사이트 (Fumadocs + Next.js)
- [Handbook App](/apps/handbook): 핸드북 사이트 (book-style content)
- [MCP Server](/apps/kb-mcp): MCP 검색 서버 (TypeScript)

## Architecture
- [CLAUDE.md](/CLAUDE.md): 프로젝트 규칙과 아키텍처 개요
- [AGENTS.md](/AGENTS.md): AI 에이전트용 프로젝트 네비게이션

## Development
- [Setup](/docs/setup): 개발 환경 설정 (yarn install → yarn dev)
- [Content Guide](/docs/content): MDX 문서 작성 가이드

## Optional
- [Changelog](/CHANGELOG.md): 변경 이력
- [Contributing](/CONTRIBUTING.md): 기여 가이드

실제 프로젝트에 적용하기

위 예시에서 각 링크는 실제 존재하는 파일을 가리킵니다. llms.txt를 작성한 후 모든 링크가 유효한지 반드시 확인하세요.

llms.txt 자동 검증

# llms.txt의 모든 링크 유효성 검사 (간단 스크립트)
grep -oP '\(/[^)]+\)' llms.txt | tr -d '()' | while read path; do
  if [ ! -e ".${path}" ]; then
    echo "❌ 존재하지 않는 경로: ${path}"
  fi
done

AI가 실패하는 패턴

실수	AI가 실패하는 이유	수정 방법
README에 모든 정보를 담음	AI가 200줄+ 문서에서 핵심을 놓침	llms.txt + README + CLAUDE.md 분리
llms.txt 없이 README만 제공	AI가 프로젝트 문서 구조를 파악 못함	llms.txt로 문서 색인 제공
설치 과정을 산문으로 설명	AI가 실행할 명령어를 추출 못함	Quick Start를 코드 블록으로

AI 프롬프트 예시

이 프로젝트의 구조를 분석해서 llms.txt를 생성해줘.

규칙:
- 프로젝트명과 한 줄 설명으로 시작
- 문서 파일들의 경로와 한 줄 설명을 나열
- 필수 문서(Docs)와 선택 문서(Optional)를 분리
- 경로는 실제 파일이 있는 경로만 포함

체크리스트

항목	확인
llms.txt가 프로젝트 루트에 있는가	☐
llms.txt의 모든 링크가 실제 파일을 가리키는가	☐
README가 30줄 이내로 간결한가	☐
README에 Quick Start가 코드 블록으로 있는가	☐
상세 문서가 별도 파일로 분리되었는가	☐
CLAUDE.md/AGENTS.md가 별도로 존재하는가	☐

README & 온보딩 문서

목차

README & 온보딩 문서

목차