README & 온보딩 문서
README는 사람의 진입점, AGENTS.md는 에이전트 규칙, llms.txt는 LLM용 Markdown 색인으로 역할을 분리하고 링크 정확성을 CI로 검증하는 온보딩 문서 설계.
핵심 요약
- README 하나로 사람과 에이전트를 모두 만족시키려 들면 비대해지니 표면별로 역할을 나눕니다.
- README는 소개·Quick Start·주요 링크만 담아 30~60줄 안팎으로 유지하고 세부 규칙은
AGENTS.md로 넘깁니다. llms.txt는 웹 문서의 Markdown 색인을 두자는 제안이지, 검색 순위나 자동 크롤링을 보장하는 표준이 아닙니다.llms.txt는 sitemap과 달리 LLM 친화적 요약과 중요 문서 링크를 제공하며 실제 존재하는 파일/URL만 포함합니다.- 중요한 HTML 문서는
.mdmirror를 제공하고 링크 정확성은 CI나 주간 작업으로 검증합니다.
AI 시대에도 README는 사라지지 않습니다. 다만 README 하나로 사람과 에이전트를 모두 만족시키려 들면 문서가 금세 비대해집니다. README는 사람의 첫 진입점으로 두고, 에이전트용 색인과 프로젝트 규칙은 별도 표면으로 나눕니다.
역할 분리가 필요한 이유
| 표면 | 주요 독자 | 핵심 역할 |
|---|---|---|
README.md | 사람 | 프로젝트 소개, 빠른 시작, 주요 링크 |
AGENTS.md | 코딩 에이전트 | 빌드/테스트 명령, 작업 규칙, 금지사항 |
CLAUDE.md | Claude Code | Claude Code 전용 메모리와 import |
llms.txt | LLM/도구/사내 RAG | 웹 문서의 Markdown 색인 |
docs/**/*.md | 사람 + 에이전트 | 상세 가이드, ADR, runbook, API 설명 |
README: 사람의 진입점
README는 짧아야 합니다. 신규 팀원이나 외부 기여자가 "이 프로젝트가 무엇이고 어떻게 실행하는지"만 빠르게 파악하면 충분합니다.
세부 규칙은 AGENTS.md와 문서 사이트로 넘깁니다.
# Project Name
[뱃지: CI, 버전, 라이선스]
한 줄 설명.
## Quick Start
\`\`\`bash
pnpm install
pnpm dev
\`\`\`
## Documentation
- [Architecture](docs/architecture.md)
- [API Reference](docs/api.md)
- [Contributing](CONTRIBUTING.md)
## Agent Instructions
- [AGENTS.md](AGENTS.md)
- [CLAUDE.md](CLAUDE.md)llms.txt: 제안/관례로 다루기
llms.txt는 웹사이트 루트의 /llms.txt에 Markdown 색인을 두자는 제안입니다.
LLM이 복잡한 HTML을 일일이 해석하지 않고도 사이트의 핵심 문서와 Markdown 버전을 찾게 하자는 것이 목표입니다.
과대 해석 금지
llms.txt는 유용한 관례이지만, 검색 순위 상승이나 주요 모델 제공자의 자동 크롤링을 보장하는 표준은 아닙니다.
"AI 검색 최적화 마법 파일"이 아니라, 우리가 직접 관리하는 명확한 문서 색인으로 보면 됩니다.
llms.txt 구조
# Project Name
> 프로젝트 한 줄 설명
## Docs
- [Getting Started](/docs/setup.md): 설치와 초기 설정
- [API Reference](/docs/api.md): REST API 엔드포인트 목록
- [Architecture](/docs/architecture.md): 시스템 아키텍처와 ADR
## Optional
- [Changelog](/CHANGELOG.md): 변경 이력
- [Contributing](/CONTRIBUTING.md): 기여 가이드함께 설계할 것
| 항목 | 권장 |
|---|---|
/llms.txt | 사람이 읽을 수 있는 짧은 Markdown 색인 |
| Markdown mirrors | 중요한 HTML 문서는 .md 버전 또는 원본 Markdown 링크 제공 |
/llms-full.txt 또는 확장 파일 | 필요 시 더 긴 전체 색인 제공. 표준 보장처럼 표현하지 않음 |
sitemap.xml | 검색 엔진/크롤러용 전체 URL 목록 |
robots.txt | 크롤링 허용/차단 정책 |
| 내부 RAG 색인 | 실제 운영 답변 품질을 좌우하는 검색/임베딩 파이프라인 |
llms.txt는 sitemap.xml과 역할이 다릅니다. sitemap은 URL을 찾으라고 있는 것이고, llms.txt는 LLM 친화적인 요약과
중요 문서 링크를 모아 둔 색인입니다.
Before/After
Before — 모든 것이 README에 쌓임:
# My Project
프로젝트 소개...
설치 방법...
환경변수...
API 문서...
아키텍처...
코딩 규칙...
테스트 규칙...
배포 절차...After — 목적별로 분리:
| 파일 | 대상 | 내용 |
|---|---|---|
README.md | 사람 | 소개, Quick Start, 주요 링크 |
AGENTS.md | 에이전트 | 명령어, 위치 안내, 검증, 금지사항 |
CLAUDE.md | Claude Code | @AGENTS.md import + Claude 전용 규칙 |
llms.txt | LLM/도구 | 문서 색인과 Markdown 링크 |
docs/ | 사람 + 에이전트 | 상세 문서 |
실전 예시: 모노레포의 llms.txt
# reopt-kb
> Yarn 4 Workspaces + Turborepo 기반 문서 사이트 모노레포
## Apps
- [KB App](/apps/kb/README.md): 메인 지식기반 문서 사이트
- [Handbook App](/apps/handbook/README.md): 핸드북 사이트
- [MCP Server](/apps/kb-mcp/README.md): MCP 검색 서버
## Agent Instructions
- [AGENTS.md](/AGENTS.md): 공통 에이전트 지침
- [CLAUDE.md](/CLAUDE.md): Claude Code 지침
## Architecture
- [Architecture Overview](/docs/architecture.md): 시스템 구조
- [ADR Index](/docs/adr/index.md): 아키텍처 결정 목록
## Operations
- [Runbook](/docs/runbook.md): 장애 대응
- [Release Process](/docs/release.md): 릴리스 절차실제 링크만 포함
llms.txt의 링크는 실제 존재하는 파일이나 URL만 가리켜야 합니다.
존재하지 않는 링크를 색인에 넣으면 에이전트와 RAG 파이프라인이 잘못된 탐색 경로를 학습합니다.
자동 검증
프로젝트 루트 기준 상대 링크를 검증하는 간단한 스크립트입니다.
awk -F'[][]|[()]' '/^- \\[/{ print $4 }' llms.txt | while read -r path; do
case "$path" in
http://*|https://*) continue ;;
/*) target=".$path" ;;
*) target="$path" ;;
esac
if [ ! -e "$target" ]; then
echo "missing: $path"
exit 1
fi
done웹사이트 URL까지 검증하려면 빌드된 사이트를 대상으로 링크 체커를 별도 실행합니다.
AI가 실패하는 패턴
| 실수 | AI가 실패하는 이유 | 수정 방법 |
|---|---|---|
| README에 모든 정보를 담음 | 핵심 지침과 사람용 설명이 섞임 | README, AGENTS, docs로 분리 |
llms.txt를 SEO 보장 수단으로 취급 | 제안/관례를 공식 크롤링 표준처럼 오해 | 색인 품질과 링크 정확성에 집중 |
llms.txt 링크가 깨짐 | 에이전트가 잘못된 문서 경로를 따라감 | CI에서 링크 검증 |
AGENTS.md와 README 내용 중복 | 둘 중 하나가 stale해짐 | README는 링크, AGENTS는 규칙 |
| Markdown mirror 없음 | LLM이 복잡한 HTML에서 본문 추출 실패 | 핵심 문서의 .md 버전 제공 |
AI 프롬프트 예시
이 저장소의 README, docs 디렉토리, package.json, AGENTS.md를 분석해서
llms.txt 초안을 작성해줘.
규칙:
- 실제 존재하는 파일/URL만 포함한다.
- README와 중복되는 긴 설명은 넣지 않는다.
- Docs, Agent Instructions, Architecture, Operations를 구분한다.
- /llms.txt가 검색 순위를 보장한다고 표현하지 않는다.
- 링크 검증 결과를 함께 보고한다.체크리스트
| 항목 | 확인 |
|---|---|
| README가 사람의 첫 진입점으로 30~60줄 안팎에 유지되는가 | ☐ |
AGENTS.md가 README와 분리되어 있는가 | ☐ |
Claude Code를 쓴다면 CLAUDE.md가 @AGENTS.md를 import하거나 명확히 분리되어 있는가 | ☐ |
/llms.txt가 실제 링크만 담고 있는가 | ☐ |
| 중요한 문서에 Markdown 버전 또는 원본 Markdown 링크가 있는가 | ☐ |
llms.txt를 SEO/크롤링 보장으로 홍보하지 않는가 | ☐ |
| CI 또는 주간 작업에서 링크 검증을 수행하는가 | ☐ |