백엔드를 매번 다시 구축하지 마세요: 더 나은 AI 보조 개발 워크플로우

AI는 백엔드 코드를 빠르게 생성할 수 있습니다. 하지만 그것이 자동으로 당신이 빠르게 제품을 출시하는 데 도움을 준다는 의미는 아닙니다.

새로운 프로젝트를 시작할 때마다 인증 (Authentication), JWT 설정, 리프레시 토큰 (Refresh tokens), 역할 확인 (Role checks), 유효성 검사 (Validation), 예외 처리 (Exception handling), 그리고 파일 업로드 (File uploads)를 위한 프롬프트를 작성해야 한다면, 약속된 속도의 상당 부분은 이미 해결했던 인프라를 다시 구축하는 데 소비됩니다.

더 높은 레버리지를 제공하는 접근 방식은 간단합니다:

안정적인 백엔드 기반(Backend foundation)에서 시작한 다음, 그 위에 제품 특화된 동작을 구현하는 데 AI를 사용하세요.

이러한 전환은 AI에게 더 강력한 컨텍스트 (Context)를 제공하고, 아키텍처 (Architecture)를 일관되게 유지하며, 프롬프트 크기를 줄이고, 엔지니어링 시간을 사용자가 실제로 관심을 갖는 기능으로 이동시킵니다.

요약 (TL;DR)

생산적인 AI 백엔드 워크플로우는 다음과 같아야 합니다:

재사용 가능하고 운영 환경에 적합한(Production-oriented) 백엔드 기반으로 시작합니다.
기존의 인증 (Authentication), 인가 (Authorization), 스토리지 (Storage), 그리고 테스트 흐름을 실행하고 검증합니다.
AI에게 명확한 아키텍처 경계와 리포지토리 컨텍스트 (Repository context)를 제공합니다.
전체 인프라를 다시 쓰는 대신, 작고 제품 특화된 변경 사항을 요청합니다.
새로운 동작, 특히 보안에 민감한 변경 사항을 검토하고 테스트합니다.

AI는 알려진 시스템을 확장할 때 가장 효과적입니다. 기능을 구현하면서 시스템 전체를 발명해야 할 때는 예측 가능성이 훨씬 떨어집니다.

모든 백엔드를 처음부터 생성할 때 발생하는 숨겨진 비용

대부분의 백엔드 애플리케이션은 의미 있는 제품 개발이 시작되기 전에 다음과 같은 동일한 기본 역량이 필요합니다:

회원가입 및 로그인 (Registration and login)
액세스 및 리프레시 토큰 (Access and refresh tokens)
역할 기반 액세스 제어 (Role-based access control)
보호된 경로 (Protected routes)
요청 유효성 검사 (Request validation)
일관된 예외 처리 (Consistent exception handling)
파일 업로드 및 다운로드 API (File upload and download APIs)
보안 설정 (Security configuration)
테스트 가능한 컨트롤러, 서비스, 리포지토리 레이어 (Testable controller, service, and repository layers)

이러한 역량들은 필수적이지만, 대개 당신의 제품을 차별화하는 요소는 아닙니다.

사용자들은 또 다른 커스텀 JWT 필터를 위해 비용을 지불하지 않습니다. 그들은 당신의 제품이 제공하는 워크플로우 (workflow), 자동화 (automation), 데이터 모델 (data model), 협업 기능 (collaboration feature), 또는 운영 개선 (operational improvement)을 위해 비용을 지불합니다.

AI가 기반 구조를 반복적으로 재생성할 때, 당신의 팀은 여전히 이를 검토해야 합니다. 이는 제품 개발 작업을 안전하게 계속하기 전에 보안 규칙 (security rules), 패키지 구조 (package structure), 토큰 동작 (token behavior), 명명 규칙 (naming conventions), 검증 (validation), 영속성 로직 (persistence logic), 그리고 테스트 커버리지 (test coverage)를 확인해야 함을 의미합니다.

