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

이 시리즈의 3편에서는 DoveRunner Docs 사이트를 두 가지 '에이전트 준비도'(Agent Readiness) 측정 도구로 점검한 결과를 정리했습니다. isitagentready.com에서는 100점 만점에 43점, Fern Agent Score에서는 0점이었습니다. 두 점수 모두 같은 근본 원인을 가리키고 있었는데, AI 에이전트가 이 문서를 최적으로 소비하기 위한 인프라가 아직 갖추어져 있지 않다는 점이었습니다.

이 글에서는 이 두 점수의 향상을 위해 적용한 개선 작업과, 그 개선의 결과가 무엇을 말해 주는지 알아보겠습니다.

시작점: isitagentready.com

isitagentready.com은 DoveRunner Docs를 콘텐츠 사이트 기준으로 100점 만점에 43점, 'Level 1: Basic Web Presence' 등급으로 평가했습니다. 적용 가능한 7개 항목 가운데 4개가 실패한 상태였습니다.

세 가지 개선 작업으로 네 개의 실패 항목 중 세 개를 해결했습니다. 나머지 하나인 DNS-AID는 의도적으로 건너뛴 항목입니다.

개선 1: Link 응답 헤더

난이도: 낮음

Link 헤더(RFC 8288)는 서버가 HTTP 응답에서 리소스 간의 관계를 선언할 수 있게 해 줍니다. 에이전트 준비도 관점에서 중요한 용도는 페이지의 Markdown 버전을 가리키는 것인데, 이 헤더를 읽은 에이전트는 각종 태그와 스크립트로 가득한 HTML을 파싱하는 대신 마크다운 버전을 통해 필요한 콘텐츠만을 가져올 수 있기 때문입니다.

기존에 DoveRunner Docs는 Link 헤더를 전혀 내보내지 않고 있었습니다. 해당 사이트의 배포 및 호스팅 플랫폼인 Vercel의 설정을 변경해 모든 페이지 응답에 헤더 하나를 추가했습니다.

점수: 43 → 57

개선 2: Markdown 콘텐츠 협상

난이도: 중간

이 작업은 사이트를 제공하는 방식만이 아니라 빌드하는 방식까지 바꿔야 했기 때문에 가장 손이 많이 가는 개선이었습니다.

요구 사항은 이렇습니다. 에이전트가 요청에 Accept: text/markdown을 담아 보내면, 서버는 페이지를 HTML이 아닌 순수 Markdown으로 반환해야 합니다. HTML에는 내비게이션 요소, 사이드바, 레이아웃 마크업이 들어 있어 에이전트가 문서를 읽으려 할 때 잡음이 됩니다. 반면 Markdown은 에이전트가 깔끔하게 다룰 수 있는 형식입니다.

DoveRunner Docs는 정적으로 빌드되는 사이트입니다. 원본 콘텐츠는 Markdown으로 작성되지만 모든 HTTP 응답은 HTML로 나갑니다. 이를 해결하기 위해 빌드 시점에 모든 페이지의 Markdown 버전을 미리 생성하고, Accept 헤더가 일치할 때 CDN이 해당 파일을 투명하게 제공하도록 설정했습니다. 문서 콘텐츠 자체나 원본 파일은 전혀 건드리지 않았고, 전달 계층만 손봤습니다.

그 결과 Accept: text/markdown을 보내는 에이전트는 이제 깨끗한 Markdown을 받고, HTML을 요청하는 브라우저는 그대로 HTML을 받습니다. 같은 URL이 두 경우를 모두 처리합니다.

점수: 57 → 71

DNS-AID에 대한 판단

항목: Discoverability / DNS-AID 판단: 건너뜀 (적용 대상 아님)

DNS-AID는 에이전트가 스스로를 에이전트 디렉터리에 등록하기 위한 명세입니다. 다른 에이전트나 오케스트레이터에 의해 발견되어야 하는 소프트웨어, 즉 에이전트를 위해 설계된 규격입니다.

DoveRunner Docs는 에이전트가 소비할 수 있도록 준비되는 문서 사이트이지, 스스로를 등록하는 에이전트가 아닙니다. 따라서 이 항목은 적용되지 않습니다.

