🚀 서론

"작동하는 소프트웨어 > 포괄적인 문서"라는 애자일 선언문(Agile Manifesto)의 한 구절은 오랫동안 "문서는 나중에 해도 된다"라는 면죄부로 사용되어 왔습니다. 또한, 생성 AI의 보급으로 인해 "AI가 코드를 직접 이해할 수 있으므로 문서는 작성할 필요가 없다"라고 오해하고 계신 분들도 계실지 모릅니다.

하지만, AI 시대에 이러한 사고방식은 치명적입니다.

AI 코딩 에이전트(AI Coding Agent)의 출력 품질은 입력되는 컨텍스트(Context)의 품질에 직접적으로 의존합니다. 문서가 없다면 AI는 아무것도 알지 못합니다. 아무것도 모르는 인간이 작성하는 코드도 문제지만, 아무것도 모르는 AI는 훨씬 더 심각합니다. 인간의 수십 배 속도로, 엉뚱한 구현을 대량으로 만들어내기 때문입니다.

문서는 이제 AI 에이전트가 미래의 또 다른 AI 에이전트를 위해 남기는 기록입니다 [1].
현재의 AI가 내린 설계 판단, 채택하지 않은 선택지, 프로젝트의 규칙과 같은 정보를 기록으로 남기지 않으면, 다음에 찾아올 AI 에이전트는 같은 실수를 반복하게 됩니다.

이 기사에서는 DORA의 실증 데이터와 Thoughtworks의 논의를 바탕으로, AI 시대의 문서 전략으로서 3가지 원칙을 제안합니다.

📊 배경: 왜 지금 문서 전략을 재검토해야 하는가

DORA가 실증한 "문서는 AI의 전력 배증기"

Google의 DORA(DevOps Research and Assessment) 팀은 2021년에 문서 품질을 독립적인 역량(Capability)으로 처음 측정했습니다. 이후의 연구를 통해 문서의 중요성은 매년 명확해지고 있습니다.

DORA 2025에서 문서가 "AI 접근 가능한 내부 데이터(AI-accessible internal data)"로 흡수된 것은, 문서의 역할이 "인간을 위한 품질 속성"에서 "AI가 소비하는 컨텍스트 데이터"로 변화했음을 의미합니다.

"You can't connect an AI to information that doesn't exist, and you shouldn't connect it to information that is wrong."

(존재하지 않는 정보에 AI를 연결할 수는 없으며, 잘못된 정보에 연결해서도 안 된다.)

— DORA, AI-accessible internal data

인지적 부채: AI가 축적하는 새로운 부채

2026년 2월, Margaret-Anne Storey는 Thoughtworks의 리트릿(Retreat)에서 **인지적 부채(Cognitive Debt)**를 제창했습니다.

"Technical debt lives in the code; cognitive debt lives in developers' minds."

(기술적 부채는 코드에 깃든다. 인지적 부채는 개발자의 머릿속에 깃든다.)

— Margaret-Anne Storey, 2026

기술적 부채(Technical Debt)가 코드에 축적되는 것에 반해, 인지적 부채는 **개발자의 머릿속에만 존재하는 암묵지(Tacit Knowledge)**에 축적됩니다. AI 코딩 에이전트는 다음과 같은 이유로 이 부채를 가속화합니다.

• 세션 간 컨텍스트 상실— AI는 새로운 세션을 시작할 때마다 이전의 지식을 망각합니다.
• AI가 생성한 코드의 '왜(Why)'가 남지 않음— AI는 코드를 작성할 수 있지만, 설계 결정의 배경을 자발적으로 기록하지 않습니다.
• 속도가 독이 됨— 인간보다 수십 배 빠른 속도로 코드를 작성하기 때문에, 문서화되지 않은 판단이 고속으로 축적됩니다.

"This velocity multiplier becomes a debt accelerator."

(이 속도 승수(Velocity Multiplier)는 부채의 가속기가 됩니다.)

— Rachel Laycock (Thoughtworks CTO), 2026

애자일 선언문(Agile Manifesto)의 재해석

"Working software over comprehensive documentation"

(포괄적인 문서보다 작동하는 소프트웨어를 중시한다)

— Agile Manifesto, 2001

선언문이 부정하는 것은 "comprehensive"(포괄적인) 문서이지, 문서 그 자체가 아닙니다.

