Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
본 기사는 정보가 분산되는 문제를 해결하는 'SSOT(Single Source of Truth)' 개념을 소개합니다. 특히 Markdown 에디터 Obsidian을 SSOT 허브로 삼고, Python 스크립트를 이용해 GitHub 공개 리포지토리로 자동 동기화하는 개발 가이드라인 관리 구조를 초보자도 이해하기 쉽게 설명합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기시스템 개발이나 문서 관리 과정에서 '최신 정보가 어디에 있는지 알 수 없다'는 문제에 직면해 본 적이 없으신가요? 요구사항 정의서는 A 툴에, 설계도는 B 툴에, 소스코드 설명은 각 리포지토리의 README에, 그리고 개인 메모는 로컬에...와 같이 정보가 여기저기 흩어져 버리는 현상입니다.
이를 해결하는 아키텍처 개념이 바로 'SSOT(Single Source of Truth)'입니다.
본 기사에서는 AI 에이전트 개발 가이드라인 관리를 주제로, Markdown 에디터인 'Obsidian'을 정보의 중심(SSOT)으로 삼고, Python 스크립트를 이용해 GitHub상의 공개용 리포지토리로 자동 동기화하는 구조에 대해 초보자도 이해하기 쉽게 설명합니다.
SSOT란 '신뢰할 수 있는 유일한 정보원'을 의미하는 설계 사상입니다. 시스템 아키텍처나 데이터베이스 설계 분야뿐만 아니라, 개인의 지식 베이스(knowledge base)나 팀 내 문서 관리에 적용 가능한 강력한 개념입니다.
예를 들어, 어떤 API의 명세서를 Notion으로 관리하고 개발자용 상세 문서를 GitHub로 관리한다고 가정해 봅시다. 명세가 변경되었을 때 두 가지 툴 모두를 업데이트해야 하며, 어느 한쪽의 업데이트를 잊으면 '어떤 정보가 정확한지?'라는 정보 불일치(inconsistency)가 발생합니다.
SSOT의 관점에 따라 '이 정보는 여기(유일한 장소)에서 관리한다'고 규칙을 정함으로써, 정보의 확실성이 보장되고 유지보수 노력도 크게 줄어듭니다.
이번 실습 예시인 'ssot-guide'와 같은 프로젝트에서는 Obsidian을 SSOT의 허브(중심)로 채택하고 있습니다.
Obsidian은 로컬 환경에 저장되는 일반 텍스트(Markdown 파일)로 지식 베이스를 구축할 수 있는 도구입니다. 클라우드 서비스와 달리, 다음과 같은 이유로 SSOT로서 매우 우수합니다.
저 자신의 실무 경험에서도 머릿속의 생각을 정리하는 '개인 노트'와 팀에서 공유하는 '공식 문서'를 별도의 툴로 관리하는 것은 비효율적입니다. Obsidian에서 작성한 메모를 그대로 SSOT로 삼고, 적절한 포맷으로 변환하여 공개하는 구조가 있다면 정보 운영이 가장 원활합니다.
Obsidian에 작성된 내용을 '유일한 정보원(SSOT)'으로 삼아, 이를 GitHub Pages 등에서 공개할 별도의 리포지토리로 동기화하는 구조를 구축해 봅시다.
실제 대상 리포지토리의 커밋 히스토리를 보면, 다음과 같은 메시지가 짧은 시간 동안 여러 개 나열되어 있는 것을 알 수 있습니다.
sync: obsidian-ssot 70f1d41 → ssot-guide
sync: obsidian-ssot 0b45a1e → ssot-guide
이는 'Obsidian 관리용 리포지토리(동기화 원본)'에서 '공개용 리포지토리(동기화 대상)'로 데이터가 동기화된 흔적입니다. 파일을 수동으로 복사 붙여넣기 하는 것이 아니라, 자동적이거나 반자동적으로 스크립트가 실행되고 있음을 짐작할 수 있습니다.
이러한 동기화 처리는 Python의 표준 라이브러리인 shutil (파일 조작)과 subprocess (Git 명령어 실행)을 조합함으로써, 수십 줄의 코드로 구현이 가능합니다.
아래에 지정된 디렉토리의 파일을 동기화하고 Git에 커밋 및 푸시하는 Python 스크립트 예시를 보여드립니다.
import subprocess
import shutil
from pathlib import Path
...
이 스크립트의 핵심은 subprocess 모듈을 사용하여 Git 명령어를 Python에서 직접 실행하고 있다는 점입니다. 또한, shutil.copytree를 이용해 폴더 전체를 복사함으로써 삭제된 파일 관리도 정확하게 수행할 수 있습니다.
이 스크립트를 CI/CD 툴(GitHub Actions 등)로 주기적으로 실행하거나 로컬 환경의 Cron으로 돌림으로써, 다음과 같은 압도적인 이점을 얻을 수 있습니다.
불필요한 파일 제외: Obsidian에는 개인 메모나 일기, 설정 파일 등도 혼재되어 있습니다. '공개용 폴더'만 동기화함으로써, 정보 유출을 방지하면서 필요한 정보만을 공개할 수 있습니다. -
변경 이력 자동 기록: Python 스크립트가 자동으로 커밋 메시지를 추가하여 푸시하기 때문에, 문서의 변경 이력이 GitHub 상에 시간 순서대로 깔끔하게 축적됩니다.
'정보가 여기저기 흩어지는' 문제는 개발 속도와 품질을 크게 저하시킵니다.
본 기사에서 소개했듯이, Obsidian을 'SSOT(Single Source of Truth, 유일한 정보원)'으로 중앙에 배치하고 Python 스크립트로 공개용 리포지토리로 동기화하는 아키텍처를 채택한다면, 정보의 일관성을 유지하면서 스트레스가 없는 문서 운영이 가능해집니다.
'정보를 한 곳에 모으고 자동으로 배포한다'는 SSOT의 개념은 개인 개발부터 팀 개발까지 폭넓게 응용할 수 있습니다. 우선 작은 프로젝트로 Obsidian과 Python을 사용한 자동 동기화 시스템을 시도해보시는 것은 어떨까요?
본 기사는 개인 Zenn에도 공개되어 있습니다.