2단계
SSOT — 어디에 두는가
25 분
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 변수?
- 환경변수 —
.envvs Vault vs 1Password?
각각에 "하나만" 고르지 않으면 drift.
2. SSOT 배치 선택지
| 배치 | 장점 | 단점 |
|---|---|---|
| 코드 (git) | 버전 관리 · 리뷰 쉬움 | 런타임 변경 불가 |
| DB | 런타임 변경 | 배포 ≠ 변경 |
| 외부 도구 (Notion · Figma) | 비개발자 편집 | 코드와 분리 · 자동화 어려움 |
| 환경변수 | 간단 | 복잡한 구조 불가 |
3. 실전 1 — DB 스키마 = SQL 파일
frontend/admin/sql/codingstairs/
├── 001_create_categories.sql
├── 002_create_posts.sql
├── 003_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 개월 뒤 오늘 코드가 이해됩니다.
Next
- 03-folders-as-contracts