AI가 참조하는 것은 반년 전의 '거짓 문서'일지도 모릅니다 — 문서 드리프트(Documentation Drift)를 막고 인간과 AI의

AI에게 코드를 작성하게 하는 것이 정말 빨라졌죠.

요건을 대략적으로 전달하면 함수가 만들어지고, 테스트도 생성되며, 리팩터링(Refactoring)도 해줍니다. 1년 전이라면 반나절이 걸렸을 작업이 커피를 내리는 사이에 끝나기도 합니다.

하지만, 딱 하나 뒤처지고 있는 것이 있습니다.

문서(Documentation) 입니다.

코드는 계속 변합니다. 하지만 README는 3개월 전 그대로입니다. 설계 메모는 '최초 버전(version)' 그대로입니다. 주석(Comment)은 이미 존재하지 않는 함수의 사용법을 설명하고 있습니다. 그러다 문득, 자신이 쓴 코드임에도 불구하고 반년 뒤의 자신이 "이거 왜 이렇게 되어 있었지..."라며 멍하니 서 있게 됩니다.

솔직히 말씀드리겠습니다. 이것은 AI로 개발이 빨라지면 빨라질수록 악화됩니다.

게다가 2026년인 지금, 더 까다로운 일이 일어나고 있습니다. 그 어긋난 문서를 이번에는 AI가 읽고, 그럴싸하게 틀린 답을 내놓는 것입니다.

순서대로 따져보면, 이런 부정적인 루프가 돌기 시작합니다.

AI로 코드를 초고속으로 변경
↓
문서가 따라가지 못하고 몰래 어긋남 (=드리프트(Drift))
...

이거, 좀 아깝지 않나요? 어렵게 AI로 빨라졌는데, 문서의 어긋남이 원인이 되어 AI의 발목을 잡고 있습니다.

이 기사에서는 이 부정적인 루프를 끊어내기 위한 사고방식과, 내일부터 업무에서 바로 사용할 수 있는 구체적인 메커니즘을 가능한 한 쉽게 정리해 보겠습니다. 전문 용어는 모두 그 자리에서 풀어서 설명할 테니, "문서가 중요하다는 건 알지만 계속 뒤로 미뤄왔다"는 분일수록 끝까지 읽어주시면 감사하겠습니다.

먼저 용어부터 짚고 넘어가죠. **문서 드리프트 (Documentation Drift)**란, 코드는 변해가는데 문서는 이를 따라가지 못해 양측이 조금씩 계속 어긋나는 현상을 말합니다. "Drift"는 "표류"를 뜻합니다. 자신도 모르는 사이에 서서히 멀어져 가는 느낌이죠.

이미지로 비유하자면, 이사를 했는데 옛날 주소가 적힌 지도를 계속 나눠주고 있는 상태와 비슷할지도 모릅니다. 지도 자체는 깨끗하게 인쇄되어 있습니다. 하지만 그 지도대로 걷다 보면 아무도 없는 빈터에 도착하게 됩니다. 지도가 "거짓"이 된 것입니다. 이것이 드리프트입니다.

여기서 이 기사에 등장할 용어들을 먼저 정리해 두겠습니다. 알고 계신 분은 건너뛰셔도 됩니다.

문서 (Documentation): 코드의 사용법·설계·이유를 설명하는 문장 전반. README도 API 레퍼런스(API Reference)도 주석(Comment)도 포함합니다.

README: 리포지토리(Repository)의 입구에 두는 "먼저 읽어주세요" 설명서.

docstring (독스트링): 함수나 클래스 바로 옆에 쓰는 설명문. """이 함수는 X를 한다"""와 같은 것.

API 레퍼런스 (API Reference): 어떤 함수·엔드포인트(Endpoint)가 있고, 인자(Argument)나 반환값(Return value)이 무엇인지 나열한 사양(Specification) 목록.

ADR: "왜 이 설계로 했는가"를 남기는 결정 기록. 나중에 자세히 설명하겠습니다.

이유는 간단합니다. 코드는 "돌아가면 정의"지만, 문서는 돌아가지 않기 때문에 뒷전으로 밀리기 때문입니다.

