개발자들이 실제로 유지 관리하는 문서를 위한 AI

2026년 당신의 개발자 문서(developer documentation)로 유입되는 트래픽의 약 45%는 사람이 아닙니다.

이것은 비유가 아닙니다. 수천 개의 엔지니어링 팀의 문서를 호스팅하는 Mintlify가 2026년 3월에 발표한 트래픽 연구에 따르면, AI 코딩 에이전트(Claude Code, Cursor, OpenCode, ChatGPT 및 기타 도구들)가 현재 호스팅된 문서 사이트로 들어오는 모든 요청의 **45.3%**를 차지하고 있습니다. 사람이 직접 브라우징하는 비율은 45.8%입니다. 이 에이전트들 중 Claude Code와 Cursor 두 가지가 전체 봇 트래픽의 **95.6%**를 차지합니다.

따라서 당신의 문서가 틀렸을 때, 당신은 단순히 신입 사원을 오도하는 것에 그치지 않습니다. 당신은 팀의 나머지 구성원들이 기능을 출시하기 위해 사용하는 도구에 잘못된 답변을 공급하고 있는 것입니다. 이 비대칭성은 잔혹합니다. 단 하나의 오래된 POST /v1/orders 페이지가 누군가 알아차리기 전에 수천 개의 Cursor 자동 완성(autocompletions)으로 흘러 들어갈 수 있습니다.

이로 인해 오래된 문서화(documentation) 문제는 갑자기 매우 중요한 하중을 견뎌야 하는 문제가 되었습니다.

그리고 오래된 문서화 문제는 문서를 작성하는 것이 아닙니다. AI는 작성을 해결했습니다. Claude에게 세 개의 불렛 포인트(bullet points)를 구술하면 12초 만에 세련된 위키(wiki) 항목을 얻을 수 있습니다. 어려운 부분, 즉 아직 아무도 실제로 해결하지 못한 부분은 문서가 작성된 다음 날, 다음 주, 다음 분기에도 **문서의 정확성을 유지하는 것(keeping the docs true)**입니다.

이 글은 그것을 위해 무엇이 필요한지에 관한 것입니다. 구체적으로는: 변화하는 코드베이스(codebase)와 접촉하면서도 살아남을 수 있는 위키, API 레퍼런스(API references), 그리고 아키텍처 결정 기록(architecture decision records)을 생성하는 방식으로 AI를 사용하는 방법에 대해 다룹니다. 핵심적인 요령은 여기서 AI의 가장 유용한 역할이 *생성(generation)*이 아니라 *검증(verification)*이라는 점입니다. 일단 이를 받아들이면, 세 가지 워크플로우(workflows)가 자연스럽게 도출됩니다.

생성(Generation)이 해결하지 못하는 유지 관리 문제

문제를 해결하기 전에 그 버그의 이름을 먼저 정의해 봅시다.

문서화 (Documentation)가 부패하는 이유는 일반적인 개발 루프 (development loop) 내에서 코드가 변경될 때 문서가 그에 맞춰 정렬되도록 강제하는 장치가 없기 때문입니다. 리팩터링 (refactor)을 머지 (merge)합니다. 테스트는 통과합니다. CI는 초록불입니다. 해당 서브시스템 (subsystem)에 관한 위키 (wiki) 페이지는요? 아무도 그것을 알리지 않았습니다. 아무도 그것이 존재하는지 모릅니다. 이제 문서는 미묘하고도 값비싼 오류를 품게 되었으며, 6주 후에 누군가 버그를 발견하고 찾아보기 전까지는 계속 틀린 상태로 남아있을 것입니다.

Stripe의 Developer Coefficient 연구에 따르면, 개발자들은 약 41시간의 주당 근무 시간 중 미래를 구축하는 대신 과거를 수정하는 데(디버깅, 리팩터링, 기술 부채 (technical debt) 처리 등) 평균 주당 17.3시간을 소비하는 것으로 나타났습니다. 이는 주간 업무 시간의 약 42%를 뒤로 돌아가는 데 사용하고 있다는 의미입니다. 그중 상당 부분은 "문서를 믿었는데 문서가 틀렸고, 잘못된 가정으로 2시간을 허비한 뒤에야 문서를 다시 작성했다"는 내용입니다. 이는 모두가 지불하고 있지만 아무도 항목별로 기록하지 않는 세금과 같습니다.