출력물은 빠르게 생성될 수 있습니다. 하지만 검토 부담은 그렇지 않습니다.

AI가 생성한 백엔드 설정이 어긋나기 시작하는 이유

백엔드 인프라 (infrastructure)는 연결된 시스템입니다. 인증 (Authentication)은 인가 (authorization)에 영향을 미칩니다. 인가는 라우트 (routes)에 영향을 미칩니다. 라우트는 DTO, 서비스 (services), 리포지토리 (repositories), 검증 (validation), 그리고 예외 처리 (exception handling)에 의존합니다. 파일 접근은 인증과 소유권 규칙 (ownership rules) 모두에 의존할 수 있습니다.

각 관심사 (concern)가 별도의 대화나 프롬프트 (prompt)에서 생성될 때, 코드는 다음과 같이 어긋날 수 있습니다:

반복되는 과정 사이에서 패키지 구조 (package structures)가 변경됨
DTO와 엔티티 (entities)가 일관되지 않은 명명 규칙을 가짐
보안 규칙 (security rules)이 이전에 생성된 엔드포인트 (endpoints)와 충돌함
컨트롤러 (controllers)가 서비스 (services)에 속해야 할 로직을 흡수함
관련 없는 레이어 (layers)에서 리포지토리 (repositories)를 직접 사용함
기능에 따라 예외 응답 (exception responses)이 달라짐
아키텍처 (architecture)가 계속 변하기 때문에 테스트를 유지 관리하기가 더 어려워짐
모든 수정 사항에 더 많은 컨텍스트 (context)와 더 많은 토큰 (tokens)이 필요함

문제는 AI가 백엔드 개발을 할 능력이 없다는 것이 아닙니다.

문제는 AI에게 잘못된 업무를 할당하는 것입니다. 검토된 구현 (implementation)을 재사용할 수 있음에도 불구하고, 횡단 관심사 (cross-cutting) 인프라를 다시 만드는 것은 코딩 에이전트 (coding agent)를 잘못 사용하는 것입니다. 이미 구축된 코드베이스 (codebase)를 확장하는 것이 훨씬 더 적합합니다.

재사용 가능한 백엔드 기반이 이미 해결해야 하는 것들

유용한 보일러플레이트 (boilerplate)는 제품을 경직된 설계에 가두지 않으면서 반복적인 설정을 제거해야 합니다.

최소한, 기반 구조는 다음 사항들에 대해 명확한 솔루션을 제공해야 합니다:

인증 및 토큰 생명주기 (Authentication and token lifecycle)

등록(Registration), 로그인(login), 비밀번호 처리(password handling), 액세스 토큰(access tokens), 리프레시 토큰(refresh tokens), 로그아웃 동작(logout behavior), 그리고 인증 오류(authentication errors)는 하나의 일관된 흐름을 따라야 합니다.

권한 부여 (Authorization)

역할(Roles)과 권한(permissions)은 여기저기 흩어진 조건부 체크(conditional checks)보다는 예측 가능한 라우트(route) 또는 메서드 수준(method-level)의 규칙을 통해 강제되어야 합니다.

파일 처리 (File handling)

업로드(Uploads), 다운로드(downloads), 스트리밍(streaming), 메타데이터(metadata), 소유권(ownership), 검증(validation), 그리고 저장소 경계(storage boundaries)는 명시적이어야 합니다. 구현 시 로컬 스토리지(local storage), S3, 또는 다른 제공업체를 사용할 수 있지만, 제품 코드(product code)가 저장소 세부 사항에 직접적으로 의존해서는 안 됩니다.

검증 및 오류 처리 (Validation and error handling)

요청(Requests)은 일관되게 검증되어야 하며, API 오류(API errors)는 안정적인 응답 형식(response format)을 따라야 합니다.

계층 경계 (Layer boundaries)

컨트롤러(Controllers)는 HTTP 관련 사항을 관리해야 합니다. 서비스(Services)는 비즈니스 동작(business behavior)을 소유해야 합니다. 리포지토리(Repositories)는 영속성(persistence)을 처리해야 합니다. 보안(Security) 및 저장소 통합(storage integrations)은 격리된 상태를 유지해야 합니다.

