diff --git a/Lecture/FinalProject/Doc/WBS_잘_쓰는_법.html b/Lecture/FinalProject/Doc/Step1/WBS_잘_쓰는_법.html
similarity index 100%
rename from Lecture/FinalProject/Doc/WBS_잘_쓰는_법.html
rename to Lecture/FinalProject/Doc/Step1/WBS_잘_쓰는_법.html
diff --git a/Lecture/FinalProject/Doc/WBS_잘_쓰는_법.pdf b/Lecture/FinalProject/Doc/Step1/WBS_잘_쓰는_법.pdf
similarity index 100%
rename from Lecture/FinalProject/Doc/WBS_잘_쓰는_법.pdf
rename to Lecture/FinalProject/Doc/Step1/WBS_잘_쓰는_법.pdf
diff --git a/Lecture/FinalProject/Doc/기획서_잘_쓰는_법.html b/Lecture/FinalProject/Doc/Step1/기획서_잘_쓰는_법.html
similarity index 100%
rename from Lecture/FinalProject/Doc/기획서_잘_쓰는_법.html
rename to Lecture/FinalProject/Doc/Step1/기획서_잘_쓰는_법.html
diff --git a/Lecture/FinalProject/Doc/기획서_잘_쓰는_법.pdf b/Lecture/FinalProject/Doc/Step1/기획서_잘_쓰는_법.pdf
similarity index 100%
rename from Lecture/FinalProject/Doc/기획서_잘_쓰는_법.pdf
rename to Lecture/FinalProject/Doc/Step1/기획서_잘_쓰는_법.pdf
diff --git a/Lecture/FinalProject/Doc/Step2/API설계문서_작성법.html b/Lecture/FinalProject/Doc/Step2/API설계문서_작성법.html
new file mode 100644
index 0000000..79cdc97
--- /dev/null
+++ b/Lecture/FinalProject/Doc/Step2/API설계문서_작성법.html
@@ -0,0 +1,188 @@
+
+
+API 설계 문서 작성법
최종 프로젝트 STEP 2 · REST API 및 Function Calling 명세서
AI 애플리케이션 개발 과정 · 최종 프로젝트 산출물 가이드
GET /api/v1/incidents
POST /incidents/{id}/recovery
202 Accepted
restart_service
+API 설계 문서는 팀의 계약서다
최종 프로젝트 · API 설계 문서 작성법
2
코드를 쓰기 전에, 무엇을 주고받을지 합의해 두는 문서
프런트 ↔ 백엔드
따로 개발해도 맞물린다
화면이 어떤 주소로 무엇을 보내고 무엇을 받는지 미리 정한다. 서로 기다리지 않고 동시에 개발할 수 있다.
에이전트 ↔ 도구
Function Calling의 기준
LLM이 호출할 Tool의 이름, 입력, 실패 코드를 정한다. 에이전트 설계가 이 명세 위에 올라간다.
설계 ↔ 검증
테스트의 근거
평가는 문서가 있는지가 아니라 설계·구현·검증이 이어지는지를 본다. 명세가 곧 테스트 케이스가 된다.
+STEP 2에서 이 문서가 놓이는 자리
최종 프로젝트 · API 설계 문서 작성법
3
앞 단계의 요구사항을 받아, 뒤 단계의 구현과 검증에 기준을 넘겨준다
기획서
기능 요구사항
+FR-01 …
→
API 설계 문서
오늘 다루는
+산출물
→
DB 스키마 설계서
STEP 2의
+짝 산출물
→
에이전트 설계
Tool 정의를
+가져다 쓴다
→
통합 테스트
명세대로
+동작하는지 확인
API 설계 문서와 DB 스키마 설계서는 STEP 2의 필수 산출물이다. 두 문서는 같은 식별자와 필드명을 써야 한다.
+문서에 들어가는 여섯 가지
최종 프로젝트 · API 설계 문서 작성법
4
01
인증 방식
토큰 발급·전달·검증 방법과 401·403 조건
02
API 목록
메서드·경로·인증·설명을 한눈에 보는 표
03
엔드포인트 상세 명세
요청·응답·오류를 예시값과 함께
04
입력 검증 규칙
허용 값·길이·필수 조건을 Pydantic 모델로
05
Tool 정의
이름·호출 주체·입력·출력·실패 코드
06
Tool 호출 흐름
요청이 에이전트와 Tool을 거치는 순서
+REST는 자원을 주소로, 행위를 메서드로 나타낸다
최종 프로젝트 · API 설계 문서 작성법
5
RESTful API는 이 약속을 지켜서 만든 API다. 주소만 봐도 무엇을 다루는지 알 수 있다
자원 (Resource)
다루는 대상에 주소를 준다
장애, 복구 작업처럼 서비스가 다루는 대상 하나하나가 고유한 주소(URL)를 갖는다.
/incidents
+/incidents/inc-001
행위 (Method)
할 일은 메서드로 말한다
같은 주소에 메서드만 바꿔 조회, 생성, 수정, 삭제를 구분한다.
GET · POST
+PATCH · DELETE
표현 (Representation)
내용은 JSON에 담는다
자원의 현재 상태를 JSON 문서로 표현해 요청과 응답에 싣는다.
{"id": "inc-001",
+ "status": "open"}
+REST가 지키는 세 가지 원칙
최종 프로젝트 · API 설계 문서 작성법
6
원칙을 지키면 처음 보는 API도 예측할 수 있고, 서버를 여러 대로 늘리기 쉽다
원칙 1
클라이언트와 서버의 분리
화면은 API 규격만 알면 된다. 서버 내부가 바뀌어도 규격이 같으면 화면은 그대로 동작한다.
원칙 2
무상태 (Stateless)
서버는 앞선 요청을 기억하지 않는다. 그래서 요청마다 토큰과 필요한 ID를 모두 실어 보낸다.
원칙 3
일관된 인터페이스
모든 자원에 같은 주소 규칙, 같은 메서드 의미, 같은 오류 형식을 쓴다.
+HTTP 요청과 응답은 세 부분으로 읽는다
최종 프로젝트 · API 설계 문서 작성법
7
시작줄: 요청은 메서드와 경로, 응답은 상태 코드
헤더: 인증 토큰, 본문 형식 같은 부가 정보
본문: 주고받는 데이터(JSON). GET 요청에는 보통 본문이 없다.
API 설계 문서는 이 세 부분을 엔드포인트마다 적는 것이다.
요청과 응답의 구조
# 요청 ① 시작줄
+POST /api/v1/incidents/inc-001/recovery HTTP/1.1
+# 요청 ② 헤더
+Authorization: Bearer <JWT>
+Content-Type: application/json
+# 요청 ③ 본문
+{"action": "restart", "approval_id": "apr-001"}
+
+# 응답 ① 시작줄
+HTTP/1.1 202 Accepted
+# 응답 ② 헤더
+Content-Type: application/json
+# 응답 ③ 본문
+{"job_id": "job-001", "status": "queued"}
+메서드마다 의미와 성질이 정해져 있다
최종 프로젝트 · API 설계 문서 작성법
8
메서드
하는 일
안전 (조회만)
멱등
성공 코드
GET
조회
예
예
200
POST
생성, 실행 요청
아니오
아니오
201 / 202
PUT
전체 교체
아니오
예
200
PATCH
일부 수정
아니오
보장되지 않음
200
DELETE
삭제
아니오
예
204
멱등은 같은 요청을 여러 번 보내도 결과가 한 번 보낸 것과 같다는 뜻이다.
+POST는 멱등이 아니므로, 복구 요청이 두 번 들어와도 한 번만 실행되게 하는 장치(중복 방지 키, 409 응답)를 설계에 넣는다.
+상태 코드는 첫 자리로 읽는다
최종 프로젝트 · API 설계 문서 작성법
9
누구 쪽 문제인지가 첫 자리에 담겨 있다. 무조건 200으로 응답하고 본문에 오류를 넣지 않는다
2xx
성공
요청을 정상 처리했다. 조회, 생성, 접수, 삭제에 따라 코드를 구분한다.
200 OK
+201 Created
+202 Accepted
+204 No Content
4xx
요청 쪽 문제
보낸 쪽이 고쳐야 한다. 값, 인증, 권한, 대상, 충돌 중 무엇이 문제인지 알려준다.
400 · 422 잘못된 값
+401 인증 · 403 권한
+404 없음 · 409 충돌
5xx
서버 쪽 문제
서버가 고쳐야 한다. 내부 오류 내용은 응답에 노출하지 않고 로그에 남긴다.
500 Internal Server Error
+503 Service Unavailable
+RESTful하지 않은 주소를 고쳐 쓴다
최종 프로젝트 · API 설계 문서 작성법
10
이렇게 쓰지 않는다
이렇게 쓴다
이유
GET /getIncidents
GET /incidents
동사는 메서드가 이미 말하고 있다
GET /incident/list
GET /incidents
목록은 복수형 명사 하나로 충분하다
POST /deleteIncident?id=1
DELETE /incidents/1
대상은 경로에, 행위는 메서드에 둔다
GET /incidents/1/delete
DELETE /incidents/1
GET은 조회만 한다. 데이터를 바꾸지 않는다
/Recovery_Jobs
/recovery-jobs
소문자와 하이픈으로 통일한다
진단·복구처럼 '실행'하는 행위는 명사로 떨어지지 않는다.
+이때는 POST와 하위 경로(/incidents/{id}/diagnose)로 표현하는 것이 실무 관례다.
+목록 조회는 필터·정렬·페이지를 쿼리로 받는다
최종 프로젝트 · API 설계 문서 작성법
11
경로는 자원을 가리키고, 조건은 ? 뒤 쿼리 파라미터로 붙인다.
요구사항 FR-01의 "상태·발생시간·자산명으로 필터링"이 곧 쿼리 파라미터 목록이다.
응답에는 목록과 함께 전체 건수, 현재 페이지를 담는다.
파라미터 이름과 기본값은 팀에서 정해 문서에 적는다.
GET /api/v1/incidents (형식 예시)
GET /api/v1/incidents?status=open&asset=svc-api-01
+ &sort=-created_at&page=1&size=20
+Authorization: Bearer <JWT>
+
+HTTP/1.1 200 OK
+{
+ "items": [
+ {"id": "inc-001", "status": "open",
+ "asset": "svc-api-01"}
+ ],
+ "total": 37,
+ "page": 1,
+ "size": 20
+}
+요구사항에서 API를 뽑아낸다
최종 프로젝트 · API 설계 문서 작성법
12
요구사항 한 줄마다 "무엇을, 어떻게 하는가"를 물으면 엔드포인트가 나온다
요구사항
다루는 대상
행위
엔드포인트
FR-01 장애 목록 조회
incidents
조회
GET /api/v1/incidents
FR-02 AI 원인 진단
incidents의 진단
실행 요청
POST /api/v1/incidents/{id}/diagnose
FR-03 복구 작업 승인
incidents의 복구
실행 요청
POST /api/v1/incidents/{id}/recovery
FR-04 복구 이력 조회
recovery-jobs
조회
GET /api/v1/recovery-jobs/{id}
예시는 산출물 샘플(InfraCare AI, 교육용 가상 서비스) 기준이다. 팀 주제의 대상과 행위로 바꿔 쓴다.
+주소와 메서드를 정하는 규칙
최종 프로젝트 · API 설계 문서 작성법
13
주소는 명사, 복수형으로
동사는 주소에 넣지 않고 메서드에 담는다.
/incidents /recovery-jobs
메서드가 곧 행위다
GET 조회, POST 생성·실행, PATCH 수정, DELETE 삭제
GET · POST · PATCH · DELETE
버전을 앞에 붙인다
나중에 규격을 바꿔도 기존 화면이 깨지지 않는다.
/api/v1/…
포함 관계는 경로로 표현한다
특정 장애에 대한 복구 요청은 그 장애 아래에 둔다.
/incidents/{id}/recovery
+인증 방식은 네 줄로 적는다
최종 프로젝트 · API 설계 문서 작성법
14
항목
적을 내용
예시
인증
토큰을 어디서 발급받는가
Supabase Auth 로그인 → JWT Access Token 발급
전달
요청에 토큰을 어떻게 싣는가
Authorization: Bearer <access_token>
검증
서버가 무엇을 확인하는가
서명·만료·역할 (복구 실행은 operator/admin만 허용)
오류
실패하면 무엇을 돌려주는가
401 토큰 누락·만료 / 403 권한 부족
401은 "누구인지 모른다", 403은 "누구인지는 알지만 권한이 없다"는 뜻이다. 둘을 구분해서 적는다.
+API 목록 표로 전체를 한 장에 담는다
최종 프로젝트 · API 설계 문서 작성법
15
메서드
경로
인증
설명
관련 요구사항
GET
/api/v1/incidents
JWT
장애 목록 조회
FR-01
POST
/api/v1/incidents/{id}/diagnose
JWT
AI 진단 실행
FR-02
POST
/api/v1/incidents/{id}/recovery
JWT + 운영자
복구 작업 요청
FR-03
GET
/api/v1/recovery-jobs/{id}
JWT
복구 작업 상태 조회
FR-04
'관련 요구사항' 열을 더하면 기획서와의 연결이 바로 보인다. 구현한 API는 반드시 목록에 있고, 목록에 없는 API는 만들지 않는다.
+상세 명세는 여덟 칸을 채운다
최종 프로젝트 · API 설계 문서 작성법
16
핵심 엔드포인트마다 표 하나. 빈칸이 남아 있으면 설계가 아직 끝나지 않은 것이다
1
호출 목적
누가, 언제, 왜 부르는가
2
요청 헤더
Authorization, X-Request-ID 등
3
경로·쿼리
이름, 타입, 필수 여부, 기본값
4
요청 본문
실제 값이 들어간 JSON
5
입력 검증
허용 값, 길이, 조건부 필수
6
정상 응답
상태 코드와 응답 JSON
7
오류 응답
상태 코드별 발생 조건
8
응답 예시
오류 JSON의 형식
+예시: 복구 요청 API의 요청과 응답
최종 프로젝트 · API 설계 문서 작성법
17
202는 "접수했고 처리 중"이라는 뜻이다. 오래 걸리는 작업에 쓴다.
응답의 job_id로 진행 상태를 따로 조회한다.
예시값은 다른 산출물과 같은 ID를 쓴다. (inc-001, apr-001, req-001)
POST /api/v1/incidents/{incident_id}/recovery
POST /api/v1/incidents/inc-001/recovery
+Authorization: Bearer <JWT>
+Content-Type: application/json
+X-Request-ID: req-001
+
+{
+ "action": "restart",
+ "target_id": "svc-api-01",
+ "approval_id": "apr-001"
+}
+
+HTTP 202
+{
+ "job_id": "job-001",
+ "status": "queued",
+ "incident_id": "inc-001"
+}
+오류 응답도 설계의 일부다
최종 프로젝트 · API 설계 문서 작성법
18
정상 응답만 적은 문서는 절반짜리다. 실패 조건과 오류 코드를 표로 만든다
상태 코드
발생 조건
오류 코드(예시)
400
허용되지 않는 값
INVALID_ACTION
401
토큰 누락·만료
UNAUTHORIZED
403
권한 또는 승인 없음
APPROVAL_REQUIRED
404
장애 ID 없음
INCIDENT_NOT_FOUND
409
같은 복구가 이미 실행 중
DUPLICATE_JOB
오류 형식은 하나로 통일한다: {"error": {"code": "APPROVAL_REQUIRED", "message": "승인 필요"}}
+FastAPI는 입력 검증 실패를 기본 422로 돌려준다. 400과 422 중 무엇을 쓸지 팀에서 정해 문서에 적는다.
+입력 검증은 Pydantic 모델로 적는다
최종 프로젝트 · API 설계 문서 작성법
19
Literal: 허용하는 값의 목록
Field: 길이와 범위 제한
model_validator: 여러 필드가 얽힌 조건. 위험한 작업이면 승인 ID가 필수
문서의 검증 규칙과 코드의 모델은 같아야 한다.
schemas.py
from typing import Literal
+from pydantic import BaseModel, Field, model_validator
+
+RISKY = {"restart"}
+
+class RecoveryRequest(BaseModel):
+ action: Literal["restart", "reconnect", "fallback"]
+ target_id: str = Field(min_length=1, max_length=64)
+ approval_id: str | None = None
+
+ @model_validator(mode="after")
+ def need_approval(self):
+ if self.action in RISKY and not self.approval_id:
+ raise ValueError("APPROVAL_REQUIRED")
+ return self
+REST API와 Tool은 호출하는 주체가 다르다
최종 프로젝트 · API 설계 문서 작성법
20
구분
REST API
Tool (Function Calling)
호출 주체
화면(프런트엔드), 외부 시스템
에이전트(LLM)
호출 방법
HTTP 메서드 + 경로
Tool 이름 + JSON 인자
권한 확인
JWT에 담긴 사용자 역할
에이전트별 허용 Tool 목록
문서에 적는 것
요청·응답·상태 코드
입력 스키마·출력·실패 코드·실행 조건
LLM이 만든 인자도 사용자 입력처럼 다룬다. Tool 안에서 같은 검증을 한 번 더 한다.
+Tool 정의는 에이전트가 읽는 명세다
최종 프로젝트 · API 설계 문서 작성법
21
이름은 동사_명사: restart_service
호출 주체와 권한: RecoveryAgent, recovery.execute
실행 조건: 운영자 승인을 확인한 뒤
출력과 실패 코드: job_id, status / TOOL_TIMEOUT, TARGET_NOT_FOUND, APPROVAL_REQUIRED
description은 LLM이 언제 쓸지 판단하는 근거다. 구체적으로 쓴다.
Tool 입력 스키마
{
+ "name": "restart_service",
+ "description": "승인된 대상 서비스를 재시작한다",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "target_id": {"type": "string"},
+ "approval_id": {"type": "string"},
+ "request_id": {"type": "string"}
+ },
+ "required": ["target_id", "approval_id", "request_id"]
+ }
+}
+Tool 호출 흐름을 한 줄로 그린다
최종 프로젝트 · API 설계 문서 작성법
22
요청 하나가 어떤 순서로 에이전트와 Tool을 거치는지 문서에 남긴다
API 요청
인증과
+입력 검증
→
Supervisor
작업 분배
→
Diagnosis
+Agent
원인 진단
→
승인 확인
approval_id
+검사
→
Recovery
+Agent
복구 Tool
+호출
→
Verification
+Agent
정상화 확인,
+상태 기록
API의 X-Request-ID와 Tool의 request_id를 같은 값으로 이어 두면, 로그에서 요청 전체를 한 번에 추적할 수 있다.
+오래 걸리는 작업은 접수와 조회로 나눈다
최종 프로젝트 · API 설계 문서 작성법
23
에이전트 실행은 몇 초에서 몇 분이 걸린다. 응답을 붙잡고 기다리게 하지 않는다
① 접수
바로 202를 돌려준다
작업을 대기열에 넣고 job_id를 즉시 반환한다.
POST …/recovery
+→ 202 {"job_id": "job-001"}
② 조회
상태를 따로 묻는다
가능한 상태 값의 목록을 문서에 적어 둔다.
GET /recovery-jobs/{id}
+→ {"status": "queued"}
③ 스트리밍
진행 상황을 흘려보낸다
STEP 5의 실시간 화면에서 쓴다. 이벤트 종류를 명세한다.
POST /api/v1/chat/stream
+→ text/event-stream
+다른 산출물과 같은 이름을 쓴다
최종 프로젝트 · API 설계 문서 작성법
24
문서마다 이름이 다르면 설계·구현·검증의 연결을 보여줄 수 없다
기획서
요구사항 ID를 연결한다
API마다 FR-01 같은 요구사항 번호를 붙인다.
DB 스키마 설계서
필드명과 컬럼명을 맞춘다
incident_id, approval_id를 두 문서에서 똑같이 쓴다.
AI 보안 가드레일 문서
권한 규칙이 일치한다
역할별·Tool별 권한표와 인증 규칙이 서로 같아야 한다.
통합 테스트 결과서
오류 표가 테스트가 된다
"승인 없는 요청 → 403" 한 줄이 테스트 케이스 하나다.
+자주 나오는 실수와 고치는 법
최종 프로젝트 · API 설계 문서 작성법
25
실수
이렇게 고친다
같은 API인데 문서 안에서 경로나 필드명이 다르다
+(/recover 와 /recovery, action 과 strategy)
API 목록 표를 기준으로 삼고 상세 명세를 거기에 맞춘다
정상 응답만 적었다
상태 코드별 오류 표를 추가한다
"문자열", "숫자"만 있고 예시값이 없다
실제 값이 들어간 JSON을 넣는다
Tool에 실패 코드와 실행 조건이 없다
실패했을 때 에이전트가 할 행동까지 적는다
구현하면서 문서와 코드가 달라졌다
FastAPI의 /docs 화면과 대조하고 문서 버전을 올린다
+팀 주제로 바꿔 쓴다
최종 프로젝트 · API 설계 문서 작성법
26
샘플의 '장애·복구'를 우리 서비스의 대상과 행위로 바꾼다. 아래는 형태만 보여주는 예시다
묶음배달 오토힐링
대상: 배달, 장애
복구 요청과 상태 조회 구조를 그대로 쓸 수 있다.
GET /deliveries
+POST /incidents/{id}/heal
+Tool: reassign_rider
축제 안심 관광 비서
대상: 행사, 혼잡도
외부 공공 API를 부르는 Tool의 실패 코드가 핵심이다.
GET /events/{id}/congestion
+POST /chat/stream
+Tool: get_crowd_level
자전거 상담·코스 추천
대상: 코스, 상담
검색 조건을 쿼리 파라미터로 명세한다.
GET /courses?region=…
+POST /consultations
+Tool: search_safety_info
+제출 전 체크리스트
최종 프로젝트 · API 설계 문서 작성법
27
모든 API가 목록 표에 있고 요구사항 ID와 연결된다
인증 방식과 401·403 조건이 적혀 있다
핵심 엔드포인트의 상세 명세 여덟 칸이 모두 채워졌다
요청과 응답에 실제 값이 든 JSON 예시가 있다
상태 코드별 오류 조건과 오류 코드 표가 있다
검증 규칙이 Pydantic 모델과 일치한다
Tool마다 입력 스키마·출력·실패 코드·실행 조건이 있다
경로·필드명·ID가 DB 스키마 등 다른 산출물과 같다
+오늘 팀에서 할 일
최종 프로젝트 · API 설계 문서 작성법
28
완벽한 문서보다 합의된 초안이 먼저다. 구현하면서 버전을 올린다
① API 목록 표
요구사항 전체를
+표 한 장으로
→
② 상세 명세 1개
핵심 엔드포인트의
+여덟 칸 채우기
→
③ Tool 정의 1개
입력 스키마와
+실패 코드까지
→
④ 팀 리뷰
프런트·백엔드·AI
+담당이 함께 읽기
문서 머리말에 문서 버전과 작성 상태를 적는다. 예: 문서 버전 v0.1 | 작성 상태: 초안
+
+
+DB 스키마 설계서 작성법
최종 프로젝트 STEP 2 · PostgreSQL(Supabase) · pgvector · Redis
AI 애플리케이션 개발 과정 · 최종 프로젝트 산출물 가이드
users 1:N incidents
PRIMARY KEY
VECTOR(1536)
ROW LEVEL SECURITY
+DB 스키마 설계서는 데이터의 설계도다
최종 프로젝트 · DB 스키마 설계서 작성법
2
API 설계 문서가 '주고받는 것'의 약속이라면, 이 문서는 '저장하는 것'의 약속이다
무엇을
저장할 데이터를 정한다
테이블과 컬럼, 타입, 제약을 정한다. API가 주고받는 필드가 어디에 저장되는지 보인다.
어떻게
테이블을 잇는다
기본키와 외래키로 관계를 정한다. 잘못된 데이터가 들어오지 못하게 DB가 막아 준다.
누가
볼 수 있는 사람을 정한다
RLS 정책으로 역할별 조회·수정 권한을 정한다. 보안 가드레일 문서의 근거가 된다.
+API 설계 문서에서 이어지는 자리
최종 프로젝트 · DB 스키마 설계서 작성법
3
두 문서는 STEP 2의 짝 산출물이다. 나란히 놓고 함께 쓴다
기획서
기능 요구사항
+FR-01 …
→
API 설계 문서
지난 시간에
+다룬 산출물
→
DB 스키마 설계서
오늘 다루는
+산출물
→
에이전트 설계
메모리와
+체크포인트 저장
→
통합 테스트
권한과 데이터
+정합성 확인
API 요청과 응답의 필드가 테이블의 컬럼이 된다. 필드명과 컬럼명, ID 형식을 두 문서에서 똑같이 쓴다.
+문서에 들어가는 여섯 가지
최종 프로젝트 · DB 스키마 설계서 작성법
4
01
ERD와 관계 명세
테이블 사이의 관계를 그림과 표로
02
엔터티 정의
컬럼마다 타입·제약·의미
03
pgvector 스키마
문서·청크 테이블과 벡터 인덱스
04
RLS 정책
역할별 조회·등록·수정·삭제 권한
05
세션·캐시 설계
JWT와 Redis 세션의 수명주기
06
인덱스와 쿼리 최적화
자주 쓰는 조회의 인덱스와 검증 방법
+테이블은 행과 열로 된 표다
최종 프로젝트 · DB 스키마 설계서 작성법
5
엑셀 시트와 비슷하지만, 열마다 타입과 규칙이 정해져 있다는 점이 다르다
테이블 (엔터티)
대상 하나에 표 하나
사용자, 장애, 복구 작업처럼 서비스가 다루는 대상의 종류마다 테이블을 하나씩 만든다.
users
+incidents
+recovery_jobs
컬럼 (열)
속성과 타입, 제약
대상이 갖는 속성이다. 어떤 타입의 값이 들어가는지, 비워도 되는지를 함께 정한다.
status TEXT NOT NULL
행 (레코드)
실제 데이터 한 건
장애 한 건, 사용자 한 명이 행 하나다. API 응답의 JSON 객체 하나에 해당한다.
inc-001 | detected
+키와 제약이 데이터를 지킨다
최종 프로젝트 · DB 스키마 설계서 작성법
6
용어
뜻
예시
기본키 (PK)
행 하나를 유일하게 가리키는 컬럼
incidents.id
외래키 (FK)
다른 테이블의 기본키를 가리키는 컬럼
recovery_jobs.incident_id → incidents.id
UNIQUE
같은 값이 두 번 들어갈 수 없다
users.email
NOT NULL
값을 비워 둘 수 없다
incidents.status
외래키를 걸어 두면, 존재하지 않는 장애에 대한 복구 작업은 저장 자체가 거부된다. 검증을 코드가 아니라 DB가 해 준다.
+테이블 사이의 관계는 세 종류다
최종 프로젝트 · DB 스키마 설계서 작성법
7
ERD를 그리기 전에, 두 테이블이 몇 대 몇으로 짝지어지는지 먼저 말로 적어 본다
1 : N
가장 흔한 관계
사용자 한 명이 장애 여러 건을 등록한다. 외래키는 N 쪽 테이블에 둔다.
incidents.created_by
+→ users.id
N : M
중간 테이블로 푼다
장애 하나에 태그 여러 개, 태그 하나에 장애 여러 건. 둘을 잇는 테이블을 따로 만든다.
incident_tags
+(incident_id, tag_id)
1 : 1
드물게 쓴다
사용자와 프로필처럼 하나씩 짝지어진다. 한 테이블로 합칠 수 있는지 먼저 본다.
profiles.user_id
+→ users.id (UNIQUE)
+자주 쓰는 타입 여섯 가지
최종 프로젝트 · DB 스키마 설계서 작성법
8
타입
쓰는 곳
예시
UUID
사용자, 문서 등의 식별자
users.id
TEXT
문자열. 이름, 상태, 본문
incidents.status
INT
개수, 순번
document_chunks.chunk_index
TIMESTAMPTZ
시각 (시간대 포함)
created_at
JSONB
구조가 자주 바뀌는 부가 정보
documents.metadata
VECTOR(n)
임베딩 벡터 (pgvector)
document_chunks.embedding
시각은 TIMESTAMPTZ로 통일한다. 시간대가 없는 타입을 섞으면 한국 시간과 9시간 어긋나는 오류가 생긴다.
+API의 필드에서 테이블을 뽑아낸다
최종 프로젝트 · DB 스키마 설계서 작성법
9
API 설계 문서의 요청·응답 JSON을 펼쳐 놓고, 필드마다 저장할 곳을 정한다
API 필드
테이블.컬럼 (예시)
비고
incident_id
incidents.id
경로 파라미터가 곧 기본키
action, target_id
recovery_jobs.action, target_id
요청 본문을 그대로 기록
approval_id
recovery_jobs.approval_id
NOT NULL. 승인 없이는 저장 불가
job_id, status
recovery_jobs.id, status
응답은 저장된 행을 돌려준 것
JWT의 사용자
incidents.created_by → users.id
누가 등록했는지 남긴다
예시는 산출물 샘플(InfraCare AI, 교육용 가상 서비스) 기준이다. 팀 주제의 대상으로 바꿔 쓴다.
+ERD는 테이블을 상자로, 관계를 선으로 그린다
최종 프로젝트 · DB 스키마 설계서 작성법
10
화살표 하나가 1:N 관계 하나다. 상자 안에는 키 컬럼을 반드시 적는다
users
id PK
+email UNIQUE
→
incidents
id PK
+created_by FK
+status
→
recovery_jobs
id PK
+incident_id FK
+approval_id
그림은 Mermaid erDiagram이나 ERD 도구로 그려서 붙인다. 손으로 그린 그림보다 수정과 버전 관리가 쉽다.
+관계 명세 표로 그림을 글로 확인한다
최종 프로젝트 · DB 스키마 설계서 작성법
11
부모 테이블
관계
자식 테이블
연결 키
users
1 : N
incidents
incidents.created_by → users.id
incidents
1 : N
recovery_jobs
recovery_jobs.incident_id → incidents.id
documents
1 : N
document_chunks
document_chunks.document_id → documents.id
users
1 : N
sessions
sessions.user_id → users.id
ERD의 선 개수와 이 표의 행 수가 같아야 한다. 다르면 둘 중 하나가 빠진 것이다.
+엔터티 정의는 컬럼마다 네 칸을 채운다
최종 프로젝트 · DB 스키마 설계서 작성법
12
테이블
컬럼
타입 / 제약
의미
users
id
UUID / PK
사용자 ID
users
email
TEXT / UNIQUE
로그인 이메일
incidents
id
TEXT / PK
장애 ID
incidents
created_by
UUID / FK users.id
등록한 사용자
incidents
status
TEXT / NOT NULL
장애 상태
recovery_jobs
incident_id
TEXT / FK incidents.id
대상 장애
status처럼 값이 정해진 컬럼은 허용 값도 적는다: detected → diagnosing → … → resolved
+모든 테이블에 created_at TIMESTAMPTZ를 둔다.
+설계서의 표는 그대로 SQL이 된다
최종 프로젝트 · DB 스키마 설계서 작성법
13
엔터티 정의 표의 한 행이 SQL의 한 줄이다.
REFERENCES가 외래키다.
DEFAULT now()로 생성 시각을 자동 기록한다.
문서에 싣는 SQL은 Supabase SQL Editor에서 실제로 실행해 본 것만 넣는다.
schema.sql
CREATE TABLE incidents (
+ id TEXT PRIMARY KEY,
+ created_by UUID NOT NULL REFERENCES users(id),
+ status TEXT NOT NULL DEFAULT 'detected',
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE recovery_jobs (
+ id TEXT PRIMARY KEY,
+ incident_id TEXT NOT NULL REFERENCES incidents(id),
+ action TEXT NOT NULL,
+ approval_id TEXT NOT NULL,
+ status TEXT NOT NULL DEFAULT 'queued',
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+pgvector는 문서와 청크를 나눠 저장한다
최종 프로젝트 · DB 스키마 설계서 작성법
14
RAG에 쓰는 지식 문서는 원문 정보와, 잘게 자른 조각(청크)의 벡터로 나뉜다
documents
원문의 정보
제목, 출처, 부가 정보를 저장한다. 청크가 어느 문서에서 나왔는지 추적하는 기준이다.
documents
+(title, source_uri)
document_chunks
조각과 벡터
잘라 낸 본문과 임베딩 벡터, 문서 안에서의 순번을 저장한다. 검색은 이 테이블에서 일어난다.
document_chunks
+(content, embedding)
모델 정보
어떤 모델로 만들었나
모델을 바꾸면 벡터의 차원과 의미가 달라진다. 기존 벡터와 섞어 쓸 수 없으므로 기록해 둔다.
embedding_model
+embedding_version
+벡터 컬럼과 인덱스를 명세한다
최종 프로젝트 · DB 스키마 설계서 작성법
15
VECTOR(n)의 n은 임베딩 모델의 출력 차원과 같아야 한다.
인덱스의 연산자(vector_cosine_ops)와 검색식의 연산자(<=>)를 맞춘다.
UNIQUE (document_id, chunk_index)로 같은 조각이 두 번 적재되지 않게 한다.
pgvector 스키마
CREATE TABLE document_chunks (
+ id UUID PRIMARY KEY,
+ document_id UUID NOT NULL REFERENCES documents(id),
+ chunk_index INT NOT NULL,
+ content TEXT NOT NULL,
+ embedding VECTOR(1536),
+ UNIQUE (document_id, chunk_index)
+);
+
+CREATE INDEX idx_chunks_embedding
+ ON document_chunks
+ USING hnsw (embedding vector_cosine_ops);
+
+-- 검색: 코사인 거리가 가까운 순서로 5건
+SELECT content FROM document_chunks
+ORDER BY embedding <=> :query_vec LIMIT 5;
+RLS 정책은 역할과 명령의 표로 적는다
최종 프로젝트 · DB 스키마 설계서 작성법
16
RLS(Row Level Security)는 행 단위 권한이다. 같은 테이블이라도 사용자마다 보이는 행이 다르다
테이블
SELECT
INSERT
UPDATE
DELETE
incidents
viewer는 본인 것, 운영자는 전체
operator / admin
operator / admin
admin
recovery_jobs
operator / admin
복구 서비스 전용
복구 서비스 전용
금지
documents
허용 그룹의 로그인 사용자
admin
admin
admin
document_chunks
문서의 접근 권한을 따름
관리 서비스
관리 서비스
관리 서비스
이 표는 API 설계 문서의 403 조건, 보안 가드레일 문서의 권한표와 같은 내용이어야 한다.
+RLS 표는 정책 SQL로 옮긴다
최종 프로젝트 · DB 스키마 설계서 작성법
17
RLS를 켜면 정책에 없는 접근은 모두 거부된다.
auth.uid()는 요청에 실린 JWT의 사용자 ID다.
service_role 키는 RLS를 건너뛴다. 서버에만 두고 브라우저에 노출하지 않는다.
다른 사용자의 토큰으로 조회해 0건이 나오는지 테스트한다.
Supabase RLS (형식 예시)
ALTER TABLE incidents ENABLE ROW LEVEL SECURITY;
+
+-- 본인이 등록한 장애만 조회
+CREATE POLICY incidents_select_own
+ ON incidents FOR SELECT
+ TO authenticated
+ USING (created_by = auth.uid());
+
+-- 자기 이름으로만 등록
+CREATE POLICY incidents_insert_own
+ ON incidents FOR INSERT
+ TO authenticated
+ WITH CHECK (created_by = auth.uid());
+JWT와 Redis 세션의 수명주기를 적는다
최종 프로젝트 · DB 스키마 설계서 작성법
18
PostgreSQL 밖에 저장하는 데이터도 스키마다. 키 이름 규칙과 만료 시간을 문서에 남긴다
① 발급
Supabase Auth가
+JWT 발급
→
② 검증
서명·만료·역할
+확인
→
③ 저장
session:{id}
+TTL 30분
→
④ 갱신
요청마다 TTL
+갱신 정책 적용
→
⑤ 폐기
로그아웃·만료 시
+세션 삭제
JWT의 만료 시간과 Redis의 TTL은 서로 다른 값이다. 둘 다 적고, 어느 쪽이 먼저 끝나면 어떻게 되는지도 적는다.
+인덱스는 자주 쓰는 조회에서 출발한다
최종 프로젝트 · DB 스키마 설계서 작성법
19
API 목록의 GET부터 본다
어떤 조건으로 찾고 정렬하는가.
GET /incidents?status=open
조건과 정렬을 묶어 만든다
필터 컬럼 먼저, 정렬 컬럼 다음.
INDEX incidents (status, created_at DESC)
실행 계획으로 확인한다
인덱스 전후 결과를 문서에 싣는다.
EXPLAIN ANALYZE SELECT …
벡터 인덱스는 짝을 맞춘다
차원, 연산자, 검색식이 같아야 한다.
vector_cosine_ops ↔ <=>
+다른 산출물과 같은 이름을 쓴다
최종 프로젝트 · DB 스키마 설계서 작성법
20
DB 스키마는 거의 모든 산출물이 참조한다. 이름이 어긋나면 전체가 어긋난다
API 설계 문서
필드명과 컬럼명을 맞춘다
incident_id, approval_id와 ID 형식을 똑같이 쓴다.
에이전트 설계서
메모리가 저장되는 곳
체크포인트와 장기 메모리(pgvector)의 테이블을 밝힌다.
AI 보안 가드레일 문서
RLS 표가 권한표다
역할별 권한이 두 문서에서 같아야 한다.
통합 테스트 결과서
차단되는지 확인한다
권한 없는 조회가 막히는 것이 테스트 케이스다.
+자주 나오는 실수와 고치는 법
최종 프로젝트 · DB 스키마 설계서 작성법
21
실수
이렇게 고친다
같은 컬럼이 문서 안에서 이름이 다르다
+(created_by 와 owner_id)
엔터티 정의 표를 기준으로 삼아 ERD와 관계 표를 맞춘다
ID 형식이 API 문서와 다르다
+(UUID라고 적고 예시는 inc-001)
형식을 하나로 정하고 두 문서를 함께 고친다
ERD 그림만 있고 제약이 없다
PK·FK·NOT NULL·UNIQUE를 컬럼마다 적는다
임베딩 모델의 차원과 VECTOR(n)이 다르다
모델 이름과 차원을 컬럼 옆에 함께 기록한다
RLS를 켜지 않고 service_role로만 접근한다
테이블마다 RLS 표를 만들고 차단 테스트를 남긴다
+제출 전 체크리스트
최종 프로젝트 · DB 스키마 설계서 작성법
22
ERD 그림과 관계 명세 표가 서로 일치한다
모든 컬럼에 타입·제약·의미가 적혀 있다
모든 테이블에 기본키와 created_at이 있다
API 설계 문서와 필드명·ID 형식이 같다
벡터 차원, 인덱스 연산자, 임베딩 모델이 적혀 있다
테이블마다 역할별 RLS 표가 있다
Redis 키 이름 규칙과 TTL이 적혀 있다
문서의 SQL을 실제로 실행해 확인했다
+오늘 팀에서 할 일
최종 프로젝트 · DB 스키마 설계서 작성법
23
API 설계 문서를 옆에 펼쳐 놓고 시작한다
① 테이블 목록
API 필드에서
+저장할 대상 뽑기
→
② ERD와 관계 표
키 컬럼과
+1:N 관계 그리기
→
③ 엔터티 정의
핵심 테이블의
+SQL 실행까지
→
④ RLS 표 초안
역할별 권한을
+팀이 함께 정하기
문서 머리말에 문서 버전과 작성 상태를 적는다. 예: 문서 버전 v0.1 | 작성 상태: 초안
+
+
+멀티 에이전트와 Auto-Healing
최종 프로젝트 적용 가이드 · 앞 과정에서 배운 것을 팀 서비스에 연결하기
AI 애플리케이션 개발 과정 · 최종 프로젝트 가이드
Role · Tool · Contract
max_steps
retry → fallback
incident log
+세 개념은 서로 다른 질문에 답한다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
2
에이전트를 여러 개 만든다고 복구가 생기지 않고, 복구를 하려고 꼭 에이전트가 필요한 것도 아니다
멀티 에이전트
누가 어떤 순서로?
역할, Tool 권한, 입출력 계약이 서로 다른 에이전트가 정해진 순서로 일을 나눈다.
자기 성찰
답이 맞나?
응답은 왔지만 내용이 기준에 못 미칠 때, 평가하고 고쳐서 다시 낸다.
Auto-Healing
시스템이 돌아가나?
호출이나 서비스가 고장 났을 때, 감지하고 복구한 뒤 정상인지 확인한다.
+자주 하는 오해 네 가지
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
3
오해
실제
프롬프트를 여러 번 호출하면 멀티 에이전트다
역할·권한·계약이 같다면 함수를 여러 번 부른 다단계 체인이다
LangGraph를 쓰면 멀티 에이전트다
프레임워크가 아니라 구조가 기준이다. 역할, 상태, 전이를 실제로 연결해야 한다
재시도를 붙이면 Auto-Healing이다
재시도는 복구 수단 하나다. 감지, 분류, 검증, 기록이 이어져야 한다
LLM에게 "다시 해 봐"라고 하면 복구된다
합격 기준은 코드가 검사하고, 복구 순서는 미리 정해 둔다
+개념마다 대응하는 산출물이 있다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
4
STEP 3과 STEP 4의 문서는 아래 질문에 대한 팀의 답을 적는 것이다
상태 전이
+그래프 설계서
STEP 3
+누가 어떤 순서로
→
자기 성찰
+테스트 결과서
STEP 3
+답이 맞나
→
협업 아키텍처
+설계서
STEP 4
+역할과 인계
→
보안 가드레일
+설계 문서
STEP 4
+해도 되는 일인가
→
Auto-Healing
+구현 결과서
STEP 4
+시스템이 돌아가나
평가는 문서가 있는지가 아니라 설계·구현·검증이 이어지는지를 본다. 같은 실행 ID와 같은 이름으로 문서를 잇는다.
+에이전트, 도구, 오케스트레이터를 구분한다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
5
구성 요소
하는 일
예
모델
판단과 생성에 쓰는 엔진
여러 역할이 같은 모델을 써도 된다
에이전트
맡은 역할에 따라 판단하고 결과를 만든다
요청 분석, 초안 작성, 근거 검토
도구 · API
정해진 입력으로 작업을 실행한다
DB 조회, 문서 검색, 예약 저장
오케스트레이터
순서, 상태, 전이, 상한을 통제한다
Python 함수, LangGraph
검증 코드
조건을 기계적으로 확인하고 차단한다
필수 필드, 권한, 합계
함수나 그래프 노드 하나가 곧 에이전트 하나는 아니다. 로그인, 파일 읽기, 합계 계산은 일반 코드로 충분하다.
+에이전트를 나눠도 되는 네 가지 이유
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
6
이 중 하나로 설명되지 않으면 나누지 않는다. 에이전트가 늘면 비용, 지연, 오류 경로도 늘어난다
권한
Tool 권한이 다르다
조회만 하는 역할과 실행하는 역할을 나누면, 진단 담당이 복구를 실행할 수 없다.
병렬
동시에 할 수 있다
서로 독립인 조회를 동시에 실행하고 결과를 합친다.
검증
생성과 검증을 분리한다
글을 쓴 역할이 자기 글을 평가하지 않게 한다.
추적
책임을 추적해야 한다
누가 무엇을 넘겼는지 기록으로 남겨야 하는 업무다.
+에이전트마다 네 가지를 정한다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
7
협업 아키텍처 설계서의 역할 표가 이 네 칸으로 이루어진다
01
역할
무엇을 하는지와 함께, 무엇을 하지 않는지를 적는다.
02
입출력 계약
Pydantic 스키마로 정한다. 검증을 통과한 결과만 다음 역할로 넘긴다.
03
Tool 권한
역할마다 허용 Tool 목록을 둔다. 목록 밖의 호출은 코드가 거부한다.
04
종료 조건
최대 단계 수, 통과 조건, 실패했을 때의 행동을 정한다.
+역할 카드와 계약을 코드로 적는다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
8
non_goals를 적어야 역할이 겹치지 않는다.
allowed_tools 밖의 Tool은 호출할 수 없다.
근거가 없는 답은 계약에서 걸러진다.
앞 호출이 끝난 것과, 다음 역할이 쓸 결과가 준비된 것은 다르다.
agents.py (형식 예시)
from pydantic import BaseModel, Field
+
+class DraftResult(BaseModel):
+ answer: str = Field(min_length=1)
+ evidence_ids: list[str] = Field(min_length=1)
+
+WRITER = {
+ "role": "초안 작성",
+ "non_goals": ["품질 평가", "외부 시스템 변경"],
+ "allowed_tools": frozenset({"search_docs"}),
+ "output": DraftResult,
+ "max_steps": 3,
+}
+
+def handoff(raw: dict) -> DraftResult:
+ # 계약을 통과한 결과만 다음 역할로 넘긴다
+ return DraftResult.model_validate(raw)
+다섯 가지 협업 패턴에서 고른다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
9
패턴
언제 쓰나
예
Sequential
앞 결과가 다음 역할의 입력일 때
분석 → 작성 → 검토
Parallel + Join
독립인 조회를 동시에 하고 합칠 때
날씨·장소·예산 → 일정
Router
요청 종류에 따라 한 곳으로 보낼 때
조회 / 위험 작업 / 일반 질문
Supervisor–Worker
관리자가 나누고 결과를 보며 다시 지시할 때
계획 → 위임 → 종합
Handoff
책임 자체를 다른 역할에 넘길 때
상담 → 전문 담당
LLM이 다음 역할을 고르는 구조라도, 허용되는 전이와 호출 상한과 종료는 코드가 통제한다.
+일부만 실패했을 때의 정책을 미리 정한다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
10
정책은 LLM이 즉석에서 정하지 않는다. 업무 요구사항으로 문서에 적어 둔다
Fail Fast
하나라도 실패하면 중단
모든 결과가 있어야 의미가 있는 업무에 쓴다. 결제, 예약 확정이 그렇다.
Best Effort
성공한 것으로 계속
일부가 빠져도 쓸모가 있을 때 쓴다. 빠진 정보는 결과에 표시한다.
Required / Optional
필수만 성공하면 계속
역할마다 필수 여부를 정한다. 선택 결과 없이 진행한 것은 복구가 아니다.
+자기 성찰은 생성과 평가를 분리한 루프다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
11
Writer가 쓰고, Evaluator가 기준별로 평가하고, Reviser가 피드백을 반영한다
Writer
초안 생성
→
Evaluator
기준별 평가,
+피드백 작성
→
Reviser
피드백을
+반영해 수정
→
재평가
통과하면
+바로 종료
→
상한 도달
failed로 종료,
+사람 검토
끝까지 통과하지 못하면 실패로 끝낸다. 통과하지 못한 결과를 성공인 것처럼 내보내지 않는다.
+자기 성찰 루프의 네 가지 규칙
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
12
기준
평가 기준을 먼저 정한다
평균 점수 하나가 아니라, 어떤 기준에서 떨어졌는지 이름이 남게 한다.
검사
검사할 수 있는 것은 코드로
스키마, 근거 유무, 금지 표현은 Python이 확인한다. LLM 평가는 그다음이다.
피드백
피드백은 구체적으로
어느 부분이 왜 틀렸는지를 Reviser에게 넘긴다. "다시 해 봐"는 피드백이 아니다.
상한
반복 횟수를 코드로 제한
최대 횟수를 상수로 둔다. 끝나는 조건이 없는 루프는 버그다.
+자기 성찰 테스트 결과서에 남길 것
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
13
항목
내용
평가 기준
기준의 이름과 합격 조건
시나리오
정상, 근거 누락, 잘못된 Tool 선택처럼 서로 다른 경우
라운드별 기록
초기 응답 → 평가와 피드백 → 수정 → 최종 판정
종료 사유
통과, 상한 도달, 치명 오류 중 무엇으로 끝났나
비용
반복 횟수, 토큰 사용량, 소요 시간
실행 로그나 추적 화면을 붙여, 표의 숫자가 실제 실행에서 나왔음을 보인다.
+Auto-Healing은 여섯 단계의 운영 흐름이다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
14
장애를 마법처럼 해결하는 기능이 아니다. 감지하고, 전략을 고르고, 결과를 확인하는 흐름이다
① 감지
timeout, 5xx,
+빈 응답
→
② 분류
장애 유형
+판단
→
③ 전략 선택
재시도, 대체,
+차단, 이관
→
④ 실행
허용된 조치만
+제한적으로
→
⑤ 검증
정상인지
+다시 확인
→
⑥ 기록
전 과정을
+로그로
검증에 실패하면 다음 전략으로 넘어가거나 사람에게 넘긴다. 복구 후 검증이 없으면 복구했다고 말할 수 없다.
+분류가 먼저다: 모든 오류를 재시도하지 않는다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
15
오류
다음 행동
이유
Timeout, 429, 5xx
재시도 후 대체 경로
일시적 오류다
401 인증 실패
즉시 중단
다시 해도 안 된다. 키와 설정을 확인한다
입력 누락
재계획, 추가 질문
입력이나 계획이 잘못됐다
권한 위반, Prompt Injection
차단
재시도는 정책을 반복해서 공격하는 셈이다
원인 불명
사람에게 이관
자동 복구 대상이 아니다
팀 서비스의 장애 유형표를 이 형식으로 먼저 만든다. Auto-Healing 구현 결과서의 첫 표가 된다.
+복구는 정해진 순서로 한 계단씩 내려간다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
16
어떤 순서로 무엇을 시도할지는 장애가 나기 전에 정해 둔다
① 재시도
같은 작업을
+기다렸다 다시
→
② 제공자 전환
다른 LLM
+제공자로
→
③ 대체 응답
캐시, 규칙,
+검증된 템플릿
→
④ 사람 이관
실패를 기록하고
+검토 요청
대체 응답을 썼으면 화면과 로그에 그렇게 표시한다. 정상 생성인 것처럼 보이게 하지 않는다.
+복구 계단을 코드로 적는다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
17
일시적 오류만 재시도한다. 다른 예외는 그대로 올라가 중단되거나 차단된다.
횟수와 대기 시간에 상한을 둔다.
어느 경로로 응답했는지 함께 돌려줘 화면에 표시한다.
모든 시도를 로그에 남긴다.
healing.py (형식 예시)
import time
+
+class Transient(Exception):
+ """timeout, 429, 5xx 같은 일시적 오류"""
+
+def call_with_healing(providers, template, log, wait=0.5):
+ for name, call in providers: # primary, secondary
+ for attempt in range(1, 4): # 최대 3회
+ try:
+ result = call()
+ log.append((name, attempt, "ok"))
+ return result, name
+ except Transient:
+ log.append((name, attempt, "transient"))
+ time.sleep(wait * 2 ** (attempt - 1))
+ log.append(("template", 1, "fallback"))
+ return template, "template"
+무엇을 복구하는지 대상을 구분한다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
18
복구 대상
예
복구 후 확인할 것
LLM · 도구 호출
타임아웃 재시도, 제공자 전환
계약, 근거, 업무 조건
작업 흐름
실패한 단계만 재실행, 저장된 상태에서 재개
성공 결과 보존, 중복 실행 방지
서비스 · 인프라
컨테이너 재시작, 트래픽 차단
Health와 실제 요청 처리
모든 팀이 서버 재시작을 만들 필요는 없다. 팀 서비스에서 실제로 일어날 실패를 고른다.
+화면이 다시 연결된 것(SSE 재연결)은 화면의 복구다. 뒤에서 실패한 작업까지 복구된 것은 아니다.
+위험한 작업은 자동으로 다시 실행하지 않는다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
19
결제, 삭제, 재시작, 알림 발송처럼 되돌리기 어려운 작업에 적용한다
승인
사람이 먼저 승인한다
에이전트가 혼자 복구하지 않는다. 승인 ID가 없으면 실행이 거부되게 만든다.
중복 방지
이미 처리됐을 수 있다
응답이 끊겼어도 첫 요청은 처리됐을 수 있다. 다시 저장하기 전에 중복을 확인한다.
시뮬레이션
모의 실행부터 시작한다
처음에는 실제 재시작 대신 전략 선택까지만 실행한다. 모의 실행임을 결과에 밝힌다.
+기록이 곧 증빙이다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
20
복구에 성공했어도 장애가 있었다는 사실을 남긴다.
같은 실행 ID로 감지부터 검증까지 이어 볼 수 있게 한다.
대체 경로를 썼는지 표시한다.
API Key, 비밀번호, 불필요한 개인정보는 기록하지 않는다.
incident 기록 (형식 예시)
{
+ "incident_id": "inc-001",
+ "detected_failure": "api_timeout",
+ "selected_strategy": "retry_with_backoff",
+ "retry_count": 1,
+ "fallback_used": false,
+ "recovery_status": "success",
+ "validation_result": "health_check_passed",
+ "duration_ms": 8200
+}
+복구율은 장애를 주입해서 숫자로 보인다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
21
Auto-Healing 구현 결과서의 핵심은 재현할 수 있는 실험과 그 결과다
① 주입
일부러 고장 낸다
장애 유형마다 여러 건씩 주입한다. Mock 오류, 429 유발, 잘못된 입력을 쓴다.
② 측정
검증 통과만 센다
감지 시간과 복구 시간도 함께 잰다.
복구율 = 검증 통과 건수
+ ÷ 자동 복구 대상 건수
③ 구분
섞어서 세지 않는다
정상 복구, 대체 응답, 사람 이관을 따로 적는다. 복구 실패 시나리오도 하나 이상 넣는다.
+세 루프가 한 요청 안에서 만난다
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
22
요청 하나가 지나가는 길에 가드레일, 오케스트레이션, 자기 성찰이 차례로 놓인다
가드레일
입력 검증,
+위반이면 차단
→
Orchestrator
순서와 전이
+통제
→
Agents
역할별 실행,
+계약 검증
→
Evaluator
품질 미달이면
+수정 루프
→
응답
경로와 근거를
+함께 표시
어느 단계에서든 호출이 실패하면 Auto-Healing이 분류, 복구, 검증, 기록을 맡는다. 복구하지 못하면 사람에게 넘긴다.
+업무 유형별 적용 예시
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
23
업무
역할 분담
품질 개선
장애 복구
리서치 보고서
계획 → 근거 수집 → 작성·검토
근거 없는 주장을 수정
검색 실패 시 재시도, 다른 출처
상담·예약 지원
분류 → 규정 검토 → 예약안
규정·시간 위반을 수정
조회는 재시도, 저장은 중복 확인
장애 대응
증상 분석 → 조치 계획 → 검증
위험·롤백 누락을 수정
승인된 조치 후 Health 재검증
학습 자료·문항
자료 분석 → 생성 → 근거 검토
오답·보기 중복을 수정
제공자 전환, 검증 실패면 중단
특정 팀의 요구사항이 아닌 예시다. 팀의 사용자와 핵심 기능에 맞춰 바꿔 쓴다.
+시연에서 보여 줄 다섯 장면
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
24
장면
보여 줄 것
정상 흐름
누가 어떤 입력을 받아 무엇을 다음 역할에 넘겼는가
내용 오류
검토가 무엇을 지적했고, 어떻게 수정하고 다시 평가했는가
복구 성공
장애 주입 → 감지 → 조치 → 재검증 → 종료를 같은 실행 ID로
복구 실패
상한을 넘으면 반복하지 않고 실패와 사람 이관으로 끝나는가
위험 경계
권한 부족이나 근거 누락을 성공으로 우회하지 않는가
개념 확인을 위한 수업용 점검 제안이다. 별도 배점이나 에이전트 개수 규정은 아니다.
+적용 점검표
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
25
에이전트마다 역할·하지 않는 일·허용 Tool·입출력 스키마가 있다
에이전트를 나눈 이유를 권한·병렬·검증·추적으로 설명할 수 있다
실행 순서와 종료 조건이 코드나 그래프에 있다
자기 성찰에 평가 기준·최대 횟수·실패 처리가 있다
장애 유형표 → 전략 → 검증 → 기록이 이어져 있다
401·권한 위반·Prompt Injection은 재시도하지 않는다
대체 응답을 쓰면 화면과 로그에 표시한다
복구 실패 시나리오를 하나 이상 실험해 남겼다
+지금 팀에서 할 일
최종 프로젝트 · 멀티 에이전트와 Auto-Healing 적용 가이드
26
넓게 벌이지 말고, 흐름 하나와 실패 하나를 끝까지 연결한다
① 핵심 흐름 하나
사용자 시나리오
+하나 고르기
→
② 역할 표
책임, 입출력,
+Tool, 종료 조건
→
③ 실패 하나
실제로 일어날
+장애를 끝까지
→
④ 주입과 기록
일부러 고장 내고
+로그로 증빙
앞 과정에서 실습한 제공자 전환, 평가·수정 루프, 계약 검증 코드를 다시 실행해 보고 팀 서비스에 맞게 결합한다.
+
+