AI 에이전트 문서 콘텐츠 점검과 수정: 점수가 매겨지지 않는 계층

앞선 4편에서는 DoveRunner Docs의 인프라 계층을 개선했습니다. 응답 헤더를 추가하고, 에이전트가 요청하면 Markdown 형식으로도 문서를 내려주도록 바꾸고, robots.txt에 Content Signals를 선언했습니다. Is Your Site Agent-Ready? 사이트의 점수는 43점에서 86점으로, Fern Agent Score 사이트에서는 0점에서 99점으로 올라갔습니다.

작업하는 내내 문서 본문은 한 글자도 건드리지 않았습니다.

이것이 ‘에이전트 준비도(Agent Readiness)’를 두 계층으로 나누어 보는 이유입니다. 인프라 계층은 점검 도구가 통과와 실패로 판정해 주고, 무엇을 고쳐야 하는지도 도구가 알려 줍니다. 반면 콘텐츠 계층에는 그런 도구가 없습니다. 에이전트가 문서를 잘 읽어 갈 수 있다는 사실과, 그 문서를 읽고 올바른 연동 코드를 만들어 낸다는 사실은 전혀 다른 문제이기 때문입니다.

이 글에서는 DoveRunner 문서의 콘텐츠 계층에서 실제로 무엇이 잘못되어 있었는지를 AI 에이전트와 함께 찾아내고 고쳐서 프로덕션까지 반영한 과정과, 그 결과가 남긴 한계에 대해 알아보겠습니다. 이 작업을 우리는 AI 에이전트 문서 콘텐츠 점검이라고 부릅니다.

전체 작업은 여섯 단계로 진행되었습니다. 어디까지가 에이전트의 몫이고 어디부터가 사람의 몫이었는지가 이 글의 핵심이므로 순서부터 정리해 두겠습니다.

1. 에이전트가 연동 워크플로 단위로 문서의 Markdown 원본을 훑습니다.

2. 발견한 문제를 유형, 설명, 원본 위치와 함께 목록으로 정리합니다.

3. 에이전트가 고칠 수 있는 것을 고쳐 원본 파일에 반영하고, 목록에는 처리 결과를 남깁니다.

4. 제품군별로 PR을 나누어 올립니다.

5. 각 제품 담당 PO가 자기 제품의 문서 변경을 검토하고 확인합니다.

6. 프로덕션에 배포합니다.

문서 점검을 페이지 단위로 하면 페이지 단위의 문제만 나옵니다. 오타, 끊어진 링크, 빠진 파라미터 설명 같은 것들입니다. 이런 문제도 물론 고쳐야 하지만 에이전트가 연동 코드를 잘못 만들어 내는 원인은 대개 다른 곳에 있습니다.

그래서 이번에는 제품군 별로 고객 입장에서 정리한 엔드투엔드 연동 시나리오를 기준으로 삼았습니다. 개발자가 실제로 밟아 나가는 하나의 여정, 예를 들어 FairPlay 인증서를 발급받는 시점부터 패키징을 거쳐 iOS 플레이어에서 재생이 확인되는 시점까지를 하나의 단위로 놓고, 그 여정에 걸리는 문서들을 함께 읽도록 했습니다.

이렇게 보면 단일 페이지만 볼 때는 보이지 않던 문제가 드러납니다. 각 페이지는 저마다 정확한데 페이지와 페이지 사이에서 정보가 끊기는 경우입니다. 앞 문서가 넘겨준 값의 형식과 뒤 문서가 기대하는 형식이 어긋나 있거나, 반드시 먼저 처리해야 하는 선행 조건이 정작 그 조건이 필요한 문서가 아니라 다른 제품 문서의 중간에 묻혀 있는 식입니다.