AI가 문서를 고속으로 작성할 수 있는 지금, 문서를 작성하지 않을 이유가 사라졌습니다.

2026년 2월 Deer Valley 리트릿에서 Laura Tacho는 다음과 같이 말했습니다.

"The Venn Diagram of Developer Experience and Agent Experience is a circle."

(개발자 경험(Developer Experience)과 에이전트 경험(Agent Experience)의 벤 다이어그램은 하나의 원이다.)

— Laura Tacho, 2026

인간에게 좋은 개발 환경은 AI에게도 좋은 개발 환경입니다. 이후에 설명할 세 가지 원칙은 인간을 위한 것이기도 하며, AI를 위한 것이기도 합니다.

📝 원칙 1: 모든 문서를 Markdown으로 작성하라

AI 시대의 문서는 인간을 위한 가독성과 **AI를 위한 기계 가독성(Machine Readability)**을 모두 충족해야 합니다. 이 두 가지를 동시에 실현할 수 있는 최적의 형식이 바로 Markdown입니다.

왜 Markdown인가

• 인간과 AI 모두 읽고 쓸 수 있음— 플레인 텍스트(Plain Text)이면서도 구조화된 정보를 표현할 수 있습니다.
• Git diff가 깔끔함— PR(Pull Request)에서 변경 사항이 인간과 AI 모두에게 명확하게 보입니다.
• 도구 독립성— 특정 소프트웨어에 의존하지 않고 어떤 에디터에서도 편집할 수 있습니다.
• GitHub에서 네이티브 렌더링— 리포지토리 내에서 바로 읽을 수 있습니다.

도표도 Markdown 내에 텍스트로 작성하라

문서에 도표는 필수적이지만, AI가 정확하게 읽을 수 없는 형식은 피해야 합니다.

• PowerPoint로 그린 그림— .pptx는 ZIP으로 압축된 XML의 집합체이므로 AI에게 노이즈가 많습니다.
• 화이트보드에 쓰고 카메라로 찍은 이미지— OCR(광학 문자 인식) 정밀도에 의존하며 구조 정보가 손실됩니다.
• draw.io의 바이너리 형식— Git diff가 작동하지 않으며 AI도 읽을 수 없습니다.

대신, Mermaid나 PlantUML과 같은 텍스트 기반의 DSL(Domain Specific Language)로 표현합니다. 그중에서도 Mermaid는 GitHub의 Markdown 내에서 네이티브하게 렌더링되며, AI가 생성, 수정, 해석하기 쉬워 최우선 선택지로 적합합니다.

텍스트 DSL의 결정적인 장점은 AI가 도표를 생성하고 업데이트할 수 있다는 점입니다. AI가 설계 결정을 내릴 때 아키텍처 다이어그램이나 시퀀스 다이어그램(Sequence Diagram)도 함께 생성 및 업데이트하게 하면, 문서와 코드 사이의 괴리를 방지할 수 있습니다.

ADR은 Markdown으로 작성하라: 가장 중요한 문서

ADR(Architecture Decision Records, 아키텍처 결정 기록)은 AI 시대에 가장 중요한 문서 형식입니다.

• 「왜」를 기록하는 유일한 메커니즘 — 코드는 「무엇을」 표현하지만 「왜」는 표현하지 않습니다.
• AI의 리그레션 (Regression) 방지 — AI가 과거에 부정되었던 선택지를 다시 제안하는 것을 방지합니다.
• 인지적 부채 (Cognitive Debt)에 대한 직접적인 대책 — 세션 간에 손실되는 컨텍스트 (Context)를 영속화합니다.

## Context（배경）
<!-- 의사결정이 필요하게 된 상황·제약을 가치 중립적으로 기술 -->
## Decision（결정）
...

특히 Alternatives Considered 섹션이 중요합니다. AI가 세션 간에 컨텍스트를 잃더라도, 이 섹션을 읽으면 「왜 다른 선택지를 채택하지 않았는가」를 이해할 수 있습니다. 이것이 없으면 AI는 매번 똑같은 논의를 반복합니다.

참고로 Devin의 DeepWiki와 같이 리포지토리 (Repository)에서 문서를 자동 생성하는 도구도 등장하고 있지만, 이것들은 소스 코드의 현재 상태를 읽어내어 기술할 뿐이며, 「왜 이런 설계가 되었는지」, 「어떤 선택지를 검토하고 기각했는지」까지는 읽어낼 수 없습니다. ADR과 같은 「왜」의 기록은 인간과 AI가 대화 속에서 의식적으로 남겨야 합니다.