근본 원인은 동기 부여의 문제가 아니라 구조적인 문제입니다. 개발자들이 문서를 피하는 것은 게을러서가 아닙니다. 시스템이 그들에게 문서를 작성하도록 만들지 않기 때문입니다. 세 가지 실패 모드 (failure modes)가 반복해서 나타납니다:

1. 소유권 (Ownership) 부재. 코드에는 CODEOWNERS 파일이 있습니다. 문서는 그렇지 않습니다. 인증 (auth) 팀이 플래그 (flag) 이름을 변경할 때, 이전 이름을 언급하는 문서에 아무도 알림을 보내지 않습니다. 어떤 스크립트도 그 문서가 존재하는지 모르기 때문입니다.
2. 검증 (Verification) 부재. 코드가 틀리면 테스트가 실패합니다. 문서가 틀려도 실패하는 것은 아무것도 없습니다. 괴리 (Drift)는 사람이 알아차리기 전까지는 보이지 않습니다.
3. 업데이트 프롬프트 (Update prompt) 부재. PR 템플릿 (PR template)은 테스트를 업데이트했는지 묻습니다. 하지만 위키를 업데이트했는지는 거의 묻지 않습니다. 설령 묻는다 하더라도, 개발자들은 반사적으로 "예"라고 답하고 넘어가 버립니다.

Confluence에 AI가 생성한 무한한 산문을 쏟아부어도 이 문제 중 단 하나도 해결할 수 없습니다. 문서는 여전히 부패할 것입니다. 오히려 부패할 표면적이 더 넓어졌기 때문에 더 빠르게 부패할 뿐입니다.

이것이 바로

다시 말해, AI는 사진 같은 기억력을 가졌지만 판단력은 전혀 없는 주니어 기술 작가(tech writer)와 같습니다. 이를 시니어 리뷰어(senior reviewer) 및 검증 하네스(verification harness)와 결합하면 혁신적인 도구가 됩니다. 하지만 Confluence 쓰기 권한(write key)과 친절한 프롬프트만 주고 이를 방치한다면, 잘못된 정보(wrongness)를 생산하는 과정을 자동화하는 꼴이 됩니다.

아래의 세 가지 워크플로우(workflow)는 모두 이 아이디어의 변형입니다.

위키 업데이트: PR에 결합하기

위키(wiki) 관리 실패는 가장 흔하게 발생하는 문제이며, 동시에 해결하기도 가장 쉽습니다.

효과적인 패턴은 다음과 같습니다: 모든 PR(pull request)은 반드시 위키 델타(wiki delta)를 생성해야 하며, AI는 코드 차이점(diff)을 바탕으로 해당 델타의 초안을 작성합니다. 위키 전체가 아니라, 변경된 부분만 작성하는 것입니다. 인간 리뷰어는 이를 승인, 수정 또는 거부합니다. 리뷰어는 이미 코드를 리뷰하고 있는 바로 그 사람입니다. 위키 업데이트는 동일한 PR 내에 존재하며, 동일한 머지(merge) 조건에 의해 제어됩니다.

이는 앞서 언급한 세 가지 실패 모드(failure modes)를 모두 해결합니다:

• 소유권 (Ownership): PR 작성자는 코드 변경 사항을 소유하는 것과 동일한 방식으로 위키 델타를 소유합니다.
• 검증 (Verification): 리뷰어는 코드와 문서를 나란히 놓고 확인합니다. 누군가 알아차리지 못하고 문서 드리프트(drift)가 배포되는 것은 불가능합니다.
• 업데이트 프롬프트 (Update prompt): 이는 PR 템플릿에 적힌 정중한 요청 사항이 아니라, 필수 입력 필드입니다. 빈칸으로 두면 머지할 수 없습니다.