테스트가 실패하면 깨닫습니다. 빌드가 깨지면 깨닫습니다. 하지만 문서가 어긋나도 아무런 에러는 발생하지 않습니다. CI(지속적 통합)도 빨간색으로 변하지 않습니다. 아무도 곤란해하지 않는 것처럼 보입니다. 그래서 뒷전으로 밀리고, 조용히 부패해 갑니다.

사람을 탓하는 것이 아닙니다. 인간은 잊어버리는 생물이고, 마감 직전에 "문서도 고치자"라고 매번 완벽하게 할 수 있는 사람은 거의 없습니다. 선의에 의존하는 메커니즘은 언젠가 반드시 무너집니다. 이것은 성격의 문제가 아니라 구조의 문제입니다.

숫자도 조금 살펴봅시다. 다만, 여기서 언급하는 비율은 엄밀한 학술 조사라기보다 업계 블로그나 조사 수치이므로, "대략 이런 느낌이구나" 정도로 받아들여 주세요.

어떤 업계 조사에 따르면, 문서의 약 60%는 반년 만에 낡은 것이 된다고 합니다.

개발자는 코드를 "쓰는" 것보다 "읽고 이해하는" 데 시간의 절반 이상을 사용한다고도 합니다.

GitHub에서는 2025년에 약 9.86억 개의 커밋(Commit)이 있었다고 합니다. 변경이 빠를수록 드리프트도 빠릅니다. 당연한 결과죠.

그리고 여기가 중요한데, 드리프트는 단순히 "기분 나쁜" 문제만이 아닙니다. 실제로 버그를 만들어냅니다.

소프트웨어 공학 연구에서도 코드와 주석의 불일치(inconsistency)가 버그 유입으로 이어진다는 사실이 조사된 바 있습니다. 예를 들어, 논문 「Investigating the Impact of Code Comment Inconsistency on Bug Introducing」(arXiv:2409.10781)에서는 주석의 불일치가 버그 도입에 미치는 영향을 분석했습니다. 나아가 코드 변경 시 "이 주석, 이제 너무 오래된 거 아냐?"라는 의문을 커밋 전에 머신러닝으로 탐지하려는 연구(Deep Just-In-Time Inconsistency Detection, arXiv:2010.01625)나, code-LLM으로 불일치를 탐지 및 수정하는 DocChecker(arXiv:2306.06347) 등 전용 데이터셋(CUP2나 JITDATA)까지 만들어져 오랫동안 다뤄져 온 테마이기도 합니다.

즉, **"문서의 어긋남(drift)은 단순한 태만이 아니라, 품질에 영향을 미치는 기술적 과제"**로서 계속 연구되어 왔다는 뜻입니다.

여기서부터가 이 글에서 가장 전달하고 싶은 핵심입니다.

잠시 멈춰서 생각해 보셨으면 합니다... 지금 당신의 문서를 읽고 있는 것은 인간뿐인가요?

그렇지 않습니다. 2026년 현재, 문서의 독자에는 AI가 추가되었습니다.

Cursor나 GitHub Copilot, Claude Code와 같은 코딩 에이전트가 당신의 코드를 다룰 때, 무엇을 단서로 삼는다고 생각하시나요? 맞습니다. README, 주석, API 레퍼런스, 설계 메모. 이들은 문서를 "문맥(context)"으로서 읽고 있습니다.

게다가 읽는 방식이 인간과는 완전히 다릅니다.

인간은 문서를 위에서부터 순서대로 읽습니다. 하지만 AI는 다릅니다. 관련 있어 보이는 파편(fragment)을 수집하여 자신의 컨텍스트 윈도우(context window, AI가 한 번에 읽을 수 있는 작업대의 넓이)에 끼워 넣어 사용합니다. 따라서 문서가 어떻게 구조화되어 있는지가 AI의 답변 품질을 그대로 좌우합니다. 한 조사에 따르면, 문서 발견 경로의 3분의 1 이상이 이미 AI를 경유하고 있다고도 합니다.

여기서 아까 언급한 부정적인 루프를 다시 한번 살펴보세요.

