에이전트 준비도: 기계가 실제로 활용하는 문서 만들기

개발자가 프롬프트를 입력합니다. AI 코딩 에이전트가 문서를 읽고, 연동 코드를 생성하고, 풀 리퀘스트(PR)를 엽니다. 이 코드는 팀의 누구도 직접 작성하지 않았고, 더 이상 누구도 우리가 기대한 방식대로 문서를 읽지 않습니다. 이런 흐름은 이미 현실이 되었고, API나 SDK를 제공하는 입장이라면 한 가지 질문을 피하기 어렵습니다. 우리 문서는 사람뿐 아니라 에이전트가 사용할 수 있도록 만들어져 있는가 하는 점입니다.

저는 오랫동안 그 반대편에서 일했기 때문에 이 질문이 더 크게 다가옵니다. DRM과 스트리밍 분야에서 개발자 문서를 쓰고 다듬어 왔는데, 이 영역에서는 잘못된 파라미터 하나가 일부 사용자에게만 재생 오류를 일으키며 조용히 서비스를 망가뜨립니다. 에이전트가 이 문제를 새로 만들어 내는 것은 아닙니다. 다만 그 대가를 훨씬 키울 뿐입니다.

이 글에서는 ‘에이전트 준비도’(Agent Readiness)가 무엇인지, 문서가 에이전트 앞에서 어디서 무너지는지, 그리고 그것을 어떻게 측정할 수 있는지 차례로 알아보겠습니다.

에이전트는 문서를 어떻게 읽는가

기술 문서는 사람을 위해 쓰여 왔고, 사람은 경험으로 빈틈을 메우며 읽습니다. 행간의 의미를 추론하고, A의 전제 조건이 다른 문서에 흩어져 있어도 ’A 다음 B’를 자연스럽게 이해합니다.

에이전트는 문서에 명시적으로 적힌 내용을 기준으로 동작합니다. 어떤 제약이 적혀 있지 않으면 그 제약이 없다고 가정합니다. ’A 다음 B’가 사실은 C를 먼저 끝내야 가능한데 그 C가 다른 페이지에 있다면, 에이전트는 C 없이 B를 생성합니다. 실패를 다루는 방식도 사람과 다릅니다. 사람은 오류를 만나면 빠진 단계를 알아차리지만, 에이전트는 재시도 로직을 만들거나, 다른 방법을 추론하거나, 더 심각하게는 그럴듯해 보이지만 실제로는 틀린 우회책을 자신 있게 만들어 냅니다.

잘못된 파라미터 하나로 충분합니다

제가 가장 자주 마주치는 형태를, 구체적인 세부 사항을 걷어 내고 정리해 보겠습니다. 어떤 연동에서 콘텐츠를 여러 클라이언트 플랫폼에 맞게 준비해야 하는데, 그 플랫폼들이 모두 같은 옵션을 지원하지는 않는다고 해 보겠습니다. 설정 항목 하나가 두 가지 유효한 값을 받는데, 이를 각각 A 모드와 B 모드라고 부르겠습니다. 대부분의 플랫폼은 둘 중 어느 쪽이든 받지만, 한 플랫폼은 B 모드만 지원합니다. 그리고 이 제약은 문서가 아니라 누군가의 머릿속에만 있습니다. 에이전트가 어떻게 움직이는지 보겠습니다. 해당 항목이 두 값을 모두 받는다는 설명을 읽고, 다른 플랫폼에서 동작하는 것을 본 A 모드를 그대로 선택해 배포합니다. 빌드는 성공합니다. 단위 테스트도 통과합니다. CI도 초록불입니다. 그런데 그 한 플랫폼의 사용자만 아무것도 불러오지 못하고, 돌아오는 오류는 스택의 거의 모든 계층이 원인일 수 있을 만큼 일반적입니다.

이런 실패가 위험한 이유가 여기에 있습니다. 모든 검증 단계에서 결과물이 정상으로 보이고, 운영 환경의 일부 사용자에게서만 문제가 드러나기 때문에 출시 전에 잡아내기가 가장 어렵습니다.

조금 더 조용한 형태도 있습니다. 많은 연동은 코드 작성에 앞서 선행 작업을 요구합니다. 계정 발급, 자격 증명 등록, 외부 승인 같은 것들입니다. 그중 일부 자격 증명은 외부 기관이 발급하고, 특정 등급의 계정에서만 받을 수 있으며, 발급까지 며칠이 걸리기도 합니다. 문서가 이 의존성을 연동 흐름의 맨 앞에서 알려 주지 않으면, 에이전트는 그대로 지나쳐 버립니다.

에이전트 준비도의 두 층

그렇다면 문서가 준비되어 있는지 어떻게 측정할 수 있을까요. 저는 에이전트 준비도를 서로 독립적인 두 개의 층으로 나누어 보는 방식이 도움이 된다고 생각합니다.

• 인프라 층(Infrastructure Layer): 에이전트가 문서를 찾고 읽을 수 있는가. 크롤러 접근이 허용되어 있는가, 콘텐츠가 내비게이션에 둘러싸인 HTML이 아니라 Markdown으로 제공되는가, 핵심 페이지를 기계가 읽을 수 있게 정리한 llms.txt 파일이 있는가, MCP 서버 카드가 있는가. (llms.txt는 검색 엔진에게 사이트맵이 하는 역할을 AI에게 하는 파일입니다.) 이 층은 자동화 도구로 점검할 수 있습니다.
• 콘텐츠 층(Content Layer): 에이전트가 읽기 시작한 뒤, 그 내용만으로 올바른 코드를 생성할 수 있는가. 필요한 전제 조건이 그것을 요구하는 단계보다 먼저 제시되어 있는가, 문서 간 의존성이 정작 필요한 지점에서 드러나 있는가, 보안 제약이 위반했을 때의 결과와 함께 경고로 표시되어 있는가. 이 층은 어떤 도구로도 대신할 수 없으며, 실제 연동 과정을 직접 따라가 보아야 합니다.

