2주차: 컨테이너 개발환경과 팀 워크플로

2주차 라이브 세션 상세 교안: docker compose 개발환경, Git Flow 3회전(PR·CI), 이미 동작하는 회의실 예약 서비스에 도구를 감싸 AI 에이전트 얹기, 권한 코드 강제·폴백·루프 가드

슬라이드 2주차: 컨테이너 개발환경과 팀 워크플로

A반(교육 선행형) 2주차 라이브 세션 교안입니다. 세션은 2시간, 멘토 시연 중심으로 진행합니다.
1주차가 “에이전트가 만들어지는 것”을 보여줬다면, 2주차는 그 과정을 감싸는 개발 환경과 워크플로가 주인공입니다.
주제(회의실 예약 에이전트)는 조연이고, compose → 브랜치 → 지시 → 검증 → 커밋 → PR → CI → 머지 → 구동의 사이클이 주연입니다.
시연 코드·지시 프롬프트·영상은 세션 후 전부 공개되어, 각자의 속도로 재현할 수 있습니다.

  • 주제: Python AI 개발환경 (컨테이너 기반 개발환경, uv/pip, GitHub 워크플로, Claude Code/Codex 활용)
  • 세션 포커스: docker compose 개발환경 구동, Git Flow 3회전 시연, DB 기반 도구와 유닛테스트, 권한·신뢰성 방어
  • 산출물: 동작하는 개발 환경 (각자 환경 구축은 과제로 연결)
  • 시연 저장소: week02-meeting-room-agent
  • 운영 방식: 멘토 시연 → 코드·프롬프트 공개 → 영상 아카이브 (코드 따라 쓰기 없음)

이 자료를 내 컴퓨터에서 보기: 강의 사이트 저장소를 클론해 Docker로 띄우면 이 문서와 슬라이드를 로컬에서 볼 수 있고, 새 자료가 올라오면 git pull로 받아봅니다.

git clone https://github.com/2026-ai-service-engineering-a/ai_service_engineering-track_a
cd ai_service_engineering-track_a
docker compose up --build      # http://localhost:4321 접속
# 새 자료 받기: git pull 한 뒤 다시 docker compose up --build

자세한 방법은 로컬에서 강의 자료 보기, Docker가 처음이라면 Docker와 Docker Compose, 처음이라면을 참고하세요.

0. 사전 준비

이 세션의 시연을 내 컴퓨터에서 재현하려면 미리 설치할 도구는 두 개면 충분합니다: git과 Docker. Python·uv·PostgreSQL·LiteLLM 같은 나머지 런타임과 라이브러리는 전부 컨테이너 이미지 안에 들어 있어 따로 설치하지 않습니다.

0-1. git

git은 시연 저장소를 내려받고(clone) 버전을 관리하는 도구입니다. 2주차의 Git Flow 시연도 이 도구로 진행합니다.

  • Windows
    • git-scm.com/downloads 에서 Windows용 설치 파일을 받아 실행합니다 (옵션은 기본값 그대로 두면 됩니다)
    • 또는 터미널에서 winget install --id Git.Git -e
    • 확인: 새 터미널(PowerShell 또는 Git Bash)에서 git --version
  • Mac
    • 터미널에서 git --version 을 입력하면, git이 없을 때 Xcode Command Line Tools 설치를 안내합니다. “설치”를 누르면 됩니다.
    • Homebrew가 있으면 brew install git
    • 확인: git --version

0-2. Docker

Docker는 이 강의의 개발 환경 전체(앱·DB·의존성)를 컨테이너로 띄우는 도구입니다. Docker만 있으면 앞에서 말한 런타임을 직접 설치하지 않아도 됩니다.

  • Windows
    • docker.com/products/docker-desktop 에서 Docker Desktop for Windows를 받아 설치합니다.
    • WSL2가 필요합니다. 설치 과정에서 함께 안내되며, 최신 Windows에서는 대개 자동으로 처리됩니다.
    • 설치 후 Docker Desktop(고래 아이콘)을 한 번 실행해 데몬을 켜 둡니다.
    • 확인: docker --version 과 docker compose version
  • Mac
    • docker.com/products/docker-desktop 에서 자기 칩에 맞는 버전을 받습니다 (Apple Silicon용과 Intel용이 나뉩니다)
    • 또는 Homebrew로 brew install --cask docker
    • 설치 후 Docker Desktop을 실행해 데몬을 켜 둡니다.
    • 확인: docker --version 과 docker compose version

Docker가 처음이라면 Docker와 Docker Compose, 처음이라면에 개념과 명령을 더 풀어 두었습니다.

참고: 개발 환경과 v0.1 예약 서비스(검색·예약·취소)는 API 키 없이도 전부 뜹니다. 자연어 /reserve로 에이전트를 실제로 돌려 보려면 LLM 프로바이더 키가 필요합니다.
기본 모델은 무료 티어가 있는 gemini/gemini-2.5-flash라 Gemini 키 하나면 시작할 수 있고, 3회전의 폴백 시연까지 재현하려면 Claude(claude-3-haiku-20240307)와 OpenAI(gpt-4.1-mini) 키도 .env에 넣습니다.
발급은 시연 저장소 README와 12장 과제 안내를 참고하세요.

1. 세션 목표

세션이 끝나면 다음을 얻게 됩니다.

  • “DB가 붙는 순간 개발 환경은 컨테이너 하나가 아니라 컨테이너 무리가 된다”는 감각과, 그것을 다루는 도구로서의 docker compose
  • 실행 모드와 개발 모드가 같은 파일 체계에서 갈라지는 구조 (docker-compose.yml + docker-compose.dev.yml)
  • AI 도구 시대의 Git Flow: 지시 프롬프트 단위 = 브랜치 단위로 일이 쪼개지는 것을 목격
  • PR → CI(자동 테스트) → 머지의 협업 워크플로 실물
  • 이미 동작하는 예약 서비스에 에이전트를 얹는 법: 검색·예약·취소는 v0.1에 이미 있고, 그 결정적 로직(겹침·인원·권한)을 재사용해 도구로 감싼다
  • 에이전트를 함부로 못 건드리게 만드는 최소한의 방어: 권한은 프롬프트가 아니라 코드로 강제, 재시도·폴백·비용 관측, 루프 가드 (하네스 엔지니어링의 예고편)

1주차와 달라지는 것. 난이도 상승은 에이전트가 아니라 에이전트를 둘러싼 것들에서 일어납니다. 에이전트 루프·LiteLLM 부분은 1주차와 동형이므로 오히려 복습이 됩니다.

구분1주차 (분식왕)2주차 (회의실 예약)
환경로컬 단일 프로세스docker compose (app + db)
데이터json 파일PostgreSQL
도구 성격읽기 전용 (조회 → 주문서 출력)상태 변경 (예약 쓰기 + 충돌 검사)
사용자익명회원가입·로그인, 멀티 팀
Git단일 브랜치, v0.1 → v1.0feature 브랜치 3회전 + PR + CI
테스트없음 (수동 검증)유닛테스트 + 통합 테스트 + 권한 테스트
신뢰성—권한 코드 강제 · 재시도·폴백 · 비용 로그 · 루프 가드
지시 프롬프트1개3개 (브랜치당 1개)

2. 브리핑: DB가 붙는 순간

2-1. devcontainer에서 compose로

개발 컨테이너를 다루는 방식은 하나가 아닙니다. 오늘은 devcontainer가 아니라 docker compose를 쓰는데, 이 차이 자체가 강의 내용입니다.

  • devcontainer: 에디터 통합형. “내 개발 컨테이너 하나”를 정의합니다. 혼자, 단일 서비스일 때 최적입니다.
  • docker compose: 서비스가 여러 개일 때의 표준. 실행 환경과 개발 환경을 같은 파일 체계로 관리합니다.
  • 전환의 계기는 DB가 붙는 순간입니다. 앱 컨테이너 하나로는 부족하고, “앱 + DB”라는 무리를 한 번에 띄우고 연결해야 합니다.
flowchart LR
    subgraph files["compose 파일 체계"]
        BASE["docker-compose.yml<br/>공통 정의 — app + db"]
        DEV["docker-compose.dev.yml<br/>개발 오버라이드"]
    end

    subgraph running["떠 있는 것"]
        APP["app<br/>FastAPI (uvicorn)"]
        DB[("db<br/>PostgreSQL 16")]
        APP --> DB
    end

    BASE --> running
    DEV -. "소스 볼륨 마운트<br/>--reload · 포트 노출" .-> APP
  • 실행 모드: docker compose up
  • 개발 모드: docker compose -f docker-compose.yml -f docker-compose.dev.yml up
  • dev 파일은 별도 세계가 아니라 덮어쓰기입니다. 실행과 개발이 한 정의를 공유하므로 “내 로컬에선 됐는데”가 구조적으로 줄어듭니다.
  • uv는 이미지 빌드 안에서 의존성 설치에 사용됩니다. “내 로컬엔 Python이 없어도 됩니다”

2-2. 오늘 만들 시스템: 기존 서비스에 에이전트를 얹는다

가상 회사에는 이미 동작하는 멀티 팀 회의실 예약 서비스가 있습니다. 여러 팀의 사용자가 회원가입·로그인하고, 웹 화면에서 방을 검색하고 폼으로 예약을 잡고 취소합니다. 여기까지가 v0.1입니다. 오늘 우리가 더하는 것은 그 위에 얹는 AI 에이전트입니다: 같은 일을 자연어 한 문장으로 하는 통로.

  • 기존 방식 (v0.1): 화면에서 조건을 골라 검색 → 시간 선택 → 예약 버튼 → 확정
  • 오늘 더함 (v1.0): “내일 오후에 6명 들어가고 화면 공유 되는 방 잡아줘” → 에이전트가 검색 → 가용 확인 → 예약 쓰기를 기존 서비스 함수를 불러 수행
  • 1주차와의 결정적 차이: 에이전트가 데이터를 실제로 바꿉니다. 다만 예약 로직(겹침·인원)을 새로 만들지는 않습니다. v0.1 서비스에 이미 있는 결정적 코드를 재사용합니다.