같은 점검을 돌리는 다른 팀이라면 짚어 둘 만한 구분입니다. 에이전트 준비도 도구의 모든 항목이 측정 대상을 콘텐츠 사이트로 가정하는 것은 아니며, 어떤 항목은 대상 자체가 에이전트라고 가정합니다. 실패 항목을 개선 우선순위로 올리기 전에 항목 설명을 먼저 읽어 보면 불필요한 노력을 줄일 수 있습니다.

개선 3: Content Signals

난이도: 낮음 (robots.txt에 한 줄)

Content Signals는 사이트가 AI 활용에 대한 선호를 robots.txt 파일에 직접 선언할 수 있게 해 주는 표준입니다. 여기서는 세 가지 선호가 중요합니다.

• ai-train: 이 콘텐츠를 AI 모델 학습에 사용해도 되는가?
• search: 검색 엔진이 색인해도 되는가?
• ai-input: AI 에이전트가 이를 컨텍스트로 사용해도 되는가?

DoveRunner Docs에서는 각 선택이 모두 의도된 것입니다.

• ai-train=no: DoveRunner의 문서에는 독자적인 연동 패턴과 플랫폼별 구현 세부 사항이 담겨 있습니다. 이를 AI 모델 학습에 사용하면 경쟁사에 이로울 수 있습니다. 이 문서는 DoveRunner 제품을 다루는 개발자를 돕기 위한 것이지, 외부의 학습용 말뭉치로 쓰이기 위한 것이 아닙니다.
• search=yes: 공개된 개발자 문서는 색인되는 것이 맞습니다. 이를 제한할 이유가 없습니다.
• ai-input=yes: 이것이야말로 에이전트 준비도 프로젝트 전체의 목적입니다. 이 문서는 AI 코딩 에이전트가 개발자의 연동을 도울 때 컨텍스트로 활용할 수 있도록 최적화되고 있습니다. 이를 막는다면 프로젝트의 목표와 모순됩니다.

Content Signals의 실질적 가치는 바로 이 구분에 있습니다. ai-train=no, ai-input=yes라는 조합입니다. Disallow: GPTBot 식의 전면 차단은 정작 도우려던 에이전트에게 문서를 보이지 않게 만듭니다. 반면 Content Signals를 쓰면 더 정밀하게 의사를 밝힐 수 있습니다. 우리 문서를 개발자를 돕는 데에는 쓰되, 모델 학습에는 쓰지 말라는 것입니다.

점수: 71 → 86

결과

최종 점수: 86/100, Level 5: Agent-Native

세 가지 개선 작업을 적용하는 동안 문서 콘텐츠는 전혀 손대지 않았습니다. 43점에서 86점으로의 향상은 전적으로 인프라에서 나왔습니다. 사이트를 어떻게 제공하는지, 어떤 헤더를 내보내는지, 자신의 AI 활용 선호를 어떻게 선언하는지가 그것입니다.

이것이 에이전트 준비도 프레임워크에서 인프라와 콘텐츠를 분리하는 이유입니다. 두 문제는 서로 다른 개선 방식을 요구하며 서로 다른 시간 축으로 움직입니다. 인프라 격차는 며칠이면 좁힐 수 있지만, 콘텐츠 격차는 문서 전체에 걸쳐 실제 연동 여정을 따라가며 점검해야 하는 작업으로 4편에서 다룬 내용입니다.

2편에서 소개한 3단계 성숙도 모델에 대응시키면 다음과 같습니다.

• Stage 1 (Discoverability): 대체로 완료. robots.txt, sitemap, Link 헤더가 모두 통과합니다. 한 가지 의미 있는 공백이 남는데, AI 에이전트를 위한 기계 판독용 사이트 색인인 llms.txt입니다. 이는 isitagentready.com이 아니라 Fern Agent Score의 점검 항목으로, 다음 절에서 다룹니다.
• Stage 2 (Governance): 완료. Markdown 제공, Content Signals, AI 봇 규칙이 모두 통과합니다.
• Stage 3 (Controlled Interaction): 관련 없음. API Catalog, MCP Server Card, OAuth Discovery는 문서 위주의 콘텐츠 웹사이트에는 불필요한 항목들입니다.

두 번째 스캐너: Fern Agent Score

