지금까지의 실습이 페이지 하나, 기능 하나를 만드는 수준이었다면 이번 편은 조금 더 야심 차다. 사용자의 영어 수준을 진단하고, 맞춤 콘텐츠를 제공하고, AI 튜터와 대화하며 첨삭까지 받는 ‘영어 학습 프로그램’을 백엔드 관점에서 설계하고 뼈대를 세워본다. 프런트엔드 화면 하나가 아니라 API 서버, 데이터 모델, 외부 AI 연동까지 얽히는 프로젝트인 만큼, 이번에는 AI 개발 파트너에게 무엇을 먼저 정리해달라고 요청해야 하는지가 더 중요해진다.
이 편의 목표는 완성된 영어 학습 서비스를 만드는 것이 아니다. 개인화·상호작용성을 요구하는 복잡한 프로젝트를 AI 파트너와 함께 어떻게 기능 단위로 쪼개고, 어떤 순서로 API를 세워나가는지 그 흐름을 손에 익히는 것이다. 백엔드 프레임워크로는 FastAPI를 쓴다. 파이썬 표준 타입 힌트만으로 요청 검증과 문서화를 자동으로 처리해주기 때문에, AI가 생성한 코드를 사람이 검토하기에도 유리하다.
외부 AI API(대화형 튜터, 음성 인식, 첨삭 등)를 실제로 연동하는 세부 구현은 이 편의 범위를 벗어난다. 대신 그 API들을 호출할 자리를 어떻게 설계하고, AI 개발 파트너에게 그 뼈대를 어떤 프롬프트로 요청하는지에 집중한다. 어떤 AI 서비스를 최종적으로 선택하든, 오늘 세운 뼈대의 형태는 크게 달라지지 않는다.
1단계 — 기능을 쪼개고 우선순위를 정한다
영어 학습 프로그램은 욕심을 내기 시작하면 끝이 없다. 수준 진단, 맞춤 콘텐츠, 말하기 연습, 작문 첨삭, 학습 리포트까지 전부 한 번에 만들려고 하면 AI 개발 파트너에게 던지는 프롬프트부터 뒤죽박죽이 된다. 실습에서는 아래 네 가지로 범위를 좁힌다.
- 수준 진단 — 초기 테스트로 초급/중급/고급을 판별
- AI 튜터 대화 — 특정 주제로 자유롭게 대화하며 스피킹 연습
- 작문 첨삭 — 사용자가 쓴 글에 대한 피드백
- 학습 기록 — 대화·첨삭 이력을 저장하고 나중에 조회
이 네 가지는 각각 별도의 API 엔드포인트로 나눌 수 있는 단위다. 한 기능이 끝나야 다음 기능을 요청하는 식으로 진행하면, AI가 만든 코드 중 어디까지가 검증됐고 어디부터가 새로 추가된 부분인지 항상 명확하게 구분할 수 있다.
여기서 하나 더 정해두면 좋은 것이 있다. 네 기능 중 무엇을 먼저 만들지 순서를 정하는 일이다. 실습에서는 외부 AI 의존도가 낮은 순서, 즉 학습 기록 → 수준 진단 → 작문 첨삭 → AI 튜터 대화 순으로 진행한다. 데이터베이스만 있으면 되는 기능부터 다지고, 외부 서비스 연동이 필요한 기능은 뒤로 미루면 초반에 막히는 지점을 줄일 수 있다.
2단계 — 안티그라비티에서 전체 구조 먼저 스케치하기
코드를 짜기 전에 AI 개발 파트너에게 전체 그림을 먼저 그려달라고 요청한다. 이번에도 안티그라비티 워크스페이스에서 새 프로젝트를 시작하고, 아래 프롬프트로 대화를 연다.
AI 기반 영어 학습 프로그램의 백엔드를 FastAPI로 만들려고 해.
기능은 4개: 수준 진단, AI 튜터 대화, 작문 첨삭, 학습 기록 조회.
지금은 코드를 짜지 말고, 각 기능이 어떤 API 엔드포인트와
데이터 모델(Pydantic)을 필요로 하는지 목록으로 정리해줘.
외부 AI API를 호출하는 부분은 함수 이름만 정해두고,
실제 연동 코드는 아직 만들지 마.“외부 AI API 연동 코드는 아직 만들지 마”라는 조건을 넣은 이유가 있다. 이 시점에는 어떤 AI 서비스를 쓸지, 어떤 요금제를 쓸지 정해지지 않은 경우가 많다. 연동 부분을 함수 껍데기로만 남겨두면, 나중에 실제 서비스를 붙일 때 그 함수 내부만 바꾸면 되므로 전체 구조를 다시 손댈 필요가 없다.
3단계 — FastAPI로 뼈대 세우기
FastAPI는 파이썬 표준 타입 힌트만으로 요청 데이터의 형식을 검증하고, 그 결과로 대화형 API 문서까지 자동으로 만들어준다. FastAPI 공식 문서는 이 프레임워크를 쓰면 기능 개발 속도가 대략 200~300% 빨라지고, 사람이 만드는 실수로 인한 버그가 약 40% 줄어든다고 소개한다. 정확한 수치는 프로젝트마다 다르겠지만, AI가 생성한 코드를 검토하는 사람 입장에서는 타입 힌트 자체가 일종의 명세서 역할을 해준다는 점이 특히 유용하다.
아래는 2단계에서 정리한 기능 중 ‘수준 진단’과 ‘학습 기록 조회’를 FastAPI 엔드포인트로 옮긴 뼈대다. 이 코드는 진단 결과를 받아 저장하는 엔드포인트 하나와, 특정 사용자의 학습 기록을 조회하는 엔드포인트 하나로 구성된다.
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class DiagnosisResult(BaseModel):
user_id: int
level: str # "beginner" | "intermediate" | "advanced"
weak_points: list[str]
@app.post("/diagnosis")
def save_diagnosis(result: DiagnosisResult):
# TODO: 데이터베이스에 진단 결과 저장
return {"status": "saved", "level": result.level}
@app.get("/learning-log/")
def get_learning_log(user_id: int):
# TODO: 해당 사용자의 대화·첨삭 이력 조회
return {"user_id": user_id, "logs": []}FastAPI 공식 문서가 설명하듯, DiagnosisResult처럼 Pydantic 모델로 요청 본문의 형태를 선언해두면 데이터가 유효하지 않을 때 자동으로 명확한 에러가 발생하고, 이 스키마 그대로 대화형 문서에도 반영된다. AI에게 새 엔드포인트를 요청할 때도 “이런 Pydantic 모델을 입력으로 받는 엔드포인트를 만들어줘”라고 명시하면, 검증 로직을 따로 요청하지 않아도 기본적인 타입 검증은 자동으로 딸려온다.
TODO로 남긴 부분을 채우는 프롬프트
뼈대가 확인됐다면, TODO로 남겨둔 데이터베이스 저장 로직을 요청할 차례다. 이 프롬프트는 뼈대의 함수 시그니처는 그대로 두고 내부 구현만 채워달라는 요청이다.
save_diagnosis와 get_learning_log 함수의 시그니처는 그대로 두고,
TODO 부분만 SQLAlchemy를 이용해 구현해줘.
테이블은 diagnosis_results(user_id, level, weak_points, created_at)
하나로 충분해. weak_points는 문자열 배열이니 JSON 컬럼으로
저장해줘.4단계 — AI 튜터 대화 모듈의 자리 만들기
AI 튜터 대화는 이 프로젝트에서 외부 AI API에 가장 크게 의존하는 부분이다. 어떤 서비스를 쓰든 API 서버 쪽 구조는 비슷하다. 사용자의 메시지를 받아, 대화 맥락과 함께 외부 AI에 전달하고, 응답을 돌려주는 형태다. 아래 프롬프트는 이 구조를 요청하면서, 외부 AI 호출 부분은 함수로 분리해달라고 명시한다.
AI 튜터 대화 엔드포인트를 FastAPI로 만들어줘.
- 입력: user_id, message, topic(대화 주제)
- 이전 대화 맥락을 함께 담아 외부 AI 호출 함수
call_tutor_ai(context, message)로 넘겨줘
- call_tutor_ai 함수는 지금은 껍데기만 만들고,
더미 응답("(AI 응답 자리)")을 반환하게 해줘
- 대화가 끝나면 diagnosis_results와 별도로
conversation_logs 테이블에 사용자 메시지와 AI 응답을 기록해줘이렇게 만들면 call_tutor_ai 함수 하나만 나중에 실제 AI 서비스 호출 코드로 바꿔치기하면 된다. 나머지 엔드포인트, 데이터 검증, 로그 기록 로직은 이미 검토를 마친 상태로 그대로 남는다. 외부 AI API 키나 요금 정책이 프로젝트마다 다르므로, 실제 연동 코드는 선택한 서비스의 공식 문서를 직접 확인하며 채워 넣는 것이 안전하다.
5단계 — 작문 첨삭 모듈 붙이기
스피킹 연습과 별도로, 사용자가 직접 쓴 글을 첨삭받는 기능도 같은 방식으로 붙일 수 있다. 대화 모듈과 구조는 비슷하지만 입력이 한 번에 긴 텍스트로 들어온다는 점, 그리고 응답이 단순 대화가 아니라 문법·어휘·문맥 세 갈래로 나뉜 피드백이라는 점이 다르다. 이 차이를 프롬프트에 명시해야 AI가 대화 모듈 코드를 복사한 듯한 결과물을 내놓지 않는다.
작문 첨삭 엔드포인트를 FastAPI로 만들어줘.
- 입력: user_id, essay_text(사용자가 쓴 글, 최대 2000자)
- essay_text 길이가 2000자를 넘으면 422 에러를 반환하도록
Pydantic 필드 검증을 걸어줘
- 외부 AI 호출은 call_writing_feedback(essay_text)로 분리하고,
지금은 문법/어휘/문맥 세 항목이 빈 문자열인 더미 응답을 반환해줘
- 첨삭 결과는 essay_feedback 테이블에 원문과 함께 저장해줘essay_text에 최대 길이를 못 박아둔 이유는 4단계 마지막에서 짚은 것과 같다. 자유 입력 필드는 제한이 없으면 그대로 외부 AI 호출 비용과 응답 지연으로 이어진다. 첨삭처럼 입력 자체가 긴 기능일수록 이 제한을 뼈대 단계에서부터 요청해두는 편이 낫다.
뼈대가 만들어졌다면, FastAPI가 자동으로 띄워주는 대화형 문서 화면(/docs 경로)에서 방금 만든 엔드포인트를 직접 눈으로 확인할 수 있다. 별도의 API 테스트 도구 없이도 이 화면에서 값을 채워 넣고 바로 요청을 보내볼 수 있으므로, 엔드포인트를 하나 완성할 때마다 이 화면에서 정상적으로 값이 오가는지 확인하는 습관을 들이면 좋다.
6단계 — 검토할 때 놓치기 쉬운 지점
AI가 뼈대를 다 채워줬다고 바로 다음 기능으로 넘어가기 전에, 아래 두 가지는 꼭 확인하자.
- 사용자 입력 검증 —
message같은 자유 입력 필드에 길이 제한이 걸려 있는지. 제한이 없으면 외부 AI 호출 비용이 예상보다 커질 수 있다. - 실패 시 처리 — 외부 AI 호출이 타임아웃되거나 오류를 반환했을 때 사용자에게 무엇을 보여줄지. “AI 응답 자리” 같은 더미 대신 실제로는 재시도나 에러 메시지 처리가 필요하다.
이 두 가지는 뼈대 단계에서는 눈에 잘 띄지 않다가, 실제 서비스에 AI API를 연결하는 순간 바로 문제가 되는 지점이다. AI에게 뼈대를 요청할 때 “입력 길이 제한과 실패 시 처리도 포함해줘”라고 미리 조건을 걸어두면, 나중에 따로 챙기는 수고를 덜 수 있다.
결론
영어 학습 프로그램처럼 기능이 여러 개 얽힌 프로젝트에서는 “다 만들어줘”보다 “이 기능의 뼈대만 만들고, 나머지는 함수 껍데기로 남겨줘”가 훨씬 유용한 요청이 된다. 이번 편에서는 FastAPI로 진단·기록·대화·첨삭 네 종류의 엔드포인트를 각각 독립적으로 세우고, 외부 AI 호출처럼 아직 확정되지 않은 부분은 함수 하나로 분리해 나중에 갈아끼울 수 있게 설계했다.
이렇게 나눠두면 좋은 점은 또 있다. 나중에 팀원이 합류하거나, AI 튜터 대화만 다른 AI 서비스로 교체하고 싶을 때도 call_tutor_ai, call_writing_feedback 같은 함수 몇 개만 살펴보면 된다. 엔드포인트 전체를 다시 훑을 필요가 없다는 뜻이다. 이는 처음부터 완성형 코드를 한 번에 요청했다면 얻기 어려운 구조다.
기능이 늘어날수록 이런 식으로 경계를 미리 그어두는 습관이 중요해진다. 지금은 각 함수가 더미 응답만 반환하지만, 실제 AI 서비스를 연결하는 시점이 오면 이 문서에서 정리한 뼈대가 그대로 통합 지점이 되어준다. 다음 편에서는 이렇게 만든 코드를 팀 단위로 관리하고 정리하는 리팩토링 이야기로 이어간다.
참고 자료
- FastAPI 공식 문서(한국어) — https://fastapi.tiangolo.com/ko/
#영어학습프로그램백엔드, #FastAPI뼈대설계프롬프트, #AI튜터대화모듈구현, #바이브코딩영어앱, #외부AI연동함수분리, #바이브코딩, #FastAPI, #영어학습프로그램, #AI개발파트너, #백엔드설계
