더 나은 문서화가 AI 환각(Hallucinations)을 해결하지 못하는 이유

제 친구 중 한 명은 지난주 Stripe Connect 연동 작업을 디버깅하는 데 6시간을 보냈습니다.

그는 Cursor를 사용하고 있었습니다. Claude 3.5 Sonnet을 사용하고 있었습니다. 그리고 세계에서 가장 문서화가 잘 된 API 중 하나를 사용하고 있었습니다.

6시간 동안, 모델은 그의 검증 로직에 X-Stripe-Connect-Signature라는 이름의 웹훅 헤더(webhook header)를 계속 삽입했습니다. 그는 그것을 복사했습니다. 테스트했습니다. 문서를 읽었습니다. 다시 읽었습니다. 모델에게 "공식 문서를 다시 한번 확인해줘"라고 요청하기도 했습니다.

모델은 계속해서 같은 행동을 반복했습니다.

그 헤더는 존재하지 않습니다.

Stripe는 다른 모든 작업에 사용하는 것과 동일한 헤더인 Stripe-Signature를 사용하여 Connect 웹훅을 검증합니다. "Connect" 버전은 모델이 미세 조정(fine-tuning) 과정 중 어느 시점에 조용히 만들어낸 것이었으며, 이제 그의 스택에 있는 모든 에이전트(agent)가 요청이 있을 때마다 자신 있게 그것을 재현하고 있었습니다.

그는 주니어 엔지니어가 아닙니다. 이미 6개의 스타트업을 출시한 경험이 있습니다. 그는 단지 AI 코딩 어시스턴트를 사용하는 거의 모든 팀이 지금 저지르고 있는 것과 똑같은 실수를 저질렀습니다. 바로 문서화가 문제라고 가정한 것입니다.

문제가 아니었습니다. 거의 대부분의 경우 그렇지 않습니다.

모두가 틀리는 진단

지금 당장 어떤 AI 엔지니어링 Slack 채널에 들어가더라도 똑같은 대화가 반복되는 것을 들을 수 있을 것입니다.

"우리 에이전트들이 우리 API를 계속 환각(hallucinating)하고 있어. 문서를 개선해야 해."

그래서 팀들은 문서를 개선합니다. 엔드포인트(endpoints)를 다시 작성합니다. 코드 샘플을 추가합니다. 더 나은 Markdown을 제작합니다. 더 화려한 문서 프레임워크로 마이그레이션합니다. Notion을 발행합니다. OpenAPI를 발행합니다. llms.txt를 발행합니다.

하지만 환각은 계속 발생합니다.

왜냐하면 진단이 틀렸기 때문입니다.

환각이 일어나는 API는 글쓰기의 문제가 아닙니다. 어조(tone)의 문제도 아닙니다. 심지어 "문서가 불완전하다"는 문제도 아닙니다.

그것은 구조적인 문제입니다. 웹상에서 문서가 형성되는 방식은 모델이 실제로 읽는 방식과 근본적으로 상충됩니다.

실제 운영 환경에서 환각(Hallucination)이 나타나는 방식

다음에 실제 제품의 문서를 대상으로 AI 코딩 어시스턴트(AI coding assistant)를 사용할 때 네트워크 탭(network tab)을 열어보세요.

다음 세 가지 중 하나를 보게 될 것입니다:

에이전트(agent)가 문서 루트를 크롤링(crawl)하여 렌더링된 HTML의 처음 12KB만 가져온 뒤 작업을 끝내버립니다.
에이전트가 벡터 인덱스(vector index)에서 3~4개의 청크(chunk)를 검색합니다. 대개 잘못된 청크일 것입니다. 왜냐하면 임베딩 모델(embedding model)은 당신의 "인증(Authentication)" 페이지가 헤더 동작에 대한 표준 소스(canonical source)라는 사실을 전혀 모르기 때문입니다.
에이전트가 아무것도 가져오지 못합니다. 문서는 JavaScript 싱글 페이지 애플리케이션(SPA)이며, 크롤러(crawler)가 로딩 스피너(loading spinner) 너머를 보지 못했기 때문입니다.

모든 경우에서, 모델은 _"이 웹훅(webhook)을 검증하려면 어떤 헤더를 사용해야 하나요?"_와 같은 정밀한 스키마 수준(schema-level)의 질문에 답하도록 요구받습니다. 하지만 그 답변을 위해 사용되는 산문(prose)은 페이지를 처음부터 끝까지 읽고 레이아웃, 사이드바(sidebar), 어조(tone)로부터 문맥을 이해할 것으로 기대되는 인간을 위해 작성된 것입니다.

모델은 레이아웃을 이해하지 못합니다. 사이드바를 이해하지 못합니다. 어조를 이해하지 못합니다. 모델이 받는 것은 구조적 신호(structural signal)의 대부분이 제거된, **평탄화된 문단들의 주머니(flattened bag of paragraphs)**일 뿐입니다.

