이 단계에서 하는 것: Gemini API 키를 준비하고 백엔드 개발자 서브에이전트를 설정한다. API 명세에 따라 거래·통계 API를 Next.js API route로 구현하고, 서버에서 Gemini API를 호출하는 자동 분류·요약 기능을 추가한다. 다음 단계로 넘길 것: Supabase의 실제 데이터를 처리하는 API와 서버에서 실행되는 AI 분류·요약 기능.
앞 단계에서 DBA가 Supabase의 테이블과 인증을 설정했고, 아키텍트가 API 명세서를 작성했다. 이제 그 명세에 따라 API를 구현한다. 잔액·통계는 서버에서 계산하고, 클라이언트는 Supabase에 직접 접근하지 않는다. 비밀값은 서버 환경변수로 관리한다.
docs/API명세.md에 인증 기준 엔드포인트와 상태코드가 정리돼 있다.docs/ERD.md대로 Supabase에 테이블·시드가 있고, 회원가입/로그인과 RLS가 동작한다.docs/가이드/에 코딩컨벤션·프로젝트구조 문서가 있다..env.local에 Supabase 접속 정보가 들어 있다. (Gemini API 키는 이 장 첫 단계에서 발급한다.)자동 분류·월별 요약 기능을 구현하기 전에 Gemini API 키를 준비한다. 이 실습은 Gemini API를 사용하며, 무료 사용량으로 기능을 시험한다.
https://aistudio.google.com)에 구글 계정으로 로그인한다..env.local 파일을 직접 열어, 발급받은 키를 아래 한 줄로 내가 적어 넣는다. NEXT_PUBLIC_을 붙이지 않는다(붙이면 브라우저로 노출된다).GEMINI_API_KEY=발급받은키[중요] 키를 Claude 대화창에 붙여 넣지 않는다. 앞에서 DB 연결 문자열을 다룬 것처럼 사람이 비밀값을
.env.local에 직접 입력한다. 대화창에 입력한 값은 대화 기록에 남을 수 있다. Claude는 이후 코드에서 해당 환경변수를 참조하도록 구현한다.
이렇게 나오면 성공: 내가 직접 .env.local을 열어 GEMINI_API_KEY=... 한 줄을 적어 넣었다. 이 이름은 배포 단계의 Vercel 환경변수에서 그대로 다시 쓴다.
[확인]
.env.example도 갱신한다. 환경변수 이름을 추가했으므로 견본 파일에도 이름을 기록한다. 실제 키 값은 넣지 않는다.
.env.local에 있는 변수 이름 중 .env.example에 빠진 것을 더해줘. 값은 비우고 이름만. 이미 있으면 그대로 둬.백엔드 개발자가 API 명세, ERD, 가이드 문서를 기준으로 구현하도록 책임을 정의한다.
'백엔드 개발자' 서브에이전트를 만들어줘. 서버 구현을 담당한다.docs/API명세.md·docs/ERD.md와 docs/가이드/코딩컨벤션.pdf·프로젝트구조.pdf의 내용을 기준으로 구현한다. 라이브러리는 최신 공식 문서를 확인해서 쓰고, 필요한 의존성은 알아서 추가한다.화면(프론트엔드), DB 스키마·마이그레이션(DBA), API 명세서는 수정하지 않는다. 명세에서 빠진 내용을 발견하면 먼저 보고한다.명세에 없는 걸 임의로 만들지 않고, 애매하면 먼저 묻는다.이렇게 나오면 성공: 백엔드 개발자 역할이 만들어지고, API 명세·ERD·가이드 문서를 근거로 구현하며 애매한 것은 먼저 묻겠다고 정리된다. 서브에이전트를 만든 뒤에는 Claude Code를 한 번 다시 띄운다(/exit 뒤 claude). 새 서브에이전트는 다음 세션부터 보인다.
거래·통계 API와 AI 분류·요약 기능은 API 명세서에 엔드포인트가 정의되어 있다. 서브에이전트가 이 문서와 역할 규칙을 참고하도록 다음과 같이 요청한다.
백엔드 개발자 서브에이전트로 백엔드 개발해줘. 결제는 뒤에서 따로 붙일 거니까 이번엔 빼줘.AI 모델은 docs/아키텍처.md에 정한 것을 쓴다(다른 모델로 바꾸지 마).명세에 없는 세부는 명세의 공통 규칙대로 네가 정하고 보고에 적어. 명세·ERD·마이그레이션은 고치지 않는다.확인은 내가 한다. DB 값을 고치거나 실제 AI 호출을 하지 마.뒤 두 줄이 있는 이유: 이 줄이 없으면 AI가 구현 전에 계획을 세우며 명세의 빈틈(오류 판정 순서, 문장 세는 기준 등)을 질문으로 올리고 "명세를 먼저 고칠까"를 묻는다. 그리고 확인하겠다며 DB의 프리미엄 값을 바꾸고 실제 AI를 부르려 한다. 세부는 개발자가 정해도 되는 것이고, 확인은 사람이 다음 장에서 화면으로 한다.
지시가 짧은 이유: 거래 생성·목록·삭제, 월별 통계, AI 자동 분류와 요약의 요구사항은
API명세.md에 있다. 데이터 구조는ERD, 코드 배치는프로젝트구조.pdf, 사용할 AI는아키텍처.md에서 확인할 수 있다. 서버의 책임과 비밀값 관리 규칙은CLAUDE.md와 서브에이전트 설정에 적혀 있다.
이렇게 바꿔도 좋다: 분류 카테고리 후보를 우리 카테고리 목록으로 제한해 보자.
이렇게 나오면 성공: 거래 생성·목록 조회·월별 통계 API가 서버에서 Supabase에 접근해 로그인 사용자의 데이터만 응답하고, 거래 내용을 넣으면 카테고리를 추천하는 API와 이번 달 소비를 두 문장으로 요약하는 API가 동작한다. Gemini 호출은 서버에서 일어나고 키는 클라이언트로 새지 않는다. app/api/ 아래에 명세의 엔드포인트가 결제 승인만 빼고 전부 라우트로 생겼다 — 명세 1절과 폴더를 나란히 놓고 하나씩 센다. 결제 라우트가 생겼으면 "결제는 이번엔 빼 달라고 했다"고 되돌린다.
.env.local의 Supabase 접속 정보와 RLS 설정을 다시 확인한다. AI가 "DB 값을 바꾸겠다"고 하면 거절한다 — 프롬프트에 그 말이 있다. AI 추천이 항상 '기타'로만 나오면 Gemini 호출이 실패해 대체값으로 떨어지는 것이다(화면에는 오류가 안 보이고 서버 로그에만 남는다) — .env.local의 GEMINI_API_KEY가 맞는지, 키를 넣은 뒤 "개발 서버 다시 켜줘"라고 했는지 확인한다.다음 단계에서는 프론트엔드 개발자 서브에이전트에게 로그인·거래·통계 화면 구현을 맡기고, 이 API를 호출해 실제 데이터를 표시한다.