이번 점검에서 나온 가장 위험한 사례도 이 유형이었습니다. 포렌식 워터마킹을 Transcoding & Packaging(이하 T&P)과 함께 사용하는 여정에서, T&P는 워터마킹된 결과물을 정해진 폴더 구조에 만들어 둡니다. 시청자가 재생을 시작할 때 서버는 이 결과물의 위치를 알아야 하며, 재생 세션을 발급하는 API에 prefix_folder 파라미터로 그 값을 넘겨 주게 되어 있습니다. 세션 발급 API 문서에는 이 파라미터가 정확하게 설명되어 있었습니다. 문제는 T&P 쪽 문서였습니다. 결과물이 어떤 폴더 구조로 만들어지는지 그리고 그 값을 다음 단계에서 넘겨야 한다는 사실이 적혀 있지 않았습니다.

두 문서 모두 그 자체로는 틀린 곳이 없습니다. 다만 T&P 문서만 읽고 다음 단계로 넘어가는 개발자나 에이전트는 넘겨야 할 값이 있다는 것 자체를 알 수 없었습니다. 이런 종류의 누락은 오류 메시지로 드러나지 않고 재생이 되지 않는 결과로만 나타나기 때문에 원인을 찾는 데 시간이 오래 걸립니다. 조치는 T&P 문서에 폴더 구조와 파라미터 요구 사항을 주의 블록으로 추가하고 세션 발급 API 문서로 상호 링크를 거는 것이었습니다. 작업 자체는 몇 분이면 끝나지만, 두 문서를 한 여정으로 이어서 읽기 전에는 존재 자체가 보이지 않던 문제입니다.

이 단계에서 6개 제품군에 걸쳐 71건의 콘텐츠 이슈가 나왔습니다. 각 항목은 유형(오류 / 누락 / 위치 문제), 설명, 그리고 해당 원본 파일과 줄 번호까지 함께 기록되었습니다. 이 목록이 이후 모든 작업의 기준선이 되었습니다.

목록이 만들어진 다음에는 에이전트가 손댈 수 있는 항목부터 수정하도록 했습니다. 문서가 이미 Markdown으로 관리되고 있기 때문에 에이전트가 원본 파일을 직접 고치는 데에는 형식 변환 같은 중간 단계가 필요하지 않았습니다. 수정을 마칠 때마다 에이전트는 처음 만든 목록의 비고란에 무엇을 확인했고 어떻게 처리했는지를 남겼습니다. 결과적으로 이슈 목록 자체가 작업 기록이 되었습니다.

여기서 한 가지 선택을 했습니다. 71건의 수정 사항을 하나의 PR로 묶지 않고, 제품군에 따라 세 개의 PR(Pull Request)로 나눈 것입니다.

• Multi-DRM

• Watermarking / Anti-Piracy

• Mobile App Security

그리고 각 PR에 해당 제품의 PO(Product Owner)를 리뷰어로 지정했습니다. 이렇게 나눈 이유는 검토의 품질 때문입니다. 문서 수정의 사실 여부를 판단할 수 있는 사람은 그 제품을 아는 사람뿐입니다. 71건이 뒤섞인 PR을 받은 PO는 자기 제품과 무관한 변경까지 함께 훑어야 하고, 그런 상황에서는 검토가 형식적으로 흐르기 쉽습니다. 반면 자기 제품의 변경만 담긴 PR이라면 한 줄씩 확인할 수 있는 분량이 됩니다.

세 PO 모두 자기 제품의 문서가 의도대로 수정되었음을 확인했고, 그 에 프로덕션으로 배포했습니다.

비율로는 83%입니다. 다만 이 작업에서 더 많은 것을 알려 준 숫자는 남은 9건 쪽이었습니다. 막힌 9건에 공통점이 있었기 때문입니다. 전부 답이 문서 안에 없는 문제였습니다.

에이전트는 문서 내용 전체를 읽을 수 있습니다. 그래서 문서 안에 답이 흩어져 있는 문제, 즉 다른 페이지에는 설명되어 있는데 정작 필요한 자리에 없는 정보나, 앞뒤 문서가 서로 다른 형식을 전제하고 있는 불일치는 잘 찾아내고 잘 메웁니다. 41건이 이런 방식으로 수정되었고, 13건은 중간에 이미 해결된 것으로 확인되었습니다.