두 번째 도구인 Fern Agent Score는 조금 다른 계층을 측정합니다. 사이트가 AI 에이전트를 위해 모든 페이지를 나열한 색인 파일 하나를 제공하는지, 그리고 그 페이지들을 깨끗한 텍스트 버전으로 제공하는지입니다.

이 도구는 처음에 DoveRunner Docs에 100점 만점에 0점을 매겼습니다. 점수만 보면 충격적이지만 원인은 단순했습니다. 에이전트를 위한 색인 파일이 사이트에 없었던 것입니다. 색인이 없으니 스캐너는 살펴볼 페이지를 단 하나밖에 찾지 못했고, 그 결과 거의 모든 항목이 빈칸으로 돌아오면서 점수가 0점까지 떨어졌습니다. 에이전트에게 깨끗한 콘텐츠를 제공하는 실제 기반은 이미 마련되어 있었습니다(앞의 개선 2번이 그 작업입니다). 단지 그 기반이 존재한다는 사실을 에이전트에게 알려 주는 색인을 한 번도 게시하지 않았을 뿐입니다.

파일 하나, 그리고 하나의 선택

DoveRunner Docs 와 같은 정적 문서 사이트에 이 색인 파일을 추가하는 일반적인 방법은 이미 만들어진 플러그인을 쓰는 것입니다. 이를 시도해 봤지만 결국 제거했습니다. 다섯 가지 기능이 묶여 있었으나 우리에게 필요한 것은 하나뿐이었고, 이미 쓰고 있던 도구와 버전 충돌까지 일으켰기 때문입니다. 대신 코드베이스에 이미 있던 패턴을 본떠 작은 코드 한 조각을 직접 작성했습니다. 이 코드는 사이트를 빌드할 때마다 색인을 자동으로 다시 생성하기 때문에, 추가 의존성이 없고 색인이 페이지와 어긋날 일도 없습니다.

기능 다섯 개가 묶인 플러그인은, 그중 하나만 필요하고 나머지 넷은 이미 갖추고 있을 때 좋지 않은 선택입니다.

0점에서 99점으로

색인을 게시하자 점수는 곧바로 0점에서 91점으로 뛰었습니다. 마지막 몇 점은 사이트를 실제로 배포한 뒤에야 드러난 두 가지 버그에서 나왔는데, 둘 다 같은 교훈을 남겼습니다. 에이전트가 점검하는 방식 그대로 점검해야 한다는 것입니다.

• 첫 번째는 에이전트용 안내 표시를 스캐너가 읽지 않는 영역에 둔 것이 문제였습니다. 스캐너가 실제로 들여다보는 위치로 옮기자 해결되었습니다.
• 두 번째는 더 미묘했습니다. 우리가 직접 한 테스트는 모두 통과했는데, 끝에 슬래시가 붙은 주소로 점검했기 때문입니다. 스캐너는 슬래시 없는 주소로 점검했고, 그런 주소에서는 서버가 조용히 잘못된 형식을 반환하고 있었습니다. 스캐너가 보낸 요청을 그대로 재현하자 버그는 몇 초 만에 드러났습니다.

최종 Fern Agent Score는 100점 만점에 99점입니다. 남은 1점은 인프라가 아니라 콘텐츠 문제로, 분할이 필요한 지나치게 큰 페이지 몇 개 때문이며 이 부분은 의도적으로 그대로 두었습니다. 이 작업 전체에 든 비용은 새 코드 한 조각, 작은 템플릿 수정 한 건, 설정 몇 줄, 그리고 추가 의존성 0개였습니다.

어떤 점검 결과가 직접 해 본 테스트와 어긋난다면, 그 도구가 틀렸다고 단정하기 전에 도구가 하는 동작을 그대로 재현해 보시기 바랍니다.

마치며

이제 두 스캐너 모두 대응을 마쳤습니다. 첫 번째는 86점, 두 번째는 99점입니다. 여기까지가 인프라 계층, 즉 에이전트가 문서를 발견하고 소비할 수 있는지에 대한 영역입니다. 다만 이 점수들은 더 어려운 질문, 즉 에이전트가 그 문서로부터 올바른 연동 코드를 만들어 낼 수 있는지에 대해서는 아무것도 말해 주지 않습니다.

마지막 다섯 번째 파트에서는 이 콘텐츠 계층의 문제를 찾아내고 해결한 과정을 다루겠습니다.

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