Blueprint4Agent

Blueprint4Agent는 에이전틱 코딩 기반으로 AI 애플리케이션을 빠르게 시작하고 운영하기 위한 프로젝트 블루프린트입니다.

FastAPI 기반 풀스택 서버 템플릿인 B4FastAPI를 중심으로 인증, 배포, 문서화, 테스트, CI/CD, 모니터링까지 프로젝트에 필요한 기반 환경을 하나의 표준 구조로 제공합니다. 따라서 반복적으로 필요한 초기 설정을 미리 갖춘 상태에서 개발자가 AI Agent를 활용해 기능 구현에 집중할 수 있는 개발 환경을 목표로 설계했습니다.

이 페이지에서는 BluePrint4Agent를 개발하게 된 목표와 시스템 아키텍처, 주요 기능 및 구현 과정, 그리고 프로젝트를 통해 얻은 결과와 경험을 소개합니다.

Project Goals

AI Agent가 코드를 잘 작성하려면 프로젝트의 기반 구조가 먼저 준비되어 있어야 합니다.

에이전틱 코딩을 반복적으로 적용할수록 인증, 배포, 테스트, 문서화, API 타입 생성, 모니터링 환경과 같은 기반 작업을 프로젝트마다 다시 구성해야 하는 문제가 발생합니다.

Blueprint4Agent는 이러한 반복 작업을 줄이고, 프로젝트를 시작하는 순간부터 개발과 운영이 가능한 환경을 제공하기 위해 시작했습니다. AI Agent와 개발자가 동일한 개발 규칙 안에서 협업하고, 기능 구현에만 집중할 수 있는 표준 프로젝트 구조를 만드는 것을 목표로 합니다.

System Architecture

React와 TypeScript 기반의 풀스택 프론트엔드입니다.

OpenAPI Generator를 통해 백엔드 API 클라이언트를 자동 생성하여 프론트엔드와 백엔드가 동일한 API 명세를 공유하도록 구성했습니다. 또한 Tauri 기반 Desktop 애플리케이션과 Web 환경을 함께 지원하며, 빌드된 정적 파일은 FastAPI 애플리케이션에서 함께 제공하여 단일 서버로 서비스를 운영할 수 있습니다.

AI 애플리케이션 개발에 필요한 기반 기능을 표준화한 FastAPI 기반 백엔드입니다.

인증(Authentication), OAuth, 사용자 설정, API Key, 데이터 접근 계층 등 대부분의 서비스에서 반복적으로 구현되는 기능을 기본 제공합니다. SQLAlchemy 기반으로 데이터베이스를 추상화하고 Redis를 활용한 캐시 및 세션 관리까지 포함하여, 프로젝트 초기 설정 없이 바로 기능 개발을 시작할 수 있도록 설계했습니다.

개발 환경과 운영 환경이 동일한 빌드 흐름을 사용하도록 배포 파이프라인을 구성했습니다.

Hatch를 공통 빌드 엔트리로 사용하여 로컬 개발 환경과 GitHub Actions 기반 CI/CD가 동일한 빌드 과정을 공유합니다. 생성된 결과물은 Docker Image, GitHub Container Registry(GHCR), Tauri Desktop Application으로 자동 배포되어 일관된 릴리스 환경을 제공합니다.

운영 환경을 지속적으로 관찰하고 분석할 수 있는 모니터링 환경을 기본 제공합니다.

OpenTelemetry를 통해 Metrics와 Trace를 수집하고, Prometheus와 Grafana를 활용하여 애플리케이션 상태를 시각화합니다. 개발 단계부터 운영 환경까지 동일한 Observability 구성을 제공하여 서비스 상태를 지속적으로 모니터링할 수 있도록 설계했습니다.

Features

Authentication & Service Foundation

Authentication, OAuth, Refresh Token, 사용자 설정, API Key 등 대부분의 서비스에서 반복적으로 구현되는 기반 기능을 기본 제공합니다.

Showcase

프로젝트에서 사용할 수 있는 UI 컴포넌트와 화면 예시를 미리 제공합니다. 개발자는 원하는 UI를 직접 확인하고, AI Agent는 Showcase를 참고하여 자연어 지시만으로 화면을 생성하거나 기존 레이아웃을 수정하는 등 일관된 UI 구성을 수행할 수 있습니다.

Desktop Application Support

Tauri 기반 데스크톱 애플리케이션 구조를 함께 제공하여 하나의 코드베이스에서 Web과 Desktop 환경을 모두 지원할 수 있습니다.

Deployment & CI Workflow

Docker 기반 개발 환경과 GitHub Actions 기반 CI/CD를 제공하며, Docker Image 생성, GitHub Container Registry(GHCR) 배포, Desktop Build Workflow까지 일관된 배포 환경을 제공합니다.

Observability

Prometheus 기반 Metrics와 OpenTelemetry 기반 Metrics, Traces, Logs를 지원하여 애플리케이션의 상태를 모니터링하고 운영 환경을 관찰할 수 있는 기반을 제공합니다.

Results

반복되는 프로젝트 준비 과정을 하나의 개발 환경으로 정리했습니다.

Blueprint4Agent는 AI 애플리케이션을 시작할 때 반복적으로 구현하던 인증, API 구조, OpenAPI 기반 타입 생성, Docker 배포, CI/CD, 문서화, 모니터링 환경을 하나의 템플릿으로 통합한 프로젝트입니다.

저는 프로젝트를 생성하는 순간부터 개발과 운영이 가능한 환경을 만드는 것을 목표로 했습니다. 이를 통해 반복적인 초기 설정을 줄이고, AI Agent와 개발자가 프로젝트 구성보다 기능 구현에 집중할 수 있는 개발 흐름을 만들었습니다.

Lessons Learned

AI가 잘 개발하려면 프로젝트도 AI 친화적으로 설계되어야 했습니다.

Blueprint4Agent를 개발하면서 FastAPI 기반 풀스택 아키텍처, Docker와 GitHub Actions를 활용한 배포 파이프라인, OpenAPI 기반 타입 생성, Tauri 기반 Desktop 지원, Prometheus와 OpenTelemetry를 활용한 Observability 환경까지 하나의 개발 흐름으로 정리할 수 있었습니다.

무엇보다 AI의 생산성을 높이는 핵심은 새로운 기능을 계속 추가하는 것이 아니라, AI가 이해하기 쉬운 프로젝트 구조와 일관된 개발 규칙을 먼저 제공하는 것이라는 점을 경험했습니다. 이러한 경험은 앞으로 새로운 AI 애플리케이션을 시작할 때도 동일한 개발 환경과 운영 방식을 적용할 수 있는 기반이 되었습니다.