오늘은 AI 오케스트레이션 캠프 최종 프로젝트의 새로운 후보를 구체화하고, 이후 수업에서는 REST API 설계와 AI 에이전트의 툴 호출 명세를 학습했다.
최근 멘토링에서 반복해서 강조된 것은 기능을 먼저 생각하지 말고, 누가 어떤 상황에서 불편을 겪는지 구체적으로 정의해야 한다는 점이었다.
기존에 검토하던 AI 연애 리얼리티 서비스 역시 기존 서비스와 비교했을 때 어떤 문제가 남아 있는지 충분히 확인하지 못한 상태였다. 그래서 오늘은 다른 분야를 상상하기보다 내가 직접 경험한 일에서 문제를 찾아보기로 했다.
그렇게 떠올린 분야가 음악 레슨이었다.
처음에는 동네 음악 레슨을 지도에서 찾아보고 가격을 비교하는 서비스를 생각했지만, 팀원들과 논의하면서 방향이 달라졌다.
레슨을 찾는 사람보다 여러 플랫폼에 레슨을 등록하는 선생님이 겪는 반복적인 업무가 더 구체적인 문제일 수 있다는 것을 발견했다.
이후 API 설계 수업을 들으며, 기획한 서비스를 실제로 구현한다면 기능뿐 아니라 요청·응답 구조, 인증과 권한, 실행 실패까지 정의해야 한다는 설계 과제도 살펴봤다.
1. 첫 번째 아이디어: 지도 기반 음악 레슨 탐색 서비스
음악 레슨 정보는 여러 곳에 흩어져 있다
예전에 미디와 믹싱을 배우려고 선생님을 찾았던 경험이 있다.
가까운 지역에서 어떤 선생님에게 배울 수 있는지 알아보려면 여러 사이트를 확인해야 했다.
- 당근이나 숨고 같은 생활 서비스 플랫폼
- 뮬이나 네이버 카페 같은 음악 관련 커뮤니티
- 크몽이나 탈잉 같은 서비스 플랫폼
- 인스타그램 등 개인 SNS
문제는 모든 선생님이 같은 플랫폼에 등록하는 것이 아니라는 점이었다.
어떤 선생님은 특정 커뮤니티에만 글을 올리고, 어떤 선생님은 SNS를 통해서만 문의를 받는다.
수업 가격도 비교하기 어려웠다.
예를 들어 한 선생님은 주 1회 90분 수업을 월 4회 진행하고, 다른 선생님은 주 1회 120분 수업을 월 4회 진행한다. 두 수업의 월 가격만 비교하면 실제 수업 시간에 따른 차이를 놓칠 수 있다.
게다가 가격을 공개하지 않고 상담을 통해 안내하는 경우도 있었다.
지도에서 위치와 가격을 비교한다면?
이 경험을 바탕으로 생각한 서비스는 다음과 같았다.
- 기타·보컬·미디·작곡 등 배우고 싶은 분야를 선택한다.
- 지도에서 원하는 지역을 탐색한다.
- 해당 지역의 레슨 목록과 가격을 확인한다.
- 수업 시간과 횟수를 기준으로 시간당 가격을 비교한다.
- 관심 있는 선생님의 상세 정보를 확인하고 문의한다.
부동산 앱에서 지도와 가격을 함께 확인하는 방식을 음악 레슨에 적용하는 아이디어였다.
레슨생을 직접 가르쳤던 경험에서도 위치와 가격은 중요한 조건이었다. 처음에는 선생님의 포트폴리오나 커리큘럼을 어떻게 평가해야 할지 모르는 사람도 있었기 때문이다.
하지만 이 아이디어에도 해결해야 할 질문이 있었다.
2. 팀 기획 회의: 편리한 기능이 곧 해결해야 할 문제일까?
회의에서는 지도 기반 서비스의 문제 정의가 아직 모호하다는 피드백을 받았다.
내가 제시한 불편함은 여러 사이트에 정보가 분산되어 있어 비교하기 어렵다는 것이었다.
그런데 팀원들은 이런 의견을 제시했다.
여러 사이트에 흩어진 정보를 찾는 것이 문제라면, 새로운 플랫폼을 만들지 않고 AI가 기존 사이트를 조사해 결과를 정리해 주는 방식으로도 해결할 수 있지 않을까?
생각해 보니 충분히 가능한 접근이었다.
사용자가 "수유동 근처에서 랩 레슨을 찾아줘"라고 요청하면 AI가 여러 출처에서 후보를 조사하고, 지도나 표로 정리해 보여주는 방식이다.
굳이 새로운 중개 플랫폼을 운영할 필요는 없을 수도 있었다.
플랫폼을 만든다면 선생님과 레슨생을 모집해야 하고, 등록 정보의 최신성도 관리해야 한다. 실제 문의와 거래까지 연결한다면 더 많은 운영 문제가 발생할 수 있다.
무엇보다 사용자가 기존 검색이나 일반 AI를 이용한 뒤에도 어떤 불편함을 겪는지 확인하지 못했다.
레슨을 적극적으로 비교하는 사람과 SNS에서 우연히 레슨 광고를 보고 관심을 갖는 사람은 탐색 과정 자체가 다를 수 있다는 점도 생각하게 됐다.
결국 지도는 내가 익숙하고 편하다고 생각한 인터페이스이지, 아직 검증된 해결책은 아니었다.
그래서 이 아이디어는 후속 후보로 남기고 다른 방향을 검토했다.
3. 두 번째 아이디어: 레슨 선생님의 반복적인 등록 업무
직접 레슨생을 모집하면서 겪었던 일
나는 음악 레슨을 제공하는 입장에서도 여러 플랫폼을 사용해 봤다.
플랫폼에 따라 홍보와 관리 방식이 조금씩 달랐다.
- 네이버 카페: 일정한 주기로 레슨 모집 글을 게시했다.
- 뮬: 기존 게시글의 '최신글 올리기' 기능을 활용했다.
- 숨고: 견적 요청에 따라 장소, 가격, 커리큘럼 등을 다시 설명했다.
- 다른 레슨 플랫폼: 사이트마다 요구하는 양식에 맞춰 수업 정보를 입력해야 했다.
특히 번거로웠던 부분은 같은 수업을 소개하는데도 플랫폼마다 형식이 다르다는 것이었다.
어떤 곳에서는 자유롭게 홍보 글을 작성할 수 있지만, 다른 곳에서는 정해진 항목을 입력하거나 여러 가격 상품을 구성해야 했다.
예를 들어 원래 운영하는 수업이 주 1회 90분, 월 4회 과정 하나뿐이어도 플랫폼에서 여러 가격 옵션을 요구하면 추가 내용을 준비해야 한다.
단순히 기존 글을 복사해서 붙여넣는 것으로 끝나지 않는 것이다.
최초 등록, 게시글 갱신, 문의 응대는 다른 문제였다
처음에는 이러한 일들을 모두 '레슨 홍보가 번거롭다'는 하나의 불편함으로 생각했다.
하지만 실제 업무를 나누어 보니 서로 다른 과정이었다.
업무반복되는 일
| 최초 등록 | 플랫폼별 필수 항목 확인 및 정보 입력 |
| 게시글 관리 | 글 재등록, 최신글 갱신, 정보 수정 |
| 문의 응대 | 가격·장소·커리큘럼 설명 |
내 경험상 하루 약 한 시간씩 견적과 상담 답장에 사용했던 시기도 있었다.
그러나 이것은 여러 문의에 응답한 시간을 합친 것이지, 최초 등록에 걸리는 시간이 아니다.
검증하지 않은 시간을 임의로 합치면 실제 해결하려는 문제가 흐려질 수 있다.
이번에는 범위를 좁혀 여러 플랫폼에 레슨을 처음 등록하는 과정부터 살펴보기로 했다.
4. AI 기반 음악 레슨 등록 자동화 서비스로 방향 전환
두 번째 아이디어를 논의하면서 문제를 조금 더 구체적으로 설명할 수 있게 됐다.
타깃 사용자
여러 플랫폼에서 레슨생을 모집하는 개인 음악 레슨 선생님이다.
랩뿐 아니라 보컬, 기타, 드럼, 미디, 작곡, 믹싱 등 다양한 음악 레슨을 고려했다.
페인포인트와 문제 정의
**페인포인트(Pain Point)**는 사용자가 실제 업무에서 느끼는 불편함이다.
이번에 발견한 불편함은 같은 레슨 정보를 여러 플랫폼에 맞춰 반복적으로 작성하고 수정해야 한다는 것이다.
이를 구체적인 문제로 정리하면 다음과 같다.
음악 레슨 선생님은 여러 플랫폼에서 레슨생을 모집할 때 같은 수업 정보를 사이트별 입력 방식과 요구사항에 맞게 반복해서 준비하고 등록하는 데 시간과 노력이 든다.
첫 번째 아이디어보다 사용자와 업무 과정이 구체적으로 드러나는 문제 정의였다.
핵심 기능: 한 번 입력하고 플랫폼별로 변환하기
구상한 서비스의 흐름은 다음과 같다.
레슨 선생님이 공통 정보 입력
↓
등록할 플랫폼 선택
↓
플랫폼별 필수 정보 확인
↓
부족한 정보 추가 질문
↓
AI가 사이트별 내용 변환
↓
선생님이 검토 및 수정
↓
허용된 방식으로 등록 지원
↓
완료·실패·확인 필요 상태 표시
선생님은 레슨 장소, 가격, 시간, 커리큘럼, 이력 등을 한 번 입력한다.
AI는 각 플랫폼에서 필요한 정보를 확인하고 입력 양식에 맞춰 내용을 준비한다.
여기서 중요한 것은 AI가 없는 정보를 임의로 만들어서는 안 된다는 점이다.
예를 들어 한 플랫폼이 세 가지 가격 상품을 요구하는데 선생님이 한 과정만 운영한다면, AI가 나머지 상품과 가격을 마음대로 만들면 안 된다.
필요한 정보가 부족하다고 안내하고 실제 선생님에게 확인받아야 한다.
5. AI 에이전트를 어디까지 활용할 수 있을까?
서비스 아이디어를 구체화하면서 실제 구현에 필요한 기술도 논의했다.
플랫폼별 입력 항목을 확인하고 내용을 변환하는 작업에는 LLM을 활용할 수 있을 것 같았다.
브라우저 자동화, API, MCP 등의 방법도 후보로 언급됐다.
다만 자동으로 등록할 수 있다는 가정부터 하고 개발해서는 안 된다.
플랫폼마다 정책과 인증 방식이 다르고, 자동 등록을 허용하지 않을 수도 있기 때문이다.
또한 공개된 웹페이지라고 해서 자동 수집이나 게시가 모두 허용되는 것은 아니다. 허용된 API와 자동화 경로부터 확인해야 한다.
멀티 에이전트가 꼭 필요할까?
프로젝트가 AI 오케스트레이션 과정이라고 해서 처음부터 여러 에이전트를 만드는 것이 정답은 아니다.
현재 생각한 역할은 정보 정리, 플랫폼 요구사항 확인, 내용 변환, 오류 검토, 등록 지원이다.
하지만 이것들을 각각 독립된 에이전트로 구현할 필요가 있는지는 아직 알 수 없다.
일반적인 템플릿이나 단일 AI만으로 해결할 수 있는 업무도 있을 것이다.
따라서 실제 작업을 비교하면서 역할을 분리할 필요가 있는지 판단하고, 멀티 에이전트 구조의 추가 가치도 확인할 계획이다.
6. 오늘 진행한 작업과 GitHub 기획안 정리
오늘은 아침 회의와 이전 멘토링 피드백을 정리하고, 신규 프로젝트 후보를 검토했다.
회의 과정에서 음악 레슨 탐색 서비스와 등록 자동화 서비스를 비교했으며, 두 번째 아이디어를 우선 구체화하기로 했다.
이후 회의 내용과 직접 경험한 사례를 바탕으로 AI 기반 음악 레슨 다중 플랫폼 등록 지원 서비스 1차 기획안을 작성했다.
기획안에는 타깃 사용자, 페인포인트, 문제 정의, 서비스 흐름, AI 활용 방향, 기술적 제약, 사용자 검증 계획 등을 정리했다.
또한 하루 동안 진행한 내용과 남은 과제를 GitHub 작업 기록에 남겼다.
아직 구현이나 자동 등록 테스트를 진행한 것은 아니다.
현재 완료한 것은 사용자 문제를 구체화하고 검증할 수 있는 형태의 1차 기획안을 만드는 작업이다. 팀의 최종 프로젝트 주제도 아직 확정되지 않았다.
7. REST API 설계 수업: 기능을 어떻게 연결하고 정의할 것인가?
프로젝트 기획을 정리한 이후에는 REST API 설계와 API 명세서 작성 방법에 관한 강의가 이어졌다.
이번 수업은 서비스를 실제로 개발하기 전에 프론트엔드, 백엔드, AI 에이전트가 어떤 정보를 주고받고, 각각 어떤 책임을 가져야 하는지 문서로 정의하는 과정에 관한 내용이었다.
REST API란?
REST(Representational State Transfer)는 클라이언트와 서버가 자원을 중심으로 통신하도록 설계하는 아키텍처 스타일이다.
API(Application Programming Interface)는 서로 다른 프로그램이 기능이나 데이터를 주고받을 수 있도록 정한 인터페이스다.
REST API에서는 주로 HTTP 메서드를 사용해 특정 자원에 대한 작업을 표현한다.
대표적인 메서드는 다음과 같다.
HTTP 메서드주요 기능CRUD
| GET | 데이터 조회 | Read |
| POST | 데이터 생성·처리 요청 | Create 등 |
| PUT | 데이터 전체 교체 | Update |
| PATCH | 데이터 일부 수정 | Update |
| DELETE | 데이터 삭제 | Delete |
여기서 CRUD는 Create, Read, Update, Delete의 약자로 데이터를 생성·조회·수정·삭제하는 기본 작업을 의미한다.
REST API를 설계할 때는 URL에 동작을 나타내는 명령어를 넣기보다 무엇을 다루는지 자원 중심으로 표현하는 것이 중요하다고 설명했다.
예를 들어 레슨 정보를 관리하는 API를 만든다고 가정하면 다음과 같이 설계할 수 있다.
GET /api/v1/lessons
POST /api/v1/lessons
GET /api/v1/lessons/{lesson_id}
PATCH /api/v1/lessons/{lesson_id}
DELETE /api/v1/lessons/{lesson_id}
이것은 수업 내용을 레슨 서비스에 적용해 본 가상의 예시이며, 실제 프로젝트에서 확정하거나 구현한 API는 아니다.
같은 URL이라도 HTTP 메서드에 따라 수행하는 작업이 달라진다.
REST의 주요 설계 원칙
강의에서는 특히 세 가지를 설명했다.
첫 번째는 클라이언트와 서버의 분리다.
프론트엔드는 사용자에게 화면을 보여주고 입력을 받는다. 백엔드는 요청을 처리하고 데이터를 관리한다.
역할을 분리하면 화면과 서버 기능을 독립적으로 개발하고 수정하기 쉬워진다.
두 번째는 무상태성(Stateless)이다.
서버는 개별 요청을 이해하고 처리하는 데 필요한 정보를 요청마다 받을 수 있어야 한다.
이것은 서버가 데이터베이스를 사용하거나 정보를 저장할 수 없다는 뜻이 아니다. 이전 요청에서 기억한 사용자별 대화 상태에 의존하지 않고 현재 요청을 처리할 수 있도록 한다는 의미다.
세 번째는 일관된 인터페이스다.
API마다 다른 규칙을 사용하는 대신 자원 식별 방식과 요청·응답 구조에 일관성을 유지해야 한다.
이러한 규칙이 있어야 여러 개발자가 같은 API 명세서를 보고 작업할 수 있다.
8. HTTP 요청과 응답, 상태 코드를 이해하기
REST API 설계에서 중요한 부분은 클라이언트가 무엇을 보내고 서버가 무엇을 반환하는지 정의하는 것이다.
HTTP 요청은 어떻게 구성될까?
HTTP 요청 메시지는 크게 시작줄, 헤더, 본문으로 구성된다.
다음은 JSON 데이터를 전달하는 요청의 예시다.
POST /api/v1/lessons HTTP/1.1
Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json
{
"title": "미디 입문 레슨",
"duration_minutes": 90,
"monthly_price": 250000
}
이 예시는 설명을 위해 만든 것으로 실제 API 호출 결과는 아니다.
각 구성 요소의 역할은 다음과 같다.
- POST: 서버에 데이터를 생성하거나 처리하도록 요청하는 HTTP 메서드
- /api/v1/lessons: 요청 대상 자원을 나타내는 경로
- Authorization: 인증 정보를 전달하는 헤더
- Content-Type: 본문의 데이터 형식을 나타내는 헤더
- JSON: 서버에 전달하는 실제 데이터 형식
JSON(JavaScript Object Notation)은 키와 값으로 데이터를 표현하는 형식으로, API에서 자주 사용된다.
상태 코드로 요청 결과 구분하기
서버는 요청을 처리한 결과를 HTTP 상태 코드로 반환한다.
상태 코드의미
| 200 OK | 요청 성공 |
| 201 Created | 새로운 자원 생성 완료 |
| 202 Accepted | 요청 접수, 처리 완료는 아님 |
| 204 No Content | 성공했지만 반환할 본문 없음 |
| 400 Bad Request | 잘못된 요청 |
| 401 Unauthorized | 인증 실패 또는 인증 정보 없음 |
| 403 Forbidden | 접근 권한 부족 |
| 404 Not Found | 요청한 자원을 찾을 수 없음 |
| 409 Conflict | 현재 자원 상태와 요청이 충돌 |
| 422 Unprocessable Content | 요청 내용의 검증·처리 문제 |
| 500 Internal Server Error | 서버 내부 오류 |
강의에서는 상태 코드를 개별 숫자만으로 외우기보다 그룹별로 이해하는 것도 강조했다.
2xx는 성공, 4xx는 클라이언트 요청과 관련된 오류, 5xx는 서버 측 오류를 나타낸다.
특히 401과 403은 구분해야 한다.
401은 인증되지 않았거나 인증 정보가 유효하지 않은 상황이고, 403은 요청을 수행할 권한이 없는 상황이다.
사용자가 로그인했더라도 다른 사람의 레슨 정보를 수정할 권한은 없을 수 있다.
이처럼 사용자가 누구인지 확인하는 인증과 무엇을 할 수 있는지 확인하는 권한 검사는 서로 다른 과정이다.
9. API 명세서에는 무엇을 작성해야 할까?
강의에서는 API 구현에 앞서 명세서에 포함해야 하는 항목들을 설명했다.
주요 구성은 다음과 같다.
- 공통 정보 및 인증 방식
- 전체 API 목록
- 엔드포인트별 상세 명세
- 입력값 검증과 권한 규칙
- AI 에이전트의 툴 호출 명세
- 타임아웃·재시도·중복 실행 방지 등 실행 규칙
여기서 엔드포인트(Endpoint)는 클라이언트가 특정 API 기능에 접근하기 위한 경로와 요청 방식을 의미한다.
엔드포인트별 상세 명세
각 API에서는 다음과 같은 내용을 정의해야 한다.
- 호출 목적: 누가 언제 어떤 이유로 사용하는가?
- 요청 방식: HTTP 메서드와 URL은 무엇인가?
- 헤더 및 파라미터: 어떤 인증 정보와 값이 필요한가?
- 요청 본문: 어떤 JSON 데이터를 전달하는가?
- 검증 규칙: 필수 정보와 권한을 어떻게 확인하는가?
- 정상 응답: 성공했을 때 어떤 결과를 반환하는가?
- 오류 응답: 실패했을 때 어떤 코드와 메시지를 반환하는가?
- 실행 규칙: 시간 초과, 재시도, 중복 요청은 어떻게 처리하는가?
URL에서도 명명 규칙을 통일하도록 설명했다.
일반적으로 소문자와 하이픈을 사용하고, API 버전을 경로에 포함하는 방식을 활용할 수 있다.
GET /api/v1/registration-jobs
목록을 조회할 때 필터, 정렬, 페이지 번호 등은 쿼리 파라미터로 전달할 수 있다.
GET /api/v1/registration-jobs?status=completed&page=1&size=20
이러한 규칙은 서로 다른 개발자가 API를 이해하고, 프론트엔드와 백엔드를 연결하는 데 도움이 된다.
요구사항과 API 문서를 연결하기
강의에서는 기능 요구사항을 나타내는 FR ID도 강조했다.
기획서에 작성한 기능 요구사항이 실제 어떤 API로 구현되고, 어떤 데이터와 권한 규칙을 사용하는지 연결해야 한다는 내용이다.
최종적으로는 기능 요구사항, API 설계서, DB 스키마, AI 보안 규칙, 통합 테스트 결과 사이의 일관성을 확인해야 한다.
단순히 문서를 여러 개 작성하는 것이 아니라 모든 문서가 같은 기능과 동작을 설명해야 한다는 점이 중요하다.
10. AI 에이전트의 툴 호출은 일반 API와 무엇이 다를까?
이번 수업에서 프로젝트와 직접 연결해 생각해 볼 수 있었던 부분은 AI 에이전트의 툴 호출 명세였다.
일반적인 REST API에서는 프론트엔드나 외부 시스템이 서버에 요청을 보낸다.
반면 AI 에이전트가 툴을 사용할 때는 LLM이 작업에 필요한 툴을 선택하고 호출 인자를 생성할 수 있다.
예를 들어 레슨 등록 지원 서비스에서 다음과 같은 작업을 생각할 수 있다.
사용자가 레슨 정보 입력
↓
AI가 입력 정보 분석
↓
등록할 플랫폼의 필수 항목 확인
↓
부족한 정보 확인 요청
↓
등록 초안 생성
↓
사용자 검토 및 승인
↓
허용된 등록 기능 실행
하지만 LLM이 생성한 인자를 곧바로 신뢰해서는 안 된다.
AI가 잘못된 값을 생성하거나 권한을 벗어나는 작업을 요청할 수도 있기 때문이다.
AI 툴 실행 전 확인해야 할 사항
강의에서는 툴 실행 전에 서버가 다음 항목을 검증해야 한다고 설명했다.
- 해당 에이전트에게 허용된 툴인가?
- 요청한 사용자에게 작업 권한이 있는가?
- 작업 대상 데이터가 해당 사용자의 소유인가?
- 필요한 사용자 승인 절차를 거쳤는가?
예를 들어 A 선생님의 레슨 정보를 B 선생님의 계정으로 수정하거나 등록해서는 안 된다.
AI가 생성한 요청이라고 해서 인증과 권한 검사를 생략할 수 없는 것이다.
또한 에이전트가 여러 개라면 어떤 에이전트가 어떤 툴을 사용하고, 실패했을 때 누구에게 다음 작업을 전달하는지까지 명세해야 한다.
강의에서는 슈퍼바이저가 작업을 분배하고, 진단 에이전트가 문제를 분석한 뒤 복구 에이전트로 전달하는 흐름을 예로 설명했다.
이 구조를 실제 프로젝트에 적용할지는 아직 결정하지 않았지만, 멀티 에이전트 시스템에서 역할과 실행 권한을 명확히 구분해야 하는 이유를 살펴볼 수 있었다.
11. 오래 걸리는 AI 작업을 처리하는 방법
API 설계에서는 정상적으로 요청을 처리하는 것뿐 아니라 작업이 오래 걸리거나 실패하는 상황도 고려해야 한다.
동기 처리와 비동기 처리
일반적인 API 요청에서는 서버가 작업을 처리하고 결과를 반환할 때까지 클라이언트가 기다릴 수 있다.
하지만 LLM 호출이나 여러 단계의 에이전트 작업은 시간이 오래 걸릴 수 있다.
이런 작업을 모두 요청 처리 중에 끝내려고 하면 응답 시간이 길어지고 서버 자원도 오래 점유하게 된다.
이때 활용할 수 있는 방식이 비동기 작업 처리다.
사용자 요청
↓
서버가 작업 접수
↓
202 Accepted 반환
↓
백그라운드 작업 실행
↓
작업 상태 저장
↓
사용자가 처리 상태 조회
↓
완료 또는 실패 결과 확인
202 Accepted는 서버가 요청을 접수했지만 아직 작업을 완료하지 않았다는 의미다.
따라서 작업 결과를 별도로 확인할 수 있는 구조를 함께 고려해야 한다.
타임아웃, 재시도, 중복 실행 방지
강의에서는 작업이 실패했을 때 재시도하는 방법도 설명했다.
대표적인 방식이 **지수 백오프(Exponential Backoff)**다.
재시도를 즉시 반복하지 않고 1초, 2초, 4초처럼 대기 시간을 늘리는 방식이다.
다만 모든 요청을 무조건 재시도하면 안 된다.
예를 들어 플랫폼에 레슨 등록 요청을 보냈는데 응답이 늦어진 상황을 생각할 수 있다.
실제로는 등록이 완료됐지만 클라이언트가 응답을 받지 못했을 수도 있다. 이때 같은 요청을 다시 보내면 중복 등록이 발생할 수 있다.
이처럼 반복 요청에 의한 잘못된 결과를 방지하려면 **멱등성(Idempotency)**도 고려해야 한다.
멱등성은 동일한 요청을 여러 번 수행해도 서버 자원에 미치는 최종 효과가 같도록 하는 성질이다.
조회에 사용하는 GET이나 자원 교체에 사용하는 PUT은 기본적으로 멱등성을 갖도록 정의된 메서드다. 반면 POST는 일반적으로 중복 실행을 별도로 방지해야 한다.
레슨 등록 자동화에서도 실제 등록 결과를 확인하고, 같은 작업이 반복 실행되지 않도록 하는 방식이 중요할 수 있다.
12. 오늘 배운 API 설계를 프로젝트에 연결한다면?
오늘 작성한 음악 레슨 등록 지원 기획안은 아직 서비스 흐름을 정의하는 초기 단계다.
하지만 API 설계 수업에서 배운 내용을 바탕으로 구현 단계에서 확인해야 할 사항을 구분할 수 있다.
기획한 기능설계 시 확인할 사항
| 레슨 정보 입력 | 입력 JSON 형식과 필수 항목 |
| 플랫폼 선택 | 플랫폼별 요구사항 관리 |
| AI 내용 변환 | 툴 입력·출력 명세와 검증 |
| 사용자 검토 | 수정 권한과 승인 상태 |
| 등록 요청 | 인증 방식과 중복 실행 방지 |
| 등록 상태 확인 | 작업 상태와 오류 응답 |
예를 들어 등록 지원 작업이 오래 걸린다면 요청을 접수한 뒤 별도의 작업 ID를 반환하고, 사용자가 완료 여부를 조회하는 방식을 검토할 수 있을 것이다.
또한 AI가 레슨 소개를 변환했을 때 원본에 없는 가격이나 커리큘럼이 추가되지 않았는지 확인하는 검증 단계도 필요하다.
다만 이것들은 오늘 학습한 설계 개념을 프로젝트 후보에 적용해 본 방향이다.
실제 API 명세 작성, DB 스키마 설계, 에이전트 구현, 성능 테스트까지 진행한 것은 아니다.
프로젝트 주제가 최종 선정되고 구현 범위가 정해진 뒤 구체화해야 한다.
13. 다음에 확인하고 복습할 부분
프로젝트 기획 검증
앞으로는 다른 음악 레슨 선생님들에게 직접 물어볼 계획이다.
- 최근 어떤 플랫폼에 레슨을 등록했는가?
- 최초 등록할 때 어떤 내용을 반복해서 입력했는가?
- 플랫폼별 양식 때문에 추가로 준비한 정보는 무엇인가?
- 최초 등록에 실제로 얼마나 시간이 걸렸는가?
- 기존 템플릿이나 일반 AI로도 충분히 해결할 수 있는가?
그리고 같은 레슨 자료를 가지고 세 가지 방식을 비교해 보고 싶다.
- 기존 문구를 직접 복사하고 수정하는 방식
- 일반 AI를 활용해 플랫폼별 초안을 만드는 방식
- 플랫폼별 필수 항목과 입력을 지원하는 방식
작업 시간뿐 아니라 누락된 정보, 잘못 변환된 가격, 사람이 수정해야 했던 횟수도 함께 확인해야 한다.
AI가 작업 시간을 단축하더라도 가격이나 커리큘럼을 잘못 입력한다면 좋은 해결책이라고 볼 수 없기 때문이다.
우선 한 플랫폼의 실제 등록 요구사항과 허용 범위를 확인한 뒤, 11월 21일 토요일 프로젝트 논의에서 구현 범위를 검토할 계획이다.
API 설계 복습
기술적으로는 다음 개념을 복습할 필요가 있다.
- REST API와 HTTP 메서드의 역할
- URL 경로와 쿼리 파라미터의 차이
- JSON 요청·응답 구조
- JWT 인증과 401·403 상태 코드
- API 명세서와 기능 요구사항(FR) 연결
- AI 툴 호출 시 권한과 입력값 검증
- 비동기 처리, 재시도와 멱등성
특히 REST API와 AI 에이전트 툴 호출의 차이, 그리고 API가 오래 걸리는 작업을 처리하는 방식을 다시 정리해 보고 싶다.
14. 오늘의 회고: 사용자 문제에서 시스템 설계까지
오늘은 프로젝트 기획과 기술 설계를 서로 다른 관점에서 살펴본 하루였다.
기획 회의에서는 무엇을 만들어야 하는가를 고민했고, 이후 강의에서는 그 기능을 실제 시스템으로 만들 때 무엇을 정의해야 하는가를 배웠다.
처음에는 여러 플랫폼에 흩어진 레슨 정보를 지도에 보여주면 편리할 것이라고 생각했다.
하지만 회의에서 질문을 받으면서 내가 제시한 기능이 실제 사용자의 가장 큰 문제를 해결하는지 확신할 수 없었다.
반면 레슨 선생님으로 활동하면서 여러 사이트에 정보를 등록했던 과정을 떠올리자 구체적인 작업이 보였다.
어떤 정보를 입력하고, 어떤 부분을 다시 수정하며, 플랫폼마다 어떤 요구사항이 다른지 설명할 수 있었다.
이러한 경험이 있다고 해서 다른 선생님도 같은 불편함을 느낀다고 단정할 수는 없다. 오히려 직접 경험한 부분과 추가 검증이 필요한 부분을 구분하는 것이 중요하다는 생각이 들었다.
또 하나 기억에 남는 것은 모든 기능을 처음부터 만들 필요가 없다는 점이다.
게시글 갱신, 광고 관리, 문의 자동 응대, 지도 기반 탐색까지 모두 구현한다면 서비스의 규모는 커질 수 있다. 하지만 실제 문제가 해결되는지는 오히려 확인하기 어려워질 수 있다.
지금은 많은 기능보다 하나의 반복 업무를 정확하게 해결할 수 있는지가 더 중요하다.
API 설계 수업 역시 이 흐름과 연결해서 생각해 볼 수 있었다.
사용자의 작업을 하나의 기능으로 정의하더라도 실제 개발에서는 요청과 응답, 인증과 권한, 오류 처리, 재시도 같은 세부적인 규칙들이 필요하다.
특히 AI 에이전트가 외부 서비스에 실제 작업을 수행하도록 만들려면 단순히 LLM이 명령을 생성하는 것에서 끝나지 않는다.
사용자가 승인한 내용인지, 실행할 권한이 있는지, 이미 처리된 요청인지, 실패하면 어떤 상태를 남길 것인지까지 고려해야 한다.
오늘은 코드를 직접 구현하거나 API 테스트를 진행한 날은 아니지만, 기획에서 구체화해야 할 사용자 문제와 이후 개발에서 정의해야 할 기술적 책임을 함께 정리할 수 있었다.
최종 프로젝트를 진행하면서 점점 더 중요하게 느껴지는 것은 AI 기술 자체보다 누구를 위해 어떤 문제를 해결해야 하는지 설명하고, 그 해결 과정을 검증 가능한 형태로 설계하는 능력이다.
다음에는 실제 음악 레슨 선생님들도 같은 문제를 겪고 있는지 확인하고, 기존 방식보다 더 나은 해결책을 만들 수 있을지 검증해 보고 싶다.