그래서 모델은 빈칸을 채워 넣습니다. 언어 모델(language model)이 항상 하는 일을 수행합니다. 즉, 학습 데이터의 모든 내용이 헤더가 존재하며 특정 방식으로 명명된다고 말하기 때문에, Stripe 헤더처럼 들리는 무언가를 만들어냅니다.

그것이 환각(hallucination)입니다. 그것은 창의성의 실패가 아닙니다. 구조의 실패입니다.

왜 "더 나은 문서"가 실질적인 변화를 만들지 못하는가

신입 엔지니어에게 당신의 API를 호출하는 방법을 가르치고 싶다고 상상해 보세요.

당신은 그들에게 다음을 제공할 것입니다:

✅ OpenAPI 스펙(spec)
✅ Postman 컬렉션(collection)
✅ SDK 소스(source)
✅ 실행 가능한 예제(runnable example)

당신이 하지 않을 행동은 다음과 같습니다: "이 400페이지 분량의 마크다운(Markdown)을 읽고 어떤 것이 표준인지 추론해 보세요."

두 번째 옵션이 바로 우리가 오늘날 AI 에이전트(AI agents)에게 하고 있는 일입니다.

우리가 "문서화를 개선하자"라고 말할 때, 보통 다음과 같은 의미로 사용합니다: 더 나은 산문을 작성하자. 더 명확한 도입부를 추가하자. 경고 문구를 위로 올리자. 코드 샘플을 하나 더 추가하자.

이 중 그 어느 것도 모델에게는 도움이 되지 않습니다. 모델은 이미 당신의 산문을 가지고 있었습니다. 모델은 당신의 산문을 가지고 있는 도중에 존재하지 않는 헤더를 생성해 버린 것입니다.

모델에게 부족한 것은 에이전트(agent)가 인덱싱(indexing)하고, 버전 관리(versioning)하며, 정밀하게 호출할 수 있는 구조입니다:

엔드포인트(endpoints)에 대한 HTML 페이지가 아닌, 정형화된 엔드포인트 목록
파라미터(parameter)에 대한 설명 문단이 아닌, 정형화된 파라미터 이름과 그 타입(types)의 목록
"위 섹션을 참조하세요"가 아닌, 정형화된 헤더, 코드 및 제약 조건(constraints)의 목록
에이전트가 6분 전에 크롤링(crawled)한 HTML에 갇혀 있는 대신, *"이 엔드포인트의 최신 버전은 무엇인가요?"*라고 물을 수 있는 방법

이것은 글쓰기 연습이 아닙니다. 이것은 인프라(infrastructure) 구축 연습입니다.

Markdown은 인간을 위해 만들어졌습니다. 에이전트에게는 다른 것이 필요합니다.

문제의 솔직한 버전은 이렇습니다. 우리는 인내심과 Ctrl-F 검색창, 그리고 좋은 판단력을 가진 인간 독자를 위해 문서화 웹 전체를 구축했습니다.

에이전트는 그 중 어느 것에도 해당하지 않습니다.

에이전트는 인간 독자보다는 프로그래밍 가능한 API 소비자(consumer)에 더 가깝습니다. 에이전트에게는 다음과 같은 것이 필요합니다:

필요 사항	의미
타입이 지정된 인터페이스 (A typed surface)	"어떤 엔드포인트가 존재하나요? 이것은 무엇을 반환하나요?"
...

이 중 그 어느 것도 Markdown 파일의 속성이 아닙니다. 이것들은 인터페이스(interface)의 속성입니다.

문서가 단순히 산문으로 이루어진 평면적인 덩어리인 척하는 것을 멈추고, 에이전트가 *호출(call)*하는 인터페이스로 취급하기 시작할 때까지, 우리는 자신 있게 지어낸 헤더, 폐기된(deprecated) 엔드포인트, 그리고 채팅에서는 맞게 보이지만 프로덕션(production) 환경에서는 깨져버리는 통합 사례들을 계속 마주하게 될 것입니다.

AI 네이티브 문서화 계층(AI-Native Documentation Layer)의 모습

해결책의 형태는 이미 프로덕션 스택(production stacks)에서 나타나고 있습니다.

그것은 모델 컨텍스트 프로토콜 (Model Context Protocol), 줄여서 MCP라고 불립니다. 이는 AI 에이전트가 다른 도구와 대화하는 방식과 동일한 방식으로 문서화 소스와 대화할 수 있게 해주는 작고 단순한 프로토콜입니다.

MCP 형태의 "문서(docs)"는 다음과 같은 모습입니다:

