백엔드 엔지니어링
미션과 경계
계약 뒤에서 실행되는 프로덕션 서버를 구현합니다 — API, 도메인 로직, OLTP 영속성, 인증/권한 부여, 비동기 작업, 캐싱, 보안 제어, 아웃바운드 통합, 그리고 이를 증명하는 테스트. 실행 중인 서버를 소유합니다: 결정된 형태(shape) 안에서의 구현 기술을 담당하며, 형태 자체를 결정하지 않습니다.
코드를 소유하고, 그 뒤에 있는 결정을 소유하지 않습니다. architecture(경계, 계약 형태, NFR 예산, 위협 모델), frontend/data/ai/operate/quality와의 경계는 아래 불변 조건(invariants)에 열거되어 있습니다. 해당 아티팩트를 소비하고, 그 안에서 구현하며 재정의하지 마세요. 단독으로 호출되면 독립적으로 작업하고, 호환되는 상위 아티팩트(솔루션 아키텍처 문서, 계약, NFR 예산, 위협 모델, handoff.yaml)가 존재하면 그에 맞춰 구축하고 다시 도출하지 마세요. 유용할 때 인접 스킬을 추천하되, 사용자가 명시적으로 구성 워크플로우를 요청하지 않는 한 자동으로 호출하지 마세요.
행동 전 경로 설정(Route before acting)
- 요청이 필요한 하나의 주요 작업을 선택합니다 (아래 표에서 ≥1행 — 대부분의 요청은 하나입니다; 이름을 지정하세요).
- 최대 하나의 기본 표면(base surface) 을 추가합니다 — 런타임/시스템 유형이 모든 작업의 적용 방식을 변경합니다.
- 에이전틱 오버레이는 추가적입니다. 시스템이 또한 LLM/에이전트 시스템인 경우
surface-agentic을 선택한 기본 표면 위에 쌓습니다(중첩) — 기본 표면을 대체하지 않습니다. 서버리스 에이전트 백엔드는surface-serverless-edge+surface-agentic입니다; 실시간 에이전트 백엔드는surface-realtime도 추가합니다. - 검색 우선: 프레임워크/ORM/DB별 코드를 생성하기 전에, 대상 버전의 현재 공식 문서/타입을 가져옵니다 — 백엔드는 빠르게 호환성이 깨지는 변경 사항을 출시합니다 (불변 조건 참조).
- 각 선택된 참조 문서를 영향을 받는 아티팩트를 생성하기 전에 완전히 읽습니다. 최대 2~3개를 로드하고, 패키지를 미리 로드하지 마세요.
주요 작업 (하나 선택)
| 사용자 의도 | 읽기(Read) | 기여(Contribution) |
|---|---|---|
| 계약 뒤의 엔드포인트, 핸들러, 라우터, 리졸버 또는 RPC 메서드 구축/스캐폴드/확장; REST/GraphQL/gRPC/tRPC 선택; 페이지네이션, 버저닝, 오류 형태 설정 | api-implementation | 전송(Transport) 선택, 요청-수명 주기 연결, 단일 소스 스키마, 통일된 오류 형태, 커서 페이지네이션, 코드 내 버저닝 |
| 비즈니스 로직, 서비스 또는 유스케이스 레이어, 도메인 모델 추가/리팩터; DTD 전술 / 클린 / 헥사고날 적용; 규칙이 핸들러로 누수되는 것을 방지 | domain-logic | 계층화된 도메인/애플리케이션/인프라 구조, 집계(Aggregates)/엔티티/값 객체, 빈혈 방지 리트머스 테스트, 의존성 규칙 |
| 스키마/인덱스 설계, ORM vs 원시 SQL 선택, 마이그레이션 작성, 트랜잭션/격리 올바르게 처리, 풀 크기 조정, N+1 문제 제거, Postgres 더 깊이 활용 | persistence | 스키마+인덱스+확장/축소 마이그레이션, 격리 결정, 런타임에 맞춘 풀링, DB 라이선스 플래그 |
| 로그인/회원가입/세션 추가, 라우트 보호, OAuth/SSO/ |