테스트 구조 (Testing structure)

코드베이스는 매 테스트마다 관련 없는 인프라(infrastructure)를 부트스트래핑(bootstrapping)하지 않고도 서비스와 엔드포인트(endpoint) 동작을 실질적으로 테스트할 수 있어야 합니다.

이러한 결정들이 안정화되면, AI는 각 작업마다 새로운 패턴을 만들어내는 대신 기존 패턴을 따를 수 있습니다.

AI 보조 백엔드 개발을 위한 더 나은 워크플로우

1. 백엔드 기반으로 시작하기

설정(setup) 과정을 배우는 것이 목적이 아니라면, 빈 리포지토리(empty repository)로 시작하지 마세요.

제품 출시를 위해서는 이미 공통 인프라(infrastructure)가 구현된 코드베이스로 시작해야 합니다. 예를 들어, BuildBaseKit은 다음과 같은 것들을 제공합니다:

AuthKit-Lite: Spring Boot JWT 인증, 리프레시 토큰(refresh tokens), 그리고 역할 기반 액세스(role-based access)를 위한 도구
FiloraFS-Lite: 경량 로컬 파일 저장소(local file storage) API를 위한 도구
FiloraFS-Pro: 인증, S3 통합, 파일 관리, 스트리밍, 그리고 프로덕션 지향적 저장소 워크플로우(production-oriented storage workflows)를 위한 도구

목표는 코드를 이해하는 것을 피하는 것이 아닙니다. 목표는 설정 비용(setup cost)을 반복해서 지불하는 것을 피하는 것입니다.

2. AI에게 확장을 요청하기 전에 기반을 검증하세요

먼저 프로젝트를 실행하고 기본 흐름(baseline flows)을 테스트하세요.

다음 사항들이 예상대로 작동하는지 확인하십시오:

회원가입 및 로그인
액세스 토큰(access-token) 인증
리프레시 토큰(refresh-token) 동작
보호된 엔드포인트(protected endpoints)
역할 확인(role checks)
파일 업로드 및 검색
유효성 검사 실패(validation failures)
예외 응답(exception responses)
기존 자동화된 테스트

이 단계는 검증된 베이스라인(known-good baseline)을 구축합니다. 이 단계가 없다면, 나중에 발생한 실패가 기반(foundation)에서 온 것인지, 생성된 변경 사항에서 온 것인지, 아니면 그 둘 사이의 상호작용에서 온 것인지 신뢰성 있게 판단할 수 없습니다.

3. AI에게 명시적인 프로젝트 컨텍스트를 제공하세요

코드베이스는 그 제약 조건들이 가시적일 때에만 유용한 제약 조건을 제공합니다.

코딩 에이전트(coding agent)가 따라야 할 아키텍처(architecture), 컨벤션(conventions), 명령어(commands), 그리고 경계(boundaries)를 문서화하세요. 유용한 리포지토리(repository) 파일에는 다음이 포함됩니다:

AGENTS.md: 에이전트 전용 작업 지침용
ARCHITECTURE.md: 패키지 책임 및 시스템 설계용
AI_RULES.md: 협상 불가능한 컨벤션 및 금지된 변경 사항용
AGENT_CONTRIBUTING.md: 구현 및 검증 단계용

BuildBaseKit의 AI-ready Spring Boot foundations는 코딩 에이전트가 리포지토리를 변경하기 전에 이를 이해할 수 있도록 돕기 위해 이러한 유형의 문서를 사용합니다.

좋은 컨텍스트는 다음과 같은 질문에 답할 수 있어야 합니다:

비즈니스 로직(business logic)은 어디에 위치해야 하는가?
어떤 보안 흐름(security flows)이 변경되지 않고 유지되어야 하는가?
에러는 어떻게 표현되는가?
어떤 명령어가 테스트를 실행하는가?
어떤 명명 규칙(naming conventions)이 이미 사용 중인가?
기능(feature)이 수정할 수 있는 모듈은 무엇인가?
변경이 완료되었다고 간주하기 전에 무엇을 검증해야 하는가?