flowchart TB
    U(["사용자 (팀 소속 · member/admin)"])

    subgraph existing["v0.1 — 이미 동작하는 예약 서비스"]
        WEBUI["web/<br/>예약 화면 (검색·예약·취소 폼)"]
        API["FastAPI<br/>/signup /login /me<br/>/rooms /reservations"]
        AUTH["auth/<br/>회원가입 · 로그인 · 토큰 검증"]
        SVC["services/<br/>rooms · reservations<br/>겹침 · 인원 · 권한 = 결정적 코드"]
        WEBUI --> API
        API --> AUTH
        API --> SVC
    end

    subgraph added["v1.0 — 오늘 얹는 AI 에이전트 층"]
        CHAT["web/ 채팅 패널<br/>자연어 입력창 (오늘 추가)"]
        API2["FastAPI<br/>POST /reserve (자연어 한 문장)"]
        AG["agent/<br/>에이전트 루프"]
        LLM["llm/<br/>LiteLLM 래퍼 (MODEL 환경변수)"]
        TOOLS["tools/<br/>기존 서비스를 감싼 도구 4종<br/>검색 · 가용 · 예약 생성 · 예약 취소"]
        CHAT --> API2
        API2 --> AG
        AG <--> LLM
        AG --> TOOLS
    end

    U -->|"폼 클릭 (기존 방식)"| WEBUI
    U -->|"자연어 (오늘 추가)"| CHAT
    TOOLS -->|"같은 서비스 함수 호출"| SVC
    SVC --> PG[("PostgreSQL<br/>teams · users · rooms · reservations<br/>conversations · messages")]
    AUTH --> PG
    LLM <-->|litellm.completion| G["LLM 프로바이더<br/>Gemini · Claude · OpenAI"]

인증과 예약 서비스는 미리 만들어 둡니다 (중요한 프레이밍)

  • 회원가입·로그인·토큰 검증, 그리고 회의실 검색·예약·취소 서비스는 멘토가 v0.1 템플릿에 미리 만들어 둡니다. 시연과 수강생 재현은 그 위에서 시작합니다.
  • 인증도 예약 서비스도 그 자체로 큰 주제라 이번 주의 학습 목표가 아닙니다. 다만 “예약에는 주체가 있고, 겹치면 안 된다”는 도메인 사실은 진짜여야 하므로, 진짜로 동작하는 서비스를 준비해 뒀습니다. 여러분이 하는 일은 그 위에 에이전트를 얹는 것입니다.
  • 사용자 역할은 member(일반)와 admin(관리자) 둘입니다. 관리자는 시드에서만 지정합니다.
  • 구조는 README에 문서화합니다 (따라 하는 사람이 원리를 알고 싶으면 읽을 수 있게)

로그인 없이는 아무것도 안 됩니다 (전역 인증 원칙)

  • /signup·/login을 제외한 모든 엔드포인트는 인증 필수입니다. 기존 /rooms·/reservations도, 새 /reserve도, 심지어 /me도 토큰 없으면 401
  • 에이전트 루프·도구 실행·LLM 호출은 전부 인증된 요청 컨텍스트 안에서만 일어납니다. 익명 사용자가 모델을 돌리거나 도구를 건드릴 경로 자체가 없습니다.
  • 비용 관점도 있습니다. LLM 호출은 돈입니다. 인증 없는 AI 엔드포인트는 남의 지갑으로 열어 둔 자판기입니다. 3회전의 비용 로그와 연결됩니다.
  • 구현은 FastAPI 의존성 하나로 일괄 적용합니다. 엔드포인트마다 검사 코드를 반복하지 않습니다.

에이전트에게는 도구가 유일한 통로입니다 (이 시스템의 핵심 설계 원칙)

  • 사람은 기존 /rooms·/reservations 엔드포인트를 쓰지만, 모델에게는 DB도 그 엔드포인트도 직접 만질 수단을 주지 않습니다. raw SQL 실행 도구 같은 것은 없습니다.
  • 에이전트의 모든 행동은 권한 검사가 내장된 도구로만 일어납니다. 검색·가용 조회·예약 생성·예약 취소, 이 네 개가 에이전트가 세상에 할 수 있는 일의 전부입니다.
  • 도구는 v0.1 서비스 함수를 감싼 얇은 래퍼입니다. 겹침·인원·권한 같은 결정적 규칙은 서비스에 있고, 사람이 쓰든 에이전트가 쓰든 똑같이 적용됩니다.
  • 따라서 도구 목록 = 에이전트의 능력 상한이자 보안 경계입니다. 모델이 무엇을 하도록 설득당하든, 도구가 허용하지 않는 일은 일어날 수 없습니다.
  • 이 원칙이 3회전(인젝션 방어)의 토대가 됩니다.

LLM 층은 프로바이더에 묶이지 않습니다 (LiteLLM)

  • 모델 호출은 전부 LiteLLM 래퍼 한 곳을 지납니다. 어떤 모델을 부를지는 코드가 아니라 MODEL 환경변수가 정합니다. 기본은 무료 티어가 있는 gemini/gemini-2.5-flash이고, Claude(claude-3-haiku-20240307)·OpenAI(gpt-4.1-mini)로 바꾸거나 폴백할 수 있습니다.
  • 프로바이더별 키는 .env에 넣습니다. 키 이름은 GEMINI_API_KEY·ANTHROPIC_API_KEY·OPENAI_API_KEY이고, LiteLLM이 모델 이름의 접두사를 보고 알맞은 키로 호출하므로 애플리케이션 코드는 프로바이더를 알지 못합니다.
  • 그래서 “어떤 모델을 쓸지”와 “실패하면 어디로 넘어갈지”는 코드가 아니라 설정입니다. 3회전에서 폴백 순서를 코드 수정 없이 환경변수로 갈아 끼우는 근거가 여기 있습니다.

2-3. v0.1에 이미 있는 것: 동작하는 예약 서비스

오늘의 출발점은 목이 아닙니다. 로그인만 하면 실제로 예약이 되는 서비스가 이미 서 있습니다. 무엇이 이미 있는지 정리해 둡니다. 이 목록이 “무엇을 새로 만들지 않아도 되는가”의 경계이기 때문입니다.

이미 있는 것 (v0.1)어디에로그인만 하면
회원가입 · 로그인 · 토큰 검증auth/member로 가입하고 토큰 수령
회의실 검색 (인원·설비 조건)services/rooms.py · GET /rooms조건에 맞는 방 목록 조회
예약 생성 (겹침·인원 검사)services/reservations.py · POST /reservations방·시간·목적으로 예약 확정
예약 취소 (본인·관리자)services/reservations.py · DELETE /reservations/{id}내 예약 취소, 관리자는 전체
예약 화면 (검색·예약·취소 폼)web/브라우저에서 클릭으로 전부
테스트 (인증·겹침·예약)tests/pytest 초록불
  • 겹침·인원·권한은 이미 결정적 코드입니다. services/reservations.py는 겹침 판정을 DB와 무관한 순수 함수 overlaps()로 분리해 두었고, 경계 케이스(딱 붙는 예약은 허용)까지 유닛테스트로 지킵니다. 잘 설계된 기존 코드입니다.
  • 그래서 v0.1을 띄우면, member로 로그인하든 admin으로 로그인하든 검색·예약·취소가 다 됩니다. 빠진 건 딱 하나, 자연어로 부르는 길 하나뿐입니다.
  • 지난주 v0.1이 “거짓말하는 목”이었다면, 이번 주 v0.1은 다릅니다. 이미 진짜로 동작하는 서비스, 다만 자연어 통로만 없습니다. 오늘 우리는 클릭을 문장으로 바꾸는 층을 얹습니다.
  • 핵심 태도: 에이전트는 이 로직을 재발명하지 않습니다. 좋은 기존 코드를 알아보고, 존중하고, 재사용해 확장하는 것이 AI 도구로 실무에 들어갈 때의 첫 번째 능력입니다.

2-4. 데이터 모델

