SSOT는 문서가 아니라 삭제 작업이었다

같은 표가 세 군데에 있었습니다.

처음엔 편했습니다.
한 문서는 기획자가 보고, 한 문서는 개발자가 보고, 한 문서는 에이전트가 읽었습니다.
각자 필요한 말투로 정리돼 있으니 좋아 보였습니다.

문제는 셋이 동시에 조금씩 달라졌다는 점입니다.

어느 문서에는 주간 요약, 다른 문서에는 주간 리포트, 또 다른 곳에는 7일 요약이라고 적혀 있었습니다.
셋 다 같은 기능을 가리키는 것 같았지만, 구현하는 사람 입장에서는 같은지 다른지 알 수 없었습니다.

그때 저는 SSOT를 “정본 문서를 하나 더 잘 쓰는 일”이라고 생각했습니다.

틀렸습니다.

SSOT는 나머지를 지우는 일이었습니다.

링크가 아니라 복사가 문제였습니다

처음엔 새 정본을 만들었습니다.

이 문서가 최종입니다.
여기만 보세요.
이렇게 적었습니다.
그런데 예전 문서들은 그대로 남아 있었습니다.
심지어 검색에는 예전 문서가 더 잘 걸렸습니다.

며칠 뒤 누군가는 옛 표를 보고 작업했습니다.
당연히 틀렸습니다.
그 사람 잘못이라고 하기는 어려웠습니다.
문서가 있었고, 문서는 그럴듯했고, 아무 곳에도 “이 표는 폐기됨”이라고 강하게 표시돼 있지 않았습니다.

그때 SSOT의 진짜 작업이 보였습니다.

새 문서를 쓰는 것보다, 옛 복사본의 권위를 제거하는 게 더 중요했습니다.

정본은 하나, 나머지는 소비자

제가 지금 쓰는 방식은 단순합니다.

첫째, 정본을 하나만 둡니다.

둘째, 나머지 문서는 같은 내용을 다시 쓰지 않습니다.

셋째, 필요하면 링크하거나 생성된 산출물로 만듭니다.

canonical-routing.md  ← 진짜 표
README.md             ← 링크만
agent-entrypoint.md   ← 링크만
generated-summary.md  ← 빌드로 재생성

중요한 건 “같은 정보를 더 보기 좋게 다시 적기”를 참는 겁니다.
다시 적는 순간 두 번째 진실이 생깁니다.

처음엔 이게 좀 불편했습니다.
읽는 사람마다 원하는 형태가 다르니까요.
근데 복사본을 허용하면 나중에 더 큰 비용을 냅니다.
사람은 최신 문서를 읽었다고 생각하고, 실제로는 낡은 문서를 읽습니다.

코드에서도 똑같이 터졌습니다

문서만 그런 게 아니었습니다.

상태를 바꾸는 경로가 두 개 있을 때도 같은 문제가 생겼습니다.
A 경로에서 pending 상태를 바꾸고, B 경로에서도 비슷한 상태를 바꿉니다.
둘 다 선의입니다.
둘 다 “혹시 몰라서” 들어간 가드입니다.

결과는 패치 루프였습니다.

A를 고치면 B에서 터졌습니다.
B를 막으면 C 같은 우회 경로가 보였습니다.
그때 필요한 건 가드 하나가 아니라 writer 하나였습니다.

이 상태는 누가 쓴다?
나머지는 읽기만 하는가?
동일 이벤트가 두 번 들어오면 같은 결과가 나는가?

이 질문에 답하지 못하면 아직 SSOT가 아닙니다.
그냥 “중요해 보이는 문서”나 “제일 많이 쓰는 코드 경로”일 뿐입니다.

삭제가 제일 무서웠습니다

SSOT 작업에서 가장 무서운 순간은 삭제입니다.

복사본을 지우거나, 옛 경로를 deprecated로 바꾸거나, fallback writer를 끊을 때 손이 멈춥니다.
혹시 누가 쓰고 있으면 어떡하지.
혹시 이 문서만 보고 있으면 어떡하지.

그래서 삭제 전에 grep을 합니다.
호출자를 봅니다.
링크를 봅니다.
필요하면 한동안 “이 문서는 폐기됨” 배너만 남깁니다.

하지만 끝까지 남겨두지는 않습니다.

정본이 둘이면 언젠가 둘 다 틀립니다.

요즘 SSOT라는 말을 보면 저는 먼저 묻습니다.

“정본을 어디에 쓸까요?”가 아닙니다.

“무엇을 지울까요?”입니다.