출처 https://www.youtube.com/watch?v=Fj8DKMbdIzU · 채널 Matt Pocock (AI Hero) · 길이 02:04 · 공개 2026-07-16 17:04 (KST) 포맷 유튜브 쇼츠. 말하는 사람 화면 위쪽에
AI/Docs/Code세 박스로 된 손그림 다이어그램이 얹히고, 논지가 바뀔 때마다 다이어그램이 세 번 바뀐다. 이 다이어그램이 곧 영상의 뼈대다. 원본 자막(자동 생성):raw/transcripts/2026-07-16-delete-most-of-your-docs.en.srt
한눈에 보는 요약
- 안티패턴은 이것이다 — 코드를 설명하는 문서 레이어를 따로 만들어두고, AI가 코드가 아니라 그 문서를 주로 참조하게 만드는 것. Pocock은 이게 AI 코딩 결과물을 더 좋게가 아니라 더 나쁘게 만들면서 토큰까지 잡아먹는다고 본다.
- 이유는 문서가 검증 불가능하기 때문이다. 레포 안의 마크다운은 실행되지 않고 코드에 대해 테스트되지도 않는다. 그래서 코드로부터 표류(drift)한다. 문서는 A라고 하는데 실제 코드는 B인 상태가 조용히 만들어진다.
- 그러면 진실의 원천이 둘이 된다. 둘이 충돌하는 순간 AI는 어느 쪽이 진짜인지 알 방법이 없다. 코드가 어차피 스스로 설명할 수 있는 것을 설명하려고 문서 레이어를 통째로 세우는 건 “massive antipattern”이라는 게 그의 표현이다.
- 그래서 부담은 코드가 져야 한다. 잘 포맷팅되어 있고, 파일 시스템상 있어야 할 자리에 있고, 합리적인 크기의 덩어리로 조직되어 있고, 인터페이스와 구현이 분리되어 AI가 필요한 것만 집어갈 수 있어야 한다.
- 다만 문서 전면 폐지는 아니다. 코드가 표현할 수 없는 것이 셋 있다 — ADR(어떤 대안을 고려하고 왜 버렸는가), 용어집(이 코드베이스에서 “order”가 대체 뭔가), 그리고 탐색을 빠르게 해줄 얇은 네비게이션 문서. 이 셋은 남긴다.
- 결론은 위치의 문제다. 문서는 코드 옆에 있는 보조물이지, 코드 위에 앉아 “이걸 읽고 코드를 이해하라”고 말하는 진실의 원천이 아니다.
장면별 상세 설명
[00:09] 1. 기본값 — AI가 가진 단서는 코드뿐이다
첫 다이어그램은 AI → Code 화살표 하나가 전부다. AI가 코드베이스를 탐색하게 놔두면 대부분의 경우 AI가 의지할 것은 코드 자체뿐이고, 코드는 그 자체로 설명이 되어야 한다 — AI가 해석할 수 있을 만큼의 정보가 코드 안에 들어 있어야 한다.
이건 곧 코드에 큰 부담을 지운다는 뜻이고, Pocock은 그 부담을 그대로 받아들인다. 그가 나열하는 조건은 네 가지다.
- 코드가 잘 포맷팅되어 있을 것
- 파일 시스템상 올바른 위치에 놓여 있을 것
- AI가 들여다보기 좋은 합리적인 크기의 덩어리로 조직되어 있을 것
- 인터페이스와 구현이 분리되어 있어서 AI가 필요한 부분만 가져갈 수 있을 것
즉 “AI가 읽을 수 있게 만든다”는 과제의 답이 문서가 아니라 코드 구조 자체라는 것이 출발점이다.
[00:39] 2. 안티패턴 — 문서가 코드 위에 올라앉고, 점선이 벌어진다
두 번째 다이어그램에서 구조가 바뀐다. Docs 박스가 Code 위에 얹히고 화살표는 AI → Docs로만 간다. 그리고 Docs와 Code 사이는 실선이 아니라 점선이다 — 이 점선이 영상 전체의 논점이다.
많은 사람이 하는 일이 이것이다. 자기 코드에 대한 문서를 만들고, AI가 주로 그 문서에 의존하게 한다. 문제는 그 문서 — 레포 안의 마크다운 파일들 — 가 실행 가능하지도 않고 코드에 대해 테스트되지도 않는다는 점이다. 검증 장치가 없으니 문서는 코드로부터 조용히 멀어진다.
그 결과가 진실의 원천 두 개다. 문서는 한 가지를 말하고, 실제 코드 — 진짜 진실의 원천 — 는 다른 것을 말한다. 둘이 충돌하면 AI는 어느 쪽이 진짜인지 알 수 없다. Pocock이 “정말 정말 큰 문제이자 거대한 안티패턴”이라고 부르는 지점이 여기다. 코드가 어차피 설명할 수 있는 것을 설명하려고 문서 레이어를 통째로 세우는 것 말이다.
[01:16] 3. 남겨야 할 문서 — 코드가 말할 수 없는 것들
세 번째 다이어그램에서 Docs가 Code 위가 아니라 옆으로 내려오고, AI에서 두 박스로 화살표가 각각 뻗는다. Code 박스가 Docs 박스보다 눈에 띄게 크다 — 비중의 그림이다.
그는 여기서 오해를 먼저 차단한다. 모든 문서에 반대하는 것도, 레포에 코드만 있어야 한다는 것도 아니다. 코드는 스스로를 설명해야 하지만, 코드가 설명할 수 없는 것들이 있다.
- ADR(Architectural Decision Record) — 지금 있는 코드 대신 어떤 대안이 고려됐는지는 코드가 알려줄 수 없다. 그래서 레포에 결정 기록이 필요하다.
- 용어집(glossary) — 코드와 함께 쓰는 도메인 언어도 코드만으로는 전달되지 않는다. “이 코드베이스에서 order가 뭔지 AI가 알까? 아마 모를 것”이라는 게 그의 예시다.
- 얇은 네비게이션 문서 — 코드의 주요 부분들을 돌아다니기 위한 얇은 레이어는 AI의 탐색 속도를 실제로 높여준다.
세 항목의 공통점은 분명하다. 코드에서 파생될 수 없는 정보만 문서로 남긴다. 반대로 코드를 다시 서술하는 문서는 표류할 뿐이다. 마지막 문장이 결론이다 — “문서를 진실의 원천으로, 코드를 이해하려고 읽는 것으로 두는 개념, 그건 전혀 좋아하지 않는다.”
부록 — 실전 체크리스트
- 레포의 마크다운을 훑고 코드를 다시 서술하는 문서를 골라낸다. 그건 지운다. 코드가 읽기 어려워서 필요했던 문서라면 문서를 고치지 말고 코드를 고친다.
- 남기는 문서는 코드에서 파생 불가능한 것만 — ADR, 용어집, 얇은 네비게이션 인덱스.
- (영상에는 없는 적용 예 — 같은 논리를 에이전트 지침에 옮기면)
AGENTS.md/CLAUDE.md에 API 시그니처·파일 목록·동작 설명을 복사해두지 않는다. 복사하는 순간 표류가 시작되고, 충돌할 때 에이전트는 어느 쪽을 믿을지 모른다.
원문 인용 모음
- [00:01] “There’s this really annoying pattern that I see people do everywhere that I think is making their AI coding output worse, not better, and costing them tokens.”
- [00:19] “It’s supposed to have enough information in the code so that AI can interpret it. That puts a lot of burden on my code.”
- [00:52] “They’re usually not executable. They’re not testable against the code. And so they can drift away from the code.”
- [01:02] “If there are two sources of truth and they conflict, then AI won’t know which one is the real one.”
- [01:12] “A massive antipattern to build this whole layer of docs just to explain what the code can anyway.”
- [01:28] “Code can’t tell you what alternatives were considered instead of the code that’s there. And so you need architectural decision records in your repo to capture those.”
- [01:42] “Does it know what an order is in your codebase? Probably not. And so a glossary is extremely helpful.”
- [01:56] “But the concept of docs as the source of truth, as the thing that you read to understand the code, no, I don’t like that at all.”
관련 노트
- moc-ai-coding — AI 코딩 도구·워크플로 MOC
- moc-ai-agents-context-stack — 에이전트에게 무엇을 컨텍스트로 줄 것인가
- 2026-07-03-justinyan-mattpocock-skills-vs-superpowers — 같은 화자의 스킬 설계 논의