KB가 진짜 Single Source of Truth가 되기까지

이 글은 SEMO 구축기 시리즈의 일곱 번째 글입니다.

팀 지식이 사방에 흩어져 있던 시절

봇 팀이 7개로 늘어나면서 새로운 문제가 터졌습니다. 팀 지식이 어디에 있는지 아무도 몰랐습니다. 서비스 상태는 Notion에, 기술 스택은 README에, 의사결정은 Slack 스레드에, PO 정보는 스프레드시트에. 봇에게 '이 서비스 기술 스택이 뭐야?'라고 물으면 매번 다른 곳을 뒤져야 했습니다.

더 심각한 문제는 정보의 불일치였습니다. Notion에는 React라고 적혀 있는데 실제로는 Next.js로 전환된 경우, Slack에서 논의된 아키텍처 결정이 문서에 반영되지 않은 경우가 빈번했습니다.

KB(Knowledge Base) 아키텍처

PostgreSQL + 벡터 임베딩

모든 팀 지식을 하나의 시스템에 모았습니다. PostgreSQL 기반의 KB는 텍스트 저장과 동시에 벡터 임베딩을 생성해 시맨틱 검색을 지원합니다. '인증 관련 결정'이라고 검색하면 키워드 매칭이 아니라 의미 기반으로 관련 문서를 찾아줍니다.

온톨로지 기반 도메인 구조

KB는 도메인/키/서브키 구조로 조직됩니다. semicolon 도메인에는 조직 공통 정보가, introduction이나 axoracle 같은 서비스 도메인에는 서비스별 정보가 들어갑니다. 각 도메인 타입(organization, service, bot 등)마다 허용된 키 스키마가 있어 구조적 일관성을 강제합니다.

CLI 기반 읽기/쓰기

봇과 사람 모두 semo kb get/search/upsert CLI로 KB에 접근합니다. 예를 들어 semo kb get introduction base-information으로 서비스 기본 정보를 조회하고, semo kb upsert semo decision/architecture-v5으로 의사결정을 기록합니다. 모든 쓰기 시 임베딩이 자동 생성되어 검색이 가능합니다.

3자 동기화: KB가 SSOT인 이유

KB가 진정한 Single Source of Truth가 되려면 다른 저장소와 동기화되어야 합니다. SEMO에서는 소스코드 ↔ KB(DB) ↔ 봇 로컬 파일 세 축의 동기화를 '3자 동기화 규칙'으로 강제합니다.

• 소스코드 변경 시: KB와 봇 파일에 반영할 내용이 있는지 확인

• KB 변경 시: 소스코드나 봇 파일과 불일치가 생기지 않는지 확인

• 봇 파일 변경 시: KB에 기록할 사항이 있는지 확인

이 규칙은 Enforcement Hook으로 자동 검증됩니다. 봇이 의사결정을 내리고 KB에 기록하지 않으면 decision-reminder.sh 훅이 차단합니다. KB 조회 없이 도메인 질문에 답하면 kb-first-guard.sh가 차단합니다. 시스템이 규율을 강제하는 겁니다.

KB 위에 구축된 자율 실행 시스템—Cron과 Commitment—은 다음 글에서 다룹니다.