서론

회사의 정보를 AI 에이전트가 다룰 수 있는 「CompanyOS(회사의 OS)」를 만들려고 하면, 반드시 가장 먼저 부딪히게 되는 질문이 있습니다.

회사의 지식(문서·규정·의사록·코드)을 어디에, 어떤 형태로 두고, AI에게 어떻게 읽히게 할 것인가?

저는 현재 GitHub를 Single Source of Truth(단일 진실 공급원)로 삼고, 거기서 읽어오는 방식을 축으로 생각하고 있습니다. GitHub에 집약하면 이력·리뷰·권한·차이(diff)가 모두 Git의 메커니즘을 타게 되어, 「누가 언제 무엇을 바꿨는지」가 자동으로 남기 때문입니다.

문제는 그 GitHub의 내용을 AI에게 읽히기 직전에 어떻게 보유하고 변환할 것인가입니다. 대략 다음과 같은 3가지 방식이 있습니다.

직접 clone 참조 방식— 서버에 repository를 clone 하여 파일을 그대로 읽음 -
벡터 / 그래프 방식— pg_vector 등으로 embedding(임베딩)화 하여 의미 검색·그래프 방식으로 호출 -
파일 스토리지 / API 방식— 오브젝트 스토리지나 OpenAPI를 통해 파일을 전달

이 기사에서는 이 3가지 방식을 비교표 + 장점 / 단점으로 정리합니다. 결론부터 말씀드리면, **「우선 직접 참조로 시작해서, 양이 늘어나면 벡터를 추가하는 하이브리드 방식이 현실적인 해답」**입니다.

전제: 왜 GitHub를 Single Source of Truth로 만드는가

DB 이야기를 하기 전에 토대를 확인하겠습니다. GitHub를 「정(正)」으로 두는 이점은 다음과 같습니다.

버전 관리： 변경 이력·차이·롤백이 표준 장착되어 있음 -
리뷰： Pull Request를 통해 「지식의 변경」을 인간이 리뷰할 수 있음 -
권한 관리： 리포지토리 / 디렉토리 단위의 액세스 제어 -
플레인 텍스트 중심： Markdown·YAML·코드는 AI가 가장 읽기 쉬운 형식 -
이식성： 벤더 락인(Vendor Lock-in)이 약하며, 언제든 git clone으로 전부 가져올 수 있음

즉, GitHub는 **「원본의 보관 장소」**로서 매우 우수합니다. 반면 GitHub 자체는 「의미로 검색하는」 용도에는 적합하지 않습니다. 여기서 하류의 DB / 스토리지 전략이 중요해집니다.

[GitHub = 원본 / Single Source of Truth]
│ git clone / pull / webhook
↓
...

① 직접 clone 참조 방식

서버(또는 에이전트의 실행 환경)에 git clone을 해두고, 파일을 그대로 읽는 방식입니다. Claude Code와 같은 에이전트가 바로 이 형태로 동작합니다.

서버
└ /repos/company-os ← git pull로 최신화
├ handbook/
...

장점

구축이 가장 빠름： git clone을 하기만 하면 됨. 추가 인프라가 거의 필요 없음 -
항상 최신·완전 일치： 원본 그 자체를 읽으므로 정보의 어긋남(동기 지연)이 없음 -
AI와 상성이 좋음： 디렉토리 구조와 index.md를 「지도」로 사용할 수 있음 -
디버깅이 용이： AI가 「어떤 파일을 읽었는지」가 명확하여 추적이 쉬움 -
저렴함： 스토리지 비용과 서버 비용만 발생

단점

확장(Scale)하기 어려움： 수만 파일 규모가 되면 전체 grep이 무거워지고, context(컨텍스트)에 다 담기지 않음 -
의미 검색을 할 수 없음：「해지 시 환불 정책」과 같은 모호한 질의에 취약함 (키워드 일치에 의존) -
동기 운영이 필요： git pull을 실행할 cron / webhook을 직접 준비해야 함 -
대용량에 부적합： 이미지·PDF·바이너리 파일이 많으면 clone 규모가 비대해짐

소중규모(수백수천 파일)에서 우선 동작시키고 싶다면 이것이 가장 좋습니다.

② 벡터 / 그래프 방식 (pg_vector 등)

GitHub의 문서를 청크(chunk)로 분할 → embedding(임베딩)화 → pg_vector에 저장하여 의미로 검색(RAG)하는 방식입니다. 문서 간의 링크를 에지(edge)로 가지면 「그래프처럼」 따라갈 수도 있습니다.

GitHub의 .md
↓ 분할 (chunk)
↓ embedding (예: text-embedding-004 / 768차원)
...

장점

의미 검색 (Semantic Search) 가능: 표현 방식이 달라도 "의미가 가까운" 문서를 찾아낼 수 있음 -
확장성 (Scale): 수만~수백만 개의 청크(chunk)라도 근사 최근접 이웃 탐색 (ANN)을 통해 고속 처리 가능 -
컨텍스트 (Context) 절약: 관련 있는 소수의 청크만 전달하므로 토큰 (token) 사용량을 억제할 수 있음 -
그래프적 탐색: 링크 및 참조 관계를 에지 (edge)로 활용하여 관련 지식을 줄줄이 엮어서 추적 가능 -
횡단 검색: 여러 리포지토리 및 여러 포맷을 한 곳에서 통합 검색 가능