드리프트(drift)된 문서를 AI가 "올바른 현재의 사양"이라고 믿고 읽습니다. 그러면 AI는 존재하지 않는 함수를 호출하고, 폐기된 인자를 전달하며, 더 이상 사용하지 않는 설계 전제로 코드를 작성합니다. 그리고 그것이 "그럴싸하게 동작하는 것처럼 보이기" 때문에, 리뷰에서 놓치게 되면 조용히 사고로 이어집니다.

그래서 저는 다음과 같이 사고방식을 전환하는 것이 좋다고 생각합니다.

문서는 "인간을 위한 설명문"이 아니라, "인간과 AI가 공유하는 문맥 자산(shared context)"이다.

이 한마디, 사소해 보이지만 꽤 강력합니다. "누군가 읽을지도 모르는 글"이라고 생각하면 뒤로 미루기 쉽지만, "나와 AI가 내일 다시 사용할 작업의 전제"라고 생각하면 다루는 태도가 달라집니다.

이러한 흐름 속에서 2026년에 확산되기 시작한 것이 바로 llms.txt라는 메커니즘입니다.

이것을 아주 간단히 말하자면, **"AI 에이전트를 위한 요점 정리 안내판"**입니다. 웹사이트에 robots.txt(검색 엔진용 안내)가 있는 것처럼, AI를 위해 "우리 문서는 여기 있고, 요점은 이것이다"라는 내용을 AI가 읽기 쉬운 Markdown 형식으로 배치해 두는 발상입니다. B2A(Business-to-Agent, 기업에서 AI 에이전트로)의 첫 번째로 널리 사용되는 규약이라고 불리기도 합니다.

내부 구조는 단순합니다.

# Acme Payments API
> 결제를 생성·조회·환불하기 위한 REST API. 인증은 Bearer 토큰.
## Authentication
...

포인트는 # 제목 → > 1~2문장의 요약 → ## 섹션 → 각 문서로의 링크라는 형태로, AI가 적은 토큰으로 전체상을 파악할 수 있도록 정리하는 것입니다. 마케팅적인 수식어는 배제하고 인증, 엔드포인트, 에러와 같이 통합에 필요한 정보에 집중합니다. 링크 모음으로 가볍게 구성하는 llms.txt와, 전문을 포함하여 자기 완결성을 갖추는 llms-full.txt를 구분해서 사용하는 방식도 있습니다.

다만, 이 점은 솔직하게 말씀드려 놓겠습니다. llms.txt는 W3C나 IETF와 같은 표준화 기구가 승인한 "공식 규격"이 아닙니다. 어디까지나 커뮤니티에서 시작된 관습이며, 2026년 시점에서도 중앙의 공식 리소스가 존재하는 것은 아닙니다. 따라서 "이것을 두면 영원히 안심할 수 있다"가 아니라, "AI를 위해 문맥(Context)을 정리한다"라는 사고방식 그 자체를 가져가는 것이 정답이라고 생각합니다.

보충: 리포지토리 루트에 배치

AGENTS.md (코딩 에이전트를 위한 "이 리포지토리 활용법") 역시 같은 "AI에게 전달할 문맥"의 일종입니다. 다만 그것은 리포지토리에 상주하는 "지시서"입니다. 이 글에서 다루는 것은 README, 레퍼런스(Reference), ADR(Architecture Decision Record)을 포함하여, 문서 전반이 부패하지 않도록 유지하는 운영에 관한 이야기입니다. 레이어가 조금 다르다고 이해해 주시면 좋겠습니다.

그렇다면 어떻게 드리프트(Drift)를 막을 수 있을까요? 출발점이 되는 사고방식이 바로 Docs as Code (문서의 코드화) 입니다.

이름 그대로, 문서를 소스 코드와 동일한 방식으로 다룬다는 방침을 말합니다. 구체적으로는 다음과 같습니다.