📁 원칙 2: 모든 문서를 소스 코드와 동일한 리포지토리에서 관리한다

「Confluence나 SharePoint에 문서를 두어도, AI가 접근할 수 있다면 문제없지 않을까?」라고 생각할지도 모릅니다. 하지만 문제는 접근 가능성이 아니라, 버전 관리의 일체성에 있습니다.

분리 관리의 구조적 문제

소스 코드와 문서의 버전 관리가 분리되어 있으면, 다음과 같은 문제가 구조적으로 발생합니다.

• 버전 연결의 어려움 — 소스 코드의 특정 버전에 대응하는 문서의 버전을 관리하기 어렵습니다. AI가 오래된 문서를 참조하여 잘못된 구현을 생성할 리스크가 항상 따릅니다.
• 접근 가능성의 상실 — 문서의 이동, 삭제, 링크 끊김 등으로 인해 AI와 인간 모두로부터 접근할 수 없게 됩니다.
• 동시 업데이트의 보장 없음 — 소스 코드를 업데이트해도 문서가 업데이트되지 않습니다. DORA 2025가 경고하는 「잘못된 정보에 AI를 연결하는」 상태에 빠지게 됩니다.

동일한 커밋 (Commit)으로 소스 코드와 문서가 함께 업데이트되어, git checkout으로 임의의 시점의 코드와 사양을 동시에 복원할 수 있어야 합니다. 이 일체성이 AI가 신뢰할 수 있는 컨텍스트를 얻기 위한 전제 조건입니다.

CI에 문서 게이트를 설치한다

「문서는 나중에 쓰자」를 구조적으로 방지하려면, CI 파이프라인에 문서 게이트 (Document Gate)를 통합합니다. 문서 게이트에는 두 가지 계층이 있습니다.

• 구조·문체 체크 — textlint, markdownlint를 통한 Markdown 품질 검증
• 코드와의 정합성 체크 — AI가 코드 변경을 이해하고, 문서와의 괴리를 감지

기존 문서 Linter의 한계

기존에 문서의 Lint라고 하면, textlint나 markdownlint와 같은 도구를 사용하는 것이 주류였습니다. 이것들은 문서의 문체나 Markdown의 구조를 체크하는 데는 유효합니다. 하지만 이것들이 검증할 수 있는 것은 어디까지나 문서 단체의 품질이며, AI 시대에 필요한 다음과 같은 체크는 할 수 없습니다.

• 코드 변경에 대해 왜 이 변경을 하게 되었는지, 이유나 경위가 문서에 기록되어 있는가
• 코드 변경에 대응하는 문서가 올바르게 업데이트되었는가
• 코드의 동작과 문서의 기술 내용 사이에 괴리가 발생하지 않았는가
• 신규 기능 추가에 대해 필요한 문서가 작성되었는가

굳이 CI 게이트에서 문서가 작성되었는지 체크하지 않아도, 리포지토리를 읽어 자동으로 문서를 생성하게 하면 되지 않느냐고 생각할지도 모릅니다. 하지만 앞서 언급했듯이 자동 생성 도구는 「무엇이 있는지」는 기록할 수 있어도, 「왜 그렇게 되었는지」는 기록할 수 없습니다. CI 게이트의 목적은 이 「왜」가 확실히 기록되도록 하는 것입니다.

기존의 규칙 기반 (Rule-based) GitHub Actions로는 코드의 의미론적 변경을 이해하고, 그에 대응하는 문서의 정합성을 판단하는 것이 거의 불가능합니다. 「src/가 변경되면 docs/에도 변경이 있는가」 정도의 파일 경로 기반 체크는 작성할 수 있지만, 내용의 정합성까지는 검증할 수 없습니다.

AI를 활용한 더욱 고도화된 도큐먼트 게이트 (Document Gate)

GitHub가 발표한 Agentic Workflows는 이 과제에 대한 현실적인 해결책을 제시하고 있습니다. PR을 트리거로 AI 에이전트(AI Agent)를 기동하여, 코드 차분(diff)과 문서를 횡단적으로 읽고 괴리를 자동으로 탐지하는 메커니즘을 구축할 수 있다면, 기존의 CI(지속적 통합)로는 불가능했던 '코드와 문서의 의미적 정합성 체크'를 실현할 수 있을 것입니다.

