왜 AI가 'Over-Documentation'를 당신의 새로운 비밀 무기로 만드는가

Source: Dev.to

(번역할 텍스트가 제공되지 않았습니다. 번역이 필요한 본문을 알려주시면 한국어로 번역해 드리겠습니다.)

시스템의 시간 경과에 따른 퇴화

모든 시스템은 시간이 지남에 따라 퇴화합니다. 이는 보편적이며—일본, 미국, 유럽… 어디든 상관없습니다.

문제는 시스템이 퇴화하는가가 아니라 왜 퇴화하는가 입니다.

Initial build:   Coherent design with clear intent
      ↓
Change 1:       “Working” fix by someone who doesn’t know the intent
      ↓
Change 2:       Fix to accommodate Change 1
      ↓
Change 3:       “Don’t know why, but it breaks without this”
      ↓
Critical mass:   Nobody understands the whole system
      ↓
End state:       Touch it and it breaks. Don’t touch it and it rots.

각 변경은 “올바른” 것입니다. 그러나 원래 의도와 맞지 않는 변경이 누적되면서 시스템을 파괴합니다.

AI가 상황을 악화시킨다, 개선하지 않는다

Before AI:
  Code generation ████░░░░░░   Quality check ████░░░░░░

After AI:
  Code generation ██████████   Quality check ████░░░░░░
                                   ↑
                             Still the same

AI는 생산성을 가속화하지만, 이해를 가속화하지는 않습니다.

• “AI가 작성했으니 아마 괜찮을 거야” → 검토 감소
• 코드 생성 속도 증가 → 의도 없는 변경이 더 빠르게 누적
• 세션 리셋 → AI가 왜 결정을 내렸는지 기억하지 못함

AI는 훌륭한 “도구”이지만, “기억”은 아닙니다.

대부분의 AI 논의가 놓치는 점

대부분의 개발자들은 아직도 “와, 정말 빠르다!” 단계에 있습니다. 문제는 실제 사용 몇 달 후에야 드러납니다—어떤 것이 왜 그렇게 구축되었는지 이해하려고 할 때, 아무도 모른다는 사실을 깨닫게 됩니다.

해결책: 인프라로서의 의사결정

핵심 통찰: AI는 기억할 수 없지만, AI는 읽을 수 있다.

AI 이전

Records exist → Humans read them → Understanding → Action
                     ↑
                 Bottleneck (too slow, too much)

인간은 현실적으로 수개월에 걸친 의사결정 기록을 읽을 수 없었기 때문에, 상세한 기록은 거의 보관되지 않았다.

AI 이후

Records exist → AI reads them → Explains to humans → Action

AI는 “읽기” 비용을 제로로 만들기 때문에 이제 모든 것을 기록할 수 있다.

새로운 아키텍처

Human + AI → Decision → History (Git)
                           ↓
                      (Persists)
                           ↓
New person + AI → Reads history → Reconstructs intent

핵심 원칙 (아카이브 담당자에게서 차용)

이것은 새로운 아이디어가 아닙니다; 도서관과 정부는 수십 년 동안 이를 사용해 왔습니다. 우리는 이를 코드에 적용하고 있을 뿐입니다.

기록되는 내용

모든 결정에는 다음이 포함됩니다:

• 무엇이 결정되었는가
• 왜 결정되었는가
• 무엇이 이전과 달라졌는가
• 무엇이 남아 있는가

기록되지 않는 항목

• 세션 로그
• 브레인스토밍
• 실패한 시도
• 탐색

탐색은 허용됩니다. 지속성은 허용되지 않습니다.

핵심 규칙: 탐색과 결정을 분리하기

Session log:      Exploration + failures + decisions + chat → all mixed
Decision history: Decisions only → single authoritative past

AI에게는 쓰여진 모든 것이 동등하게 “실제”로 간주됩니다. 탐색과 결정을 섞어버리면, 거부된 아이디어가 다시 유효한 옵션으로 떠오를 수 있습니다.

새로운 사람들이 시스템을 배우는 방법

구식 방식

New person → Reads documentation → Asks senior engineer → Maybe understands

새로운 방식

New person → Asks AI: “Why is this designed this way?”
AI → Reads decision history → Explains with context

새로운 사람은 더 이상 “전문가”를 찾아다닐 필요가 없습니다. 전문가의 결정은 구조에 보존됩니다.

Why This Only Works Now

Documentation could be written. It couldn’t be read. AI changed that.

패러다임 전환

#은 인간을 위한 것이다  
기록은 AI가 읽기 위해 존재한다  

**Handoff**은 사람‑대‑사람이다  
**Handoff**은 구조‑대‑AI‑대‑사람이다  

문서는 적을수록 좋다  
모든 것을 기록하라; AI가 필요한 것을 추출한다  

왜 아무도 이것에 대해 이야기하지 않을까

• 시간 범위가 너무 짧음 — 대부분의 AI 논의는 단일 세션에 초점을 맞춤
• 대화에 참여하는 사람이 잘못됨 — 마케터와 연구자, 유지보수 엔지니어가 아님
• 문제가 나타나기까지 시간이 걸림 — 6개월 이상 지나야 눈에 띔
• 교차 분야 지식 필요 — AI + 소프트웨어 엔지니어링 + 아카이브 사고

핵심 요약

AI는 여러분의 시스템이 아무도 이해하지 못하는 레거시가 되는 것을 막지 못합니다.

구조가 할 것입니다.

질문은 “AI를 어떻게 더 잘 활용할까?” 가 아니라
“시간, 사람, 그리고 AI 세션을 넘어 의도가 살아남도록 하기 위해 어떤 인프라가 필요할까?” 입니다.

답변

• Decisions (not sessions) become history → 결정(세션이 아니라)은 역사가 됩니다
• Git is the single authority → Git은 유일한 권위입니다
• AI generates and reads the records → AI는 기록을 생성하고 읽습니다
• Humans verify and make trade‑off calls → 인간은 검증하고 트레이드오프 결정을 내립니다

이것이 시스템이 원래 구축자를 넘어 살아남는 방법입니다.

이 글은 구조적 접근 방식이 AI‑지원 개발에서 프롬프트 최적화를 능가하는 방법에 대한 지속적인 탐구의 일부입니다. 실질적인 구현에 관심이 있다면 제 “Context as Infrastructure” 시리즈를 확인해 보세요.

How do you preserve intent in your system?