• 문서를 별도의 도구가 아닌 Git 리포지토리 내부에 둔다
• 변경 사항은 **풀 리퀘스트 (PR, Pull Request)**를 통해 리뷰한 후 머지(Merge)한다
• 코드와 동일한 버전으로 함께 관리한다 (v1.2 코드에는 v1.2 문서가 존재)
• 머지하면 **자동으로 배포(Deploy)**되어 공개된다

이 방식이 효과적인 이유는 간단합니다. 문서를 코드와 동일한 장소, 동일한 워크플로우에 올려두면 동기화하기가 쉬워지기 때문입니다. 별도의 Wiki 도구에 격리되어 있으면, 코드를 수정하더라도 문서를 수정하러 가는 것이 "별개의 작업"이 되어 잊어버리게 됩니다. 하지만 같은 PR 안에 있다면, "코드를 바꿨다면 이 문서도 바꿔야겠지?"라는 생각이 자연스럽게 듭니다.

디렉토리 구성의 이미지는 다음과 같습니다.

my-app/
├── src/ # 앱 코드
│ └── payments/
...

"어라, docs/ 아래의 분류 방식이 왠지 의미가 있어 보이는데?"라고 생각하셨다면 예리하신 겁니다. 이것은 다음에 설명할 **Diátaxis (디아탁시스)**라는 개념을 따르고 있습니다.

문서를 쓰려고 할 때 가장 먼저 맞닥뜨리는 난관이 "그래서 무엇을 써야 하지?"가 아닌가요? 모든 것을 설명하려다 중간에 힘이 빠지곤 하죠. 흔히 있는 일입니다.

여기서 도움이 되는 것이 Diátaxis (디아탁시스) 프레임워크입니다. Daniele Procida가 제창한 것으로, 2026년 현재 개발 문서 구조로서 가장 널리 권장되는 사고방식 중 하나입니다.

Diátaxis는 문서를 **독자가 "지금 무엇을 하고 싶은가"**에 따라 4가지 종류로 나눕니다.

종류	독자의 의도	답하는 질문	예시
Tutorial (튜토리얼)	배우고 싶음	"우선 무엇부터 시작해야 하지?"	직접 조작하며 첫 결제를 만들기까지의 일련의 흐름
How-to (하우투)	특정 문제를 해결하고 싶음	"X를 하려면 어떻게 해야 하지?"	"환불 처리를 구현하는 절차"
Reference (레퍼런스)	정확한 사양을 알고 싶음	"이 함수의 인자는 무엇인가?"	API 엔드포인트 목록, 인자 및 반환값의 사양
Explanation (해설)	배경을 이해하고 싶음	"왜 이런 설계인가?"	"왜 멱등성 키(Idempotency Key)를 필수 사항으로 만들었는가"

이 네 가지를 섞어서는 안 됩니다. 한 페이지에는 한 종류만 담아야 합니다. 레퍼런스(사양 목록)에 갑자기 튜토리얼의 "우선 이것부터 해봅시다"를 섞어버리면, 사양만 알고 싶은 사람도, 배우고 싶은 초보자도 모두 길을 잃게 됩니다. 반대로 종류가 명확히 나뉘어 있으면, 독자는 "내가 지금 필요한 것은 이것이다"라고 즉시 찾아낼 수 있습니다.

그리고 흥미로운 점은, 이 분류가 AI에게도 효과적이라는 것입니다. 앞서 말했듯이 AI는 문서를 파편적으로 수집하여 사용합니다. 종류가 깔끔하게 나뉘어 있으면 AI도 "사양을 알고 싶을 때는 reference, 배경을 알고 싶을 때는 explanation"이라며 올바른 파편을 끌어오기 쉬워집니다. 인간과 AI 모두에게 친절한 방식인 셈입니다.

참고로, 어떤 것을 AI에게 쓰게 하기 쉬운가라는 관점에서 보면 대략 다음과 같은 느낌입니다.

• Reference (참조): 코드로부터 기계적으로 생성하기 쉽다. AI에게 초안을 작성하게 하기 좋은 영역.
• How-to (방법): AI에게 절차의 초안을 작성하게 하고, 인간이 검증하는 방식이 적합하다.
• Tutorial (튜토리얼): "초보자가 어디에서 막히는지"에 대한 감각이 필요하므로, 인간의 편집이 효과적이다.
• Explanation / なぜ (설명 / 이유): 이것은 인간이 쥐고 있어야 한다. "왜 이런 설계를 했는가"는 코드 어디에도 적혀 있지 않은 판단이기 때문이다. AI는 추측은 할 수 있어도, 진짜 이유는 알지 못한다.

