AI에 의한 개발 속도를 문서 업데이트가 따라가지 못하고 있다.

Claude Code에게 새로운 기능을 만들어 달라고 했더니, 예상과 다른 동작이 발생하여 여러 번의 재작업(rework)이 발생했다. 원인을 추적해 보니, 문서에 적혀 있던 전제가 오래된 것이었다. Claude Code는 그것을 의심하지 않고 그대로 믿고 구현했다. 결국 무의미한 토큰과 시간을 낭비하게 되었다.

인간이라면 "어라, 이거 정말 맞나?" 하고 한 번쯤 코드를 확인하러 간다. 하지만 AI는 적혀 있는 대로 동작한다. 이 차이는 개발 속도가 빨라질수록 치명적인 약점이 된다.

그래서 발상을 전환했다. "노후화시키지 않기"를 노력하는 것이 아니라, "노후화되어도 실질적인 피해가 발생하지 않는" 문서의 형태를 만드는 것이다.

한 일은 간단하다. 문서에 적는 내용을 "개요·지도·이유"의 세 가지로 압축하고, 상세한 사양(specification)은 코드와 테스트가 보장하도록 했다.

문서에 남기는 것은 다음 세 가지만으로 제한했다.

전체상을 파악하기 위한 읽기물. 상세한 내용에는 들어가지 않는다. "상세 내용은 코드와 테스트를 참조"라고 단정 짓는 것이 중요하며, 여기에 사양을 쓰기 시작하면 끝이 없어진다.

의존 관계(dependency)·데이터 흐름(data flow)·부작용(side effect)이 어디에 있는지를 명시한다. 다음에 이 기능을 만질 사람이 파일을 찾아 헤매지 않도록 하기 위한 정보이다.

설계 판단·제약 사항·"일부러 하지 않은 것". 이 부분은 코드를 읽어도 알 수 없는 정보이므로, 사실 문서에 적을 가치가 가장 높은 부분이다. 반대로 말하면, 코드를 읽으면 알 수 있는 것은 여기에 적지 않는다.

데이터 구조·유효성 검사(validation)·경계값과 같은 "사양"은 문서에 적지 않기로 결정했다.

이유는 단순하다. 사양은 코드와 함께 계속 변하기 때문이다. 문서에 적는 순간부터 그것은 노후화의 카운트다운이 시작된다. 그리고 AI는 그 카운트다운을 눈치채지 못한 채, 오래된 사양 그대로 구현이나 수정을 진행해 버린다.

반면, 테스트는 코드와 함께 업데이트되지 않으면 동작하지 않는다. 즉 사양과 테스트는 어긋나면 깨지는 관계에 있고, 사양과 문서는 어긋나도 아무도 눈치채지 못하는 관계에 있다. 그렇다면 사양의 위치는 자연스럽게 테스트 쪽이 된다.

같은 발상으로, 동일한 설계 판단의 이유를 여러 문서에 중복해서 적는 것도 그만두었다. 이유가 두 곳에 있으면 수정할 때 한쪽만 수정하여 모순이 발생한다. 하나의 설계 판단은 한 곳에 모아두면, 애초에 "어느 쪽이 맞는지 알 수 없게 되는" 사고가 일어날 리 없다.

• 이 코드가 무엇을 하는지 설명할 수 있는가
• 다음에 만질 사람이 어디를 보면 되는지 알 수 있게 되어 있는가
• 왜 이런 설계를 했는지, 변경하면 무엇이 깨지는지가 적혀 있는가
• 반대로, 적지 않아도 될 사양까지 적어버리지는 않았는가

AI가 개발의 주체가 되어갈수록, 문서는 "정확함을 유지하는 것"보다 "틀리더라도 피해가 적은 것"이 더 중요해진다고 느끼고 있다.