이 단계에서 하는 것: 앞에서 설정한 솔루션 아키텍트 서브에이전트에게 PRD·화면기획서·ERD를 바탕으로 API 명세서(
docs/API명세.md)를 작성하도록 요청한다. 양식은docs/templates/API-Spec-템플릿.md, 엔드포인트는 아키텍트가 화면기획서에서 뽑는다. 사람이 확인하고 명세를 1.0으로 확정한다. 다음 단계로 넘길 것: 엔드포인트마다 요청·응답·오류와 화면별 값 대조표가 정리된, 버전 1.0 '확정' 상태의 API 명세서.
API 명세서는 백엔드와 프론트엔드가 함께 따르는 기준이다. 요청 경로와 형식, 응답 형식, 상태 코드를 먼저 정하면 두 역할이 각각 구현할 때 같은 규칙을 참고할 수 있다. 이번 단계에서는 코드를 작성하기 전에 명세서를 완성한다.
명세서는 docs/templates/API-Spec-템플릿.md의 양식에 따라 작성한다. 양식에는 머리(버전·상태·근거·변경 이력)와 0 공통 규칙, 1 엔드포인트 목록, 2 엔드포인트별 명세(요청·응답·오류 표), 3 화면별 값 대조표, 4 계산값, 5 질문의 여섯 절이 있다. 초안은 0.1, 사람이 확정하면 1.0으로 올리고, 결제처럼 뒤에 엔드포인트가 바뀌면 1.1로 올린다. 엔드포인트의 경로와 메서드는 AI가 설계하지 않고 개발 리더가 표로 준다. 이름과 주소는 설계가 아니라 약속이라, AI가 정하게 두면 사람마다 /api/stats와 /api/summary처럼 갈라져 서버와 화면이 서로 다른 주소를 부르게 된다.
docs/PRD.md·docs/화면기획서.md·docs/아키텍처.md·docs/ERD.md를 작성했고, Supabase 테이블과 인증을 설정했다.docs/templates/API-Spec-템플릿.md를 한 번 열어 둔다 — 여섯 절과 표 아래의 작성 규칙이 있다.아키텍처 설계를 맡았던 솔루션 아키텍트 서브에이전트를 다시 사용한다. 양식(템플릿)과 근거 문서를 지정한다.
솔루션 아키텍트 서브에이전트로, docs/PRD.md·docs/화면기획서.md·docs/ERD.md를 근거로 API 명세서를 docs/templates/API-Spec-템플릿.md 양식대로 docs/API명세.md에 만들어줘.화면이 서버에 요청할 것을 엔드포인트로 뽑아. 요청·응답의 필드 이름은 ERD의 컬럼 이름을 그대로 쓴다. 결제 승인은 뒤 단계에서 구현하지만 명세에는 지금 적는다.명세가 정할 수 있는 것(기본값, 빈 결과, 실패 응답 모양, 오류 code)은 네가 정하고 0절 공통 규칙에 적어. 질문은 PRD·ERD를 바꿔야 하는 것만 5절에 남겨.엔드포인트를 아키텍트에게 맡기는 이유: 필요한 기능은
PRD에, 화면이 서버에 요청할 것은화면기획서에, 저장된 데이터는ERD에 있다. 아키텍트는 그것으로 엔드포인트와 요청·응답·오류를 뽑는다. 사람이 경로와 메서드를 불러 주면 API 설계를 사람이 하는 셈이다. 같은 기능이라도/api/stats/monthly와/api/summary처럼 사람마다 주소가 다를 수 있지만, 뒤 단계의 서버와 화면은 이 명세 하나를 보고 만들므로 각자의 프로젝트 안에서는 어긋나지 않는다. 상태 코드와 라우트 구성 원칙은프로젝트구조.pdf가, 서버의 책임은CLAUDE.md가 이미 정하고 있다.
이렇게 나오면 성공: docs/API명세.md가 만들어지고, 다음이 담겨 있다.
- 머리에 버전 0.1, 상태 '초안', 근거 문서(PRD·화면기획서·ERD)와 그 버전.
- 1절 엔드포인트 목록이 화면기획서의 화면마다 필요한 요청(내 정보, 카테고리 목록, 거래 목록·생성·수정·삭제, 월별 통계, AI 추천·요약, 결제 승인)을 다 덮는다. 열 개 안팎이다. 화면이 쓰는 요청이 빠졌으면 그 화면 이름을 짚어 더해 달라고 하고, 로그인 엔드포인트처럼 아키텍처가 두지 않기로 한 것이 생겼으면 빼 달라고 한다.
- 2절에 엔드포인트마다 요청·응답·오류 표가 있고, 필드 이름이 ERD의 컬럼 이름과 같다(ERD를 옆에 띄워 두세 개 대조한다).
- 0절 공통 규칙에 "로그인 정보가 없으면 401", "집계·AI 호출·프리미엄 판정·결제 승인은 서버가 한다"가 있다. 요약 엔드포인트에 403(프리미엄 아님)이 있다.
- 3절 화면별 값 대조표에 화면기획서의 화면(로그인·회원가입은 API를 쓰지 않으니 '대상 아님'으로 표시될 수 있다)이 있고, 5절은 비어 있거나 PRD·ERD를 바꿔야 하는 질문만 남아 있다.
파일을 열어 위 다섯 가지를 직접 본 뒤, AI에게도 두 가지를 확인시킨다.
방금 만든 docs/API명세.md에서, 잔액·통계 집계와 AI 호출·프리미엄 판정이 서버에서 이뤄진다고 명확히 적혔는지 확인하고,각 엔드포인트가 미인증(401) 상황을 어떻게 다루는지 한 줄씩 확인후, 없으면 API명세.md 수정 작성해.이렇게 나오면 성공: 집계·AI 호출·프리미엄 판정이 서버 몫이라는 점과, 모든 엔드포인트의 401 처리가 한 줄씩 확인된다. 빠진 것은 AI가 명세에 보탠다.
명세 단계에서 "명세가 정할 수 있는 것은 네가 정해"라고 했으니 질문은 거의 남지 않는다. 남은 것도 아키텍트 의견대로 정하게 하고 확정한다. PRD를 바꿔야 하는 질문이 남았으면 아래 프롬프트에 답을 한 줄 덧붙인다.
개발 리더로서 확정한다. 5절에 남은 질문은 네 의견대로 정하고 변경 이력에 적어. 상태를 '확정', 버전을 1.0으로 바꿔.명세와 어긋나게 된 docs/아키텍처.md·docs/ERD.md의 문장은 명세에 맞춰 고치고 각 문서의 변경 이력에 적어줘. 스키마·마이그레이션·DB는 바꾸지 않는다.이렇게 나오면 성공: 머리의 상태가 '확정', 버전이 1.0으로 바뀌고 변경 이력에 결정한 내용이 적힌다(여러 줄이어도 된다). 5절 질문 표가 비어 있다. 엔드포인트 수가 초안과 같다 — 늘었으면 변경 이력에서 왜 늘었는지 확인한다. 한국 시간 기준이냐, AI 제한 시간은 몇 초냐처럼 PRD에 있는 걸 물으면 "PRD에 있다, 그대로"라고 문서를 가리킨다 — 프롬프트에 다시 적지 않는다.
버전을 올리는 이유: 다음 단계의 백엔드와 프론트엔드는 "명세 1.0대로" 구현한다. 결제 단계에서 승인 엔드포인트의 세부가 바뀌면 1.1로 올리고 바꾼 것을 변경 이력에 적는다. 그래야 코드가 어느 명세를 따랐는지 알 수 있다.
docs/API명세.md 작성을 맡겼다. 양식은 템플릿, 엔드포인트는 아키텍트가 화면기획서에서 뽑았다.API 명세서는 다음 단계의 구현 기준이다. 백엔드는 명세에 따라 API를 구현하고, 프론트엔드는 명세에 적힌 경로와 형식으로 요청한다. 다음 단계에서는 백엔드 개발자 서브에이전트에게 API와 AI 기능 구현을 맡긴다.