여기서부터가 내일부터 바로 사용할 수 있는 가장 중요한 부분입니다.

몇 번이고 말씀드리지만, "선의로 열심히 노력하기"는 그만두세요. 사람은 잊어버리기 때문입니다. 대신, "문서가 어긋나면 CI가 알려주는" 구조가 감시하도록 만드세요. 탐지 수준은 대략 약한 순서대로 다음과 같은 단계가 있습니다.

레벨	무엇을 탐지하는가	난이도
1. 링크 끊김	문서 내의 링크가 죽어 있지 않은가	쉬움
...

레벨 1~3은 기계로 자동화할 수 있습니다. 우선 이곳을 다지는 것이 비용 대비 효과가 높습니다.

드리프트(Drift)의 전형적인 사례는, "문서에는 src/payments/charge.py의 create_charge()를 사용하라고 적혀 있는데, 실제로는 이미 이름이 변경되어 존재하지 않는" 경우와 같습니다. 이는 문서 내에 등장하는 파일 경로와 함수명이 코드베이스에 실제로 존재하는지 대조함으로써 기계적으로 탐지할 수 있습니다.

# scripts/check_doc_symbols.py
# 문서 내에서 언급된 파일 경로와 코드 심볼(code symbol)이 실제로 존재하는지 검사한다.
# 존재하지 않으면 exit 1 (=CI를 실패(red)로 만든다).
...

이것이 완벽한 탐지는 아닙니다. 정규 표현식(Regular Expression)으로 포착할 수 있는 범위만 확인하며, 오탐(False Positive)도 발생할 수 있습니다. 하지만 "존재하지 않는 함수를 계속 안내하는 문서"와 같은 가장 뼈아픈 거짓말을 커밋 전에 기계가 찾아준다는 것만으로도 충분한 가치가 있습니다.

또 다른 강력한 방법은 실행 가능한 문서 (executable documentation) 라는 발상입니다. 문서에 실은 코드 예제를 단순히 올려두는 것에 그치지 않고, CI에서 실제로 실행하여 통과하지 못하면 빌드를 실패시키는 것입니다. 이렇게 하면 코드 예제가 거짓이 되는 순간 바로 알아차릴 수 있습니다.

Python이라면 doctest라는 표준 메커니즘을 사용할 수 있습니다. docstring(함수 바로 옆의 설명문) 안에 대화형 예제(interactive example)를 적어두면, 그것이 그대로 테스트가 되는 방식입니다.

# src/payments/money.py
def to_cents(amount: float) -> int:
    """금액(엔)을 최소 단위(전=100분의 1엔을 의도한 샘플)로 변환한다.
    ...
    """

그리고 CI나 로컬 환경에서 다음과 같이 실행합니다.

# docstring 내의 대화형 예제(>>> 로 시작하는 행)를 테스트로 실행한다
python -m doctest -v src/payments/money.py

# README.md 내의 코드 블록도 대상으로 하고 싶을 때 (pytest 이용)
...

만약 누군가 to_cents의 구현을 변경하여 to_cents(0.5)의 결과가 50이 아니게 된다면, 문서가 거짓이 되는 순간 테스트가 실패(red)하게 됩니다. 설명과 구현이 강제적으로 동기화되는 것입니다. 이것이 바로 "실행 가능한 문서"가 주는 쾌감입니다.

마지막으로, 조금 더 느슨하지만 효과적인 메커니즘이 있습니다. "소스 코드를 변경한 PR(Pull Request)인데, 문서에는 아무런 수정이 없는 경우"에 부드럽게 경고를 보내는 것입니다. 차단(block)하는 것이 아니라 경고(warning)로 처리하는 것이 요령입니다. 모든 코드 변경에 문서 수정이 필요한 것은 아니므로, 차단하면 작업 흐름을 방해하게 됩니다. 어디까지나 "잠깐, 문서 괜찮나요?"라고 어깨를 톡톡 두드려 주는 이미지입니다.