목표는 추측을 줄이는 것입니다.

4. 해결된 인프라가 아니라 제품의 동작을 요청하세요

다음과 같은 광범위한 프롬프트(prompts)를 피하십시오:

Spring Boot에서 리프레시 토큰 (refresh tokens), 역할 권한 (role permissions), 검증 (validation), 예외 처리 (exception handling), 그리고 파일 업로드 통합 (file upload integration)을 포함한 JWT 인증을 구축해줘.

그러한 프롬프트는 모델이 한 번에 너무 많은 아키텍처 결정 (architectural decisions)을 내리도록 강요합니다.

기존 애플리케이션과 연결된 집중된 요청을 선호하십시오:

기존의 인증 및 이메일 패턴을 사용하여 조직 초대 엔드포인트 (organization invitation endpoint)를 추가해줘.

현재의 컨트롤러 (controller) 및 서비스 (service) 구조를 따르는 결제 서비스 (billing service)를 생성해줘.

기존의 역할 확인 (role checks) 및 파일 메타데이터 모델 (file metadata model)을 사용하여 관리자 전용 파일 승인 기능을 추가해줘.

현재의 보안 설정 (security configuration)을 변경하지 않고 팀 초대 흐름 (team-invite flow)에 대한 테스트를 추가해줘.

이러한 프롬프트들은 변경 범위 (change surface)를 작게 정의합니다. 이는 구현하기 더 쉽고, 리뷰하기 더 쉬우며, 관련 없는 코드를 불안정하게 만들 가능성이 낮습니다.

5. 플랫폼 전체를 디버깅하는 대신 기능을 테스트하세요

인증 (authentication), 저장소 (storage), 검증 (validation), 그리고 예외 처리 (exception handling)가 이미 안정적이라면, 테스트는 새로운 동작에 집중할 수 있습니다.

예를 들어, 조직 초대 기능의 경우 관련 질문은 다음과 같습니다:

권한이 있는 사용자가 초대를 생성할 수 있는가?
초대가 올바른 조직 범위 (scoped) 내에 있는가?
중복되거나 만료된 초대가 올바르게 처리되는가?
권한이 없는 역할 (unauthorized roles)이 거부되는가?
API가 설정된 에러 형식 (error format)을 반환하는가?

이는 토큰 파싱 (token parsing), 보안 필터 (security filters), 저장 경로 (storage paths), 그리고 초대 로직 (invitation logic)을 동시에 디버깅하는 것보다 더 깔끔한 엔지니어링 루프 (engineering loop)입니다.

보안에 민감한 생성된 코드는 여전히 인간의 리뷰를 필요로 합니다. 보일러플레이트 (boilerplate)는 반복적인 작업을 줄여줄 뿐, 엔지니어링 책임 (engineering accountability)을 제거하지는 않습니다.

더 작은 프롬프트는 토큰 사용량과 리뷰 비용을 줄입니다

대규모 프롬프트는 아키텍처 (architecture), 보안 요구 사항 (security requirements), 인증 동작 (authentication behavior), 검증 규칙 (validation rules), 파일 저장 기대치 (file storage expectations), 그리고 응답 형식 (response formats)을 반복해서 재진술합니다.

다음 두 가지 요청을 비교해 보십시오:

리프레시 토큰 (refresh tokens), 역할 권한 (role permissions), 검증 (validation), 예외 처리 (exception handling), 그리고 파일 업로드 통합 (file upload integration)을 포함한 보안 JWT 인증을 구축해줘.

그리고:

기존의 인증 및 검증 패턴을 사용하여 팀 초대 엔드포인트(team invitation endpoint)를 추가해줘.

두 번째 프롬프트가 더 작은 이유는 저장소(repository)에 이미 결정 사항들이 포함되어 있기 때문입니다. 이는 또한 더 작은 패치(patch)를 생성하며, 일반적으로 다음과 같은 의미를 갖습니다:

