AI 에이전트가 읽는 기술 문서, 무엇이 달라야할까 — 2부

이 글은 DoveRunner의 콘텐츠 보안 및 모바일 앱 보안 관련 개발자 문서에 체계적인 에이전트 준비 상태 평가를 적용하여 AI 코딩 에이전트가 올바른 통합 코드를 생성할 수 있는지, 아니면 오류 구현을 조용히 생성하는지 평가하는 시리즈의 두 번째 글입니다. 첫 번째 글은 여기에서 읽으실 수 있습니다.

AI 코딩 에이전트는 문서에 명시된 내용을 바탕으로 코드를 생성합니다. 문서에 없는 내용, 암묵적으로 가정된 제약, 다른 문서에 흩어진 의존성, 불투명한 오류 응답은 에이전트가 스스로 판단하고 채울 수 없습니다. 특히 B2B SaaS 개발자 문서는 이런 공백으로 가득 차 있는 경우가 많습니다.

이 공백을 측정하려면 기준이 필요합니다. 이 글에서는 '에이전트 준비도'(Agent Readiness)를 평가하는 2계층 프레임워크와 각 계층을 측정하는 두 가지 방법론에 대해 알아보겠습니다.

에이전트 준비도의 2계층

'에이전트 준비도'(Agent Readiness) 는 두 개의 계층으로 나뉩니다.

인프라 계층(Infrastructure Layer)

에이전트가 문서를 발견하고 접근할 수 있는가를 묻는 계층입니다. 웹 크롤러의 접근이 허용되어 있는가, 콘텐츠가 Markdown 형식으로 제공되는가, AI 사이트맵에 해당하는 llms.txt 파일이 존재하는가, MCP(Model Context Protocol) 서버 카드가 있는가 — 이 계층의 항목들은 자동화 도구로 측정할 수 있습니다.

콘텐츠 계층(Content Layer)

문서의 내용 자체가 에이전트가 올바른 코드를 생성하기에 충분한가를 묻는 계층입니다. 선행 조건이 그것이 필요한 단계 앞에 명시되어 있는가, 문서 간 의존성이 의존이 발생하는 시점에 드러나 있는가, 보안 제약이 위반 시 발생하는 결과와 함께 경고로 표시되어 있는가, 외부 승인이나 프로비저닝이 필요한 조건이 연동 워크플로우 안에 명시되어 있는가. 이 계층의 항목들은 자동화 도구만으로는 검증할 수 없습니다.

두 계층은 측정하는 대상이 다릅니다. 인프라 항목을 모두 통과한 문서 사이트라도 에이전트를 실패하게 만드는 암묵적 제약과 누락된 교차 참조가 있을 수 있습니다. 반대로 콘텐츠 품질이 뛰어나더라도 인프라 계층이 갖춰지지 않으면 에이전트에게 구조적으로 보이지 않는 사이트가 됩니다.

인프라 계층은 자동화 도구로 평가합니다. 콘텐츠 계층은 전체 통합 흐름을 직접 추적하는 방식으로만 평가할 수 있으며, 그 방법론은 4편에서 자세히 다루도록 하겠습니다.

인프라 성숙도 모델

인프라 계층은 단계적 성숙도 모델을 따릅니다. 에이전트 친화적인 기술 표준은 발견 가능성부터 제어된 상호작용까지 세 단계를 거치며 발전하며, 각 단계는 서로 다른 실패 유형을 나타냅니다. Stage 1에 도달하지 못한 사이트와 Stage 1~2 사이에 머무는 사이트는 다른 방식으로 실패합니다.

Stage 1 — 발견 가능성(Discoverability)

llms.txt, sitemap.xml, Link 헤더(RFC 8288)가 이 단계에 해당합니다.