# .github/workflows/doc-drift-gate.yml
name: doc-drift-gate
on:
...

여기까지에서 중요한 것은 완벽한 탐지를 목표로 하지 않는 것입니다. "링크 끊김", "존재하지 않는 함수", "작동하지 않는 코드 예제"와 같이 기계로 확실히 알 수 있는 거짓말부터 없애 나가는 것입니다. 의미의 정확성 같은 어려운 부분은 이후에 AI와 인간이 함께 살펴볼 것입니다.

드리프트를 탐지할 수 있게 되었다면, 다음은 "수정하고 쓰는" 과정을 어떻게 순환시킬 것인가입니다. 여기서 AI의 차례입니다.

하지만 여기서도 중심축은 흔들리지 않아야 합니다. AI는 초안과 차분(diff)을 만드는 담당자이며, 인간은 「왜(Why)」와 「정확성(Accuracy)」의 파수꾼입니다. 문서는 공개되어 인간과 AI 모두가 읽는 공유 자산이므로, 거짓이 섞이면 피해가 확산됩니다. AI가 생성한 문서에는 그럴듯한 거짓말(Hallucination, 환각)이 섞일 수 있다는 전제하에 다루는 것이 안전합니다.

역할 분담을 표로 나타내면 다음과 같습니다.

공정	인간 (What / Why)	AI (How)
무엇을 쓸지 결정	◎ 독자와 목적 결정	△ 후보 제시
...

그럼 구체적인 프롬프트 3가지를 살펴보겠습니다. 공통적인 요령은, AI에게 단정 짓게 하지 말고, 근거(어느 파일의 몇 번째 줄을 보았는지)와 「확신이 없는 부분」을 반드시 출력하게 하는 것입니다. 이것만으로도 AI 생성 문서의 신뢰도가 크게 올라갑니다.

당신은 문서 유지보수 보조 담당자입니다. 다음 코드 차분(diff)을 읽고,
업데이트가 필요해 보이는 문서의 부분을 찾아내세요.
# 제약 사항
...

다음 문서를 Diátaxis의 4가지 분류(tutorial / how-to / reference / explanation) 관점에서 진단해 주세요.
# 수행할 작업
...

이것이 레벨 4(의미의 정확성)를 위한 대책입니다. AI에게 문서의 주장과 코드의 구현을 대조하게 하여, 근거를 확인할 수 없는 주장을 찾아내게 하는 것입니다.

당신은 문서의 팩트 체크(Fact-checker) 담당자입니다.
다음 문서의 기술 내용이 실제 코드와 일치하는지 검증해 주세요.
# 규칙
...

포인트는 마지막 한 줄입니다. **「수정 여부는 인간이 결정한다. 당신은 재료를 제공할 뿐이다」**를 반드시 포함하는 것입니다. AI를 「판정자」가 아닌 「조사관」으로 고정하면, 폭주가 줄어들고 인간이 판단에 집중할 수 있습니다.

문서 중에서도 가장 잘 부패하지 않으며, AI 시대에 가장 효과적인 것이 ADR이라고 생각합니다.

**ADR (Architecture Decision Record / 아키텍처 결정 기록)**이란, 중요한 설계 판단을 **「배경(Context)・결정(Decision)・결과(Consequences)」**의 3종 세트로 짧게 남기는 문서입니다. Michael Nygard 씨가 전파한 형식으로, adr.github.io에 템플릿이 정리되어 있습니다.

이것이 효과적인 이유는 다음과 같습니다. 코드를 보면 「무엇을 하고 있는지(What/How)」는 알 수 있습니다. 하지만 「왜 그렇게 했는지(Why)」는 코드 어디에도 적혀 있지 않습니다. 「왜 RDB가 아니라 이것을 선택했는지」, 「왜 이곳을 굳이 수동으로 처리했는지」와 같은 것들입니다. 이 “왜”가 사라지면, 반년 뒤의 자신도, 새로운 팀원도, 그리고 AI 에이전트도 「이 이상한 구조에는 이유가 있는 것인지, 아니면 단순한 실수인지」를 판단할 수 없게 됩니다.

