Case 04 / 05 · Backend Standard

BE Template

반복되는 backend 구조와 agent context 구성을 조직 표준 FastAPI template으로 묶은 케이스.

Role: Owner
Scope: Backend Standard
Stack: FastAPI · Pyright
Status: 설계·구축 전담

문제

Problem

새 backend project마다 directory structure, DI, transaction, error response와 local setup을 다시 결정하고 있었다. agent도 project context와 작업 절차를 매번 새로 읽고 추론해야 해, 반복되는 판단이 구현마다 흩어졌다.

동시에 multi-tenancy, ID type, authentication, storage는 project마다 달랐다. 표준을 만들되 product-specific 선택을 숨기지 않는 경계가 필요했다.

결정

Decision

모든 차이를 generic framework에 넣는 대신, 반복되는 core는 고정하고 제품별 선택은 명시적인 option과 생성 workflow로 분리했다.

Stable CoreRouter → Service → Repository, DI, transaction, error contract를 stable layered core로 고정한다.
Explicit Optionsmulti-tenancy, ID type, authentication, local·managed storage는 option으로 분리해 product-specific 차이를 생성 후 확장한다.
Shared Context사람과 agent가 같은 ADR·convention·runbook과 계층형 context routing을 바라보도록 반복 작업 automation skill을 template에 내장한다.

시스템

System

backend의 안정적인 구조 계약과 project별 선택, agent 작업 context를 하나의 생성·운영 표준으로 연결했다.

Layered Core

Router → Service → Repository, DI, transaction boundary를 stable core로 표준화.

Option Matrix

tenancy·ID·authentication·storage 차이를 명시적인 option으로 분리.

Contract Guard

response wrapper matrix, ErrorCode domain prefix, contract test와 Pyright로 회귀를 제한.

Agent Context

Hub-and-Spoke routing과 init-project·add-domain·db-reset·local-setup skill을 내장.

운영 근거

Operating Evidence

layered architecture, DI, transaction, option matrix, contract test와 automation skill이 코드 근거로 확인되고, ADR·convention·runbook과 Hub-and-Spoke context routing이 문서 근거로 연결되어 있다. adoption과 setup 시간의 before/after는 측정되지 않아 정량 효과는 주장하지 않는다.