SSOT — 어디에 두는가

SSOT (Single Source of Truth) = "같은 사실이 여러 곳에 있으면 하나만 진실이라고 약속". 진짜 질문은 "어디를 진실로 고를 것인가".

1. SSOT 가 답하는 질문

DB 스키마 — 마이그레이션 파일 vs ORM 모델 vs 운영 DB?
API 스키마 — OpenAPI · Proto · Swagger vs 코드?
i18n 문자열 — messages/ko.json vs DB vs Notion?
디자인 토큰 — Figma vs CSS 변수?
환경변수 — .env vs Vault vs 1Password?

각각에 "하나만" 고르지 않으면 drift.

2. SSOT 배치 선택지

배치	장점	단점
코드 (git)	버전 관리 · 리뷰 쉬움	런타임 변경 불가
DB	런타임 변경	배포 ≠ 변경
외부 도구 (Notion · Figma)	비개발자 편집	코드와 분리 · 자동화 어려움
환경변수	간단	복잡한 구조 불가

3. 실전 1 — DB 스키마 = SQL 파일

frontend/admin/sql/codingstairs/
├── 002_create_categories.sql
├── 003_create_posts.sql
├── 004_create_life_projects.sql
...

진실: 파일
운영 DB: 거울 (migration 으로 동기화)
ORM entity: 거울 (generate)

장점: git 이력 · PR 리뷰 · 수동 psql 실행 · 재현 가능. 단점: 런타임 스키마 변경 불가 (상용 SaaS 용도 X).

4. 실전 2 — 시드 데이터 2단 SSOT

1단 — 정적 데이터 (카테고리 · 설정값) = TypeScript 코드
frontend/admin/src/shared/lib/codingstairs-seed.ts

2단 — 컨텐츠 (노트 · 블로그 글) = .md 파일
notes/backend/13-audit-log-pattern.ko.md
courses/admin-platform/series.ko.md

DB 는 walker 가 읽어 멱등 적재 (ON CONFLICT DO NOTHING)
편집은 파일에서 · 배포 후 init 버튼 · DB 반영

5. 실전 3 — SEO 메타 = 코드

// src/lib/data/metadata.ts
export const metadataMap: Record<string, MetaInfo> = {
  "/notes": { title: "노트", description: "...", keywords: [...] },
  "/edu": { ... },
};

Next.js generateMetadata 가 이 맵 먼저 조회 · 없으면 DB 폴백.

6. 실전 4 — 환경변수 = `.env` 파일 (private repo)

.env.local   # 로컬 (git ignore)
.env.dev     # DEV 배포용 (private repo 에서는 커밋 허용)
.env.prod    # PROD 배포용 (same)

편의 > 순수 보안. 공개 repo 라면 Vault · 1Password · AWS Secrets Manager.

7. 안티패턴 — SSOT 두 곳

- Figma 에 색상 정의
- CSS 변수에도 정의
- 두 곳 동기화 수동

한 쪽 바뀌면 drift. 해결: Figma 를 export → CSS 변수 자동 생성 (Figma Tokens Studio).

8. 충돌 규칙

같은 개념을 여러 곳에 정의했다면 우선순위 를 명시:

서비스 고유 rules.md > shared/*.md > RULES.md > README.md

warragon docs 구조의 실제 원칙. 충돌 시 상위 문서가 이김.

9. 갱신 의무 (drift 방지)

SSOT 가 아닌 곳이 SSOT 와 틀어지면 알림 · 에러.

새 SQL 컬럼 추가 → 다음 4 곳 동시 갱신 의무
  1. sql/*.sql
  2. seed.ts
  3. frontend types
  4. admin types

테스트에서 4 곳 일치 검증 (db-init.integration.test 가 파일 수 · 컬럼 이름 카운트).

10. 자주 걸리는 자리

코드 · DB · 문서 3 곳 중 가장 자주 바뀌는 곳이 SSOT 여야 — 코드만 고치고 DB 안 고치면 배포 후 오류
ORM 을 SSOT 로 — 여러 앱 공유 시 마이그레이션 동기화 어려움
"진실은 head 에 있다" — 개발자 기억이 기준이 됨. 문서화

하고픈 말

SSOT 는 도구 선택이 아니라 계약. "이 폴더의 이 파일만 진실이에요" 를 팀이 합의하고 지키면 3 개월 뒤 오늘 코드가 이해됩니다.

03-folders-as-contracts