문서화는 생산성 문제다 (그리고 AI가 이를 가시화했다)
Source: Dev.to
오랫동안 우리는 문서를 위생 문제로 여겼다
해야 할 것이다. 나중에 중요해지는 일이다. 오늘의 생산성에 크게 영향을 주지는 않는다.
AI는 그 가정이 얼마나 잘못됐는지 명백히 보여주었다.
AI가 우리를 더 빠르게 만들었지만, 어쩐지 더 느리게 만들었다
6개월 전, 우리는 AI를 개발 워크플로에 도입했다.
모든 것이 즉시 빨라졌다:
- 코드 초안이 몇 초 만에 나타났다
- API 명세가 스스로 작성되었다
- 리팩토링 제안이 언제나 제공되었다
- 모든 질문에 자신 있는 답변이 주어졌다
서류상으로는 생산성이 급증했다.
하지만 실제로는 이상한 일이 발생했다.
우리는 문서를 쓰는 것보다 다시 읽는 데 더 많은 시간을 보냈다.
확정된 듯 보였던 결정들이 나중 대화에서 계속 다시 등장했다.
팀원들은 주저했다: “잠깐, 어느 버전이 맞지?”
우리는 산출물을 만드는 속도가 느려진 것이 아니다.
우리는 결정하는 속도가 느려졌다.
그때 우리는 명확히 알았다:
Documentation wasn’t a side task. It was the bottleneck all along.
AI가 문제를 만든 것이 아니다. 문제를 드러냈을 뿐이다.
모든 것을 바꾼 사건
3개월 차에 우리는 컨텍스트‑크기 초과에 부딪혔습니다. AI가 핵심 모듈을 리팩터링하려고 했을 때, 모든 것을 메모리에 담을 수 없었습니다.
그래서 우리는 오래된 문서를 삭제하기 시작했습니다.
그때 우리는 어떤 문서를 삭제해도 안전한지 알 수 없다는 것을 깨달았습니다.
- 일부 문서에는 우리가 접근 방식 X를 Y보다 선택한 이유를 설명하는 컨텍스트가 있었습니다.
- 일부는 반쯤 완성된 상태였지만, 그것이 의도된 것인지 아무도 기억하지 못했습니다.
AI가 문서를 “깨끗하게 유지”하기 위해 다시 쓰고 있었습니다. 우리는 그 변화가 더 나아 보였기 때문에 받아들였었습니다.
하지만 각 재작성은 컨텍스트를 지워버렸고, 각 단순화는 우리가 잊고 있던 제약 조건을 제거했습니다.
우리는 빠르게 움직였지만, 뒤돌아볼 수 있는 능력을 잃어버렸습니다.
나쁜 문서화의 실제 비용
나쁜 문서화는 단순히 오래된 텍스트를 의미하지 않는다. 다음과 같은 문제를 낳는다:
- 명확한 진실의 출처가 없음 — 여러 문서가 권위를 주장함
- 조용한 덮어쓰기 — 과거 결정이 흔적 없이 사라짐
- 결론에서 맥락이 제거됨 — “우리는 X를 결정했다”는 “Y가 불가능했기 때문에”라는 이유 없이 제시됨
- 시간이 흐를수록 책임이 흐려짐 — 누가 이 결정을 내렸는가? 누가 변경할 수 있는가?
AI 이전에는 이러한 손상이 천천히 누적되었다. 사람들은 기억, 복도 대화, 조직 내 지식으로 보완했다.
AI는 그 완충 역할을 없앴다. 모든 문서를 동등하게 권위 있는 것으로 취급한다. 어느 결정이 임시였는지, 어느 제약이 더 이상 적용되지 않는지 추측할 수 없다.
그래서 숨겨진 비용이 즉시 드러났다:
결정 마찰은 가장 비싼 비효율 형태이다.
속도는 생산성이 아니다
대부분의 생산성 도구는 출력 속도를 최적화합니다.
AI는 그 부분에 매우 뛰어납니다.
하지만 경계 없는 속도는 새로운 종류의 낭비를 초래합니다:
- 중요한 맥락을 무시하는 자신감 있는 답변
- 원래 의도보다 범위를 조용히 확장하는 솔루션
- 최종적인 것처럼 보이지만 검증되지 않은 결정
- 완전해 보이지만 3개월 후에는 사용할 수 없는 문서
진정한 생산성은 더 많은 산출물을 만드는 것이 아니라 다음과 같습니다:
- 재작업 감소 — 같은 결정을 두 번 하지 않기
- 결정의 안전성 향상 — 무엇을 바꿀 수 있는지 알기
- 인지 부하 감소 — 문서를 신뢰하기
- 시간에 따른 의도 보존 — 왜를 이해하고 무엇만이 아니라
그리고 문서는 이 모든 것의 중심에 있습니다.
What we changed: documentation as a system, not text
우리는 문서를 “콘텐츠”가 아니라 인프라스트럭처로 다루기 시작했습니다.
인프라스트럭처는:
- 맥락을 보존하고, 결론만이 아니라
- 책임을 추적하며, 결과만이 아니라
- 불확실성을 명시하고, 숨기지 않으며
- 조용한 변경을 거부 — 모든 편집이 보이도록 하고
- 판단이 필요할 때 멈춤
우리가 만든 구체적인 변화들
- 모든 문서는 이제 라이프사이클을 가짐 – Active / Deprecated / Archived – 삭제되지 않고, 전환만 이루어짐
- 과거 결정은 절대 덮어쓰지 않음 – 결정이 바뀔 때는 기존 것을 deprecated 로 표시하고 새 결정을 작성합니다. 히스토리는 그대로 남습니다.
- 가정은 가정으로 라벨링 – 주장에
[Explicit],[Inferred],[Assumed]태그를 붙입니다. - AI가 구조와 히스토리를 관리 – 재구성, 요약, 포맷은 가능하지만, 결정을 내릴 수는 없습니다.
이는 AI를 통제하기 위한 것이 아니라 신뢰를 재구축하기 위한 것이었습니다.
우리 AI가 가장 생산적인 일
때때로, 우리 AI는 아무것도 하지 않습니다.
멈추고 다음과 같이 말합니다:
- “이 변경은 현재 범위 밖의 결정에 영향을 미칩니다. 인간 검토가 필요합니다.”
- “이 문서는 이전 제약과 충돌합니다. 어느 것이 우선인가요?”
처음에는 이것이 마찰처럼 느껴졌습니다. 우리는 AI가 문제를 해결하길 원했지, 더 많은 질문을 만들길 원하지 않았습니다.
하지만 시간이 지나면서 그 효과는 부인할 수 없었습니다:
- “완료된” 작업의 긴급한 되돌림이 감소
- 더 깔끔한 결정 경계
- 전체적인 진행 속도 향상
역설이 명확해졌습니다: 일찍 멈추는 것이 나중에 고치는 것보다 빠릅니다.
이것이 모두에게 해당되지 않는 이유
AI가 다음을 하길 원한다면:
- 당신을 대신해 결정하기
- 불확실성을 완화하기
- 무슨 일이든 항상 전진하기
이 접근 방식은 불편하게 느껴질 것입니다.
전제합니다:
- 인간이 판단에 대한 책임을 유지한다
- 경계가 속도보다 중요하다
- 생산성은 누적되는 것이며 즉각적인 것이 아니다
때때로 가장 빠른 길이 속도를 늦추고 명확히 하는 것임을 받아들여야 합니다.
하지만 AI가 시스템을 동시에 더 빠르고 더 취약하게 만들었다고 느낀 적이 있다면—
아무도 왜 결정을 내렸는지 기억하지 못해 일주일 치 작업을 되돌려야 했던 적이 있다면—
“어떤 버전이 맞나요?”라고 물었을 때 세 가지 다른 답을 받았다면—
이미 알고 있을 겁니다:
- 문서화는 번거로운 일이 아니다.
- 그것은 당신의 생산성 엔진이다.
전환
AI는 문서를 깨뜨린 것이 아니다. AI는 문서의 중요성을 무시할 수 없게 만들었다.
수년간 우리는 인간이 빈틈을 메워 주었기 때문에 형편없는 문서에도 버틸 수 있었다.
AI는 모든 빈틈을 드러냈다. 모든 모호함을. 모든 묵인된 가정을.
그는 우리에게 질문하게 만들었다: 문서가 실제로 제대로 작동한다는 것은 무엇을 의미할까?
답은… (원본 출처에서 잘린 부분)
R wasn't about better writing. It was about better infrastructure.
**Documentation isn't about describing what you did.**
**It's about preserving your ability to decide what to do next.**
That's the problem AI made visible.