Git SSoT ① — 왜 하나의 맥락을 쌓는가 · DK 기술 블로그

TL;DR

결정이랑 규칙을 위키가 아니라 코드 옆에(git) 쌓는 얘기입니다.
문서 종류는 adr / rfc / spec / prd / policy 다섯이면 충분합니다. 더 늘리면 그게 또 짐이 됩니다.
폴더 구조부터 짜지 마세요. scope 정하면 폴더는 알아서 따라옵니다.
AI한테 일 시키기 시작하면서 이게 선택이 아니게 됐습니다.

들어가며

3개월 전에 짠 스크립트를 다시 열었다가 “내가 왜 이렇게 했지”로 30분을 날린 적이 있습니다. 혼자 하는 프로젝트에서도 이런데, 사람 여럿이 붙으면 이게 인원수만큼 곱해집니다. 결정은 메신저 어딘가로 흘러가고, 명세는 누구 노트북에만 있고, 규칙이라는 건 “전에 그렇게 하기로 했잖아요” 한마디로 남습니다.

SSoT라고 거창하게 부르지만, 제 입장에서 그냥 “결정을 코드 옆에 두는 습관”입니다. 위키에 따로 적지 말고, 코드 고치는 그 PR에서 문서도 같이 고치자는 거죠. 별거 아닌 것 같은데 이거 하나로 3개월 뒤의 내가 덜 헤맵니다.

위키는 왜 안 되나

전에 팀 위키를 열심히 썼습니다. 그런데 반년쯤 지나니 위키가 거짓말을 하고 있더군요. 코드는 벌써 세 번 갈아엎었는데 위키 문서는 첫 버전 그대로. 아무도 안 고쳤으니까요. 낡아도 티가 안 나니 아무도 안 고치고, 아무도 안 고치니 더 낡습니다.

git에 넣으면 이게 자연스럽게 풀립니다. 기능 바꾸는 PR에서 그 기능 명세도 같이 diff에 올라오니까, 리뷰어가 “어 이거 문서도 고쳐야 하는 거 아냐?” 하고 잡아줍니다. 문서랑 코드가 어긋날 틈이 좁아지는 거죠. 메신저는 검색은 되는데 “지금도 유효한 결정”이랑 “그때 그냥 해본 소리”가 안 갈립니다. 머릿속에 있는 건 그 사람 나가면 같이 나가고요.

문서는 다섯 종류면 됩니다

문서를 자유롭게 만들라고 하면 사람들이 진짜 자유롭게 만듭니다. 그러다 보면 문서 찾는 게 또 일이 돼요. 저는 다섯 종류로 못 박아뒀습니다.

종류	한 줄 질문
adr	“우리가 이거 왜 이렇게 정했더라?”
rfc	“이렇게 하는 거 어때요?” (아직 논의 중)
spec	“이거 정확히 어떻게 돌아가는 거야?”
prd	“이걸 애초에 왜 만드는 거지?”
policy	“이건 그냥 무조건 지켜야 하는 거?”

경계가 애매할 때가 있는데, 사실 같은 주제가 상태 따라 종류를 갈아입습니다. rfc에서 떠들다 합의되면 adr로 굳고, prd의 “무엇을”이 구체화되면 spec으로 내려가요. 이 흐름만 감 잡으면 “이거 어디다 적지”로 고민할 일이 거의 없어집니다. 처음엔 저도 매번 헷갈렸는데, 몇 번 쓰다 보니 손이 알아서 갑니다.

폴더 말고 scope부터

폴더 구조부터 그리면 십중팔구 오버합니다. 저도 처음엔 예쁜 트리 만드느라 반나절 썼는데, 정작 문서 두 개 넣고 나니 그 구조가 안 맞더군요.

그래서 순서를 바꿨습니다. 이 문서가 어디까지 영향을 주나(scope)부터 정합니다.

ssot/
  global/          # 저장소 전체에 적용 (policy 대부분)
    policy/
    adr/
  <서비스명>/       # 이 서비스 안에서만 유효
    prd/
    spec/
    rfc/

scope가 global이면 다 같이 지키는 거, 특정 서비스면 그 안에서만 도는 규칙. 폴더 위치만 봐도 “이게 나한테 해당되는 규칙인가”가 보입니다. 폴더는 scope 담는 그릇일 뿐이에요. 그릇부터 고르지 마세요.

AI가 끼면서 얘기가 달라졌다

예전엔 SSoT가 “사람이 문서 잘 찾게” 하는 정리정돈이었습니다. 요즘은 좀 다릅니다.

코딩 에이전트한테 “결제 모듈 좀 고쳐줘” 하면, 걔는 우리 프로젝트 규칙도 과거 결정도 모르니까 그냥 교과서적인 일반론으로 짭니다. 그럴듯한데 우리 맥락엔 안 맞는 코드요. 근데 관련 spec이랑 adr, policy가 git에 정리돼 있으면 그걸 컨텍스트로 던져주는 것만으로 결과물이 확 달라집니다. 사람이랑 AI가 같은 문서를 읽게 되는 거죠. E2E 워크플로우에서 티켓이랑 SSoT 문서를 링크로 묶는 이유가 이겁니다.

솔직히 이 부분 때문에 SSoT를 진지하게 다시 보게 됐습니다. 사람 편하자고 하던 걸, 이제는 AI 붙이려고 해야 하는 상황이 된 거죠.

마무리

정리하면 위키 대신 git, 문서는 다섯 종류, 폴더보다 scope 먼저. 세 줄이지만 이거 지키는 팀이 생각보다 드뭅니다.

다음 편은 실제 운영 얘기입니다. front matter로 메타데이터 붙이고, validate-ssot로 검증하고, INDEX로 요약해서 LLM 컨텍스트를 어떻게 다이어트시키는지 — 여기서 재미있는 게 좀 나옵니다.