문서(Documentation), README 파일, API 레퍼런스는 오랫동안 개발자들이 새로운 도구를 시작하는 데 도움을 주었습니다. 코딩 에이전트가 더 많은 작업을 수행함에 따라, 이들이 정보를 탐색하고 개발자 제품을 성공적으로 사용하도록 돕는 새로운 형식들이 등장하고 있습니다.
AI 에이전트 문서화 유형 및 프로토콜
코딩 에이전트가 개발자 제품을 사용하는 것을 돕는 것은 단순히 좋은 문서를 작성하는 것 이상을 필요로 합니다. 에이전트는 정보를 어디서 찾고, 저장소(repository) 내에서 어떻게 작업해야 하며, 어떤 도구를 사용할 수 있는지 알아야 합니다. 문서 파일과 에이전트별 지침부터 MCP와 같은 프로토콜에 이르기까지, 이러한 과정을 더 쉽게 만들기 위한 자원들이 늘어나고 있습니다. 아래 표는 현재 사용 가능한 것들을 보여주며, 이후 각 방식이 어떻게 작동하는지, 그리고 언제 사용해 볼 가치가 있는지 자세히 살펴보겠습니다.
AI 에이전트 리소스 및 목적
| Resource | Primary purpose | Where it lives |
|---|
| llms.txt | Helps agents find relevant documentation | Website or documentation site |
| ... | | |
llms.txt란 무엇이며 AI 에이전트는 어떻게 사용하나요?
AI 에이전트에게 적절한 문서를 찾는 것은 항상 간단하지 않습니다. llms.txt는 제품을 소개하고 가장 유용한 문서에 링크를 제공하는 Markdown 파일로, 에이전트가 전체 사이트를 검색할 필요 없이 시작점을 얻게 해줍니다.
예를 들어, Quantiles 웹사이트 자체도 다음과 같이 시작하는 llms.txt를 제공합니다:
# Quantiles
> Quantiles는 개발자가 코딩 에이전트가 개발자 작업을 얼마나 신뢰성 있게 완료하는지 평가하도록 돕습니다.
...
에이전트는 모든 것을 컨텍스트로 로드하는 대신 작업과 관련된 링크를 따라갈 수 있습니다. 이 제안은 또한 HTML 링크나 HTTP 헤더를 통해 이러한 리소스를 발견하는 것을 지원하며, 문서 페이지의 Markdown 버전을 제공할 것을 권장합니다. 관련 관례인 llms-full.txt는 문서를 단일 파일로 결합합니다. 편리해 보이지만, 전체 내보내기는 불필요한 컨텍스트를 소모할 수 있습니다. Mintlify와 같은 플랫폼은 두 파일을 모두 생성할 수 있습니다.
llms.txt 또는 llms-full.txt가 존재한다고 해서 에이전트가 그것을 사용할 것이라고 보장하지는 않습니다. 에이전트가 이러한 리소스를 발견하고, 관련 링크를 따라가며, 작업을 완료하는 데 필요한 정보를 찾는지 평가해야 합니다.
AGENTS.md가 코딩 에이전트를 안내하는 방법
에이전트가 저장소에서 작업하기 시작할 때, 의존성 설치 및 테스트 실행부터 코딩 컨벤션 준수에 이르기까지 프로젝트가 어떻게 작동하는지 이해해야 합니다. AGENTS.md 형식은 이러한 지침을 위한 전용 공간을 제공합니다.
예를 들어, Quantiles의 AGENTS.md 시작 부분은 다음과 같습니다:
# Quantiles Agent Guide
This file is for coding assistants such as Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, OpenCode, and similar tools. It gives agents a short, public-safe map of the Quantiles repository and the rules for making focused, reviewable changes.
...
지침은 프로젝트에 따라 다릅니다. 개발 워크플로우, 테스트 요구 사항 또는 특정 도구 사용 방법에 대한 지침을 포함할 수 있습니다. 웹사이트 문서와 달리, AGENTS.md는 에이전트가 저장소에서 작업하는 것을 안내하기 위한 것이며, 모든 에이전트가 자동으로 이를 읽지는 않습니다.
⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.
[번역된 제목]: AI 에이전트 문서화 가이드: llms.txt, AGENTS.md, SKILL.md 및 MCP
Codex layers repository guidance를 따르지만, 다른 코딩 에이전트는 이를 다르게 로드하고 우선순위를 지정할 수 있습니다. 어떤 에이전트든 간에, 지침을 집중적이고 최신 상태로 유지하는 것이 중요합니다. 오래된 명령어와 불필요한 규칙은 워크플로우 비효율성을 초래하고, 작업 복잡도를 높이며, 에이전트가 제품과 상호 작용할 때 실패를 야기할 수 있습니다.
SKILL.md가 에이전트의 워크플로우 완료에 도움을 주는 방법
일부 작업은 저장소 지침만으로는 충분하지 않습니다. 에이전트는 CLI 설치, 자격 증명 구성, 여러 단계 완료 및 결과 확인 등 더 많은 것이 필요할 수 있습니다. agent skill은 이러한 워크플로우를 완료하는 데 도움을 주기 위해 재사용 가능한 지침과 지원 리소스를 제공합니다.
quantiles-skill/
├── SKILL.md
├── references/
...
SKILL.md 파일에는 이름, 설명 및 워크플로우 완료를 위한 지침이 포함되어 있습니다. 지원 파일은 필요할 때 추가 문서나 스크립트를 제공할 수 있습니다. 설명(description)은 에이전트가 언제 이 기술을 사용해야 할지 판단하는 데 도움을 주기 때문에 특히 중요합니다.
OpenAI Codex와 Anthropic의 스킬 구현 모두 '점진적 공개(progressive disclosure)'라는 프로세스를 사용하여 기술을 발견하고 사용합니다. 에이전트는 처음에 사용 가능한 기술에 대한 간략한 설명을 보고, 필요할 때 전체 지침과 지원 리소스를 로드합니다. 이것이 작동하려면 해당 기술이 에이전트가 발견할 수 있는 위치에 설치되어야 합니다. 단순히 저장소에 SKILL.md 파일을 추가한다고 해서 에이전트가 이를 찾거나 사용한다는 의미는 아닙니다. 기술이 사용 가능하다 하더라도, 에이전트가 언제 사용해야 할지 인식하고 지침을 올바르게 따를지에 대한 의문은 여전히 남아 있습니다.
MCP가 AI 에이전트를 도구 및 데이터에 연결하는 방법
문서화가 에이전트가 제품을 이해하는 데 도움을 주지만, Model Context Protocol (MCP)은 AI 애플리케이션이 자체 도구 및 데이터에 연결할 수 있는 표준화된 방법을 제공합니다. MCP 서버는 세 가지 유형의 기능을 노출할 수 있습니다:
-
도구 (Tools): 에이전트가 호출할 수 있는 작업입니다. 예를 들어, 프로젝트를 생성하거나 평가를 시작하는 것 등이 있습니다.
-
리소스 (Resources): 애플리케이션이 검색할 수 있는 정보입니다. 예를 들어, 평가 결과나 실행 로그 등이 있습니다.
-
프롬프트 (Prompts): 특정 작업이나 상호 작용을 안내하는 재사용 가능한 템플릿입니다.
예를 들어, Quantiles MCP 서버는 에이전트가 API 요청을 수동으로 구성하거나 CLI를 사용하는 대신 구조화된 도구 호출(tool calls)을 사용하여 평가의 결과물을 생성하고 비교할 수 있도록 할 수 있습니다. 에이전트가 실제로 사용할 수 있는 기능은 해당 에이전트의 MCP 클라이언트가 무엇을 지원하고 제공하는지에 따라 달라집니다.
MCP와 SKILL.md 파일도 함께 작동할 수 있습니다. 스킬(skill)은 어떤 작업을 사용해야 하는지, 어떤 순서로 사용해야 하는지, 그리고 결과를 어떻게 검증해야 하는지를 설명하며 에이전트를 워크플로우를 통해 안내할 수 있습니다. MCP는 이러한 단계를 수행하는 데 필요한 도구에 대한 접근을 제공합니다.
다양한 코딩 에이전트용 지침 파일 (Instruction files for different coding agents)
지금까지 다룬 llms.txt, AGENTS.md, SKILL.md, 그리고 MCP를 포함한 리소스들은 지원 편차가 있지만, 여러 AI 에이전트에서 작동하도록 설계되었습니다. 하지만 코딩 에이전트 역시 자체적인 지침 파일과 구성 옵션을 가지고 있습니다. 이들은 지침을 로드하는 방식, 적용되는 위치, 우선순위를 갖는 지침 등이 다를 수 있습니다. 일부 인기 있는 코딩 에이전트들이 이를 처리하는 방법은 다음과 같습니다:
-
Claude Code: 프로젝트 지침에는 CLAUDE.md를 사용하고, 더 구체적인 규칙에는 .claude/rules/를 사용합니다. 버전 및 구성에 따라 AGENTS.md도 지원할 수 있습니다.
-
Gemini CLI: 프로젝트 컨텍스트 및 지침에 GEMINI.md를 사용하며, 대체 파일명을 구성할 수 있는 옵션을 제공합니다.
-
Cursor: AGENTS.md와 .cursor/rules/에 저장된 규칙을 지원합니다. 이 규칙들은 작업과 관련성이 있을 때, 특정 파일에 대해, 또는 명시적으로 요청될 때 자동으로 적용될 수 있습니다.
-
GitHub Copilot: 리포지토리 전체의 지침에는 .github/copilot-instructions.md를 사용하고, 특정 경로에 적용되는 지침은 .github/instructions/*.instructions.md를 사용합니다.
여러 에이전트를 지원함에 따라 별도의 지침 파일을 유지하는 것이 빠르게 어려워질 수 있습니다. 가능하다면 공유된 지침은 한 곳에 보관하고, 필요한 경우에만 에이전트별 지침을 추가하세요. 그리고 AGENTS.md나 SKILL.md와 마찬가지로, 각 에이전트가 의도한 대로 지침을 발견하고 따르는지 테스트해야 합니다.
auth.md가 AI 에이전트 인증을 지원하는 방법
WorkOS에서 2026년 5월에 소개된 auth.md는 비교적 새로운 제안 중 하나입니다. 우리가 다룬 기존의 자료들과 달리, 아직 채택 초기 단계에 있습니다. 이 문서는 에이전트가 문서화와 API를 이해할 수는 있지만, 계정을 생성하거나 자격 증명을 얻어야 할 때 막히는 익숙한 문제를 해결합니다.
이 제안은 서비스가 마크다운 파일 내에서 등록(registration), 인증(authentication), 그리고 사용 가능한 권한을 설명하는 방법을 제공합니다. 이는 두 가지 주요 접근 방식을 지원합니다:
-
에이전트 검증 (Agent verified): 신뢰할 수 있는 에이전트 제공자가 사용자 신원을 검증하여, 서비스가 추가적인 사용자 상호 작용 없이 에이전트를 등록할 수 있도록 합니다.
-
사용자 주장 (User claimed): 에이전트가 등록을 시작한 후, 사용자에게 로그인하고 코드를 확인하도록 요청하여 접근 권한을 승인받습니다.
두 접근 방식 모두 궁극적으로 에이전트가 범위가 지정된 액세스 토큰을 얻도록 합니다. 하지만 auth.md만 게시하는 것만으로는 충분하지 않습니다. 서비스는 여전히 인증 엔드포인트, 토큰 발급 및 권한 확인 기능을 구현해야 합니다.
또한 auth.md와 MCP(Multi-Cloud Platform) 인가(authorization)를 구분할 가치가 있습니다. MCP 인가는 보호되는 MCP 서버에 대한 액세스를 관리하는 반면, auth.md는 에이전트가 서비스에 등록하는 것을 돕는 데 초점을 맞추어 나중에 권한을 부여받을 수 있는 신원을 갖도록 합니다.
새롭게 제안되는 방안으로서 auth.md는 주목할 가치가 있지만, 호환성과 에이전트 지원은 여전히 테스트가 필요합니다. 그리고 자동 등록의 경우에도 계정 소유권, 권한 또는 결제가 관련된 일부 워크플로는 여전히 인간의 승인이 필요할 수 있습니다.
어떤 AI 에이전트 문서화 표준을 사용해야 하며, 어떻게 평가할 것인가
가장 좋은 시작점은 에이전트가 귀하의 제품을 사용할 때 겪는 문제들을 살펴보는 것입니다. 단순한 라이브러리는 접근 가능한 문서만 필요할 수 있는 반면, 더 복잡한 워크플로우를 가진 개발자 플랫폼은 에이전트 스킬(skills), 구조화된 도구(structured tools) 및 인증 지침으로부터 이점을 얻을 수 있습니다.
다양한 리소스들이 개발자 경험의 서로 다른 부분을 다룹니다:
개발자 워크플로우에 AI 에이전트 리소스 매칭하기
| 에이전트가... | 관련 리소스 | 평가할 내용 |
|---|
| 정보를 찾을 때 | llms.txt, Markdown 문서화 | 올바른 문서를 찾을 수 있는가? |
| ... | | |
알아내려면 제품 설치, 빠른 시작 완료, 인증 구성 또는 보다 고급 기능 사용과 같은 대표적인 워크플로우를 평가하는 것부터 시작하세요. 리소스가 있을 때와 없을 때의 성능을 비교하여 어떤 부분에서 도움이 되고, 어디서 그렇지 않은지, 그리고 무엇이 개선되어야 할지 이해할 수 있습니다.
고려해야 할 몇 가지 핵심 질문은 다음과 같습니다:
-
발견 및 활성화: 에이전트가 관련 문서, 스킬 또는 도구를 찾아서 사용했습니까?
-
작업 성공 및 신뢰성: 반복적인 시도에 걸쳐 작업을 올바르고 일관되게 완료했습니까?
-
효율성: 이 작업은 얼마나 많은 시간, 토큰 사용, 그리고 도구 활동을 필요로 했습니까?
-
오류 및 복구: 에이전트가 어디에서 막혔으며, 인간의 개입 없이 복구할 수 있었습니까?
AI 에이전트가 진화함에 따라 문서도 진화합니다
AI 에이전트는 빠르게 진화하고 있으며, 이들이 제품을 사용하는 데 도움이 되는 리소스 또한 그 속도를 따라잡아야 합니다. 오늘날 한 에이전트에게 효과적이었던 것이 다른 에이전트에게는 잘 작동하지 않거나, 심지어 같은 에이전트라도 업데이트 후에 다를 수 있습니다.
대표적인 개발자 작업을 유지하는 것은 이러한 변화를 발견하기 쉽게 만듭니다. 제품, 문서 및 에이전트가 진화함에 따라 평가를 다시 실행하고, 실행 추적(execution traces)을 사용하여 무엇이 잘못되는지 이해하세요. 이러한 문제를 해결하는 것은 때때로 지침을 필요로 할 수 있습니다. 다른 경우에는 더 명확한 오류 메시지, 더 간단한 설정 프로세스 또는 더 유용한 도구 응답일 수도 있습니다.
더 많은 형식을 지원하는 것이 중요하기는 오직 그것이 개발자 경험을 개선할 때만 의미가 있습니다. 가장 중요한 것은 에이전트가 제품을 탐색하고 작업을 신뢰성 있고 성공적으로 완료할 수 있는지 여부입니다.