실제로 이는 모든 PR에 대해 실행되는 CI 단계(step)와 같은 모습입니다:

.github/workflows/wiki-delta.yml

name: Wiki Delta
on: [pull_request]
jobs:
...

(여기서 wiki-delta-bot은 대역입니다. 사용 중인 내부 도구, Mintlify의 PR 프리뷰, 또는 diff와 관련 위키 페이지를 컨텍스트로 사용하는 커스텀 Claude 호출 등으로 대체하십시오.)

중요한 세부 사항은 도구가 아닙니다. 핵심은 AI가 두 가지 입력값(inputs)을 모두 받는다는 점입니다. 바로 diff(차이점)와 기존 위키 페이지입니다. AI는 이 두 가지를 일치시키는 가장 작은 변경 사항을 작성합니다. 전체를 다시 쓰는 것이 아닙니다. 새로운 페이지를 만드는 것도 아닙니다. 바로 델타(delta, 차이)입니다. 리뷰어는 300개의 재생성된 라인이 아니라, 변경된 30개의 라인을 읽게 됩니다. 이것이 지속 가능한 프로세스와 한 스프린트(sprint) 만에 비활성화되는 프로세스를 가르는 차이입니다.

Tip
에이전트(agent) 트래픽이 가장 많은 위키 페이지부터 시작하십시오. Mintlify 스타일의 분석(analytics) 기능을 사용할 수 있다면, AI 에이전트 읽기 횟수를 기준으로 내림차순 정렬하십시오. 해당 페이지들이 최신 상태가 아닐 경우, 가장 많은 후속 도구들을 오도하게 될 것입니다.

PR(Pull Request) 요구 사항으로서 "문서가 업데이트되었는가?"라는 관문은 AI가 등장하기 훨씬 전부터 docs-as-code(문서의 코드화)의 논쟁 주제였습니다. 이것이 완전히 자리 잡지 못했던 이유는 마찰(friction) 때문이었습니다. 모든 PR에서 수동으로 문서 업데이트를 작성하는 것은 팀이 몇 번의 스프린트 후에 조용히 해당 관문 적용을 중단할 만큼 충분히 큰 비용(tax)이었습니다. AI는 이 마찰의 계산법을 바꿉니다. 봇이 이미 델타의 80%를 작성해 놓았다면, 아무리 게으른 리뷰어라도 그것을 삭제하는 대신 깔끔하게 다듬을 것입니다.

API 문서: 앵커(Anchor)를 먼저, 산문(Prose)은 나중에

API 문서는 AI 생성(generation)의 성적이 가장 좋지 않은 영역입니다. 모델에게 "이 서비스에 대한 API 문서를 작성해줘"라고 요청하면, POST /orders가 quantity: int 필드를 허용하는 아름다운 페이지를 얻게 될 것입니다. 하지만 그 필드는 당신의 코드에 존재하지 않습니다. 아무도 그것이 어디서 왔는지 찾을 수 없습니다. 그것은 두 달 동안 그 자리에 없었습니다. 이제 세 개의 내부 팀이 그 필드를 전송하는 클라이언트 코드를 작성하고 있습니다.

해결책은 작성 순서를 뒤집는 것입니다: 코드에서 시작하여, 산문으로 끝내십시오.

OpenAPI가 바로 그 지렛대입니다. 현대적인 프레임워크들(FastAPI, Spring Boot, NestJS, Hono, Go의 huma, Laravel의 Scribe)은 실제 라우트 핸들러(route handlers), 데코레이터(decorators), 그리고 타입(types)으로부터 OpenAPI 명세(specification)를 직접 생성할 수 있습니다. 이 명세는 구조적으로 기계적인 진실성을 가집니다. 존재하지 않는 라우트는 나타날 수 없습니다. 핸들러 시그니처(handler signature)에 없는 파라미터(parameter)는 나타날 수 없습니다. 그 형태가 근거를 갖게 됩니다.

