SSOT도 실측 확인이 필수다

서버 봇 공통 지침과 인프라 문서의 "단일 진실 공급원(SSOT)"을 명시하고, 거기에 맹신금지/실측대조 규칙을 덧붙였다. 동시에 오래된 심링크를 정정했다.

왜 SSOT를 명시했는가

조직 규모가 작을 때는 문서 한두 개, 대화 한번으로 충분하다. 그런데 자동화 봇이 늘어나고 서버가 여러 개가 되면, 각 봇이 다른 지침을 따르거나 문서를 다르게 해석하는 일이 발생한다. 어떤 봇은 낡은 규칙을 따르고, 어떤 봇은 새 규칙을 따르고, 온콜 엔지니어는 어느 것이 정답인지 모른다.

이걸 막기 위해 SSOT를 명시하기로 했다.

단일진실 = ops/docs/server-global-CLAUDE.md
서버에서 git pull 하면 항상 최신
각 봇의 로컬 CLAUDE.md 는 이 파일로의 symlink

깔끔하다. 모든 봇이 같은 규칙을 로드한다.

문제는 "맹신"이었다

그런데 1주일쯤 지나니 문제가 보였다:

• mac 에서 문서를 수정하고 push 했는데, 누가 서버에서 git pull 을 까먹음
• symlink 타겟 경로가 변경되었는데, 오래된 symlink는 여전히 바라보고 있음
• 한 봇은 로컬에서 CLAUDE.md 를 직접 수정해서 단일성이 깨짐
• 인프라 문서는 1주일 전 상태인데, 실제 배포된 코드는 다름

SSOT를 정의했다고 해서 자동으로 신뢰도가 올라가는 게 아니었다. 오히려 SSOT를 "맹신"하면 불일치를 놓치기가 쉬워진다. "문서에 이렇게 나와 있으니 맞겠지" 라고 넘어가는 것.

해법: 맹신금지 규칙 추가

문서에 직접 썼다.

⚠️ 토큰 비용 — 전 봇 호출마다 로드된다.
⚠️ 그러나 실제 배포 상태는 따로 확인 필요
   (symlink 깨짐, git pull 누락, 로컬 편집 등)

SSOT를 정의하되, 그것도 검증 대상으로 취급하기로 했다.

symlink stale 을 정정하면서, 앞으로 symlink 가 깨지더라도 "오래된 심링크가 있을 수 있다"는 가정 하에 확인하도록 명시했다.

팀 임팩트

온콜 엔지니어 입장에서는:
- 전에: "문서에 이렇게 나와 있으니까 이게 맞겠지" → 실제와 다름 → 30분 삽질
- 지금: "문서와 실제가 다를 수 있다" → 바로 git log/심링크 확인 → 5분 안에 해결

자동화 신뢰도도 올라간다. 봇이 실행되다가 뜬금없이 낡은 경로를 참조하면, 봇이 깨졌다고 생각하지 않고 "SSOT 도 검증하자"라는 체계적 사고가 나온다.

배운 점

SSOT는 "절대 진실"이 아니라 "최소한의 다중성을 제거하기 위한 허브"일 뿐이다. 그 자체도 "싱크 오류", "타겟 변경", "로컬 오버라이드" 같은 엔트로피에 노출된다.

따라서:
- SSOT 를 정의할 때: 그것도 오류 가능성을 문서에 명시
- 자동화 규칙을 쓸 때: "이 문서가 source of truth" 라고 선언하되, 곁에 "그러나 실측도 확인" 이라고 썼을 것 (토큰 낭비 아님)
- 팀이 커질수록: SSOT 를 정의하는 것보다, "SSOT 도 검증 대상"이라는 문화가 더 중요

다음

🛒 이 글과 어울리는 추천 상품

• 4K모니터 쿠팡에서 보기 →
• 커피머신 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.