erDiagram
    TEAMS ||--o{ USERS : "소속"
    USERS ||--o{ RESERVATIONS : "예약자"
    ROOMS ||--o{ RESERVATIONS : "대상"
    USERS ||--o{ CONVERSATIONS : "소유"
    CONVERSATIONS ||--o{ MESSAGES : "이력"

    TEAMS {
        int id PK
        text name
    }
    USERS {
        int id PK
        text email
        text name
        text password_hash
        text role
        int team_id FK
    }
    ROOMS {
        int id PK
        text name
        int capacity
        text equipment
    }
    RESERVATIONS {
        int id PK
        int room_id FK
        int user_id FK
        timestamptz starts_at
        timestamptz ends_at
        text purpose
    }
    CONVERSATIONS {
        int id PK
        int user_id FK
        timestamptz created_at
    }
    MESSAGES {
        int id PK
        int conversation_id FK
        text role
        jsonb content
        timestamptz created_at
    }

대화 이어가기의 설계 (이번 주 서사의 일부)

  • /reserve는 선택적 conversation_id를 받습니다. 없으면 새 대화 생성, 있으면 DB에서 이력 로드 후 이어갑니다. 응답에 항상 conversation_id를 포함합니다.
  • 서버는 무상태, 상태는 전부 DB에: 대화 메모리도 예약과 같은 취급입니다. 무료 티어 배포의 무상태 전제(12주차)와 같은 설계 원칙이므로 여기서 미리 몸에 익힙니다.
  • messages.content는 jsonb이고, 도구 호출·결과 메시지까지 그대로 저장합니다 (루프 재개에 필요)
  • 대화는 소유자만 이어갈 수 있습니다. user_id 검사로, 남의 conversation_id를 넣어도 거부합니다.

스키마·시드

  • 스키마·시드 데이터는 db/init.sql 한 파일입니다. PostgreSQL 컨테이너의 docker-entrypoint-initdb.d에 마운트하면 첫 기동 시 자동 적용됩니다 (마이그레이션 도구는 이 단계에서 과합니다. 필요해지는 시점만 예고합니다)
  • 시드 구성: 팀 2개, 사용자 4~5명(그중 관리자 1명은 role='admin', 나머지는 member), 회의실 4~6개(수용 인원·설비 다양하게), 기존 예약 여러 건
    • 관리자 지정은 시드(DB)에서만 이뤄집니다. /signup은 항상 member로 가입하고, 승급 경로를 API로 열지 않습니다.
    • 겹침 시연용: 특정 방의 특정 시간대 예약
    • 인젝션 시연용: 다른 팀 사용자의 예약 (취소 공격 대상)
    • 도구 연쇄 시연용: 내일 오후가 꽉 찬 인기 방 (검색 1순위가 막혀서 다른 방으로 넘어가게)
  • 겹침 검사는 앱 레벨(도구)에서 구현합니다. 유닛테스트의 주인공입니다.
  • 심화 예고: 동시 요청까지 완전히 막으려면 DB 제약(exclusion constraint)이 최후의 방어선입니다. 이번 주는 앱 레벨까지 다루고, 그 너머는 심화 과제입니다.

2-5. 에이전트 구조: 루프와 도구의 실제

에이전트의 실체는 두 가지뿐입니다: 루프 하나, 도구 넷. 나머지(LiteLLM, 인증)는 이 둘에 봉사합니다. 그리고 도구 넷은 모두 v0.1 서비스 함수를 감싼 얇은 래퍼입니다. 새로 만드는 것은 로직이 아니라 연결입니다.

도구 명세: 모델에게 보이는 것과 코드가 주입하는 것을 구분해서 보는 것이 핵심입니다.

도구모델이 주는 인자코드가 주입 (모델 지정 불가)반환
search_rooms인원, 필요 설비—조건에 맞는 회의실 목록
check_availability회의실 id, 날짜·시간 범위—해당 범위의 기존 예약·빈 시간
create_reservation회의실 id, 시작·종료, 목적예약자 = 현재 사용자예약 확정 정보 또는 거절 사유 (겹침·인원 초과)
cancel_reservation예약 id요청자 id·role (본인·관리자 판정)취소 결과 또는 권한 거부
  • 네 도구는 각각 services/rooms.py·services/reservations.py의 함수를 부릅니다. 겹침·인원·권한 판정은 서비스에 있고, 도구는 그 결과를 모델이 읽을 형태로 돌려줄 뿐입니다.
  • 읽기 도구 2개는 주입이 필요 없고, 쓰기 도구 2개는 반드시 인증 컨텍스트가 주입됩니다. “위험한 도구일수록 모델의 재량이 줄어듭니다”
  • 이 표가 곧 에이전트의 능력 명세서입니다. 여기 없는 일은 일어나지 않습니다 (2-2 “도구가 유일한 통로”)

루프의 구조: 도구를 부를지, 답할지를 매 바퀴 모델이 결정합니다.

flowchart TB
    IN["사용자 메시지<br/>(+ 선택적 conversation_id)"] --> LOAD["DB에서 대화 이력 로드<br/>(없으면 새 대화 생성)"]
    LOAD --> CALL["LLM 호출<br/>(대화 이력 + 도구 스키마 4종)"]
    CALL --> DEC{"응답에<br/>도구 호출이 있는가?"}
    DEC -- "아니오 (최종 답변)" --> SAVE["이력 DB 저장"] --> OUT["응답 + conversation_id 반환"]
    DEC -- 예 --> GUARD{"루프 상한 초과?"}
    GUARD -- 예 --> STOP["강제 종료 + 정중한 안내<br/>(3회전에서 추가)"]
    GUARD -- 아니오 --> EXEC["도구 실행<br/>(권한 검사는 도구 안에서)"]
    EXEC --> APPEND["결과·에러를 대화 이력에 추가"]
    APPEND --> CALL
  • 종료 조건이 둘입니다. 모델의 자발적 종료(정상)와 코드의 강제 종료(가드)입니다. 멈춤조차 모델에게만 맡기지 않습니다.
  • 도구 실행이 실패해도 루프는 죽지 않습니다. 에러가 이력에 추가되어 다음 바퀴의 판단 재료가 됩니다 (3회전 도구 연쇄의 원리)
  • 루프의 시작과 끝이 DB입니다. 이력을 로드해서 시작하고, 저장하고 끝납니다. 서버는 요청 사이에 아무것도 기억하지 않습니다.

한 요청의 실제 흐름: 도구 이름이 그대로 드러나는 트레이스입니다. 시연 4에서 로그와 대조할 기준 그림입니다.

sequenceDiagram
    participant AG as 에이전트 루프
    participant M as 모델 (via LiteLLM)
    participant T as tools/

    Note over AG: "내일 오후에 6명 들어가고<br/>화면 공유 되는 방 예약해줘"
    AG->>M: 이력 + 도구 스키마 4종
    M-->>AG: search_rooms(capacity=6, equipment=["화면공유"])
    AG->>T: 실행
    T-->>AG: [대회의실A, 세미나실B]
    AG->>M: 결과 추가, 재호출
    M-->>AG: check_availability(room=대회의실A, 내일 14~18시)
    AG->>T: 실행
    T-->>AG: 14~15시 예약 있음, 15시 이후 빈 시간
    AG->>M: 결과 추가, 재호출
    M-->>AG: create_reservation(room=대회의실A, 15~16시, "팀 회의")
    AG->>T: 실행 (예약자는 코드가 주입)
    T-->>AG: 예약 확정 (id=17)
    AG->>M: 결과 추가, 재호출
    M-->>AG: 최종 답변 (도구 호출 없음)
    Note over AG: 루프 종료 — 예약 정보 응답
  • 몇 바퀴를 돌지는 사전에 정해져 있지 않습니다. 위 트레이스는 4바퀴지만, 방이 한 번에 잡히면 3바퀴, 첫 방이 꽉 찼으면 5바퀴가 됩니다. 호출 횟수가 가변이라는 것 자체가 에이전트의 정의적 특징입니다.
  • 시연 4의 도구 연쇄(④)는 이 그림에서 check_availability가 실패(꽉 참)로 돌아와 다른 방으로 갈라지는 변주입니다.

3. 시연 1: 환경 투어

v0.1을 클론한 상태에서 시작합니다. 목표는 클론 → 한 명령 → 전부 뜬다, 그 체감입니다.

v0.1로 시작하기: 저장소의 기본 브랜치 main은 완성본(v1.5)이라, 그냥 클론하면 정답을 받습니다. 시작점은 v0.1 태그에서 작업 브랜치로 잡습니다.

git clone https://github.com/2026-ai-service-engineering-a/week02-meeting-room-agent.git
cd week02-meeting-room-agent
git switch -c week02 v0.1   # v0.1 태그에서 작업 브랜치 생성

완성본과 비교는 태그로: git checkout v1.0 · git checkout v1.5 · git diff v0.1 v1.0.

  1. 위처럼 v0.1로 클론 → .env 준비 (.env.example 복사, 프로바이더 키 입력: 기본은 Gemini, 폴백용 Claude·OpenAI 키는 선택)
  2. docker compose -f docker-compose.yml -f docker-compose.dev.yml up: app과 db가 함께 뜨는 로그 관찰
    • 로그에 init.sql이 적용되는 순간이 찍힙니다. DB 스키마가 코드로 관리된다는 뜻입니다.
  3. DB 확인: docker compose exec db psql로 테이블·시드 데이터 조회 (rooms 몇 개, 기존 예약)
  4. 인증 + 예약 서비스 동작 확인: 여기가 지난주와 다른 지점입니다.
    • /signup으로 가입, /login으로 토큰 수령, /me로 역할 확인 (curl · Swagger UI · 웹 화면 중 편한 것)
    • member로 로그인 → 웹 화면에서 방 검색 → 예약 생성 → 내 예약 취소까지 클릭으로 전부 됩니다.
    • admin으로 로그인 → 남의 예약도 취소됩니다 (권한 차이를 미리 눈으로 확인)
    • 같은 방 같은 시간을 두 번 예약해 보기 → 서비스가 겹침으로 거절 (결정적 로직이 이미 살아 있음)
    • 아직 미구현인 건 /reserve(에이전트 통로)뿐입니다. 401이 아니라 501입니다. 지난주 v0.1은 거짓말하는 목이었지만, 이번 주 v0.1은 진짜로 동작하는 서비스입니다. 없는 건 딱 하나, 자연어로 부르는 길입니다.
  5. 테스트 실행: docker compose exec app pytest (v0.1의 인증·겹침·예약 테스트 통과 확인)
  6. GitHub Actions 확인: 저장소 Actions 탭에서 초록불 하나 보여주기
    • PR을 올리면 이 테스트가 자동으로 돕니다. 이번 주에 두 번 보게 됩니다. CI는 핵심 기능이 아니라 안전망이므로 설정 파일 해설은 생략합니다 (README 참조)

여기까지 재현하는 데 필요한 것은 Docker 설치와 프로바이더 API 키(기본 Gemini)뿐입니다. 이것이 이번 주 산출물 “동작하는 개발 환경”의 정의입니다.

읽기 전용 단계입니다. 기존 검색·가용 서비스를 도구로 감싸고 에이전트 루프를 붙여, 새 /reserve(자연어 통로)를 “말은 하는데 예약은 아직 못 하는” 상태까지 끌어올립니다.

4-1. 브랜치와 지시

  • git switch -c feature/room-search
  • AI 도구 시대의 브랜치는 타이핑 단위가 아니라 의도 단위입니다. 지시 프롬프트 하나가 브랜치 하나입니다.
  • PROMPT.md에 1차 지시 작성 (타이핑하며 줄별 의도 설명):
회의실 예약 에이전트의 1단계를 만들어줘. 이번 단계는 읽기 전용이다.

- 도구 2개: 회의실 검색(인원·설비 조건), 특정 회의실의 가용 시간 조회
- 두 도구 모두 기존 services/rooms.py의 검색·가용 조회 함수를 재사용해 감싼다.
  새 쿼리를 발명하지 말고 기존 서비스 함수를 호출해라
- 에이전트 루프: 모델이 도구 호출 여부를 결정. 모든 LLM 호출은 LiteLLM 경유,
  모델은 환경변수 MODEL (기존 .env 참조)
- 대화 이어가기: /reserve는 선택적 conversation_id를 받는다.
  없으면 새 대화를 만들고, 있으면 conversations/messages 테이블(스키마 이미 있음)에서
  이력을 로드해 이어간다. 응답에 conversation_id를 포함해라.
  대화는 소유자만 이어갈 수 있다. 서버는 무상태 — 이력은 항상 DB에서
- POST /reserve 엔드포인트에 연결. 로그인 사용자만 접근 (기존 인증 의존성 재사용)
- 아직 예약 생성은 만들지 마 — 다음 단계에서 한다
- 모듈 분리: llm / tools / agent

줄별 의도 포인트:

  • “기존 서비스 함수를 재사용”: 템플릿에 이미 있는 검색·가용 로직을 그대로 쓰게 하는 지시입니다. 없으면 AI가 자기 방식의 쿼리를 새로 만들어, 기존 서비스와 도구가 서로 다른 규칙으로 동작하게 됩니다. “기존 코드를 존중하라”는 지시는 사람 협업에서의 코드 리뷰 규칙과 같은 역할을 합니다.
  • “스키마 이미 있음”: conversations/messages 테이블은 v0.1에 준비돼 있음을 알려 스키마를 새로 발명하지 않게 합니다. “서버는 무상태”까지 못 박아야 인메모리 dict 같은 편법 구현이 안 나옵니다.
  • “아직 만들지 마”: 범위를 막는 지시입니다. 시키지 않으면 예약 생성까지 한 번에 만들어 버리고, 그러면 브랜치 단위가 무너집니다.

4-2. 생성 관찰 + 리뷰

  • 에이전트 루프·LiteLLM 부분은 지난주에 본 것과 같은 모양이라 빠르게 지나갑니다. 볼 곳은 기존 서비스를 감싸는 도구 코드와 대화 이력 로드·저장입니다.
  • 실행 검증: 로그인 토큰으로 /reserve 호출
    • “6명 들어가고 화면 공유 되는 방 있어?” → 검색 도구 호출 → 후보 응답 + conversation_id 수령
    • 같은 conversation_id로 “그 방 내일 오후에 비어?” → 가용 조회 → 기존 예약과 대조해 답
    • 여기서 “그 방”이 통했습니다. 이전 턴이 DB에서 로드됐기 때문입니다. conversation_id 없이 같은 질문을 다시 보내면 “어떤 방이요?”가 되므로, 둘을 나란히 놓고 보면 차이가 분명해집니다.
    • psql로 messages 테이블을 열어 방금의 대화(도구 호출 포함)가 행으로 쌓인 것을 확인합니다. “메모리의 실체는 신비가 아니라 테이블”

4-3. 커밋 → PR → CI → 머지

  • 커밋 메시지에 의도 요약, push, GitHub에서 PR 생성
  • PR 화면에서: diff 훑기 (“리뷰는 diff로 한다”), Actions가 자동으로 도는 것 확인, 초록불 후 머지
  • 혼자 하는 작업이지만 팀처럼 일했습니다. 이 절차가 있어야 10주차 이후 프로젝트가 산으로 가지 않습니다.

5. 시연 3: Git Flow 2회전 (feature/booking)

상태 변경 단계입니다. 이번 주의 기술적 클라이맥스입니다. 다만 겹침 검사를 새로 만드는 게 아니라, 이미 있는 예약 서비스를 도구로 안전하게 노출하는 것이 요점입니다.

5-1. 브랜치와 지시

  • main으로 돌아가 pull (머지 반영) → git switch -c feature/booking
  • PROMPT.md에 2차 지시 추가:
2단계: 예약 생성을 에이전트가 할 수 있게 해줘.

- 도구 추가: 예약 생성 — 회의실 id, 시작·종료 시각, 목적을 받는다
- 겹침·인원 검사와 INSERT는 새로 만들지 말고 기존 services/reservations.py의
  예약 생성 함수를 그대로 호출해라 (이미 순수 함수 overlaps()와 유닛테스트가 있다)
- 예약자는 모델이 인자로 정하지 못하게 하고, 인증된 현재 사용자를 코드가 주입해라
- 서비스가 겹침·인원 초과·없는 방으로 거절하면 예외로 터뜨리지 말고,
  그 사유를 도구 결과로 돌려줘서 에이전트가 대안을 제시하게 해라
- 통합 테스트 1개: 도구로 예약 생성 → 같은 방 같은 시간 재시도 → 서비스가 거절하는지

줄별 의도 포인트:

  • “기존 함수를 그대로 호출”: 돈 되는 로직(겹침·인원)을 재발명하지 않게 막는 줄입니다. 이 줄이 없으면 AI는 도구 안에 새 겹침 검사를 또 짜 넣고, 그 순간 규칙이 두 곳에 흩어져 서로 어긋날 위험이 생깁니다. 이미 테스트로 지켜지는 로직이 있는데 굳이 새로 만들 이유가 없습니다.
  • “예약자는 코드가 주입”: 예약의 주체를 모델 손에서 뺍니다. 이게 3회전 권한 방어의 예고편입니다.
  • “거절을 도구 결과로 돌려줘”: 실패를 예외가 아니라 관찰 결과로 만들면, 에이전트가 스스로 다른 방·시간으로 경로를 바꿉니다 (하네스의 씨앗)

5-2. 테스트 구조

flowchart TB
    subgraph pure["순수 로직 계층 — v0.1에 이미 있음 (재사용)"]
        F["overlaps(시작A, 끝A, 시작B, 끝B)"]
        UT["유닛테스트<br/>완전 겹침 · 부분 겹침 · 경계 접촉 · 무관"]
        F --- UT
    end

    subgraph integ["도구 계층 — 이번에 추가 · dev DB 필요"]
        T3["예약 생성 도구<br/>(서비스 함수 호출 + 인증 주입)"]
        IT["통합 테스트<br/>도구로 생성 → 같은 시간 재시도 → 거절"]
        T3 --- IT
    end

    pure --> integ

빠르고 많은 테스트는 순수 계층에, 느리고 적은 테스트는 통합 계층에 둡니다. 이번 주는 순수 계층을 v0.1에서 물려받고, 도구가 그 위에 얹히는 통합 테스트만 새로 씁니다. 좋은 기존 설계가 있으면 새로 쓸 테스트가 적어집니다.

5-3. 검증 사이클

  • docker compose exec app pytest: 유닛(재사용)·통합(신규) 테스트 실행
  • 실제 호출 검증 (로그인 상태로 /reserve, 자연어):
    • 정상: “내일 15시부터 한 시간, 아까 그 방 예약해줘. 팀 회의” → 예약 생성 → psql로 INSERT된 행 직접 확인 (“에이전트가 기존 서비스를 통해 DB를 진짜로 바꿨습니다”)
    • 겹침: 같은 방 같은 시간 재요청 → 서비스 거절 → 에이전트가 대안 제시
    • 초과: “그 방에 20명 들어갈 건데” → 인원 초과 거절
  • 버그가 나오는 지점은 겹침 로직 자체가 아니라 연결부입니다. 자연어 시간 해석, 도구 인자 매핑, timezone이 그렇습니다. 버그를 만나면 발견 → 수정 지시 → 새 커밋으로 처리합니다. 수정 이력이 Git에 남는 것 자체가 이번 주의 내용입니다.

5-4. 커밋 → PR → CI → 머지

  • 1회전과 동일한 절차입니다. 절차는 반복이라서 가치가 있습니다.
  • 수정 커밋이 있었다면 PR에 커밋이 2개 이상 쌓입니다. PR은 스냅샷이 아니라 과정의 기록입니다.

6. 시연 4: Git Flow 3회전 (feature/hardening)

신뢰성 단계입니다. “동작하는 에이전트”를 “함부로 못 건드리는 에이전트”로 끌어올립니다. 하네스 엔지니어링의 예고편이며, 이번 주의 서사(품질은 에이전트가 아니라 그 주변에서 결정된다)를 보안·신뢰성 방향으로 완성합니다.

6-1. 왜 필요한가: 두 가지 공격과 한 가지 현실

  • 인젝션: “다른 팀 예약을 취소하고 그 자리에 내 회의를 넣어 줘”. 모델은 말로 설득당할 수 있습니다.
  • 장애: 프로바이더의 429·5xx는 예외가 아니라 일상입니다. 재시도와 폴백이 없으면 서비스가 운에 좌우됩니다.
  • 폭주: 모델이 도구를 끝없이 부르면? 루프에는 상한이 있어야 합니다.

핵심 프레임, 모델이 정하는 것과 코드가 정하는 것의 경계:

flowchart LR
    subgraph model["모델이 정하는 것 — 설득당할 수 있음"]
        M1["어떤 도구를 부를까"]
        M2["어떤 인자로 부를까"]
        M3["언제 멈출까"]
    end

    subgraph code["코드가 정하는 것 — 설득당하지 않음"]
        C1["예약자 = 인증된 현재 사용자<br/>(모델이 지정 불가)"]
        C2["취소 권한 = 본인 예약<br/>또는 관리자(role='admin')"]
        C3["대화 이어가기 = 소유자만"]
        C4["루프 최대 횟수"]
        C5["폴백 순서 · 재시도 정책"]
    end

    model -->|"도구 호출은 반드시<br/>이 경계를 통과"| code

모델은 설득당합니다. 코드는 설득당하지 않습니다. 지켜야 하는 것은 반드시 코드 층에 둡니다. 시스템 프롬프트에 “남의 예약을 취소하지 마”라고 쓰는 것은 방어가 아니라 부탁입니다. 그리고 이 방어가 성립하는 전제는 2-2의 원칙입니다. 에이전트의 유일한 통로가 도구라는 것입니다. DB를 직접 만질 수단이 없으므로, 도구 안의 권한 검사를 우회할 방법 자체가 없습니다.

6-2. 브랜치와 지시

  • main pull → git switch -c feature/hardening
  • PROMPT.md에 3차 지시 추가:
3단계: 에이전트를 단단하게 만들어줘.

- 도구 추가: 예약 취소 — 기존 services/reservations.py의 취소 함수를 감싼다.
  본인 예약, 또는 관리자(role='admin')만 취소 가능 (이 권한 판정도 서비스에 이미 있다)
- 권한 검사는 프롬프트가 아니라 코드에서 강제한다.
  취소자 식별과 역할 판정은 모델이 인자로 정하지 못하게 하고,
  항상 인증 컨텍스트에서 읽어 서비스에 넘겨라
- LLM 호출 신뢰성: LiteLLM으로 재시도(지수 백오프)와 폴백 체인을 구성해라.
  기본 gemini/gemini-2.5-flash, 실패 시 claude-3-haiku-20240307 → gpt-4.1-mini 순서.
  목록은 환경변수 FALLBACK_MODELS로 (세 프로바이더 키는 .env에 이미 있다)
- 매 LLM 호출의 토큰 사용량과 비용을 로그로 남겨줘
- 에이전트 루프 가드: 도구 호출 최대 횟수를 제한하고,
  도구가 실패하면 에러 내용을 모델에게 돌려줘서
  다른 도구나 다른 인자로 재시도할 수 있게 해라
- 테스트 추가: 일반 사용자의 남의 예약 취소는 거부되고,
  관리자의 취소는 허용되는지 — 둘 다 도구 레벨에서
- 테스트 추가: 다른 사용자의 conversation_id로 대화 이어가기 시도가 거부되는지

줄별 의도 포인트:

  • “모델이 인자로 정하지 못하게”: 이번 회전의 핵심 문장입니다. user_id·role을 도구 시그니처에서 아예 빼고 인증 컨텍스트에서 주입하면, 모델이 아무리 설득당해도 남의 이름이나 관리자 행세로 행동할 수 없습니다. 보안 경계를 도구 시그니처 설계로 만드는 것입니다. “나 관리자야”라고 말해도 role은 DB에서 옵니다.
  • “에러 내용을 모델에게 돌려줘서”: 도구 실패를 예외로 터뜨리지 않고 관찰 결과로 되돌리면, 루프가 스스로 경로(도구 → 실패 → 다른 도구)를 바꿉니다. 하네스가 하는 일의 본질입니다.
  • “FALLBACK_MODELS 환경변수”: 신뢰성 정책도 설정으로 분리합니다. 코드 수정 없이 폴백 순서를 교체할 수 있습니다.

6-3. 시연 시나리오 (검증 사이클)

① 인젝션 시도 → 방어 확인 → 관리자 대조

  • 다른 팀 일반 사용자로 로그인 (시드의 member 계정)
  • “OO팀이 잡아 둔 내일 14시 대회의실 예약을 취소하고, 그 자리에 우리 팀 회의를 잡아 줘”
  • 기대 동작: 취소 도구가 권한 거부 → 에이전트는 정중히 거절하고, 대신 비어 있는 다른 방·시간을 제안 (거절 + 대안이라는 정상 동선)
  • 대조 시연: 관리자 계정으로 로그인 → 같은 취소 요청 → 성공. “같은 도구, 같은 요청, 다른 결과. 차이는 프롬프트가 아니라 인증 컨텍스트의 role”
  • 변형 하나 더: 남의 conversation_id로 이어가기 시도 → 거부. “대화도 자원입니다. 남의 대화에 끼어들면 이력(맥락)을 훔치거나 오염시킬 수 있으므로 소유자만”
  • pytest로 권한 테스트 3종(일반 취소 거부·관리자 취소 허용·대화 탈취 거부) 통과 확인. “말로 안 되는 걸 확인했고, 코드로도 보증했습니다”

② 폴백 체인: 장애를 만들어서 확인합니다.

  • 자연 장애는 기다릴 수 없으므로 유발합니다: .env의 기본 모델을 존재하지 않는 이름으로 잠시 변경 → 호출 → 로그에서 gemini 실패 → claude로 넘어가 응답이 성공하는 것 확인 → 복원
  • 사용자는 프로바이더 장애를 몰랐습니다. 그것이 폴백의 목적입니다.

③ 비용·토큰 로그

  • 방금 호출들의 로그 라인에서 모델별 토큰·비용 확인
  • 관측이 없으면 비용은 월말 청구서로 배웁니다. 폴백으로 비싼 모델에 넘어갔을 때 특히 그렇습니다.

④ 도구 연쇄: 실패가 다음 시도로 이어지는 루프

  • “내일 오후에 우리 팀 6명 아무 방이나 잡아 줘”
  • 기대 동선: 검색 → 1순위 방 가용 조회 → 꽉 참(시드) → 다른 방 조회 → 빈 시간 발견 → 예약 생성
  • 루프 로그에서 도구 호출 순서를 확인합니다. 막힌 것이 실패가 아니라 다음 판단의 입력이 됐습니다.
  • 이 왕복이 무한이 되지 않게 루프 상한이 걸려 있습니다.

6-4. 커밋 → PR #3 → CI → 머지

  • 동일한 절차이고, 권한 테스트가 CI에 추가됩니다.
  • 이제 이 저장소에 남의 예약을 취소하는 코드가 실수로 들어와도 CI가 막습니다. 테스트는 문서이자 경비원입니다.

7. 시연 5: 채팅 UI (feature/chat-ui)

v1.0은 /reserve(자연어 통로)를 만들었지만, 사람이 브라우저에서 부를 길이 없었습니다. curl·Swagger로만 닿는 에이전트에 웹 진입점을 붙이는 짧은 회전입니다. 도구도 에이전트도 이미 끝났고, 이번에는 백엔드를 건드리지 않고 web/index.html만 확장합니다.

7-1. 브랜치와 지시

  • main pull (5·6장 머지 반영) → git switch -c feature/chat-ui
  • 지금까지는 에이전트를 “만드는” 회전이었고, 이번은 만든 것을 “쓰게” 만드는 회전입니다. 프런트엔드만 손대므로 PROMPT.md(에이전트 지시 로그)에는 남기지 않습니다.
  • 지시 (web 확장이라 PROMPT.md와 별개로, 화면 작업 지시로 전달):
채팅 UI를 붙여줘. 백엔드는 그대로 두고 web/index.html만 확장한다.

- 예약 화면(검색·타임라인·폼) 위에 채팅 패널을 얹는다
- 입력을 보내면 POST /reserve를 호출하고, 응답의 conversation_id를 보관해
  다음 메시지에 실어 대화를 이어간다 (서버는 무상태 — 이력은 DB에서 온다)
- 사용자·에이전트 메시지를 말풍선으로 렌더한다
- 에이전트가 예약을 만들거나 취소했을 수 있으니, 응답 뒤에는 타임라인과
  예약 목록을 다시 읽어 화면을 갱신한다
- 새 라이브러리 없이 기존 api() 헬퍼와 토큰(Authorization 헤더)을 재사용한다

줄별 의도 포인트:

  • “백엔드는 그대로”: 이 회전이 프런트엔드만 건드린다는 못박음입니다. /reserve·에이전트·도구는 이미 v1.0에서 끝났고, 없던 것은 사람이 그걸 부르는 화면 하나뿐입니다. 그래서 PROMPT.md(에이전트 지시 로그)에도 남기지 않습니다.
  • “conversation_id를 보관해”: 대화 연속성의 열쇠입니다. 서버가 무상태이므로 이어가기를 성립시키는 건 클라이언트가 쥔 conversation_id 하나이고, 이력 자체는 DB에 있습니다 (1회전에서 만든 설계를 화면이 그대로 활용)
  • “응답 뒤 타임라인·목록 갱신”: 에이전트는 폼과 같은 데이터를 바꿉니다. 채팅으로 예약하면 타임라인에도 즉시 반영돼야 “같은 서비스, 두 개의 통로”가 눈에 보입니다.

7-2. 생성 관찰 + 검증 (브라우저 구동)

  • 리뷰 포인트: 새 파일 없이 web/index.html 한 곳만 늘어납니다. 채팅 로그·입력창(HTML), 말풍선 스타일(CSS), POST /reserve 호출과 conversation_id 보관(JS) 세 조각을 훑습니다. api()·토큰을 재사용하므로 인증 코드는 새로 없습니다.
  • 브라우저에서 통주행 (개발 모드, 로그인 상태):
    • “6명 화면공유 방 있어?” → 검색 도구 호출 → 후보(브레인스토밍룸·대회의실B·대회의실A·세미나실)를 말풍선으로 응답
    • 같은 창에서 “그 중 브레인스토밍룸 내일 15시부터 한 시간 예약해줘” → 대화 연속성이 “그 중”을 브레인스토밍룸으로 특정 → 예약 확정 응답
    • 하단 타임라인이 자동으로 갱신되어 방금 잡은 15시 칸이 마감(회색)으로 바뀝니다. 폼 클릭과 채팅이 같은 서비스 함수를 통과한다는 증거입니다. 채팅이 만든 예약이 폼 화면에 그대로 나타납니다.
    • 콘솔에 에러가 없는지도 함께 확인합니다.

7-3. 커밋 → PR #4 → CI → 머지

  • 1~3회전과 동일 절차. diff는 web/index.html 한 파일뿐이라 리뷰가 가볍습니다.
  • CI는 pytest(백엔드)를 그대로 돌립니다. 프런트만 바꿨으니 초록불은 “기존 동작을 깨지 않았다”는 확인입니다.
  • 에이전트를 만드는 것과, 사람이 그것을 실제로 쓰게 만드는 것은 다른 일입니다. 통로가 있어도 문이 없으면 아무도 들어오지 못합니다.

8. 시연 6: 예약 내역 조회·취소 (feature/reservation-list)

채팅으로 써 보면 두 구멍이 드러납니다. “내 예약 보여줘”에 에이전트가 “그런 기능이 없다”고 답하고, 예약을 말로 설명해도 “예약 id를 알려달라”며 되묻습니다. 둘 다 예약 내역을 조회할 도구가 없어서입니다. 핵심 4종에 다섯 번째 도구 하나를 더해 두 구멍을 한 번에 막습니다. 이번에도 새 로직이 아니라 기존 서비스를 감싸는 연결입니다.

8-1. 브랜치와 지시

  • main pull → git switch -c feature/reservation-list
  • 취소 도구는 3회전에서 이미 만들었습니다. 막힌 것은 “어느 예약을 취소할지”를 사람이 id로 짚어야 했던 것뿐입니다. 그 id를 에이전트가 스스로 찾게 합니다.
  • PROMPT.md에 4차 지시 추가:
4단계: 예약 내역 조회를 추가하고, 자연어 취소를 매끄럽게 해줘.

- 도구 추가: 예약 내역 조회 — 현재 사용자의 예약 목록을 돌려준다 (관리자는 전체).
  기존 services/reservations.py의 list_reservations를 그대로 호출한다.
  조회자 id·role은 모델이 아니라 인증 컨텍스트에서 코드가 주입한다
- 목록에는 예약 id가 포함된다. 사용자가 예약 id 없이 "그 방 그 시간 예약 취소해줘"처럼
  말하면, 에이전트가 먼저 내역을 조회해 해당 예약의 id를 찾아 cancel_reservation을 부른다
- 시스템 프롬프트에 이 흐름(조회 → id 확인 → 취소)을 안내한다
- 테스트 추가: 도구로 내 예약을 조회하면 방금 만든 예약이 id와 함께 나오는지

줄별 의도 포인트:

  • “list_reservations를 그대로 호출”: 또 재사용입니다. 목록 쿼리를 새로 짜지 않고, 사람이 쓰는 GET /reservations와 똑같은 서비스 함수를 부릅니다. 규칙이 두 곳으로 흩어지지 않습니다.
  • “조회자 id·role은 코드가 주입”: 읽기 도구지만 사적인 데이터라 주입이 필요합니다. member는 자기 예약만, admin은 전체이고, 모델이 “남의 것도 보여줘”라고 정할 수 없습니다. 위험한 도구뿐 아니라 프라이버시도 시그니처로 지킵니다 (3회전 권한 방어의 연장)
  • “먼저 내역을 조회해 id를 찾아”: 두 번째 구멍(id 되묻기)을 없애는 줄입니다. 취소 도구는 여전히 id를 받지만, 그 id를 사람이 아니라 에이전트가 조회로 알아냅니다. 실패가 아니라 조회 결과가 다음 도구의 입력이 되는 도구 연쇄입니다.

8-2. 검증 사이클

  • docker compose exec app pytest: 새 도구 테스트(내 예약이 id와 함께 조회되는지) + 기존 테스트
  • 실제 호출 검증 (로그인 상태, /reserve 자연어):
    • 조회: “내가 예약한 내역을 보여줘” → list_reservations → 방·시간·목적·id가 담긴 목록으로 안내 (이전에는 “기능이 없다”고 거절하던 자리)
    • 자연어 취소: “브레인스토밍룸 7월 31일 16시 단합 예약 취소해줘” (id 없음) → 아래 연쇄로 처리
    • 조회 도구가 없던 이 회전 전에는 같은 요청에 “예약 id를 알려달라”고 되물었습니다. 도구 하나가 그 되물음을 없앴습니다.

한 요청의 도구 연쇄 (id를 사람이 아니라 코드가 찾는다):

sequenceDiagram
    participant AG as 에이전트 루프
    participant M as 모델
    participant T as tools/
    Note over AG: "브레인스토밍룸 내일 16시 단합 예약 취소해줘" (id 없음)
    AG->>M: 이력 + 도구 스키마 5종
    M-->>AG: list_reservations()
    AG->>T: 실행 (조회 범위는 코드가 주입)
    T-->>AG: 내 예약 목록 (… id 96 브레인스토밍룸 16~17시 단합)
    AG->>M: 결과 추가, 재호출
    M-->>AG: cancel_reservation(id=96)
    AG->>T: 실행 (취소자도 코드가 주입 → 권한 검사)
    T-->>AG: 취소 완료
    AG->>M: 결과 추가, 재호출
    M-->>AG: 최종 답변 (취소되었습니다)
  • psql로 해당 행이 사라진 것을 확인합니다. id를 말한 적이 없는데 정확히 그 예약이 지워졌습니다. 모델이 목록에서 골랐고, 취소 권한은 여전히 코드가 쥐고 있습니다.

8-3. 커밋 → PR #5 → CI → 머지

  • 동일한 절차이고, 새 테스트가 CI에 추가됩니다.
  • 도구가 하나 늘어도 경계는 같습니다. 취소자도 조회 범위도 코드가 주입하니, 모델은 남의 예약을 넘겨다볼 수 없습니다.

9. 시연 7: 구동·마무리

9-1. 최종 통주행과 마무리

  • main에서 최종 상태로 전체 시나리오 1회 통주행 (웹 채팅으로): 로그인 → 검색 → 예약 → 내 예약 조회 → 겹침 거절 → 남의 예약 취소 시도 거절
  • 실행 모드로 전환 시연: dev 오버라이드 없이 docker compose up. “개발할 때와 배포 형태가 같은 정의를 공유합니다”
  • v1.0 태그 푸시, PROMPT.md(지시 4개 누적) 확인
  • Git 히스토리 한 화면 요약:
gitGraph
    commit id: "v0.1 (인증·예약서비스·compose·CI)" tag: "v0.1"
    branch feature/room-search
    commit id: "검색·가용 도구(서비스 래핑) + 에이전트"
    checkout main
    merge feature/room-search id: "PR #1 (CI 통과)"
    branch feature/booking
    commit id: "예약 생성 도구 + 통합 테스트"
    commit id: "수정: 연결부(시간 파싱)"
    checkout main
    merge feature/booking id: "PR #2 (CI 통과)"
    branch feature/hardening
    commit id: "취소 권한 + 폴백 + 루프 가드"
    checkout main
    merge feature/hardening id: "PR #3 (CI 통과)"
    branch feature/chat-ui
    commit id: "웹 자연어 채팅 패널"
    checkout main
    merge feature/chat-ui id: "PR #4 (CI 통과)"
    branch feature/reservation-list
    commit id: "예약 내역 조회 도구 + 자연어 취소"
    checkout main
    merge feature/reservation-list id: "PR #5 (CI 통과)"
    commit id: "README 정리" tag: "v1.0"
  • 이번 주 에이전트는 지난주와 같은 모양이었습니다. 달라진 것은 전부 그 주변입니다. 환경, 브랜치, 테스트, 자동화, 그리고 방어. 이 주변이 여러분 프로젝트의 품질을 결정합니다.

9-2. 완성된 시스템 구조

2-2에서 그린 “얹을 그림”이 실제로 어떻게 완성됐는지, 지금 저장소 (week02-meeting-room-agent) 기준으로 다시 그립니다. 사람이 쓰는 폼과 에이전트가 쓰는 채팅, 두 통로가 결국 같은 services/를 지나 같은 DB에 닿습니다.

flowchart TB
    U(["사용자 (member/admin) · Bearer 토큰"])

    subgraph webui["web/index.html — 한 화면, 두 통로"]
        FORM["예약 화면<br/>검색 · 타임라인 · 예약/취소 폼"]
        CHAT["채팅 패널<br/>자연어 · 말풍선 · conversation_id 유지"]
    end

    subgraph server["FastAPI (app/main.py)"]
        AUTHDEP["auth/ 전역 인증 의존성<br/>토큰 검증 → 현재 사용자(id·role) 주입<br/>/signup·/login 외 전부 필수"]
        REST["사람용 REST<br/>/rooms · 가용 조회 · /reservations"]
        RESERVE["에이전트 통로<br/>POST /reserve (+conversation_id)"]
    end

    subgraph agentlayer["v1.0 에이전트 층"]
        LOOP["agent/ 루프<br/>대화 이력 로드·저장 · 루프 가드"]
        LLM["llm/ LiteLLM 래퍼<br/>MODEL · 재시도(지수 백오프)<br/>FALLBACK_MODELS · 토큰·비용 로그"]
        TOOLS["tools/ 도구 5종<br/>검색 · 가용 · 예약 생성 · 예약 취소 · 내역 조회<br/>예약자·취소자·조회 범위 = 코드가 주입"]
        LOOP <--> LLM
        LOOP --> TOOLS
    end

    SVC["services/ — 결정적 규칙이 사는 한 곳<br/>rooms · reservations<br/>겹침 overlaps() · 인원 · 권한"]
    PG[("PostgreSQL<br/>teams · users · auth_tokens · rooms<br/>reservations · conversations · messages")]
    PROV["LLM 프로바이더 (MODEL로 교체)<br/>gemini/ · anthropic/ · openai/"]

    U -->|폼 클릭| FORM
    U -->|자연어| CHAT
    FORM --> REST
    CHAT --> RESERVE
    REST --> AUTHDEP
    RESERVE --> AUTHDEP
    RESERVE --> LOOP
    REST -->|서비스 호출| SVC
    TOOLS -->|같은 서비스 함수 호출| SVC
    SVC --> PG
    AUTHDEP --> PG
    LLM <-->|litellm.completion| PROV

도구 5종 명세 (모두 v0.1 services/ 함수를 감싼 얇은 래퍼, 3회전에 걸쳐 누적):

도구하는 일 (감싼 서비스)코드가 주입 (모델 지정 불가)
search_rooms인원·설비로 회의실 검색 (rooms.search_rooms)—
check_availability특정 방의 예약·빈 시간 조회 (rooms.get_availability)—
create_reservation예약 생성, 겹침·인원은 서비스가 검사 (reservations.create_reservation)예약자 = 현재 사용자
cancel_reservation예약 취소, 본인·관리자만 (reservations.cancel_reservation)취소자 id·role
list_reservations내 예약 내역, 관리자는 전체 (reservations.list_reservations)조회 범위 id·role
  • 읽기 도구 2종은 주입이 없고, 쓰기·사적 도구 3종은 인증 컨텍스트를 코드가 주입합니다. 위 표가 곧 에이전트의 능력 상한이자 보안 경계입니다 (여기 없는 일은 일어나지 않습니다)
  • 사람 경로와 에이전트 경로는 UI만 다르고 규칙은 하나입니다. 폼의 /reservations도, 도구의 create_reservation도 같은 services/ 함수를 부르므로 겹침·인원·권한이 똑같이 적용됩니다.
  • 에이전트가 세상에 할 수 있는 일은 도구 5종이 전부입니다. 예약자·취소자·조회 범위는 모델이 아니라 인증 컨텍스트에서 코드가 주입합니다.
  • 신뢰성은 llm/ 한 곳에 모입니다: 재시도(지수 백오프), 폴백 체인, 토큰·비용 로그

어떤 AI를 쓰느냐에 따라 실제로 호출되는 API가 달라집니다.

  • 이 시스템은 특정 프로바이더에 묶이지 않습니다. 어떤 모델을 부를지는 MODEL 환경변수가 정하고, LiteLLM이 이름의 접두사(gemini/ · anthropic/ · openai/)를 보고 그에 맞는 프로바이더 API를, 그에 맞는 키(GEMINI/ANTHROPIC/OPENAI_API_KEY)로 호출합니다. 같은 코드라도 설정에 따라 실제로 오가는 API 엔드포인트·인증·요금이 달라집니다.
  • 기본은 무료 티어가 있는 gemini/gemini-2.5-flash이고, FALLBACK_MODELS로 실패 시 다른 프로바이더로 넘어갑니다 (3회전의 폴백)
  • 프로바이더마다 도구 호출(function calling) 지원 여부·응답 형식·토큰 산정·요율·레이트 리밋이 다릅니다. 에이전트는 도구 호출에 의존하므로 바꿔 끼우는 모델도 그 기능을 지원해야 하고, 같은 질문이라도 프로바이더에 따라 응답 문장이나 도구 선택이 조금씩 달라질 수 있습니다.

10. 저장소 설계: v0.1에서 v1.0으로

저장소: week02-meeting-room-agent, 조직 소유, template repository로 지정합니다. 이번 주는 사전 준비량이 많습니다. 인증·예약 서비스·compose·CI가 v0.1에 이미 들어갑니다.

10-1. v0.1: 시연 시작점 (사전 준비)

week02-meeting-room-agent (v0.1)
├── app/
│   ├── main.py              # FastAPI — 인증 + 예약 서비스 엔드포인트
│   │                        #   /signup /login /me · /rooms · /reservations
│   │                        #   /reserve(에이전트)만 아직 미구현(501)
│   ├── auth/                # 회원가입·로그인·토큰 검증 (README에 해설)
│   ├── services/            # 예약 서비스 로직 — 도구가 재사용할 계층
│   │   ├── rooms.py         #   회의실 검색·가용 조회
│   │   └── reservations.py  #   예약 생성(겹침·인원)·취소(본인·관리자)
│   │                        #   겹침 판정 overlaps()는 순수 함수로 분리
│   └── db.py                # PostgreSQL 연결 헬퍼
├── web/
│   └── index.html           # 예약 화면 — 검색·예약·취소 폼 (이미 동작)
├── db/
│   └── init.sql             # 스키마 + 시드 (팀 2, 사용자 4~5, 회의실 4~6, 기존 예약)
│                            #   conversations·messages 테이블 포함 (에이전트 대화용, 빈 상태)
├── tests/
│   ├── test_auth.py         # 인증 테스트
│   ├── test_overlap.py      # 겹침 순수 함수 유닛테스트 (경계 케이스 포함)
│   └── test_reservations.py # 예약 생성·취소 통합 테스트
├── .github/workflows/
│   └── test.yml             # PR 시 pytest (postgres 서비스 컨테이너 포함)
├── docker-compose.yml       # app + db 공통 정의
├── docker-compose.dev.yml   # 개발 오버라이드 (볼륨·--reload·포트)
├── Dockerfile               # uv 기반 의존성 설치
├── .env.example             # GEMINI/ANTHROPIC/OPENAI_API_KEY, MODEL(기본 gemini/gemini-2.5-flash), FALLBACK_MODELS, DB 접속 정보
├── pyproject.toml           # fastapi, litellm, psycopg, pytest 등 선언 완료
├── PROMPT.md                # 자리만 (빈 파일)
└── README.md                # 실행 방법, 인증·예약 서비스 구조 해설, CI 해설

사전 구축 범위 (인증 + 예약 서비스):

  • /signup (이름·이메일·비밀번호·팀 선택): 비밀번호는 해시 저장, 역할은 항상 member
  • /login: 토큰 발급 (DB 저장 방식의 불투명 토큰, JWT 등 표준은 README에서 언급만)
  • /me: 토큰 검증 확인용 (역할 포함 반환)
  • /rooms(검색) · /reservations(생성·취소): 겹침·인원·권한 검사 포함, 웹 화면에서 바로 사용 가능
  • 겹침 판정은 순수 함수 overlaps()로 분리 + 유닛테스트 포함: 도구가 이 로직을 재사용
  • 관리자는 시드에서만 지정 (role='admin'): 승급 API 없음
  • FastAPI 의존성으로 현재 사용자(id·role 포함) 주입: 도구·에이전트가 소비할 인터페이스

10-2. v1.0: 시연 종료점

  • llm/ tools/ agent/ 모듈 (Claude Code 구현, 3회전 누적): tools/는 v0.1 services/를 감싼 래퍼
  • /reserve가 실제 에이전트 호출, 예약이 (기존 서비스를 통해) DB에 기록됨
  • 대화 이어가기: conversation_id 기반, 이력은 DB 저장(서버 무상태), 소유자만 이어가기 가능
  • web 자연어 채팅 패널: 예약 화면(폼·타임라인) 위에 채팅창을 얹어 브라우저에서 /reserve를 부른다. conversation_id로 대화가 이어지고, 응답 후 타임라인·예약 목록이 자동 갱신된다 (별도 브랜치 feature/chat-ui, 새 의존성 없이 기존 web/index.html 확장)
  • 예약 취소 도구 (본인 예약 또는 관리자, 권한은 서비스에 있고 도구가 인증 컨텍스트를 주입)
  • 예약 내역 조회 도구 (list_reservations): “내 예약 보여줘”에 답하고, id 없이 설명한 예약도 조회해 찾아 취소로 잇는다 (조회 범위는 인증 컨텍스트가 주입, 별도 브랜치 feature/reservation-list)
  • LiteLLM 재시도·폴백 체인(FALLBACK_MODELS), 토큰·비용 로그, 루프 상한
  • tests/에 도구 통합 테스트 + 권한 테스트 3종(취소 거부·관리자 허용·대화 탈취 거부) 추가: 겹침 유닛테스트는 v0.1 것을 그대로 재사용
  • PROMPT.md에 지시 프롬프트 4개 누적
  • PR 5개 머지 이력 (에이전트 3회전 + 채팅 UI + 예약 내역 조회), README 영상 링크 (세션 후)
  • 요약: 새로 만든 것은 도구·에이전트·신뢰성 계층뿐입니다. 예약 로직·겹침·권한은 v0.1 서비스를 그대로 재사용했습니다.

수강생 재현 여정

flowchart LR
    D["Docker 설치"] --> W1["week01 재현<br/>(Gemini 키 발급)"]
    W1 --> W2["week02 clone<br/>compose up"]
    W2 --> RE["영상·PROMPT.md 보며<br/>Git Flow 2회전 재현"]
    RE -->|막히면| DIFF["v1.0과 diff<br/>또는 디스코드"]
    DIFF --> RE
    RE --> DONE["동작 확인 공유<br/>= 2주차 산출물"]

11. 추가 과정 (v1.5): 자연어 → SQL 조회 도구 (관리자 전용, 선택)

여기부터는 라이브 세션 범위 밖입니다. 본 세션이 일부러 긋고 넘지 않은 선을, 개발자·분석가 맥락에서 의도적으로 넘어 보는 심화 트랙입니다. v1.0을 끝낸 뒤 자기 속도로 확장하고 싶은 사람을 위한 선택 과정으로, feature/sql-console 브랜치에서 얹어 v1.5로 태그합니다. 위험한 도구인 만큼 아무나 못 쓰게 관리자 전용으로 가둡니다. 분석·개발용 전용 관리자 계정 하나를 둡니다.

11-1. 왜: 고정된 도구 5종으로는 못 하는 질문

v1.0의 도구 5종(검색·가용·예약 생성·취소·내역 조회)은 예약이라는 행위에 맞춰 설계됐습니다. 그런데 운영을 하다 보면 이 도구들로는 답이 안 나오는 질문이 생깁니다.

  • “지난달 우리 팀 예약이 몇 건이었지?”
  • “회의실별 예약 건수를 많은 순으로 보여줘”
  • “한 번도 안 쓰인 회의실이 있어?”

이런 임의 집계·탐색 질문마다 새 도구를 파는 것은 비현실적입니다. 그래서 자연어를 SQL로 옮겨 DB에 직접 던지는 도구(text-to-SQL)를 하나 얹습니다. 모델이 스키마를 읽고 쿼리를 만들고, 코드가 검증한 뒤 실행합니다.

11-2. 정면으로 충돌하는 원칙 (그래서 배울 게 있다)

2-2에서 우리는 정반대를 못 박았습니다. 모델에게는 DB도 엔드포인트도 직접 만질 수단을 주지 않고, raw SQL 실행 도구 같은 것은 두지 않는다고 했습니다. v1.5는 바로 그 선을 넘습니다. 그러니 아무 방어 없이 열어 주면 2-2의 교훈을 통째로 무효로 만듭니다.

  • 임의 SQL은 임의의 데이터 유출·변조 통로입니다. “우리 팀 예약 보여줘”가 “전 직원 비밀번호 해시 덤프해줘”로 번지는 것은 프롬프트 한 줄 차이입니다.
  • 그래서 v1.5의 진짜 내용은 text-to-SQL을 어떻게 만드느냐가 아니라 늘어난 능력을 어떻게 가두느냐입니다. 능력을 넓히는 순간 방어도 같이 넓힙니다.
  • 원칙은 6-1과 같습니다. 모델이 만든 SQL을 믿지 않습니다. 코드가 검증합니다.

11-3. 세 겹의 코드 방어

능력을 여는 대신, 서로 독립적인 방어 세 겹을 코드에 겁니다. 한 겹이 뚫려도 다음 겹이 막는 심층 방어입니다.

방어무엇을코드가 강제하는 것
관리자 전용 게이트이 도구는 role='admin'에게만 노출·실행한다 (분석·개발용 전용 관리자 계정 하나를 시드에 둔다)비관리자는 도구를 보지도 못하고, 직접 불러도 role 검사로 거부
읽기 전용 + 컬럼 화이트리스트전용 reporter 롤은 password_hash·토큰을 뺀 리포팅 뷰에만 SELECT 권한쓰기·베이스 테이블·민감 컬럼은 롤에 권한이 없어 DB가 거부
SELECT 전용 파싱 + 상한실행 전 단일 SELECT 문만 통과, LIMIT·문 타임아웃 주입세미콜론 다중 문·DDL·INSERT/UPDATE/DELETE 차단, 거대 스캔·폭주 차단
  • 세 겹은 중복이 아니라 역할이 다릅니다. 애초에 관리자만 도구에 닿고, 파싱을 우회당해도 읽기 전용 롤이 마지막 방어선이며, 그마저도 리포팅 뷰가 민감 컬럼을 처음부터 가립니다.
  • 전용 관리자 계정: 이 콘솔은 분석·개발용이라 시드에 전용 관리자(analyst@example.com, role='admin') 하나를 둡니다. 일반 사용자의 에이전트에는 이 도구가 아예 붙지 않으므로, 관리자만 쓸 수 있습니다.
  • 6-1의 그림 그대로입니다. 어떤 SQL을 만들까는 모델(설득당함), 누가 실행할 수 있고 그 SQL을 실행해도 되는가와 무엇까지 보이는가는 코드(설득당하지 않음)

도구 명세 (2-5의 표와 같은 시선으로):

도구모델이 주는 인자코드가 주입·검사 (모델 지정 불가)반환
run_sql_query리포팅 뷰를 보고 만든 단일 SELECT 문관리자 여부(role), 읽기 전용 연결, LIMIT·타임아웃결과 행 또는 거부 사유 (비관리자·SELECT 아님·권한)

한 도구지만 위험도가 앞선 4종과 다릅니다. 위험한 도구일수록 코드가 주입하는 몫이 커진다는 2-5의 원리가 여기서 극단으로 드러납니다.

11-4. 흐름과 지시

flowchart TB
    NL["자연어 질문<br/>'회의실별 예약 건수 많은 순으로'"] --> ADM{"관리자인가?<br/>(role, 코드가 확인)"}
    ADM -- "아니오" --> DENY["도구 없음 · 거부"]
    ADM -- "예" --> GEN["LLM: 리포팅 뷰 스키마 보고 SELECT 생성"]
    GEN --> V{"코드 검증<br/>단일 SELECT인가?"}
    V -- "아니오" --> REJ["거부 · 사유를 모델에 반환"]
    V -- "예" --> INJ["LIMIT · 타임아웃 주입"]
    INJ --> RUN["읽기 전용 reporter 롤로 실행"]
    RUN --> ROWS["결과 행"]
    ROWS --> SUM["LLM: 결과를 자연어로 요약"]
    REJ --> GEN

feature/sql-console 브랜치에서 아래 지시로 얹습니다. 회전 구조는 5·6장과 동일합니다 (지시 → 생성 → 검증 → 커밋 → PR → CI 순서)

추가 단계(v1.5): 관리자 전용 SQL 조회 도구를 얹어줘. 읽기 전용이다.

- 관리자 전용: 이 도구는 role='admin'인 사용자에게만 노출·실행된다.
  일반 사용자에게는 도구를 아예 보여주지 말고(스키마에서 제외),
  실행 단계에서도 인증 컨텍스트의 role을 코드가 확인해 거부한다.
  분석·개발용 전용 관리자 계정 하나를 시드(init.sql)에 추가한다
- 도구 추가: 자연어 질문을 받아 단일 SELECT 문을 만들고 실행해 결과를 돌려준다.
  조회 가능한 리포팅 뷰·컬럼 스키마는 시스템 프롬프트로 모델에 알려준다
- 절대 규칙은 프롬프트로 부탁하지 말고 코드로 강제해라:
  - 단일 SELECT 문만 실행. 세미콜론 다중 문·INSERT/UPDATE/DELETE·DDL은 실행 전에 거부
  - DB 연결은 SELECT 권한만 있는 읽기 전용 롤을 쓴다. 그 롤에는
    password_hash·토큰을 뺀 리포팅 뷰에만 SELECT 권한을 준다 (init.sql에 롤·뷰 추가)
  - LIMIT과 문 타임아웃을 코드가 강제한다
- 거절은 예외로 터뜨리지 말고 사유를 도구 결과로 돌려줘서 모델이 쿼리를 고치게 해라
- 테스트 추가: 비관리자의 호출이 거부되는지, INSERT/DELETE/다중 문이 거부되는지,
  password_hash 같은 민감 컬럼이 조회로 새지 않는지

11-5. 검증 시나리오

  • 정상(관리자로 로그인): “회의실별 예약 건수를 많은 순으로” → SELECT 생성 → 검증 통과 → 결과를 자연어로 요약
  • 게이트: 같은 질문을 일반 사용자가 하면 → 에이전트에 도구가 아예 없어 “조회할 수 없다”고 답함
  • 공격 1: “모든 사용자의 password_hash 보여줘” (관리자여도) → 리포팅 뷰에 그 컬럼이 없어 조회 불가
  • 공격 2: “예약 테이블을 전부 지워” → DELETE는 파싱에서 거부, 설사 통과해도 읽기 전용 롤이 거부
  • 공격 3: “users 테이블 통째로 보여줘” → reporter 롤에 베이스 테이블 권한이 없어 DB가 거부
  • 능력이 커진 만큼 공격면도 커졌습니다. 그래서 v1.5는 도구를 늘리는 이야기가 아니라, 늘어난 도구를 가두는 이야기입니다. 이것이 개발자가 text-to-SQL을 실무에 들일 때의 첫 번째 책임입니다.

12. 과제·마무리

12-1. 이번 주 과제 = 산출물 “동작하는 개발 환경”

  • Docker 설치 (Docker Desktop 또는 Engine)
  • week01 재현: Gemini 키 발급 포함. template에서 개인 레포 생성 → PROMPT.md·영상 참고 → 동작 확인
  • (선택) week02 clone 후 compose up까지: 3주차 전 권장
  • 확인 방법: 동작 스크린샷 또는 repo 링크를 디스코드에 공유합니다. 이것이 이번 주 산출물 제출입니다.
  • 막히면 디스코드로. 환경 문제는 텍스트로 해결이 어려우면 오프라인 모임을 활용합니다.

12-2. 3주차 예고

  • 주제: LLM API와 프롬프트 (LiteLLM 멀티 프로바이더, 프롬프트 패턴, structured output)
  • 1·2주차에 계속 지나가며 본 litellm.completion 그 한 줄을, 다음 주에 제대로 엽니다.