생성되는 파일 수 감소
관련 없는 아키텍처 변경 사항 감소
프롬프트 컨텍스트 (prompt context) 감소
더 빠른 코드 리뷰 (code review)
더 쉬운 롤백 (rollback)
더 타겟팅된 테스트 (targeted tests)

진정한 최적화는 단순히 토큰 소비를 줄이는 것이 아닙니다. 그것은 변경 범위(change surface)를 줄이는 것입니다.

빈 저장소보다 컨텍스트가 더 중요합니다

AI가 빈 프로젝트에서 시작할 때, 사용자의 기능을 구현하기 전에 다음과 같은 모든 사항을 결정해야 합니다:

패키지 구조 (package structure)
명명 규칙 (naming conventions)
API 응답 형태 (API response shape)
보안 설정 (security configuration)
토큰 생명주기 (token lifecycle)
서비스 경계 (service boundaries)
영속성 패턴 (persistence patterns)
검증 전략 (validation strategy)
예외 처리 (exception handling)
테스트 구성 (test organization)

이러한 결정 중 일부는 개별적으로는 합리적일 수 있지만, 프로젝트가 진화함에 따라 서로 충돌할 수 있습니다.

기존의 코드베이스(codebase)는 이러한 개방형 결정 사항들을 제약 조건(constraints)으로 바꿔줍니다. 그것이 바로 이점입니다.

생산적인 AI 개발은 생성되는 코드의 양을 최대화하는 것이 아닙니다. 이미 규칙이 이해된 시스템 내부에서 올바른 코드를 생성하는 것입니다.

예측 가능한 Spring Boot 구조는 확장을 더 쉽게 만듭니다

단순한 계층형 구조(layered structure)는 개발자와 코딩 에이전트(coding agents) 모두에게 명확한 지도를 제공합니다:

src/main/java/com/example/app/
├── controller/
├── service/
...

정확한 패키지 이름보다는 일관된 소유권(ownership)이 더 중요합니다.

컨트롤러(controller)가 두 번째 서비스 계층이 되어서는 안 됩니다. 리포지토리(repository)가 라우트 권한을 강제해서는 안 됩니다. 보안 클래스(security classes)에 제품 워크플로우(product workflows)를 포함해서는 안 됩니다. 스토리지 제공자(storage-provider) 코드가 관련 없는 비즈니스 로직으로 유출되어서는 안 됩니다.

경계가 예측 가능할 때, AI 에이전트는 유사한 기능을 검사하고 동일한 패턴을 사용하여 다음 기능을 구현할 수 있습니다.

피해야 할 일반적인 실수

모든 제품에 대해 인증을 매번 다시 생성하기

인증 (Authentication)은 보안에 매우 중요하며 반복적인 작업입니다. 검토가 완료된 구현체를 재사용하고, 제품이 요구하는 사항만 커스텀하세요.

스토리지 규칙을 정의하기 전에 파일 업로드를 요청하는 것

소유권, 액세스 제어 (Access Control), 크기 제한, 허용된 파일 유형, 메타데이터, 보존 (Retention), 전송 (Delivery), 그리고 스토리지 제공자 (Storage Provider)의 경계를 먼저 명확히 하세요.

제품 로직과 보안 설정을 혼합하는 것

보안은 신원 (Identity)과 액세스를 확립해야 합니다. 제품 서비스는 워크플로우를 구현해야 합니다. 이 둘을 결합하면 두 가지 모두 추론하기가 더 어려워집니다.

검토 없이 생성된 보안 코드를 수락하는 것

AI가 생성한 보안 설정은 그럴듯해 보일 수 있지만, 안전하지 않은 기본값, 불완전한 경로 커버리지 (Route Coverage), 또는 깨진 토큰 동작을 포함할 수 있습니다. 수동으로 검토하고 부정적인 케이스 (Negative Cases)를 테스트하세요.