Stage 1은 에이전트가 문서를 읽기 전에 사이트에 무엇이 있는지 알 수 있게 해줍니다. 이 단계가 없으면 URL만 가지고 접근한 에이전트는 사이트를 처음부터 무작위로 크롤링해야 하며, 어떤 페이지가 있고 서로 어떻게 연결되는지 구조적으로 파악하기 어렵습니다. llms.txt는 검색 엔진에게 sitemap.xml이 하는 역할을 AI 에이전트에게 해줍니다. 주요 페이지와 설명을 담은 기계가 읽을 수 있는 색인으로, 에이전트가 전체를 크롤링하지 않고도 사이트의 범위를 파악할 수 있게 합니다.

Stage 2 — 거버넌스(Governance)

AI 전용 robots.txt 규칙, Content-Signal 선언, Markdown 콘텐츠 제공이 이 단계에 해당합니다.

에이전트가 콘텐츠를 소비하는 방식을 제어하는 계층입니다. Markdown 제공이 중요한 이유는, HTML을 받은 에이전트가 실제 문서 내용을 추출하기 위해 내비게이션 요소, 사이드바, 레이아웃 구조를 통과해야 하기 때문입니다. 이 과정에서 노이즈가 생기고, 부수적인 요소에 묻혀 있는 제약 조건이 누락될 가능성이 높아집니다. Content-Signal은 AI 학습, 검색 색인, 프롬프트 입력 허용 여부를 robots.txt에 직접 선언하는 새로운 표준으로, 자신의 콘텐츠가 AI 시스템에 의해 어떻게 활용되는지 명시적으로 제어할 수 있게 해줍니다.

Stage 3 — 제어된 상호작용(Controlled Interaction)

API Catalog(RFC 9727), MCP Server Card, OAuth 메타데이터가 이 단계에 해당합니다.

Stage 3은 에이전트가 사람의 지시 없이 API에 자율적으로 연결하고 인증을 처리할 수 있게 합니다. MCP 서버를 구축하는 조직에게 이 단계는 에이전트 오케스트레이터(여러 AI 에이전트의 작업을 순서에 맞게 조율하는 프레임워크)가 해당 서버를 발견하고 연결하는 방법입니다. 이 단계를 건너뛰면 표준 발견 메커니즘에 의존하는 에이전트 프레임워크에서 MCP 서버는 보이지 않는 존재가 됩니다.

단계 구분은 개선 계획을 세울 때 중요합니다. Stage 1 실패는 정적 파일 몇 개와 설정 변경으로 해결됩니다. Stage 2에 대한 개선에는 콘텐츠 제공 방식의 변경이 필요합니다. Stage 3은 중장기적인 아키텍처 작업입니다. 이 세 단계를 구분하지 않고 단일한 체크리스트로 다루면 노력이 잘못된 곳에 집중되는 결과로 이어집니다.

콘텐츠 계층 평가에서 찾는 것

인프라 스캐닝은 점수를 산출합니다. 콘텐츠 계층 평가는 다른 종류의 결과를 산출합니다. 기술 문서 내용의 오류 또는 공백으로 인해 API 연동 과정의 어느 지점에서 에이전트가 실패하게 될지를 찾는 것입니다.

평가 방법은 엔드투엔드 시나리오 감사(end-to-end scenario auditing) 입니다. 평가자는 문서를 통해 완전한 고객 여정을 단계별로 추적하며, 각 단계를 그것을 뒷받침해야 하는 특정 문서 페이지에 매핑합니다. 기준은 개별 문서가 잘 작성되어 있는가가 아닙니다. 통합 순서대로 따라갔을 때, 문서 세트 전체가 에이전트에게 올바른 결과를 만들어 낼 수 있는 모든 것을 제공하는가입니다.

DoveRunner의 Content Security와 Mobile App Security 문서를 감사한 결과, 다섯 가지 실패 유형이 반복적으로 나타났습니다.

