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

AI 코딩 에이전트의 등장은 단순한 기술 트렌드가 아닙니다. Claude Code, Codex, GitHub Copilot 같은 도구를 활용해 AI 에이전트가 문서를 읽고, 통합 코드를 작성하고, Pull Request를 열고, 사람이 각 단계를 직접 검토하지 않는 워크플로우가 이미 일부 팀에서 현실이 되고 있으며, 이는 API 또는 SDK를 제공하는 모든 사업자가 주목해야 할 방향입니다.

이 흐름은 API 제공자에게 하나의 질문으로 귀결됩니다.

우리 문서는 에이전트가 소비할 수 있는 형태로 작성되어 있는가?

이 글에서는 그 질문을 DoveRunner 개발자 문서에 직접 적용한 결과를 소개하겠습니다. DoveRunner는 두 개의 주요 제품군을 운영하는 B2B SaaS 플랫폼으로, 콘텐츠 보안(멀티 DRM, 포렌식 워터마킹, Distributor Watermarking, Anti-Piracy)과 모바일 앱 보안으로 구성됩니다. 두 제품군 모두 개발자용 API 또는 SDK를 제공하며, 이 글에서 다루는 실패 패턴의 영향을 직접 받습니다.

이 시리즈는 DoveRunner 문서와 AI 코딩 에이전트가 필요로 하는 것 사이의 간극을 ‘에이전트 준비도’(Agent Readiness)라는 관점으로 측정하고 개선하는 과정을 기록합니다.

AI 에이전트가 문서를 읽는 방식

기술 문서는 사람을 위해 작성되었습니다. 사람은 문서를 읽으며 맥락을 추론하고, 도메인 지식으로 모호함을 해소하며, 경험으로 빈틈을 채웁니다. “A를 하고 나서 B를 하라”는 지시에서 A의 전제 조건이 다른 문서에 묻혀 있더라도, 사람은 그 문서를 찾아 확인합니다.

에이전트는 다르게 작동합니다. 에이전트는 문서에 명시적으로 기술된 내용을 바탕으로 코드를 생성합니다. 제약 조건이 문서에 없으면 에이전트는 그 제약이 존재하지 않는다고 가정하며, “A 다음에 B”를 수행하기 위해 먼저 C가 필요한데 C가 다른 문서에 있다면 C 없이 B를 생성합니다.

더 심각한 문제는 에이전트가 실패를 조용히 처리한다는 점입니다. 오류 메시지를 마주한 사람 개발자는 누락된 단계를 인식하지만, 에이전트는 오류를 받으면 재시도 로직을 생성하거나, 대안적 접근법을 추론하거나, 겉으로는 올바르게 보이지만 실제로는 잘못된 우회 코드를 자신 있게 작성합니다.

이는 예외 상황이 아니라, 문서가 제약 조건을 암묵적으로 남겨둘 때 나타나는 기본 동작입니다. 이 시리즈의 후속 글에서는 시나리오 기반 테스트를 통해 이 패턴이 DoveRunner 문서에서 어떻게 나타나는지 직접 확인해보겠습니다.

B2B SaaS 문서가 특히 어려운 이유

B2B SaaS API 문서는 일반 소비자용 API 문서와 성격이 다릅니다.

날씨 API나 지도 API처럼 단일 엔드포인트에 몇 가지 파라미터와 응답 스키마로 구성된 소비자용 API는 에이전트가 비교적 잘 처리합니다. 하지만 B2B SaaS는 다른 범주입니다. DRM 통합을 예로 들면, 패키저(영상 암호화·패키징) → CDN(전송) → 플레이어(기기 재생) → 라이선스 서버(재생 인가)로 이어지는 전체 체인을 연결해야 하며, 서로 다른 문서에 분산된 설정값들이 각 단계에서 정확히 맞아떨어져야 합니다.

DRM 유형에 따라 요구하는 암호화 방식도 다릅니다. FairPlay(Apple), Widevine(Google), PlayReady(Microsoft)는 각각 다른 암호화 방식을 사용하는데, FairPlay는 HLS 네이티브 암호화 방식인 CBCS만 지원하며 Widevine과 PlayReady가 사용하는 CENC와는 호환되지 않습니다.

이 제약이 문서에 명시되지 않으면 어떤 일이 벌어지는지 살펴보겠습니다. 에이전트는 패키저 문서를 읽고 encryption_scheme 파라미터가 CENC와 CBCS를 모두 지원한다는 것을 확인한 뒤, Widevine에서 동작하는 것으로 학습된 CENC로 패키징 코드를 생성합니다. 문서에는 경고가 없고 패키징 작업은 성공합니다. 단위 테스트와 CI 파이프라인도 통과됩니다. 스트림이 운영 환경에 배포됩니다.

그런데 iOS 사용자는 스트림을 재생하지 못합니다.

운영팀이 원인을 조사하기 시작합니다. CDN 설정인지, 플레이어 버전인지, 라이선스 서버인지, 패키징 파라미터인지 알 수 없는 일반적인 DRM 복호화 오류입니다. 수 시간의 디버깅 끝에 패키저 설정의 파라미터 값 하나로 귀결됩니다.

제약 조건을 위반해도 겉으로는 올바른 결과물이 생성되는 유형의 장애가 B2B SaaS 연동에서 가장 위험한 패턴입니다. 패키징은 성공하고 테스트도 통과하며, 일부 사용자에게만 운영 환경에서 장애가 드러납니다. 이것이 배포 전에 잡기 어려운 이유입니다.

B2B SaaS는 실제 통합 작업 전에 선행되어야 하는 설정 항목들도 있습니다. 계정 설정, 인증서 등록, 멀티 서비스 의존성이 그것입니다. FairPlay 인증서 등록을 예로 들면, Apple Developer Program 내 계정 소유자(Account Holder) 권한이 필요한데, 이는 일반 개발자 계정에는 없는 특정 권한 등급입니다. 또한 Apple의 처리 기간으로 3~7 영업일이 소요됩니다. 문서가 통합 플로우의 시작 부분에서 이 의존성을 명시하지 않으면, 에이전트는 이 단계 없이 그대로 진행합니다.

마치며

이 글에서 다룬 장애들은 공통적인 구조를 가집니다. 제약 조건이 존재했지만 명시적으로 문서화되지 않았고, 에이전트는 그 제약이 없는 것처럼 코드를 생성했습니다. 이는 문서의 문제로, 측정 가능하고 개선할 수 있습니다.

다음 글에서는 이를 측정하기 위한 프레임워크를 소개합니다. ‘에이전트 준비도'(Agent Readiness)는 두 가지 계층으로 구성되며, 각각을 평가하는 방법론이 다릅니다. DoveRunner 문서에 두 방법론을 모두 적용한 결과를 단계적으로 살펴보겠습니다.

DoveRunner의 ‘에이전트 준비도’ 개선 과정에 관심이 있으시다면 이 시리즈의 후속 글을 통해 자세히 알아보시기 바랍니다.

이 시리즈는 DoveRunner 개발자 문서와 AI 코딩 에이전트가 필요로 하는 것 사이의 간극을 정의하고 해소하기 위한 체계적인 노력을 기록합니다.