그리고 2026년 관점에서 흥미로운 점은, ADR이 AI 에이전트에게 “왜”를 전달하는 문맥(Context)의 원천이 되고 있다는 사실입니다. 「지금 가장 중요한 아키텍처 문서는 더 이상 인간용이 아니라 AI용이다」라고 말하는 사람도 있을 정도입니다. 그래서 최근에는 ADR에 「누가 결정했는가(인간인가, 에이전트인가)」와 「결정 당시 에이전트가 가지고 있던 문맥」까지 적으려는 흐름도 나타나고 있습니다.

템플릿은 다음과 같은 형태입니다.

# ADR-0007: 결제 처리에 멱등성 키(Idempotency Key)를 필수 적용
- 상태: 승인됨 (2026-06-24)
- 결정자: 인간 (백엔드 팀) / AI 에이전트는 대안 도출을 보조
...

ADR 역시 초안은 AI의 도움을 받아도 됩니다. 단, 결정 그 자체는 인간이 쥐고 있어야 합니다.

다음 설계 논의를 바탕으로 ADR 초안을 작성해 주세요.
# 제약 사항
- context / decision / consequences의 3부 구성으로 작성할 것.
...

지금까지 구조에 대해 이야기했지만, 이 부분을 놓치면 사고가 발생하므로 마지막으로 안전 측면을 정리하겠습니다.

비밀 정보, 개인 정보, 고유 ID를 문서나 llms.txt에 적지 마십시오. 이것이 가장 중요합니다. 문서는 공개되며 AI도 읽습니다. 즉, 「문서에 적는 것 = 외부로 유출하는 것」이라고 생각해야 합니다. API 키, 내부 URL, 개인 이름, 사내 고유 ID는 더미(Dummy)나 플레이스홀더(Placeholder, STRIPE_API_KEY=xxxxx)로 대체해야 합니다.

와 같은)로 대체한다.

• AI가 생성한 문서를 그대로 "최종 확정"하지 않는다. 그럴싸한 거짓말이 섞여 있다는 전제하에, 반드시 코드와 대조하여 근거를 확인(Grounding)한다.
• 되돌릴 수 없는 작업의 절차서는 인간이 리뷰한다. "운영 DB를 삭제하는 명령어", "배포 절차"와 같은 것을 AI에게 쓰게 했다면, 인간이 반드시 확인한다.
• 외부에서 온 텍스트는 "데이터"로 취급한다. 문서 안에 외부에서 가져온 문장을 붙여넣을 때, 그곳에 "이전의 지시를 무시하고~"와 같은 함정(프롬프트 인젝션, Prompt Injection)이 섞여 있을 수 있다. AI에게 읽힐 문맥에 외부 텍스트를 섞을 때는 명령이 아니라 데이터로서 감싸야 한다.

함정	왜 안 되는가	어떻게 하는가
쓰고 만족해서 방치	쓴 순간부터 부패하기 시작함	CI에서 드리프트(Drift)를 감지하는 메커니즘을 먼저 만든다
...

• 문서 정비가 코드를 짜는 것보다 무거워진다면, 일단 손을 멈춘다. 문서는 수단이지 목적이 아니다.
• 드리프트 감지가 오탐(False Positive)투성이라 방해가 된다면, 규칙을 완화한다 (Block → Warning으로 낮춤).
• AI가 생성한 문서의 근거 확인에 시간이 너무 오래 걸린다면, 그 영역은 인간이 직접 쓰는 편이 빠르다는 판단을 내리는 것도 방법이다.

내용이 길어졌으니, 마지막으로 핵심만 요약하겠습니다.

