AI 드리븐

지도 위치 : 1일차 · 기획 · 만들 범위와 화면 ↔ 서버의 약속 | 이전: 3차시 요구사항을 완료 기준으로 | 다음: 5차시 AI 역할 정의의 원리 키워드 : 최소 기능 범위(MVP), 서비스 인터페이스(API), 설계 기준

이 차시를 다 읽으면

1. MVP 를 유와 종차로 정의하고, Must / Should / Could / Won't로 범위를 나눌 수 있다. 특히 "이번엔 안 함" 목록이 왜 가장 중요한지 말할 수 있다.
2. API · HTTP · 메서드 · 상태 코드 를 각각 정의하고, API 표 한 줄을 코드 없이 읽을 수 있다.
3. 자주 쓰는 상태 코드 여덟 개의 뜻을 말할 수 있다.
4. 멱등성 을 정의하고, 같은 요청을 두 번 보냈을 때 위험한 요청을 골라낼 수 있다.
5. API 요청 칸에서 서버가 정해야 할 값 (금액, 권한 등)을 찾아 설계 단계에서 지적할 수 있다.

---

0. 이 차시의 판별 축

이 차시가 답하는 질문은 두 가지입니다. 무엇을 만들지 않을 것인가 (축 4), 그리고 화면과 서버가 무엇을 주고받기로 약속하는가 (축 1). 앞에서 배운 인수 기준(3차시 4절)이 "무엇이 맞는 상태인가"였다면, API 명세는 그 상태를 화면과 서버 사이의 약속 으로 옮긴 것입니다.

---

1. 범위 결정 — MVP

1.1 정의

MVP (최소 기능 제품, Minimum Viable Product) — [출시 범위]인데, [ 서비스의 핵심 가치를 전달하는 데 꼭 필요한 기능만 담는다 ]는 점에서 원하는 기능을 모두 담은 완성판과 구별된다.

나누는 기준은 한 질문입니다. "이것 없이도 서비스의 핵심 가치가 전달되는가?"

1.2 ⭐ "이번엔 안 함" 목록이 가장 중요하다

AI는 범위를 넓히는 경향이 있습니다. "예약 기능"을 시키면 쿠폰, 리뷰, 알림까지 붙이려 합니다. 범위 밖 목록이 없으면 막을 근거가 없습니다.

"이번엔 안 함" 목록을 지침 파일(2차시 2.1)에 넣어 두면, 에이전트가 범위를 벗어날 때 스스로 멈출 근거 가 생깁니다.

## 범위
- 이번엔 안 함: 리뷰, 쿠폰, 알림톡, 운영자 정산
- 위 기능이 필요해 보이면 만들지 말고 나에게 먼저 묻는다

🔍 읽는 포인트 : 두 번째 줄 "만들지 말고 묻는다"가 핵심입니다. 목록만 있으면 AI가 "필요해서 만들었습니다"라고 넘어갈 수 있습니다.

1.3 반례 — 이건 MVP가 아닙니다

---

2. ⭐ API와 HTTP의 기본

2.1 화면과 서버

클라이언트 (화면, 프론트엔드) — [서비스의 한쪽 끝]인데, [ 사용자의 기기(브라우저 · 휴대폰)에서 돌며 보여 주고 입력받는다 ]는 점에서 우리 쪽 컴퓨터에서 돌며 판정 · 저장하는 서버와 구별된다.

서버 (백엔드) — [서비스의 한쪽 끝]인데, [ 우리가 관리하는 컴퓨터에서 돌며 요청을 받아 판정하고 데이터를 저장한다 ]는 점에서 사용자 기기에서 도는 클라이언트와 구별된다.

API (서비스 인터페이스) — [소프트웨어 사이의 약속]인데, [ 클라이언트와 서버가 주고받을 요청 · 응답의 모양을 정한다 ]는 점에서 그 약속을 실제로 지키는 코드인 구현과 구별된다.

HTTP — [통신 규약]인데, [ 요청 하나를 보내면 응답 하나가 돌아오는 형식으로 웹에서 데이터를 주고받는다 ]는 점에서 연결을 열어 두고 계속 주고받는 방식과 구별된다.

화면(클라이언트) ──요청: POST /reservations {클래스, 날짜, 인원}──▶ 서버
화면(클라이언트) ◀──응답: 201 {예약 번호, 상태, 금액}────────────── 서버

🔍 읽는 포인트 : 오른쪽 화살표 줄의 POST /reservations(무엇을 하려는가)와 왼쪽 화살표 줄의 201(결과가 어떤가)만 보면 됩니다.

2.2 요청의 두 부분 — 메서드와 경로

경로 (Path) — [요청의 대상 표시]인데, [ 무엇에 대한 요청인지(클래스, 예약)를 주소로 나타낸다 ]는 점에서 무엇을 하려는지를 나타내는 메서드와 구별된다.

HTTP 메서드 — [요청의 종류 표시]인데, [ 같은 대상에 대해 무엇을 하려는지(조회 · 생성 · 변경 · 삭제)를 나타낸다 ]는 점에서 대상을 나타내는 경로와 구별된다.

2.3 응답의 두 부분 — 상태 코드와 본문

상태 코드 — [응답의 일부]인데, [ 결과의 종류를 세 자리 숫자로 알린다 ]는 점에서 실제 데이터를 담은 응답 본문과 구별된다.

첫 자리가 큰 갈래입니다. 2로 시작하면 성공, 4로 시작하면 요청한 쪽 문제, 5로 시작하면 서버 쪽 문제 입니다. 이 과정에서는 아래 여덟 개면 충분합니다.