단점

구축 및 운용 비용이 높음: 임베딩 (embedding) 파이프라인, 재인덱싱 (re-indexing), DB 운용이 필요함 -
동기화의 복잡성: GitHub가 업데이트될 때마다 재임베딩 (re-embedding)이 필요함 (차분 검출이 핵심) -
청크 설계의 어려움: 분할 입도(granularity)에 따라 답변 품질이 크게 달라짐 -
원본과의 괴리 리스크: 인덱스가 오래되면 "잘못된 정답"을 반환함 -
임베딩 (embedding) 비용: 업데이트 빈도가 높으면 API 요금이 쌓임

pg_vector나 임베딩 (embedding)의 기초는 여기서 자세히 설명하고 있습니다 → pg_vector로 시작하는 임베딩 입문

③ 파일 스토리지 / API 방식 (OpenAPI · 오브젝트 스토리지)

GitHub의 내용을 오브젝트 스토리지 (S3 등)에 배치하거나, OpenAPI로 정의한 API를 경유하여 파일을 가져오는 방식입니다. "지식에 대한 액세스"를 API로서 추상화하는 것이 목적입니다.

GitHub → CI/CD로 내보내기 → [ Object Storage / API Gateway ]
↓ OpenAPI (GET /docs/{path})
AI / 타 시스템이 HTTP로 가져옴

장점

느슨한 결합 (Loose Coupling) · 재사용 용이: AI 이외의 앱에서도 동일한 API로 지식을 사용할 수 있음 -
대용량 · 바이너리에 강함: 이미지, PDF, 영상도 CDN으로 전송 가능 -
권한을 API 계층에서 제어: 인증, 속도 제한 (rate limiting), 감사 (audit)를 API Gateway에 집약 -
계약이 명확: OpenAPI 스키마가 "지식 액세스 사양서"가 됨

단점

의미 검색은 별도로 필요: 스토리지 단독으로는 ②와 같은 검색을 할 수 없음 -
동기화 레이어가 증가: GitHub → 스토리지로의 내보내기 (CI/CD)가 필수적임 -
오버엔지니어링 (Over-engineering) 되기 쉬움: 소규모일 경우 API화의 이점이 적음 -
비용과 복잡성: Gateway, 스토리지, 인증 기반의 운용 부담이 따름

"여러 시스템에서 회사의 지식을 사용하고 싶다"는 단계에서 효과를 발휘하는, 이른바 배포 레이어의 선택지입니다.

비교표: 3가지 방식 요약

범례: ◎ 능숙 / ○ 보통 / △ 약함 / ✕ 불가·부적합

결론: 페이즈에 맞춰 추가하는 하이브리드가 현실적인 해답

3가지 방식은 "하나만 선택"하는 것이 아니라, GitHub를 정답(Source of Truth)으로 유지하면서 페이즈에 따라 겹쳐 나가는 것이 실무적입니다.

페이즈 1 (시작 단계): 우선 ① 직접 clone 참조로 시작한다. git clone

+index.md

(index.md)만으로도 AI 에이전트는 충분히 작동합니다. 저렴하고 빠르게 검증할 수 있습니다.

• 페이즈 2 (지식이 늘어나는 단계): 전체 텍스트 grep (Full-text grep)이 무거워지고 의미 검색 (Semantic Search)이 필요해지면 ② pg_vector를 추가합니다. GitHub는 원본 상태를 유지하고, pg_vector는 '검색 인덱스 (Search Index)' 역할에 집중하게 합니다.
• 페이즈 3 (전사적 확산 단계): AI 이외의 사내 시스템에서도 사용하고 싶다면 **③ OpenAPI / 스토리지 (Storage)**를 통해 배포 레이어 (Delivery Layer)를 추가합니다.

GitHub (유일한 진실의 원천)
├─ ① clone 참조 …… 초기 구축 · 디버깅 · 최신 상태 확인
├─ ② pg_vector …… 의미 검색 · 대량의 문서
...

핵심은 **"원본은 반드시 GitHub 한 곳"**이라는 원칙을 깨지 않는 것입니다. ②와 ③은 파생 인덱스(Derived Index) 또는 배포 캐시(Delivery Cache)에 불과하며, 설령 데이터가 손상되더라도 GitHub로부터 재생성할 수 있습니다. 이 원칙을 지킨다면 아무리 레이어를 추가하더라도 "진실이 두 개 존재하는 (Two Sources of Truth)" 상태에 빠지지 않습니다.

여러분의 CompanyOS는 지금 원본을 GitHub 한 곳에 유지하고 있습니까? 그리고 AI가 가장 먼저 펼쳐볼 "한 장의 지도 (index.md)"를 가지고 있습니까?

참고 링크

Discussion