ADR-001: Spec as Source of Truth (스펙이 진실의 원천)
Status: Accepted | Date: 2026-02-10
맥락
Fascia는 백엔드 시스템의 표준 표현(canonical representation)이 필요합니다. 핵심 설계 질문은 런타임 동작이 수작업으로 작성한 코드에 의해 구동되어야 하는지, 정적 설정에 의해 구동되어야 하는지, 아니면 구조화된 스펙에 의해 구동되어야 하는지입니다.
기존 플랫폼은 크게 두 진영으로 나뉩니다. 개발자가 수정할 수 있는 소스 파일을 생성하는 코드 생성 도구와, 설정이 무엇을 실행할지 기술하지만 코드가 어떻게 실행할지를 정의하는 설정+코드 시스템(Kubernetes 등)입니다. 두 접근 모두 시스템이 기술하는 것과 실제 동작 사이에 괴리를 만들어냅니다.
Fascia의 대상 사용자는 프로덕션 백엔드를 구축하는 비개발자입니다. 표현 방식은 프로그래밍 지식 없이도 이해할 수 있어야 하고, 소스 코드를 읽지 않아도 감사(audit)가 가능해야 하며, 불변식(invariant)을 깨뜨리지 않고 안전하게 수정할 수 있어야 합니다.
결정
모든 런타임 동작은 구조화되고 버전 관리되는 스펙 파일에서 도출됩니다. Entity 스펙은 비즈니스 객체를 정의하고, Tool 스펙은 실행 가능한 연산을 정의하며, Policy 스펙은 안전 제약을 정의합니다. 스펙과 다른 "코드 뒤편(code behind)"은 존재하지 않습니다.
스펙이 유일한 진실의 원천(single source of truth)입니다. Executor는 컴파일된 스펙 번들을 읽고 결정적으로 실행합니다. 어떤 런타임 컴포넌트도 스펙 외부의 것을 해석하지 않습니다.
검토한 대안
| 옵션 | 장점 | 단점 |
|---|---|---|
| 스펙 기반 (선택됨) | 결정적, 감사 가능, 버전 관리 가능, 코드 괴리 없음 | 엣지 케이스에 대한 유연성 제한 |
| 코드 생성 | 유연하고 전통 적인 접근 | 생성된 코드가 수정될 수 있어 스펙과 실제 동작 사이 괴리 발생 |
| 설정 + 코드 | 익숙한 패턴 (예: Kubernetes) | 두 개의 진실의 원천, 전체적 감사 어려움 |
결과
긍정적
- 추적 가능성 -- 모든 런타임 동작은 특정 스펙 버전까지 추적할 수 있습니다. "시스템이 왜 X를 했는가?"라는 질문에 배포된 스펙을 검사하여 답할 수 있습니다.
- 정적 분석 -- 리스크 분석, 안전 검사, 정책 적용을 아무것도 실행하지 않고 스펙에 대해 수행할 수 있습니다.
- 간편한 롤백 -- 이전 동작으로 되돌리는 것은 이전 스펙 버전을 배포하는 것입니다. 코드 머지가 필요하지 않습니다.
- 비개발자 접근 -- 비즈니스 사용자가 스펙을 생성하는 시각적 설계 도구(Chat Studio, Flow Studio)를 통해 시스템 동작을 이해하고 수정할 수 있습니다.
부정적
- 스펙 커버리지 공백 -- 스펙 모델에 맞지 않는 진정으로 새롭거나 특이한 백엔드 패턴은 표현할 수 없습니다. 모든 새로운 기능은 스펙 스키마를 확장해 야 합니다.
- 스키마 진화 오버헤드 -- 스펙 스키마 자체를 신중하게 버전 관리해야 합니다. 스키마의 호환성을 깨는 변경은 기존 고객 스펙을 무효화할 수 있습니다.
리스크
- 배포된 시스템이 깨지지 않도록 스펙 스키마 진화를 하위 호환성 보장과 함께 관리해야 합니다.
- "스펙 공백(spec gap)" -- 사용자가 스펙 시스템이 아직 지원하지 않는 동작을 필요로 하는 상황 -- 에 대해 명확한 확장 로드맵과 전체 비전에서의 탈출구(escape hatch)를 통해 해결해야 합니다.