2026-05-15 시점에서는 아직 Agentic Workflows가 일반 공개되지 않았으므로 자동화는 불가능하지만, 수동으로 이러한 체크를 유도할 수는 있을 것입니다. 스킬을 만들고, PR 템플릿에 "/docs-lint 스킬을 사용하여 AI에게 문서 체크를 수행하게 할 것"과 같은 체크 항목을 적어둔다면, 도큐먼트 게이트의 효과를 기대할 수 있습니다.

🤖 원칙 3: 커스텀 인스트럭션(Custom Instruction)을 정비하여, AI가 자동으로 문서를 남기는 메커니즘을 만든다

원칙 1(Markdown)과 원칙 2(리포지토리 관리)는 문서의 형식과 위치를 정했습니다. 하지만 가장 중요한 문제가 남아 있습니다. 누가 문서를 쓰는가? 입니다.

인간이 모든 것을 수기로 작성하는 것은 비현실적입니다. AI의 개발 속도를 인간의 문서 작성 속도가 따라잡을 수 없습니다. 답은 AI에게 쓰게 하는 것입니다. 커스텀 인스트럭션을 정비하여, AI가 대화 속에서 결정된 설계 판단이나 규칙을 자동으로 문서로서 남기는 메커니즘을 만듭니다.

컨텍스트 엔지니어링 (Context Engineering): 무엇을 영속화하고, 어떻게 읽히게 할 것인가

AI가 받는 컨텍스트(Context)에는 영속성이 다른 여러 계층이 있습니다. LangChain이 제창한 '컨텍스트 엔지니어링'의 개념을 바탕으로, 영속성의 관점에서 정리하면 다음과 같습니다.

DORA 2025 또한 Capability #3 「AI-accessible internal data」의 실천 방법으로서 컨텍스트 엔지니어링을 언급하며, AI에 내부 문서나 코드베이스를 연결하는 메커니즘의 중요성을 강조하고 있습니다.

정리하여 프로젝트 지식으로 승격시키기

최상단의 프로젝트 지식만이 구조화되어 있으며, 언제든 AI가 신뢰하고 참조할 수 있는 정보입니다. 그 외의 계층은 휘발성이 높거나(대화 이력·툴 출력), 영속적이더라도 시행착오나 논의가 혼재되어 미정리 상태이거나(Issue·PR), 기한이 정해져 있습니다(AI 메모리).

이러한 계층에 산재하는 정보 중에서 중요한 설계 판단이나 규칙을 정리하여 프로젝트 지식으로 승격시킬 필요가 있습니다.

AI 메모리 계층(Copilot Agentic Memory 또는 Claude Auto Memory)은 이 승격의 중간 지점입니다. AI가 작업 중에 발견한 지식을 자동으로 축적하지만, 영속적이지는 않습니다 (예: Copilot은 28일 후 만료). 여기에 쌓인 지식 중 중요한 것을 인간이 리뷰하여 ADR이나 인스트럭션 파일로 커밋한다. 이것이 원칙 3 사이클의 핵심입니다.

읽기는 필요할 때 필요한 것만

프로젝트 지식으로 정리·승격시킨 문서라 할지라도, 모든 것을 AI의 컨텍스트에 집어넣으면 되는 것은 아닙니다. DORA 2025는 다음과 같이 경고합니다.

"While feeding large, raw documents into an AI's context window is tempting, it is often counterproductive."

(대량의 가공되지 않은 문서를 AI의 컨텍스트 윈도우(Context Window)에 흘려넣고 싶어지지만, 이는 종종 역효과를 낳는다.)

— DORA 2025

컨텍스트 윈도우(Context Window)는 유한합니다. 경로 기반 규칙(Path-based rules)과 지연 로딩(Lazy loading)을 통해 '필요할 때 필요한 것만' 읽어들이도록 설계하는 것이 중요합니다. 정보의 정리·영속화(무엇을 남길 것인가)와 로드 전략(어떻게 읽어들일 것인가)은 별개의 문제이며, 두 가지 모두를 의식해야 합니다.

인스트럭션 파일(Instruction Files) 정비

주요 AI 코딩 에이전트(AI Coding Agent)는 모두 리포지토리(Repository) 내의 인스트럭션 파일을 읽어들이는 메커니즘을 가지고 있습니다.

