# Fastapi Backend Guidelines

> FastAPI 백엔드 개발 가이드라인 Use when this capability is needed.

- Skill: `tomevault-io/fastapi-backend-guidelines` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/fastapi-backend-guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/fastapi-backend-guidelines/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/fastapi-backend-guidelines

---


# FastAPI Backend Guidelines

## 사용 시기
- FastAPI, Python 백엔드, AI 서비스 개발 요청 시

## 기술 스택
- Python 3.12+
- FastAPI (async/await)
- SQLAlchemy 2.0 / SQLModel
- PostgreSQL (asyncpg)
- Redis (aioredis)

## 디렉토리 구조

```
backend/
├── app/
│   ├── main.py           # FastAPI 앱 엔트리포인트
│   ├── config.py         # 설정 (Pydantic Settings)
│   ├── api/
│   │   └── v1/           # API v1 라우터
│   ├── core/             # 인증, 보안, DB 세션
│   ├── models/           # SQLAlchemy 모델
│   ├── schemas/          # Pydantic 스키마
│   ├── services/         # 비즈니스 로직
│   ├── repositories/     # DB 접근 계층
│   └── ai/               # AI/ML 서비스
├── tests/                # pytest 테스트
├── alembic/              # DB 마이그레이션
└── pyproject.toml        # 프로젝트 설정
```

## 원칙

1. **async 기본** — 모든 IO 작업에 async/await 사용
2. **의존성 주입** — FastAPI Depends() 활용
3. **타입 안전** — Pydantic 모델로 입출력 검증
4. **에러 처리** — HTTPException + 글로벌 핸들러
5. **로깅** — structlog로 구조화된 로그

---
> Source: [U2SY26/u2dia-kanban](https://github.com/U2SY26/u2dia-kanban) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-15 -->