두 층은 정말로 별개입니다. 인프라 점검을 모두 통과한 사이트에도 암묵적 제약이 가득할 수 있고, 잘 쓰인 사이트라도 인프라가 갖춰져 있지 않으면 에이전트에게는 보이지 않습니다.

인프라 층은 단계적으로 성숙합니다

인프라 쪽은 대체로 단계를 밟아 갖춰지며, 이를 하나의 평면적인 체크리스트가 아니라 서로 다른 단계로 구분해 다루는 편이 좋습니다.

1. 탐색 가능성(Discoverability): llms.txt, sitemap.xml, 그리고 자원 간 관계를 표시하는 Link 헤더. 에이전트가 무엇이든 읽기 전에 사이트에 무엇이 있는지 알려 주는 단계입니다. 이것이 없으면 하나의 URL로 들어온 에이전트는 맹목적으로 사이트를 훑게 됩니다.
2. 거버넌스(Governance): AI를 고려한 robots 규칙, content-signal 선언, Markdown 제공. 에이전트가 콘텐츠를 소비하는 방식을 제어하는 단계입니다. Markdown이 중요한 이유는, HTML만 받는 에이전트가 사이드바와 레이아웃 사이에서 실제 본문을 파내야 하고 그 과정에서 제약을 놓치기 쉽기 때문입니다.
3. 제어된 상호작용(Controlled Interaction): API 카탈로그, MCP 서버 카드, OAuth 메타데이터. 에이전트가 사람의 개입 없이 API에 연결하고 인증을 처리할 수 있게 하는 단계입니다.

1단계는 정적 파일 몇 개로 끝나지만, 3단계는 본격적인 아키텍처 작업입니다. 이 단계들을 뭉뚱그리면 개선에 들일 노력이 잘못 배분됩니다.

콘텐츠 층에서 반복되는 실패

콘텐츠 쪽에서는 같은 유형의 실패가 거듭 나타납니다. 연동 과정을 처음부터 끝까지 따라가 보면, 빈틈은 대체로 다음 몇 가지로 모입니다.

• 문서 간 인계 누락: 한 단계가 다른 문서에서 설정한 값을 필요로 하는데, 어느 문서도 그 의존성을 밝히지 않는 경우.
• 보안에 민감한 조용한 실패: 인코딩이 잘못된 토큰, 암호화 방식이 잘못된 스트림처럼 정상으로 보이지만 런타임에서야 깨지는 결과물.
• 연동 흐름 밖의 전제 조건: 먼저 끝냈어야 할 계정, 인증서, 승인이 별도의 튜토리얼이나 절차 중간의 각주로만 적혀 있는 경우.
• 플랫폼과 환경 제약: 리전, 기기 인증 등급, SDK 호환성 같은 조건이 시작부의 경고가 아니라 절차 중간에 묻혀 있는 경우.
• 오류 처리 안내 부재: 불투명한 오류 응답 뒤에 어떤 실패들이 있는지 정리되어 있지 않아, 에이전트가 원인을 구분하는 대신 한꺼번에 잡는 재시도 코드를 작성하는 경우.

이 가운데 어느 것도 인프라 점검으로는 잡히지 않습니다. 이러한 빈틈은 문서와 문서 사이의 인계 지점에 존재하며, 실제로 대부분의 에이전트 실패가 바로 그곳에서 시작됩니다.

측정하는 두 가지 방법

여기서 서로를 보완하는 두 가지 방법이 나옵니다. 첫 번째는 인프라 스캔입니다. 도구로 사이트의 구조적 준비 상태를 점수화합니다. isitagentready.com은 봇 접근 제어, API 카탈로그, MCP 카드, OAuth 디스커버리를 점검하고, Fern의 Agent Score는 llms.txt 존재 여부와 Markdown 제공 여부를 확인합니다. 다만 한 도구가 모든 층을 다루지는 않으므로, 여러 도구를 함께 돌려 보는 것이 좋습니다. 두 번째는 엔드 투 엔드 시나리오 점검입니다. 고객의 전체 여정을 문서를 따라 그대로 밟아 보며, 각 단계에서 문서가 다음 단계에 필요한 모든 것을 넘겨주는지 확인합니다. 문서를 한 편씩 따로 읽고 그 자체로 충분한지 평가하는 방식으로는 경계의 빈틈을 놓치게 됩니다.

고칠 수 있는 문제입니다

다행인 점은, 이 모든 것이 결국 문서의 문제라는 사실입니다. 문서의 문제라는 것은 측정할 수 있고 고칠 수 있다는 뜻이기도 합니다. 제약은 분명히 존재했지만 적히지 않았고, 에이전트는 그 제약이 없는 것처럼 코드를 만들었습니다. 그 제약을 올바른 위치에 적어 두면, 그 실패는 에이전트에게도, 그동안 조용히 우회책을 만들어 오던 사람에게도 사라집니다.

앞으로 실제 문서를 이 기준으로 점검하며 알게 된 것들을 계속 나누어 보겠습니다.