페이지가 아닌 도구(Tools). 600개의 URL이 있는 사이트를 크롤링하는 대신, 에이전트는 search_docs, get_endpoint, list_versions, get_example을 호출합니다.
스크린샷이 아닌 스키마(Schemas). 각 도구는 타입이 지정된 계약(typed contract)을 가집니다. 에이전트는 요청하기 전에 무엇이 반환될지 미리 알 수 있습니다.
일급 시민으로서의 버전 관리(Versioning). v1, v2, beta — 명시적이고, 쿼리 가능하며, 절대 혼합되지 않습니다.
워크플로우를 인식하는 검색(Retrieval). "Connect 웹훅을 어떻게 검증하나요?"라고 물으면 벡터 검색(vector-search)의 혼돈이 아닌, 정확한 검증 섹션을 반환합니다.
프로토콜의 속성으로서의 최신성(Freshness). 문서 업데이트 → MCP 서버 업데이트 → 에이전트가 변경 사항 확인.

이것이 바로 여러분의 문서와 팀이 사용하는 모든 AI 어시스턴트 사이에 실제로 존재해야 하는 것입니다.

모든 에이전트가 여러분의 문서를 다시 크롤링하고 헤더를 다시 만들어내기를 원해서는 안 됩니다. 여러분이 원하는 것은 에이전트들이 읽어갈 수 있는 **단일한 정전적 컨텍스트 계층(single canonical context layer)**입니다.

새로운 스택 (The New Stack)

AI 엔지니어링 스택이 나아가고 있는 대략적인 형태는 다음과 같습니다:

계층 (Layer)	과거에는	변모 중인 모습
모델 (Models)	제품 (The product)	범용 상품 (A commodity)
...

모든 계층에서 동일한 현상이 일어나고 있습니다: 임시적인 산출물(ad-hoc artifacts)이 구조화된 인터페이스(structured interfaces)로 대체되고 있습니다.

2027년에 승리할 모델은 매개변수(parameters)가 가장 많은 모델이 아닙니다. 그 모델을 사용하는 팀이 모델이 행동할 수 있는 **가장 깨끗하고 구조화된 접점(surface)**을 제공한 모델이 승리할 것입니다.

만약 여러분의 문서가 여전히 평면적인 HTML 페이지의 웹 형태라면, 여러분의 AI 전략에는 구멍이 난 것입니다. 구조적인 문제를 프롬프트(prompt)만으로는 해결할 수 없습니다.

이번 주에 내가 할 일

만약 내가 개발자 도구 팀을 이끈다면, 문서의 재작성 없이 실행할 수 있는 다음과 같은 5단계 계획을 세울 것입니다:

네트워크 탭(network tab)을 여세요. 에이전트가 실시간으로 문서를 읽으려고 시도하는 과정을 지켜보세요. 신호(signal)가 얼마나 희박한지 확인하십시오.
개발자가 귀사의 제품에 대해 AI 어시스턴트에게 묻는 상위 3가지 질문을 선정하세요. Cursor나 Claude에서 실제 문서로 해당 질문들을 테스트해 보세요. 환각(hallucinations)이 발생하는 횟수를 세어보십시오.
그 세 가지 질문은 검색(retrieval)이 아니라 도구(tool)를 통해 답변되어야 한다고 결정하세요. 그 질문들 앞에 MCP 계층을 구축하십시오.
문서를 신뢰할 수 있는 단일 출처(source of truth)로 취급하되, 에이전트가 인간처럼 문서를 읽을 것이라는 기대는 버리세요. 그 위에 구조화된 계층(structured layer)을 생성하십시오.
에이전트의 정확도를 페이지뷰를 측정하는 것과 동일하게 제품 지표(product metric)로 측정하세요. 이제 이것은 개발자가 경쟁사 대신 귀사의 제품을 선택할지 여부를 결정하는 선행 지표입니다.

이 다섯 가지 단계는 문서의 산문(prose)을 단 한 줄도 다시 작성하지 않고도 수행할 수 있습니다.

맺음말

현재 AI 분야에서 가장 과소평가된 트렌드는 다음과 같습니다:

다음 세대의 해자(moat)는 모델이 아닙니다. 모델이 볼 수 있도록 허용된 구조화된 컨텍스트(structured context)입니다.

이를 가장 먼저 깨닫는 기업들은 외부에서 보기에 더 똑똑한 에이전트를 보유한 것처럼 보일 것입니다. 하지만 실제로는 그렇지 않습니다. 그들은 단지 자신들의 문서, API, 그리고 내부 지식을 에이전트가 실제로 사용할 수 있는 인프라로 전환했을 뿐입니다.

만약 여러분이 오늘날 어떤 종류의 에이전트 스택(Cursor, Claude, OpenAI Agents, 내부 코파일럿, 고객 대응 AI 등)을 운영하고 있으며, "LLM을 위해 문서를 개선하기 위해" 수정한 내용을 배포한 적이 있다면, 무엇이 효과가 있었고 무엇이 효과가 없었는지 듣고 싶습니다.

AI 에이전트가 귀사의 제품에 대해 자신 있게 무언가를 지어낸 사례를 하나만 댓글로 남겨주세요. 모든 댓글을 하나하나 읽어보고 싶습니다.

에이전트들도 그것을 읽을 것입니다. 단지 그것이 올바른 형태(shape)여야 할 뿐입니다.