에이전트가 읽는 문서.
masonfe-hyunsu
🧵 1. 개요.
AI 코딩 에이전트에 "이 라이브러리로 코드 짜줘"라고 시키면, 실제로는 없는 함수나 export를 지어 내는 일이 있다.
AI 입장에선 이 패키지 문서는 어디부터 보면 되는지 알려 주는 입구가 없었던 경우가 많다.
그래서 나온 게 하나의 만능 파일이 아니라, 장면마다 다른 입구다. 이 포스팅에서는 llms.txt(사이트), context7.json(패키지 docs), AGENTS.md(레포)가 각각 언제, 누구를 위해 쓰는지 쉽게 풀어 본다.
한 줄로 보면, AI에게 "이 문서는 여기부터 읽어"라고 적어 두는 입구다.
🧭 2. 언제 어떤 파일을 쓰나.
llms.txt(사이트), context7.json(패키지 docs), AGENTS.md(레포)는 쓰는 순간이 다르다. 아래 세 가지로 나눠 보면 된다.
사이트를 물어볼 때 — "이 서비스 문서는 어디 봐?"처럼 URL을 열어 보게 할 때. 사이트 루트에 llms.txt를 두면, 에이전트가 읽을 페이지 목록부터 잡는다.
패키지로 코드를 짤 때 — "이 npm 라이브러리로 컴포넌트 만들어줘"처럼 API를 맞게 쓰게 할 때. context7.json으로 어떤 docs 폴더를 인덱싱할지 정해 둔다.
레포를 직접 고칠 때 — "이 저장소에서 테스트 돌려가며 수정해줘"처럼 우리 코드를 건드릴 때. AGENTS.md에 빌드, 테스트, 하지 말 일을 적어 둔다.
에이전트가 문서를 잡는 흐름은 대략 아래와 같다.
같은 장면에 붙는 형제도 있다. 사이트 쪽은 llms-full.txt, 레포 쪽은 CLAUDE.md, .github/copilot-instructions.md처럼 도구별 파일을 옆에 두는 식이다. 중심 축은 여전히 llms.txt, context7.json, AGENTS.md다.
README는 그대로 사람용 입구다. 위 파일들은 README를 대체하는 게 아니라, 에이전트용 입구를 옆에 두는 일에 가깝다.
📄 3. llms.txt : 사이트부터 읽게 할 때.
사이트를 열어 보게 할 때가 첫 장면이다. 누군가 "이 라이브러리 뭐 할 수 있어?"라고 물으면, 모델은 홈페이지 HTML을 통째로 읽기 어렵다. 메뉴, 스크립트, 광고가 섞여 있어서다.
llms.txt는 그런 잡음을 빼고, 이것부터 보라는 Markdown 지도를 사이트 루트에 두는 제안이다. (llmstxt.org)
W3C 표준은 아니다. 커뮤니티 스펙이고, 열어 주는 쪽과 읽는 쪽 모두 자발적이다.
sitemap이 URL을 전부 나열한다면, llms.txt는 고른 링크 + 한 줄 설명이다. 길면 형제 파일 llms-full.txt에 두고, llms.txt에는 짧은 지도만 남기는 패턴도 있다.
형식은 단순하다.
# 이름,> 한 줄 요약,## 섹션아래- [제목](절대URL): 짧은 설명.## Optional아래는 "시간 없으면 건너뛰어도 된다"는 신호다.
masoneffect에 둔 짧은 예시다.
# masoneffect
> React, Vue, Svelte, vanilla용 애니메이션 이펙트 라이브러리.
## Docs
- [README](https://github.com/FE-HyunSu/masoneffect#readme): 설치와 기본 사용
- [llms.txt](https://github.com/FE-HyunSu/masoneffect/blob/main/llms.txt): 에이전트용 입구
## Optional
- [Homepage](https://masoneffect.com/): 데모파일이 있어도 모델이 안 열면 소용없다. robots, sitemap과도 보완 관계로 보는 편이 맞다. 그래서 길게 쓰지 않는 게 중요하다. 링크를 고르고, 설명은 한 줄로 끝낸다.
📦 4. context7.json : 패키지 docs를 집어넣을 때.
코딩할 때는 이야기가 달라진다. 에이전트는 "최신 API"를 학습 데이터만으로 맞히기 어렵다.
Context7은 그 간극을 줄이려고, 버전별 라이브러리 문서를 에이전트 컨텍스트에 넣어 주는 서비스다. (Library Owners)
패키지 주인이 할 수 있는 일은 단순하다. 저장소 루트에
context7.json을 두고 어디를 파싱할지 정한다.folders,excludeFolders는 문서 위치 필터다.rules는 "이렇게 써라"는 소비자용 주의사항이다.
{
"$schema": "https://context7.com/schema/context7.json",
"projectTitle": "My Library",
"description": "한 줄로 무엇이 되는지",
"folders": ["docs"],
"excludeFolders": ["src", "tests", "**/archive"],
"rules": ["직접 import 경로를 쓴다", "공개 API를 깨지 않는다"]
}블로그 사이트 전체보다 npm 패키지, SDK에 잘 맞는다.
파일 이름만
context7.json이고 스키마가 다르면, Context7이 기대하는 설정이라고 보기 어렵다. 이름과 내용을 맞춰야 한다.
🧾 5. AGENTS.md : 레포를 열어 일할 때.
세 번째 장면은 "이 저장소를 고치는" 일이다.
AGENTS.md는 여러 코딩 에이전트가 같이 읽자고 만든 열린 Markdown 포맷이다. (agents.md)
README가 "사람을 위한 소개"라면, AGENTS.md는 "에이전트를 위한 작업 메모"에 가깝다. 빌드, 테스트, 하지 말 것.
다만 도구마다 읽는 파일 이름이 조금 다르다. 공식 docs 기준으로만 짧게 보면 이렇다.
Claude Code — 기본은
CLAUDE.md.AGENTS.md는 네이티브로 안 읽고,CLAUDE.md에서@AGENTS.md로 가져오거나 symlink로 맞춘다. (Memory)Cursor —
AGENTS.md를 지원한다. 루트뿐 아니라 하위 폴더에도 둘 수 있다. (Rules)Codex — 세션 전에
AGENTS.md를 읽는다. 전역~/.codex, 하위AGENTS.override.md, 합산 크기 상한이 있다. (AGENTS.md 가이드)GitHub Copilot — 레포 공통 안내는
.github/copilot-instructions.md에 둘 수 있다. AGENTS.md와 같이 있으면 둘 다 참고하는 경우도 있다.공통으로 가져가려면 루트에
AGENTS.md를 두고, Claude만CLAUDE.md에서 import 하는 식이 무난하다.
🔀 6. 그래서 어디에 무엇을 두나.
파일이 세 개라서 헷갈리면, 장면부터 고르면 된다.
사이트를 AI에게 소개하고 싶다 →
llms.txt패키지 API를 코딩 에이전트가 맞게 쓰게 하고 싶다 → Context7용
context7.json+ docs레포를 연 에이전트가 헤매지 않게 하고 싶다 →
AGENTS.md(필요하면CLAUDE.md와 연결)같은 체크리스트를 llms.txt와 AGENTS.md에 복붙하면 둘 다 금방 낡는다.
llms.txt에는 읽을 곳, AGENTS.md에는 일할 때 규칙만 남기는 편이 유지보수가 쉽다.
📦 7. 실제로 보면 : masoneffect, mason-sprite.
말로만 나누면 추상적이라, 내가 만든 패키지 두 개로 다시 보면 이해가 빠르다.
masoneffect.
llms.txt를 이미 두었다. 효과 목록, tree-shaking import, 프레임워크별 템플릿이 들어 있다.
AI_SETUP_GUIDE.md도 있지만, llms.txt가 primary라고 적어 두었다.context7.json파일은 있다. 다만 공식 Context7 스키마(folders,rules)와는 다른 패키지 메타 JSON에 가깝다. 이름만 같다고 인덱서가 원하는 형태는 아니다.
mason-sprite.
README와 사이트는 있는데, 루트
llms.txt는 아직 없다.API가 단순한 편이라, 오히려 짧은 llms.txt가 잘 맞는다. import 경로,
rows/cols/fps, ref API, 잘못된 통짜 import 금지 정도면 충분하다.정리하면 패키지 레포에서는 역할이 이렇게 갈린다.
AGENTS.md — 기여자가 레포를 고칠 때
llms.txt — 바깥 에이전트가 가져다 쓸 때
context7.json — docs 인덱싱 범위를 좁힐 때
README — 사람용 빠른 시작
기여자용 입구와 소비자 에이전트용 지도를 파일부터 갈라 두면, 나중에 덜 헷갈린다.
댓글