그다음 AI가 이 근거(ground truth)를 바탕으로 산문(prose)을 작성하게 하는 것입니다. 엔드포인트(endpoint) 설명, 예시, 에러 설명, "이것을 사용할 때와 저것을 사용할 때의 차이" 등은 모두 모델이 꾸며낼 것이 없는 진정한 글쓰기 작업입니다. 왜냐하면 스키마(schema)가 이미 고정되어 있기 때문입니다. 환각(hallucination)이 발생하는 이유에 대한 Mintlify의 자체 분석도 동일한 결론에 도달합니다: 구조화된 입력(structured input)이 곧 예방책이라는 점입니다.

api/routes/orders.ts

// FastAPI 스타일의 예시이지만, 이 패턴은 프레임워크에 구애받지 않습니다
app.post(
  '/v2/orders',
...

스키마는 닻(anchor) 역할을 합니다. AI가 이후에 작성하는 모든 내용은 스키마에 의해 제한됩니다. 개발자가 새로운 필드(field)를 추가하면 명세가 변경되고, AI가 설명을 다시 작성할 때 새로운 필드를 인지하며 문서도 함께 업데이트됩니다. 개발자가 필드 이름을 변경하면, 이전 이름은 명세에서 사라지며 AI의 산문도 더 이상 해당 이름을 언급하지 않습니다. AI에게는 그럴 권한이 애초에 없었기 때문입니다.

이것이 바로 "코드로부터 문서를 생성하는(generate docs from code)" 도구들이 과거에는 약하게 느껴졌으나 이제는 강력하게 느껴지는 이유이기도 합니다. 도구 자체가 크게 변한 것은 아닙니다. 근거 계층(grounding layer)이 변했습니다. huma와 같은 2025년형 명세 생성기와 그 명세를 읽는 2026년형 모델이 결합되면, 이전 모델이라면 환각을 일으켰을 부분에서도 정확한 결과물을 만들어냅니다.

이 섹션에서의 실수(footgun): AI가 예시 값을 지어내게 두지 마세요. "주문 본문(order body)의 예시를 보여줘"라고 요청하면, 모델은 신용카드 번호, UUID, 고객 이메일 등을 아주 기쁘게 만들어내겠지만, 이 중 그 어느 것도 귀하의 시스템에 존재하는 것과 일치하지 않습니다. 실제 피스처 데이터(fixture data)나 팩토리 출력(factory output)에서 예시를 가져올 수 없다면, 사람 독자와 이 페이지를 소비할 다음 AI가 구분할 수 있도록 명확하게 예시임을 표시하십시오 ("customer_id": "<example-uuid>").

ADR: 기록하는 AI, 결정하는 당신

아키텍처 결정 기록(Architecture Decision Records, ADRs)은 기록률이 가장 낮은 문서 형태입니다.

쓰기 어렵기 때문이 아닙니다. 매우 사소한 작업입니다. 표준 ADR 형식은 컨텍스트(context), 결정(decision), 결과(consequences), 고려된 대안(alternatives considered)이라는 몇 개의 짧은 섹션으로 구성됩니다. 15분이면 작성할 수 있습니다.

ADR이 기록되지 않는 이유는, 기록을 해야 하는 바로 그 순간—결정을 내리는 바로 그 순간—당신은 몰입(flow) 상태이거나, 제품을 출시 중이거나, Slack 통화 중일 것이며, 내면의 목소리가 "나중에 적어둬야지"라고 말하기 때문입니다. 하지만 그 '나중'은 결코 오지 않습니다. 6개월 후에도 그 결정은 여전히 유효하지만, 팀원 중 누구도 왜 그런 결정을 내렸는지 기억하지 못하며, 새로운 엔지니어는 원래의 제약 조건이 문서 어디에도 없기 때문에 그 결정을 되돌리려 할 것입니다.

AI는 정확히 이 간극을 메우는 데 놀라울 정도로 뛰어납니다. 아키텍처를 결정함으로써가 아니라—그것은 트레이드오프(tradeoffs)가 귀하의 비즈니스 및 팀과 연결되어 있으므로 AI가 해서는 안 되며 할 수도 없습니다—결정의 순간에 기록자(scribe) 역할을 수행함으로써 말입니다.