JSON — [데이터 표기 형식]인데, [ { "이름": 값 } 모양으로 사람도 읽고 프로그램도 읽을 수 있다 ]는 점에서 사람만 읽는 자유 문장과 구별된다. 요청과 응답의 본문은 대부분 JSON입니다.

2.4 API 명세 한 줄에 들어가는 것

⭐ API 표는 코드를 몰라도 읽을 수 있는 서비스의 설계도입니다. 코드는 맡기더라도 API 표는 내가 직접 이해하고 승인하는 마지막 층 으로 삼습니다. 이 표만 이해해도 화면과 서버 사이에서 무엇이 오가는지 전부 파악할 수 있습니다.

---

3. 설계 기준

3.1 여섯 가지 규칙

AI도 이 규칙을 알지만, 명시하지 않으면 일관되게 지키지 않습니다.

3.2 서버가 판정할 값은 받지 않는다

화면은 사용자의 기기에서 돌기 때문에 사용자가 조작할 수 있습니다. 예약 요청에 금액을 넣으면, 누군가 55000을 100으로 바꿔 보낼 수 있습니다. 그래서 금액은 서버가 DB의 가격으로 직접 계산 합니다(0절 축 3).

⭐ API 표에서 코드 없이 찾아낼 수 있는 위험 입니다. 요청 칸에 아래 같은 값이 들어 있으면 설계 단계에서 바로 지적하세요.

앞으로 다시 만납니다 — 10 · 11차시에서 "화면이 판정 ↔ 서버가 판정" 축을 본격적으로 다루고, 16차시에서 결제 금액 위변조를 실제로 막습니다.

3.3 ⭐ 멱등성 — 같은 요청을 두 번 보내면?

멱등성 (Idempotency) — [요청의 성질]인데, [ 같은 요청을 여러 번 보내도 결과 상태가 한 번 보낸 것과 같다 ]는 점에서 보낼 때마다 상태가 바뀌는 비멱등 요청과 구별된다.

⚠️ 멱등은 "응답이 같다"가 아니라 "결과 상태가 같다" 입니다. 위 DELETE처럼 두 번째 응답은 404일 수 있습니다.

같은 요청은 생각보다 자주 두 번 갑니다. 사용자가 결제 버튼을 연타하거나, 네트워크가 끊겨 화면이 자동으로 다시 보내거나, 결제사가 같은 알림을 두 번 보내는 경우입니다. 그래서 비멱등 요청 중 중복이 치명적인 곳 (예약, 결제)은 설계 단계에서 표시해 둡니다.

앞으로 다시 만납니다 — 16차시에서 결제 요청에 같은 요청임을 알아보는 표시(멱등 키) 를 붙여 두 번 와도 한 번만 처리되게 만듭니다.

---

4. 명세를 단일 기준으로

4.1 저장과 규칙

API 명세는 docs/api.md(사람이 읽기 쉬움)나 OpenAPI 형식의 openapi.yaml(API 명세를 적는 표준 형식, 도구가 읽기 쉬움)로 저장합니다. 그리고 지침 파일에 이렇게 적습니다.

API는 docs/api.md가 유일한 기준이다. 구현이 명세와 다르면 구현을 고친다.
명세를 바꿔야 하면 먼저 사람에게 묻는다.
docs/api.md를 바꾸면 무엇이 왜 바뀌었는지 먼저 알린다.

🔍 읽는 포인트 : 첫 줄의 "구현을 고친다"가 축 1의 방향입니다. 약속(추상)이 기준이고, 코드(구상)가 따라갑니다. 셋째 줄은 AI가 구현 중에 슬그머니 계약을 바꾸는 일 을 막습니다.

⭐ 프론트엔드와 백엔드를 서로 다른 에이전트가 만들면, 둘이 같은 약속을 보고 있어야 연결됩니다(11차시). 명세 하나를 두 역할과 테스트가 함께 봅니다.

4.2 반례 — 이건 API 명세가 아닙니다

💡 비유는 마지막에 — API 명세는 콘센트 규격입니다. 규격(약속)이 정해져 있으면 어느 회사가 플러그(구현)를 만들어도 꽂힙니다.

4.3 클래스온에 적용하면

---

5. 실습 — 맡기고 검수하기

지시

docs/requirements.md를 근거로 두 문서를 만들어줘.
1. docs/scope.md: Must / Should / Could / Won't 표. Won't는 최소 4개, 각각 빼는 이유 한 줄.
2. docs/api.md: [메서드 | 경로 | 요청 본문 | 응답 본문 | 상태 코드 | 인증 | 멱등 여부] 표.
   에러 형식은 { "error": { "code", "message" } } 하나로 통일.
규칙: 요청 본문에 금액 · 사용자 ID · 권한 · 남은 자리 값을 넣지 말 것.
      비멱등 요청 중 중복되면 위험한 것은 표에 [중복 주의]로 표시할 것.
그리고 CLAUDE.md에 "Won't 목록"과 "docs/api.md가 유일한 기준" 규칙을 추가해줘 (추가 전 내용을 보여주고 승인받을 것).
보고: 두 문서의 원문 + 각 상태 코드를 어떤 실패 시나리오(requirements.md)에 대응시켰는지 표.

받을 증거

• docs/scope.md, docs/api.md 원문
• 상태 코드 ↔ 3차시 실패 시나리오 대응표

내가 직접 확인할 것

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 4차시 노트만 근거로 6문제를 내줘. 코드를 모르는 사람 기준으로.
"Won't 목록의 역할", "메서드 · 경로 · 상태 코드 읽기", "서버가 판정할 값", "멱등성"은 반드시 포함해줘.
API 표 한 줄을 주고 위험한 요청 값을 내가 찾아보게 하는 문제도 1개 넣어줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.