기재해야 할 내용은 각 도구 공통입니다.

## Project Overview ← 언어·프레임워크·목적
## Critical Build & Validation Steps ← 커밋 전에 실행하는 명령어
## Project Structure ← 디렉토리 트리
...

AI에게 문서를 자동 생성하게 하는 메커니즘

커스텀 인스트럭션(Custom Instruction)의 진가는 AI에게 "코드뿐만 아니라 문서도 작성하라"고 지시할 수 있다는 점에 있습니다.

구체적으로는, 인스트럭션 파일에 다음과 같은 규칙을 기재합니다.

• 설계 판단을 내렸다면 ADR을 작성할 것 — 새로운 라이브러리 채택, 아키텍처 변경 등 중요한 판단 시 docs/architecture-decisions/에 ADR(Architecture Decision Record)을 작성한다.
• 대화로 결정된 규칙은 인스트럭션에 추가할 것 — 프로젝트 고유의 제약 사항이나 패턴이 대화를 통해 밝혀지면 인스트럭션 파일에 기록한다.
• PR(Pull Request)에는 문서 업데이트를 포함할 것 — 코드 변경의 영향을 받는 문서를 동시에 업데이트한다.

주요 도구들은 이미 AI가 자율적으로 문서를 축적하는 메커니즘도 갖추고 있습니다. GitHub Copilot의 Agentic Memory는 작업 중에 발견한 지식을 자동으로 저장하며, Claude Code의 Auto Memory는 MEMORY.md에 기록을 남깁니다. 다만, 이러한 자동 기록은 휘발성이 높기 때문에 중요한 판단은 인간이 리뷰한 후에 ADR이나 인스트럭션 파일로 승격시켜야 합니다.

이 사이클에서 인간의 역할은 리뷰와 승인입니다. AI가 작성한 문서를 PR에서 리뷰하고, 정확성을 확인하여 머지(Merge)합니다. AI의 개발 속도를 활용하면서도, 인간의 판단력으로 품질을 담보하는 분업입니다.

🎯 요약

AI는 증폭기입니다. 좋은 개발 관행(Best Practice)을 증폭하기도 하지만, 나쁜 개발 관행도 증폭합니다.

문서가 없다면 AI는 증폭할 대상이 없습니다. 문서가 틀렸다면 AI는 오류를 증폭합니다.

문서는 AI라는 증폭기의 입력 신호 그 자체입니다. 다음 세 가지 원칙으로 이 신호의 품질을 높입시다.

• Markdown으로 작성할 것 — 인간과 AI 모두가 읽고 쓸 수 있는 형식을 선택한다.
• 리포지토리에서 관리할 것 — 코드와 문서의 버전을 일체화한다.
• AI가 자동 기록하게 할 것 — 커스텀 인스트럭션을 통해 AI가 문서를 남기는 메커니즘을 만든다.

📚 참고 문헌

• DORA State of DevOps Report 2021 — 문서 품질을 최초로 독립적인 역량 (Capability)으로서 측정

• DORA State of DevOps Report 2022 — 문서 품질이 전력 배증기 (Force Multiplier)로서 기능함을 입증

• DORA State of DevOps Report 2024 — AI 도입에 대한 최초의 정량적 측정

• DORA 2025: State of AI-Assisted Software Development — 7가지 AI 역량 모델 (AI Capability Models)

• DORA: AI-accessible internal data — 컨텍스트 엔지니어링 (Context Engineering) 실천 가이드

• Martin Fowler's Exploring Generative AI series — Deer Valley 리트릿을 포함한 생성형 AI (Generative AI) 고찰

• GitHub Copilot Custom Instructions — 인스트럭션 (Instruction) 체계의 참고 사례

• Claude Code Memory Architecture — CLAUDE.md + Auto Memory

• Agile Manifesto — 원전

• LangChain: The Rise of Context Engineering — 컨텍스트 엔지니어링 (Context Engineering) 개념 정리

• Mermaid 공식 문서 — 텍스트 기반 DSL의 대표 사례

사실 AI가 등장하기 전이라도 미래의 후임자를 위해 문서로 기록을 남겨두었어야 한다고 생각한다. 문서나 사양서 등이 전혀 남아있지 않아, '건드리지 않는 소프트웨어가 복이 있다'는 식의 상태에 빠져 있는 시스템을 본 적이 있을 것이다. ↩︎