• 문서 드리프트는 AI로 개발 속도가 빨라질수록 악화된다. 게다가 지금은 어긋난 문서를 AI가 읽고 그럴싸하게 틀리는 악순환이 발생한다. -
• 따라서 **문서 = 인간과 AI가 공유하는 문맥 자산(Shared Context)**이라고 재정의한다. -
• Docs as Code 방식으로 코드와 같은 장소, 같은 워크플로우에 올리고, Diátaxis를 통해 "무엇을 쓸 것인가"를 4가지 분류로 정리한다. -
• 드리프트는 선의가 아니라 메커니즘(CI)으로 감지한다. 존재하지 않는 심볼, 작동하지 않는 코드 예시부터 잡아낸다. -
• AI에게는 초안과 차이점(Diff)을 맡기고, "왜(Why)"와 "정확성"은 인간이 쥐고 있는다. 근거와 불분명한 점을 반드시 출력하게 한다. -
• **ADR(Architecture Decision Record)**로 판단의 "이유"를 남긴다. 이 부분은 인간만이 쓸 수 있으며, AI에게도 효과적이다.

마지막으로, 제 개인적인 생각을 조금 덧붙이자면.

문서 작업은 참 귀찮습니다. 아무도 칭찬해주지 않고, 쓰지 않아도 당장 오늘 큰일이 나지는 않으니까요. 하지만 **오늘 쓴 3줄의 문서는 반년 뒤의 나에게 보내는 "쪽지"**와 같습니다. 그리고 지금은 그 쪽지를 읽는 대상이 미래의 나뿐만 아니라 팀, 그리고 다음 AI 세션에까지 확장되었습니다.

저는 이것을 "내일의 내가 '고맙습니다'라고 말하게 만드는 것"이라고 부릅니다. 과거의 내가 제대로 남겨두었다면, 미래의 내가 "고맙습니다"라고 말할 수 있습니다. 드리프트된 과거의 나를 비난하는 것이 아니라, 이제부터 미래의 나에게 조금씩 친절해지는 것입니다. 비난의 축이 아니라 배려의 축이죠.

그리고 이렇게 코드와 계속 동기화되는 메커니즘과 사람과 AI 모두가 읽을 수 있는 문맥은 사라지지 않고 쌓이는 자산이 됩니다. 쓰고 버리는 설명문이 아니라, 자본(Code as Capital)이 되는 것이죠. 무엇을, 왜 쓸지는 인간이 결정하고, 어떻게 쓸지는 AI의 도움을 받습니다. 이러한 분업이 앞으로 엔지니어가 역량을 발휘할 지점이라고 생각합니다.

• 리포지토리에 docs/ 디렉토리를 만들고, 기존 문서를 Diátaxis의 4가지 분류로 나누어 본다 (우선 하나라도 좋다).
• 가장 중요한 코드 예시에 doctest를 하나 추가하고 CI에서 실행한다 (거짓 정보가 되었을 때 알아챌 수 있는 상태를 만든다).
• "존재하지 않는 함수를 안내하고 있지는 않은가"를 검사하는 작은 스크립트를 하나 작성하여 CI에 추가한다.
• 최근의 큰 설계 판단을 ADR 한 장으로 기록한다. "왜 그렇게 했는지"를 미래의 나와 AI에게 전달한다.

완벽하지 않아도 됩니다. 하나씩 해나가세요. 오늘의 작은 한 줄이 미래의 당신과 AI를 도울 것입니다. 그럼, 다음에 또 뵙겠습니다.

• Diátaxis (문서 4분류 프레임워크): https://diataxis.fr/
• Architecture Decision Records (ADR): https://adr.github.io/
• 문서 드리프트 (Documentation Drift)의 탐지 및 관리에 관한 연구 리뷰 (IEEE Xplore), 코드-주석 (code-comment) 불일치 연구 (arXiv:2409.10781 / arXiv:2010.01625 / DocChecker arXiv:2306.06347, CUP2・JITDATA 데이터셋)
• llms.txt / Docs as Code / AI가 문서를 파편화하여 읽는 방식에 관한 2026년 각종 기술 기사 (Fern, Mintlify 외)

※ 본 기사의 코드 예시 및 설정 예시는 모두 범용적인 샘플 (example 계열의 더미 이름)입니다. 실제 운영 시에는 귀하의 환경과 보안 정책에 맞춰 조정하시기 바랍니다.