하지만 문서 어디에도 존재하지 않는 사실은 에이전트가 만들어 낼 수 없습니다. 남은 9건을 담당 조직별로 묶어 보면 성격이 분명하게 드러납니다.

• 제품 팀 확인 필요: 자동화 연동에 필요한 API의 권장 동작과 일부 응답 규격이 문서화되어 있지 않습니다. 9건 중 절반 가까이가 여기에 몰려 있습니다.

• 플랫폼/사업 조직 확인 필요: 콘솔 화면의 표기, 특정 상품 유형의 지원 범위, 계약과 법무가 얽힌 절차처럼 제품과 사업 쪽의 확인이 있어야 문서로 옮길 수 있는 항목입니다.

이 가운데 어느 것도 글을 잘 써서 해결되는 문제가 아닙니다. 권장 폴링 주기를 문서에 쓰려면 먼저 담당 팀이 그 주기를 정해야 하고, 토큰 만료 시간을 쓰려면 그 값이 계약된 동작인지 확인되어야 합니다. 문서화 이전에 결정이 필요한 사안이며, DevRel(Developer Relations) 팀이 단독으로 해결할 수 있는 항목이 아닙니다.

이 구분이 이번 작업에서 얻은 가장 실용적인 결과였습니다. 71건은 처음에 모두 같은 무게의 ‘문서 이슈’로 보였습니다. 그러나 전수 검토를 마치고 나니 그중 62건은 문서를 고치는 것만으로 해결되는 항목이었고, 9건은 애초에 문서 문제가 아니라 전체 조직의 미결정 사항이 문서에 나타난 것이었습니다.

이번 작업의 여섯 단계를 다시 보면, 에이전트가 실제로 담당한 것은 1번부터 3번까지입니다.

문서 검토, 목록화, 수정이라는 세 구간은 성격이 같습니다. 양이 많고, 판단 기준이 비교적 명확하며, 결과를 사람이 나중에 검증할 수 있습니다. 6개 제품군의 문서를 연동 여정 단위로 교차 확인하는 일은 사람이 하기에는 지루하고 빠뜨리기 쉬운 작업인 반면, 에이전트에게는 잘 맞습니다.

4번부터 6번까지는 사람의 몫으로 남았습니다. PR을 어떻게 쪼갤지, 누구에게 검토를 맡길지, 무엇을 배포할지는 조직의 맥락에 대한 판단입니다. 특히 5번의 PO 검토는 대체할 방법이 마땅치 않습니다. 에이전트가 수정한 71건 가운데 사실관계가 틀린 것이 있는지를 판별하려면 제품을 실제로 아는 사람이 읽어야 하기 때문입니다.

문서 개선에 AI를 도입할 때 기대 수준을 어디에 둘지는 이 경계를 기준으로 잡으면 될 것 같습니다.

이상으로 AI 에이전트 문서 콘텐츠 점검을 통해 DoveRunner 문서의 콘텐츠 계층을 점검하고 수정한 과정에 대해 알아보았습니다.

다섯 편에 걸쳐 정리한 내용을 한 줄로 줄이면, 에이전트 준비도는 점수가 아니라 두 종류의 서로 다른 작업이라는 것입니다. 인프라 계층은 도구가 문제를 알려 주고 AI 에이전트가 쉽게 해결할 수 있습니다. 콘텐츠 계층은 알려 주는 도구가 없어서 실제 연동 여정을 기준으로 직접 만들어야 하고, 그렇게 만든 목록의 마지막 10% 남짓은 사람이 직접 해결해야 합니다.

DoveRunner 문서를 연동 작업에 활용하고 계시다면, 이번에 반영된 내용은 DoveRunner Docs에서 바로 확인하실 수 있습니다. 문서에서 막히는 지점이 있다면 알려 주시기 바랍니다. 이번 작업에서 확인했듯이, 가장 찾기 어려운 문제는 실제로 그 여정을 걸어 본 사람에게서 나옵니다.

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