• 문서 간 인계 공백: 통합 단계가 다른 문서에서 생성되거나 설정된 정보를 필요로 하는데, 어느 문서도 그 의존성을 명시하지 않는 경우입니다. 에이전트는 해당 단계를 단독으로 완료하고, 의존성은 건너뛰어집니다.
• 조용한 실패(silent failure): 위반 시 유효해 보이지만 실제로는 그렇지 않은 출력이 생성되는 제약 조건입니다. 예를 들면 토큰이 잘못된 인코딩으로 생성되거나, 스트림이 잘못된 암호화 방식으로 패키징되는 등의 경우입니다. 형식은 모든 단계에서 올바르게 보이고, 실패는 런타임에서야 드러나며 원인으로 거슬러 올라갈 수 없는 불투명한 오류와 함께 나타납니다.
• 연동 개발 외적인 선행 조건: 연동 작업을 시작하기 전에 계정 프로비저닝, 인증서 등록, 또는 서드파티 승인이 필요한데, 통합 가이드의 상단이 아닌 별도 튜토리얼, 각주, 절차 중간의 노트로만 문서화된 경우입니다. 에이전트는 선행 조건 없이 통합을 시작합니다.
• 플랫폼·환경 제약: 클라우드 리전, 디바이스 인증 등급, SDK 호환성 같은 런타임 조건이 시작 부분의 선행 조건 경고가 아닌 절차 중간 단계 안에 등장하는 경우입니다. 에이전트는 해당 단계를 읽고 따르며, 결과적으로 한 환경에서는 작동하지만 목표 환경에서는 실패하는 설정을 만들어 냅니다.
• 오류 처리 가이드 누락: API가 의도적으로 불투명한 오류 응답을 반환합니다. 일반적인 오류 뒤에 있는 서로 다른 실패 유형을 열거한 문서가 없으면, 에이전트는 토큰 만료, 인증서 불일치, 파라미터 오류를 구분하는 코드 대신 포괄적인 오류 처리기와 재시도 루프를 생성합니다.

이 다섯 가지 유형 중 어느 것도 인프라 스캐닝으로는 탐지할 수 없습니다. 문서의 실제 통합 경로를 직접 따라가는 방식으로만 발견할 수 있습니다.

두 가지 평가 방법론

두 가지 방법론은 함께 작동합니다.

첫 번째는 인프라 스캐닝입니다. 전문 도구가 문서 사이트를 스캔하여 구조적 준비도에 대한 점수화된 평가를 제공합니다. Cloudflare의 Is Your Site Agent-Ready? 사이트는 봇 접근 제어, API 카탈로그, MCP 서버 카드, OAuth Discovery를 검사하며, Fern의 Agent Score는 llms.txt 존재 여부와 Markdown 제공 여부를 검사합니다. 하나만 실행하면 불완전한 그림이 나오는데, isitagentready.com은 llms.txt를 전혀 확인하지 않습니다.

두 번째는 엔드투엔드 시나리오 기반 감사입니다. 감사자가 문서를 통해 완전한 고객 여정을 추적하며, 문서에 작성된 내용만으로 에이전트가 각 통합을 재현할 수 있는지 검증합니다. 모든 단계가 특정 문서 페이지에 매핑되고, 각 단계에서 묻는 질문은 하나입니다. 이 문서가 다음 단계에 필요한 모든 것을 넘겨주고 있는가?

기능 경로 분석(문서를 하나씩 읽으며 해당 기능을 다루는지 평가하는 방식)은 문서 경계에서 발생하는 공백을 놓칩니다. 대부분의 에이전트 실패는 문서 내부에서 발생하지 않습니다. 문서 간 인계 지점에서 발생합니다.

마치며

두 방법론 모두 Content Security와 Mobile App Security를 다루는 DoveRunner의 개발자 문서 사이트인 DoveRunner Docs에 적용되었습니다.

다음 편에서는 Is Your Site Agent-Ready?와 Fern Agent Score의 인프라 스캔 결과를 살펴보겠습니다. 두 점수는 같은 사이트의 서로 다른 항목을 측정하며, 두 결과를 함께 읽을 때 어느 하나만으로는 얻을 수 없는 보다 완전한 그림이 나타납니다.

이 시리즈는 DoveRunner의 개발자 문서와 AI 코딩 에이전트가 필요로 하는 것 사이의 간극을 체계적으로 정의하고 좁혀나가는 과정을 기록합니다.