헤르메스 에이전트로 아이돌 굿즈 판매 플랫폼 개발하기

게시 2026/06/17

By BLUEBUG

57 분읽는 시간

기획, 설계부터 개발, 테스트, 운영 이관 및 자율 운영까지

이 문서는 Hermes Agent를 활용해 실제 서비스를 처음부터 끝까지 만드는 전체 흐름을 다룬다. 예시 서비스는 “팬픽(FanPick)”이라는 이름의 가상 아이돌 굿즈 전문 판매 플랫폼이다. 기획 단계부터 자율 운영까지, 사람과 에이전트가 어떻게 역할을 나누고 협력하는지를 구체적으로 풀어낸다.

헤르메스 에이전트로 책 한 권을 쓰다: 설치부터 자율 집필까지

0. 들어가며: 왜 헤르메스 에이전트로 만드는가

소프트웨어 개발에 헤르메스 에이전트를 투입한다는 것은 단순히 AI 도구를 하나 더 쓰는 것과 다르다. 헤르메스는 세션이 끊겨도 기억이 유지되고, 경험에서 스킬을 생성하며, 크론(cron) 자동화와 칸반(kanban) 기반 작업 위임을 통해 사람 없이도 일정 범위의 작업을 스스로 진행할 수 있는 장기 실행형 자율 에이전트다.

이 특성은 소프트웨어 개발의 전 주기에 걸쳐 강점을 발휘한다. 기획 단계에서는 위키 기반 요구사항 정제를, 설계 단계에서는 아키텍처 문서 생성과 검토를, 개발 단계에서는 역할별 에이전트의 병렬 구현을, 테스트 단계에서는 자동화 QA와 버그 리포트를, 운영 단계에서는 24시간 무인 모니터링과 자기 치유(self-healing)를 담당한다.

아이돌 굿즈 플랫폼이 예시 서비스로 좋은 이유도 있다. 예약 판매, 한정 수량, 글로벌 팬덤 대응, 콘서트 시즌 트래픽 급증, 재고 자동 알림 등 K-POP 팬 커뮤니티 특유의 복잡한 비즈니스 로직이 가득하다. 이 복잡성을 에이전트 팀이 어떻게 처리하는지를 보면, 다른 도메인으로의 응용도 자연스럽게 떠오른다.

timeline
    title 팬픽(FanPick) 개발 전체 타임라인
    0주차 : 환경 구성
           : 헤르메스 팀 셋업
    1~2주차 : 기획 단계
             : LLM WIKI 구성
             : 요구사항 정의
    3~4주차 : 설계 단계
             : 시스템 아키텍처
             : DB · API 설계
    5~9주차 : 개발 단계
             : 멀티에이전트 구현
             : 칸반 기반 협업
    10~11주차 : 테스트 단계
               : 자동화 QA
               : 버그 수정
    12주차 : 운영 이관
            : 자율 운영 전환
    12주차~ : 자율 운영
             : 크론 자동화
             : 자기 진화

1. 서비스 정의: 팬픽(FanPick)이란

1-1. 서비스 개요

팬픽(FanPick)은 K-POP 아이돌 공식·비공식 굿즈를 전문으로 판매하는 웹/앱 플랫폼이다. 일반 이커머스와 달리 아이돌 굿즈 시장의 특성, 즉 한정 수량 예약 판매, 랜덤 상품(포토카드 랜덤 포함), 콘서트 및 팬미팅 연동 MD, 글로벌 팬 대응, 응원 기능 등을 플랫폼 핵심 기능으로 구현한다.

1-2. 주요 굿즈 카테고리

국내 실제 운영 중인 아이돌 굿즈 전문 플랫폼(에버라인, 팬텀픽, 아이돌스토어 등)을 참고하면, 주요 상품군은 앨범 및 포토북, 포토카드(포카), 아크릴 키링, 응원봉, 스티커 팩, 트레이딩 카드, 포토 슬로건, 핀버튼 세트, 엽서 세트, 시즌 그리팅 상품으로 구성된다.

1-3. 핵심 비즈니스 요구사항

요구사항	설명	난이도
예약 판매	판매 시작/종료 일시 설정, 구매 수량 제한	중
한정 수량	재고 소진 시 자동 품절 처리, 대기열 관리	고
랜덤 상품	포토카드 랜덤 포함 상품 처리, 결과 안내	중
글로벌 배송	다국어, 다통화, 국제 배송비 계산	고
트래픽 급증	콘서트 MD 오픈 시 동시 접속 폭증 대응	고
팬 커뮤니티	구매자 인증 후 후기, 인증샷 업로드	중
알림 시스템	판매 시작·마감 전 푸시/문자/이메일 알림	중
관리자 대시보드	재고·주문·정산·통계 통합 관리	중

2. 헤르메스 에이전트 팀 구성

2-1. 역할 설계 원칙

헤르메스 에이전트의 역할 분리는 “만능 비서 한 명”이 아닌 “전문가 팀”을 구성하는 방향으로 설계한다. 헤르메스에서 역할을 나눈다는 것은 두 층으로 작동한다. 하나는 어떤 역할이 필요한가(역할형 에이전트 정의)이고, 다른 하나는 그 역할을 어떤 방식으로 실행시킬 것인가(profile 직접 호출, delegation, subagent, cron)다.

각 에이전트는 SOUL.md 파일로 성격과 역할을, AGENTS.md 파일로 프로젝트 지침을 정의받는다. 이때 두 파일 모두 가능한 짧게 유지한다. “절대 하지 말 것” 몇 가지와 역할의 핵심만 담는 것이 문서가 길어져 컨텍스트가 오염되는 것보다 실제 성능이 좋다.

2-2. 팬픽 개발팀 에이전트 구성

graph TB
    HUMAN[사람\n프로덕트 오너\n최종 의사결정자]
    
    subgraph "오케스트레이션 레이어"
        PM[PM 에이전트\n기획·일정·우선순위 조율\nprofile: planner]
    end
    
    subgraph "개발 레이어"
        ARCH[설계 에이전트\n아키텍처·DB·API 설계\nprofile: architect]
        BE[백엔드 에이전트\nAPI 서버 구현\nprofile: backend]
        FE[프론트엔드 에이전트\nUI/UX 구현\nprofile: frontend]
        DATA[데이터 에이전트\nDB 마이그레이션·쿼리 최적화\nprofile: data]
    end
    
    subgraph "품질·운영 레이어"
        QA[QA 에이전트\n테스트 작성·실행·버그 리포트\nprofile: qa]
        OPS[운영 에이전트\n배포·모니터링·인시던트 대응\nprofile: ops]
        CS[CS 에이전트\n고객 문의 1차 응대·분류\nprofile: cs]
    end
    
    HUMAN <-->|"목표 설정\n결과 검토"| PM
    PM -->|"작업 위임 (delegation)"| ARCH
    PM -->|"작업 위임"| BE
    PM -->|"작업 위임"| FE
    PM -->|"작업 위임"| QA
    PM -->|"작업 위임"| OPS
    ARCH -->|"설계 문서 제공"| BE
    ARCH -->|"설계 문서 제공"| FE
    ARCH -->|"설계 문서 제공"| DATA
    BE <-->|"API 명세 공유"| FE
    QA -->|"버그 리포트"| BE
    QA -->|"버그 리포트"| FE
    OPS -->|"운영 이슈 전달"| PM
    CS -->|"CS 패턴 리포트"| PM
    
    KANBAN[(칸반 보드\n작업 상태 관리)]
    PM <--> KANBAN
    BE <--> KANBAN
    FE <--> KANBAN
    QA <--> KANBAN

2-3. 에이전트별 SOUL.md 설계 예시

각 에이전트의 SOUL.md는 역할의 본질만 간결하게 담는다. 아래는 백엔드 에이전트와 QA 에이전트의 예시다.

백엔드 에이전트 (backend.md):

역할: 팬픽 서비스의 API 서버를 구현한다.
스택: FastAPI (Python), PostgreSQL, Redis, Celery
절대 하지 말 것:
  - DB 스키마를 설계 에이전트 승인 없이 변경하지 않는다
  - 결제 관련 코드를 단독으로 프로덕션에 배포하지 않는다
  - 테스트 없이 PR을 생성하지 않는다
완료 기준: 모든 엔드포인트에 단위 테스트 존재, API 문서(OpenAPI) 자동 생성 확인

QA 에이전트 (qa.md):

역할: 팬픽 서비스의 품질을 책임진다.
절대 하지 말 것:
  - 버그를 발견하면 즉시 수정하려 하지 않는다 (리포트만 한다)
  - 기능 테스트 전에 단위 테스트를 건너뛰지 않는다
완료 기준: 신규 기능 테스트 커버리지 80% 이상, 회귀 테스트 통과

2-4. 칸반 보드 구조

헤르메스의 칸반 기능은 에이전트와 사람이 함께 공유하는 영속 작업 큐다. 작업 카드의 상태 변화와 완료·차단 이벤트가 텔레그램으로 자동 알림된다.

kanban
  column0[📋 Backlog]
    task0[글로벌 배송비 계산 API]
    task1[CS 채팅 기능]
    task2[통계 대시보드]
    task3[포인트/리워드 시스템]
  column1[🔍 In Progress]
    task4[예약 판매 타이머 UI - assignee: 프론트]
    task5[재고 알림 Celery 태스크 - assignee: 백엔드]
    task6[결제 플로우 E2E 테스트 - assignee: QA]
  column2[👀 Review]
    task7[상품 상세 API v2 - assignee: 설계]
    task8[포토카드 랜덤 로직 - assignee: PM]
  column3[✅ Done]
    task9[회원 가입·로그인 API]
    task10[상품 목록·검색 API]
    task11[장바구니 기능]

3. 기획 단계: LLM WIKI와 요구사항 정제

3-1. 왜 LLM WIKI부터 시작하는가

헤르메스 에이전트가 책 한 권을 자율적으로 쓸 수 있었던 것은 에이전트가 뛰어나서가 아니라 55개의 위키 문서라는 지식 베이스가 있었기 때문이다. 소프트웨어 개발도 같다. 에이전트가 “좋은 결정”을 내리려면, 그 결정을 뒷받침할 도메인 지식과 컨텍스트가 위키에 미리 축적되어 있어야 한다.

기획 단계에서 LLM WIKI에 담아야 할 내용은 세 가지 범주로 나뉜다. 첫째는 도메인 지식, 즉 K-POP 굿즈 시장의 구조, 주요 플랫폼 사례, 팬덤 구매 패턴, 예약 판매 관행 등이다. 둘째는 기술 레퍼런스, 즉 선택한 기술 스택의 공식 문서 요약, 유사 서비스 아키텍처 분석 결과, 결제 연동 가이드 등이다. 셋째는 팀 컨텍스트, 즉 이 프로젝트의 목표, 제약 조건, 비기능 요구사항, 팀 결정 사항 등이다.

3-2. 기획 에이전트의 역할과 작동 방식

PM 에이전트는 위키를 읽고 다음 순서로 기획 문서를 작성한다.

sequenceDiagram
    participant H as 사람 (PO)
    participant PM as PM 에이전트
    participant WIKI as LLM WIKI
    participant KB as 칸반 보드

    H->>WIKI: 도메인 자료 URL 투입 (경쟁사 분석, 시장 리포트 등)
    WIKI->>WIKI: Ingest → Summarize → Link : 문서 간 연결 자동 생성
    H->>PM: "팬픽 서비스 기획서 작성해줘 : 위키 참조하고 먼저 목차 잡아"
    PM->>WIKI: 위키 문서 전체 탐색
    PM->>PM: 서비스 구조 파악 - 핵심 기능 도출
    PM->>H: 기획서 목차 초안 제시
    H->>PM: 피드백 전달 ("글로벌 배송 기능 추가")
    PM->>WIKI: 글로벌 배송 관련 문서 추가 탐색
    PM->>PM: 기획서 본문 작성
    PM->>H: 완성 기획서 제출
    H->>PM: 승인 / 추가 수정 요청
    PM->>KB: 기획서 기반 에픽·스토리 카드 생성

3-3. 주요 사용자 스토리 도출

PM 에이전트가 위키 기반으로 도출하는 핵심 사용자 스토리는 다음과 같다.

팬(구매자) 관점:

아티스트별로 굿즈를 탐색하고, 원하는 상품을 장바구니에 담아 결제할 수 있다.
예약 판매 시작 전에 알림을 신청해, 판매 시작 시 즉시 알림을 받을 수 있다.
한정 수량 상품이 품절됐을 때 대기 등록을 하고, 재입고 시 알림을 받을 수 있다.
포토카드 랜덤 포함 상품을 구매하고, 발송 후 어떤 포카를 받게 되는지 확인할 수 있다.
해외 팬도 자국 통화로 가격을 확인하고 국제 배송으로 구매할 수 있다.
구매 인증 후 상품 후기와 인증샷을 업로드할 수 있다.

운영자 관점:

상품을 등록하고, 예약 판매 일정을 설정하며, 재고를 관리할 수 있다.
주문 현황과 배송 상태를 한 화면에서 모니터링하고, 이슈 주문을 처리할 수 있다.
아티스트별·기간별 매출과 인기 상품 통계를 확인할 수 있다.
CS 문의에 빠르게 대응하고, 환불·교환 처리를 진행할 수 있다.

3-4. 기획 단계 산출물

PM 에이전트가 기획 단계를 마치면 다음 파일들이 LLM WIKI와 Git 저장소에 저장된다.

docs/
├── PRD.md               # 제품 요구사항 문서 (Product Requirements Document)
├── USER_STORIES.md      # 에픽 및 사용자 스토리 목록
├── COMPETITOR_ANALYSIS.md  # 경쟁사 분석 (에버라인, 팬텀픽, 위드뮤 등)
├── BUSINESS_RULES.md    # 예약 판매, 랜덤 상품 등 비즈니스 로직 규칙
└── GLOSSARY.md          # 도메인 용어 정의 (포카, 시즌그리팅, MD 등)

4. 설계 단계: 아키텍처, DB, API 설계

4-1. 설계 에이전트의 역할

설계 에이전트(architect)는 기획서와 사용자 스토리를 입력으로 받아, 시스템 전체의 기술적 청사진을 만든다. 이 단계에서 내린 결정들은 이후 모든 개발 에이전트의 행동을 제약하고 안내하는 가이드가 된다.

설계 에이전트가 먼저 시작하는 것은 핵심 제약 조건 파악이다. 트래픽이 얼마나 올 수 있는가(콘서트 MD 오픈 시 급증), 데이터가 얼마나 민감한가(결제 정보), 글로벌 서비스를 고려해야 하는가, 팀(에이전트)의 기술 스택은 무엇인가. 이 제약들이 아키텍처 선택을 결정한다.

4-2. 시스템 아키텍처

graph TB
    subgraph "클라이언트 레이어"
        WEB[웹 앱\nNext.js]
        APP[모바일 앱\nReact Native]
    end

    subgraph "CDN / 엣지"
        CDN[Cloudflare CDN\n정적 자산 · 엣지 캐시]
    end

    subgraph "API 게이트웨이"
        GW[API Gateway\n인증 · 라우팅 · Rate Limit]
    end

    subgraph "마이크로서비스"
        AUTH[Auth Service\n회원·인증·세션]
        PRODUCT[Product Service\n상품·재고·카탈로그]
        ORDER[Order Service\n주문·결제·환불]
        NOTIFY[Notification Service\n푸시·이메일·SMS]
        CS_SVC[CS Service\n문의·티켓 관리]
    end

    subgraph "비동기 처리"
        QUEUE[Celery\n+ Redis Queue]
        WORKER[Worker\n재고 알림\n이메일 발송\n배송 추적]
    end

    subgraph "데이터 레이어"
        PG[(PostgreSQL\n주 데이터베이스)]
        REDIS[(Redis\n세션·캐시·큐)]
        S3[(S3\n상품 이미지\n포카 결과)]
        ES[(Elasticsearch\n상품 검색)]
    end

    subgraph "헤르메스 자율 운영 레이어"
        HERMES_OPS[운영 에이전트\n24h 모니터링]
        HERMES_CS[CS 에이전트\n문의 1차 응대]
        CRON[크론 태스크\n재고 체크·리포트·알림]
    end

    WEB & APP --> CDN --> GW
    GW --> AUTH & PRODUCT & ORDER & NOTIFY & CS_SVC
    ORDER --> QUEUE --> WORKER
    PRODUCT --> PG & REDIS & S3 & ES
    ORDER --> PG & REDIS
    AUTH --> PG & REDIS
    HERMES_OPS -.->|"모니터링·인시던트"| GW
    HERMES_CS -.->|"CS 자동 응대"| CS_SVC
    CRON -.->|"스케줄 실행"| NOTIFY & PRODUCT

4-3. 데이터베이스 스키마 설계 (핵심 테이블)

설계 에이전트는 PRD와 비즈니스 규칙 문서를 읽고 핵심 테이블을 설계한다.

erDiagram
    ARTIST {
        uuid id PK
        string name
        string name_en
        string agency
        string debut_date
        string profile_image_url
        timestamp created_at
    }

    PRODUCT {
        uuid id PK
        uuid artist_id FK
        string name
        string type "album|photocard|keyring|lightstick|sticker|etc"
        decimal price
        string currency "KRW|USD|JPY"
        int stock_quantity
        int purchase_limit_per_user
        boolean is_random "랜덤 포카 포함 여부"
        timestamp sale_start_at
        timestamp sale_end_at
        string status "draft|scheduled|on_sale|sold_out|ended"
        timestamp created_at
    }

    PRODUCT_VARIANT {
        uuid id PK
        uuid product_id FK
        string variant_name "버전A|버전B|랜덤"
        int stock_quantity
        string image_url
    }

    USER {
        uuid id PK
        string email
        string nickname
        string country_code
        string preferred_currency
        string phone
        boolean is_verified_fan
        timestamp created_at
    }

    ORDER {
        uuid id PK
        uuid user_id FK
        string order_number
        decimal total_amount
        string currency
        string status "pending|paid|preparing|shipped|delivered|cancelled|refunded"
        string payment_method
        string payment_id
        timestamp ordered_at
        timestamp paid_at
    }

    ORDER_ITEM {
        uuid id PK
        uuid order_id FK
        uuid product_id FK
        uuid variant_id FK
        int quantity
        decimal unit_price
        string random_result "랜덤 포카 결과 (nullable)"
    }

    SHIPPING {
        uuid id PK
        uuid order_id FK
        string recipient_name
        string country_code
        string address
        string tracking_number
        string carrier
        string status "pending|shipped|in_transit|delivered"
        timestamp shipped_at
    }

    WAITLIST {
        uuid id PK
        uuid user_id FK
        uuid product_id FK
        timestamp registered_at
        boolean notified
    }

    ARTIST ||--o{ PRODUCT : "has"
    PRODUCT ||--o{ PRODUCT_VARIANT : "has"
    USER ||--o{ ORDER : "places"
    ORDER ||--o{ ORDER_ITEM : "contains"
    ORDER_ITEM }o--|| PRODUCT : "references"
    ORDER_ITEM }o--o| PRODUCT_VARIANT : "references"
    ORDER ||--o| SHIPPING : "has"
    USER ||--o{ WAITLIST : "registers"
    PRODUCT ||--o{ WAITLIST : "has"

4-4. 핵심 API 명세

설계 에이전트는 OpenAPI 3.0 형식으로 API 명세를 작성하고, 이를 WIKI에 저장한다. 이 명세가 이후 백엔드·프론트엔드 에이전트의 구현 기준이 된다.

카테고리	Method	Endpoint	설명
상품	GET	`/api/v1/products`	상품 목록 (필터: 아티스트, 상태, 카테고리)
상품	GET	`/api/v1/products/{id}`	상품 상세 + 재고 실시간
상품	POST	`/api/v1/products/{id}/waitlist`	재입고 알림 신청
장바구니	GET/POST/DELETE	`/api/v1/cart`	장바구니 CRUD
주문	POST	`/api/v1/orders`	주문 생성 (재고 선점)
주문	POST	`/api/v1/orders/{id}/pay`	결제 요청
주문	GET	`/api/v1/orders/{id}`	주문 상세 + 배송 추적
알림 신청	POST	`/api/v1/notifications/subscribe`	판매 시작 알림 구독
리뷰	GET/POST	`/api/v1/products/{id}/reviews`	구매 인증 후기
관리자	GET	`/api/v1/admin/dashboard`	매출·재고 통합 현황
관리자	PATCH	`/api/v1/admin/products/{id}/stock`	재고 수동 조정

4-5. 설계 단계에서의 핵심 결정과 근거

설계 에이전트가 남기는 아키텍처 결정 기록(ADR: Architecture Decision Record)은 WIKI의 독립 문서로 저장된다. 예약 판매 한정 수량의 경우 Redis 재고 선점 방식을 선택한 근거, 포토카드 랜덤 결과 처리를 결제 완료 후 배치 처리로 설계한 근거 등이 기록된다. 나중에 개발 에이전트가 “왜 이렇게 설계됐지?”라고 물을 때 위키에서 바로 찾을 수 있어야 한다.

5. 개발 단계: 칸반 기반 멀티에이전트 구현

5-1. 개발 칸반 운영 방식

헤르메스의 칸반 기능은 에이전트와 사람이 함께 일하는 영속 작업 큐다. 작업 카드는 단순한 할일 목록이 아니라, 에이전트가 읽고 실행하는 명세서에 가깝다. 하나의 카드는 다음 구조를 갖는다.

카드 제목: 예약 판매 타이머 API 엔드포인트 구현
담당: backend 에이전트
선행 작업: [완료] 상품 DB 스키마 마이그레이션
본문:
  - GET /api/v1/products/{id}/sale-timer 엔드포인트 구현
  - 현재 시각 기준 판매 시작까지 남은 시간(초) 반환
  - 판매 중일 때는 종료까지 남은 시간 반환
  - Redis 캐시 30초 TTL 적용 (DB 부하 방지)
  - 단위 테스트 3개 이상 (판매 전, 판매 중, 판매 후)
완료 기준: 테스트 통과, OpenAPI 문서 자동 생성 확인
알림: 완료 시 QA 에이전트에게 테스트 요청 카드 자동 생성

5-2. 병렬 개발 전략

백엔드와 프론트엔드는 API 명세를 공유 기준으로 병렬 진행한다. 백엔드 에이전트가 API를 구현하는 동안, 프론트엔드 에이전트는 Mock API를 기반으로 UI를 구현한다. Git worktree를 활용해 각 에이전트가 독립 브랜치에서 작업한다.

gantt
    title 개발 스프린트 병렬 작업 구조 (스프린트 1)
    dateFormat  YYYY-MM-DD
    axisFormat %m/%d

    section 백엔드 에이전트
    회원/인증 API      :be1, 2026-01-12, 3d
    상품 목록/상세 API :be2, after be1, 3d
    장바구니 API       :be3, after be2, 2d
    주문·결제 API      :be4, after be3, 4d

    section 프론트엔드 에이전트
    공통 컴포넌트 설계 :fe0, 2026-01-12, 2d
    메인·상품 목록 UI  :fe1, after fe0, 3d
    상품 상세·장바구니 :fe2, after fe1, 3d
    주문·결제 플로우   :fe3, after fe2, 4d

    section QA 에이전트
    테스트 환경 구성   :qa0, 2026-01-12, 1d
    API 단위 테스트    :qa1, after be1, 5d
    E2E 테스트 작성    :qa2, after fe1, 5d
    통합 테스트        :qa3, 2026-01-29, 3d

5-3. 핵심 기능별 구현 흐름

예약 판매 한정 수량 구매 플로우

예약 판매에서 가장 기술적으로 까다로운 부분은 동시 구매 시 재고 초과 판매를 방지하는 것이다. 백엔드 에이전트는 설계 에이전트의 ADR을 참조해 Redis를 이용한 원자적(atomic) 재고 선점 방식을 구현한다.

sequenceDiagram
    participant U as 사용자
    participant GW as API Gateway
    participant ORDER as Order Service
    participant REDIS as Redis
    participant PG as PostgreSQL
    participant NOTIFY as Notification Service

    U->>GW: POST /api/v1/orders (장바구니 기반 주문 생성)
    GW->>ORDER: 주문 요청 전달
    ORDER->>REDIS: DECR fanpick:stock:{product_id} by {quantity}
    alt 재고 충분 (결과 >= 0)
        REDIS-->>ORDER: 선점 성공
        ORDER->>PG: 주문 레코드 생성 (status: pending)
        ORDER-->>GW: 주문 ID + 결제 URL 반환
        GW-->>U: 201 Created (결제 페이지로 이동)
        Note over ORDER,REDIS: 10분 내 결제 미완료 시\nREDIS 재고 롤백 + 주문 취소
    else 재고 부족 (결과 < 0)
        REDIS-->>ORDER: 선점 실패 (롤백)
        ORDER->>PG: 대기열 등록 처리
        ORDER-->>GW: 재고 부족 응답
        GW-->>U: 409 Conflict (품절 안내 + 대기 등록 옵션)
        NOTIFY->>U: 재입고 알림 신청 안내 푸시
    end

포토카드 랜덤 결과 처리

포토카드 랜덤 포함 상품은 결제 완료 후 배치로 처리한다. 실시간 처리가 아닌 배치 방식을 선택한 이유는 대규모 동시 구매 상황에서 결제 응답 속도를 보장하기 위해서다.

flowchart LR
    PAY[결제 완료] --> BATCH[Celery 태스크\n랜덤 결과 배정]
    BATCH --> ALGO{랜덤 알고리즘\n각 멤버 확률 적용}
    ALGO --> SAVE[결과 DB 저장\norder_item.random_result]
    SAVE --> EMAIL[이메일 발송\n내 포카 결과 확인하기]
    SAVE --> PUSH[앱 푸시 알림]
    EMAIL & PUSH --> USER[사용자 확인]

5-4. 백엔드 에이전트 실제 작업 예시

칸반 카드를 받은 백엔드 에이전트가 /goal 명령으로 목표를 설정하고 작업을 진행하는 흐름은 다음과 같다.

hermes chat --profile backend

/goal 예약 판매 타이머 API 구현 완료.
완료 기준: 테스트 3개 통과, OpenAPI 문서 확인

[에이전트] WIKI에서 예약 판매 비즈니스 규칙 문서 검색 중...
[에이전트] DB 스키마에서 sale_start_at, sale_end_at 필드 확인...
[에이전트] Redis 캐시 설계 ADR 참조...
[에이전트] products/routes.py에 /sale-timer 엔드포인트 작성 중...
[에이전트] tests/test_sale_timer.py 테스트 3개 작성...
[에이전트] pytest 실행 중... 3/3 통과
[에이전트] /docs에서 OpenAPI 문서 생성 확인
[에이전트] 칸반 카드 상태를 Review로 변경
[에이전트] QA 에이전트에게 테스트 요청 카드 생성

/background 명령은 오래 걸리는 작업(예: 전체 E2E 테스트 실행)을 대화창 밖에서 계속 진행하게 해준다. /yolo 명령은 신뢰할 수 있는 범위(예: 기존 테스트 모두 통과하는 단순 리팩토링) 안에서 승인 대기 없이 빠르게 진행할 때 쓴다.

5-5. 프론트엔드 에이전트의 주요 화면 구현

프론트엔드 에이전트는 API 명세를 기반으로 주요 화면을 구현한다. 아이돌 굿즈 플랫폼의 핵심 화면은 다음과 같다.

화면	핵심 컴포넌트	특이사항
메인 홈	아티스트 배너, 신규 굿즈, 예약 판매 D-Day	배너 실시간 업데이트
상품 목록	아티스트 필터, 상태 뱃지 (판매중/예정/품절)	검색·정렬 필터
상품 상세	잔여 재고 표시, 카운트다운 타이머, 예약 알림 버튼	실시간 재고 폴링
장바구니	수량 변경, 품절 상품 분리 표시	비회원 세션 장바구니
주문·결제	국제 배송비 자동 계산, 다국어 주소 입력	PG사 연동
주문 상세	배송 추적 타임라인, 랜덤 포카 결과 공개	결과 공개 애니메이션
마이페이지	주문 내역, 대기 등록 목록, 구매 인증 후기
관리자 대시보드	실시간 주문 현황, 재고 경보, 매출 차트	에이전트 운영 현황

6. 테스트 단계: 에이전트 자동화 QA

6-1. QA 에이전트의 테스트 전략

QA 에이전트는 단위 테스트(Unit Test), 통합 테스트(Integration Test), 엔드투엔드 테스트(E2E Test)의 세 단계로 품질을 검증한다. 에이전트가 버그를 발견하면 직접 수정하지 않고, 칸반 카드에 버그 리포트를 작성해 담당 에이전트에게 위임한다. 수정은 담당 에이전트가 하고, QA 에이전트가 재검증한다.

flowchart TD
    NEW_FEATURE[새 기능 구현 완료 칸반 카드: Review] --> UT[단위 테스트 실행\nQA 에이전트]
    UT -->|통과| IT[통합 테스트 실행]
    UT -->|실패| BUG1[버그 리포트 카드 생성\n담당 에이전트에게 위임]
    BUG1 -->|수정 완료| UT
    IT -->|통과| E2E[E2E 테스트 실행\nPlaywright]
    IT -->|실패| BUG2[버그 리포트 카드 생성]
    BUG2 -->|수정 완료| IT
    E2E -->|통과| PERF[성능 테스트\nk6 부하 테스트]
    E2E -->|실패| BUG3[버그 리포트 카드 생성]
    BUG3 -->|수정 완료| E2E
    PERF -->|통과| DONE[칸반 카드: Done\n배포 승인 요청]
    PERF -->|병목 발견| PERF_REPORT[성능 리포트 작성\n아키텍처 에이전트와 협의]

6-2. 아이돌 굿즈 플랫폼 특화 테스트 시나리오

일반 이커머스 테스트에 더해, 팬픽의 특수 상황을 반드시 테스트해야 한다.

동시 구매 시나리오 (가장 중요): 콘서트 MD 오픈 시 수천 명이 동시에 같은 상품을 구매하려는 상황을 k6로 시뮬레이션한다.

시나리오: 재고 100개 상품에 500명 동시 구매 시도
기대 결과:
  - 정확히 100건만 결제 성공
  - 나머지 400건은 품절 안내
  - DB 재고와 Redis 재고 불일치 없음
  - 결제 응답 시간 2초 이내
  - 서버 에러 0건

예약 판매 타이머 경계값 테스트: 판매 시작 1초 전, 정각, 1초 후의 재고 API 응답과 구매 가능 여부를 각각 검증한다.

랜덤 포카 확률 편향 테스트: 대량의 랜덤 결과를 생성해 각 멤버의 실제 배정 비율이 설정된 확률 범위 안에 있는지 통계적으로 검증한다.

국제 배송비 계산 테스트: 한국→미국, 한국→일본, 한국→유럽 등 주요 배송지별 배송비 계산 결과를 실제 배송사 API 응답과 비교 검증한다.

6-3. QA 에이전트의 버그 리포트 형식

버그 ID: BUG-042
제목: 재고 0개 상품에서 장바구니 추가가 막히지 않음
재현 단계:
  1. 재고 0개 상품 상세 페이지 접속
  2. "장바구니 담기" 버튼이 비활성화되지 않음
  3. 버튼 클릭 시 장바구니 추가 API 호출 발생
  4. 서버에서 재고 부족 에러 반환 → 사용자 혼란
기대 동작: 재고 0개 시 프론트엔드에서 버튼 비활성화, "품절" 표시
실제 동작: 버튼 활성화 상태, 클릭 후 에러 메시지 노출
심각도: Medium
담당: frontend 에이전트
관련 파일: components/ProductDetail/AddToCartButton.tsx

7. 운영 이관: 자율 운영 체계로 전환

7-1. 운영 이관이란 무엇인가

“운영 이관”은 이 문서에서 개발이 완료된 서비스를 사람 중심 운영에서 헤르메스 에이전트 중심의 자율 운영으로 전환하는 과정을 의미한다. 완전한 무인 자동화가 아니라, 에이전트가 일상 운영의 대부분을 처리하고 사람은 예외 상황과 전략적 결정에만 개입하는 구조다.

이관 전에 반드시 세 가지를 완료해야 한다. 첫째, 운영 에이전트의 SOUL.md가 완성되고 검증된 상태여야 한다. 둘째, 운영 에이전트가 수행할 수 있는 작업의 허용 목록(command_allowlist)과 금지 목록이 명확히 정의된 상태여야 한다. 셋째, 에이전트가 처리할 수 없는 상황(에스컬레이션 조건)과 그때 사람에게 어떻게 알릴지가 정의된 상태여야 한다.

7-2. 운영 에이전트의 권한 범위

graph LR
    subgraph "에이전트 자율 처리 가능"
        A1["재고 부족 경보 발송"]
        A2["CS 1차 분류·자동 응답<br/>(FAQ, 배송 조회)"]
        A3["일일 매출 리포트 생성"]
        A4["예약 판매 알림 발송"]
        A5["배송 추적 상태 업데이트"]
        A6["품절 상품 대기자 알림"]
        A7["서버 헬스체크·경보"]
    end
    
    subgraph "에이전트가 사람에게 에스컬레이션"
        B1["결제 오류 (금액 불일치)"]
        B2["대량 CS 폭증 (비정상 패턴)"]
        B3["재고 DB와 Redis 불일치"]
        B4["서버 다운 / P1 인시던트"]
        B5["환불 정책 예외 케이스"]
        B6["보안 이상 징후"]
    end
    
    AGENT["운영 에이전트"] -->|"자동 처리"| A1 & A2 & A3 & A4 & A5 & A6 & A7
    AGENT -->|"텔레그램 알림 + 대기"| B1 & B2 & B3 & B4 & B5 & B6
    HUMAN["사람<br/>운영자"] -->|"판단 + 지시"| AGENT

7-3. 컨테이너 격리와 보안 설정

운영 에이전트가 프로덕션 환경에 접근할 때는 권한을 최소화해야 한다. 헤르메스의 command_allowlist 설정으로 에이전트가 실행할 수 있는 명령어 목록을 제한한다. 데이터베이스에는 읽기 전용 계정으로만 접근하고, 쓰기 작업이 필요할 때는 별도의 승인 절차를 거치도록 설계한다.

보안 체크리스트:

API 키와 시크릿은 환경 변수로만 관리, SOUL.md나 AGENTS.md에 절대 기재 금지
에이전트의 파일 시스템 접근 범위를 /workspace/logs, /workspace/reports로 제한
결제·개인정보 관련 DB 테이블은 읽기 전용 접근만 허용
에이전트가 외부로 데이터를 전송하는 것은 사전에 승인된 채널(텔레그램, 지정 이메일)로만 허용

7-4. 이관 점검표 (핸드오버 체크리스트)

[ ] 운영 에이전트 SOUL.md 검토 완료
[ ] command_allowlist 설정 완료 및 테스트
[ ] 에스컬레이션 조건 정의 및 텔레그램 알림 테스트
[ ] 크론 태스크 목록 검토 및 실행 테스트
[ ] 운영 WIKI 문서 완성 (런북, FAQ, 인시던트 대응 절차)
[ ] CS 에이전트 자동 응답 시나리오 검토
[ ] 재고 경보 임계값 설정
[ ] 스테이징 환경에서 2주 운영 후 프로덕션 이관

8. 자율 운영: 크론과 자기 진화

8-1. 크론 기반 자동화 태스크

헤르메스의 크론(cron) 기능은 자연어로 스케줄을 설정한다. 운영 에이전트가 등록하는 크론 태스크들은 사람이 매번 수동으로 해야 했던 반복 작업들이다.

gantt
    title 팬픽 자율 운영 크론 스케줄 (하루)
    dateFormat HH:mm
    axisFormat %H:%M
    
    section 재고 관리
    재고 현황 스캔 및 경보 체크   :crit, 06:00, 30m
    Redis-DB 재고 정합성 체크      :09:00, 15m
    Redis-DB 재고 정합성 체크      :18:00, 15m

    section 알림 자동화
    오늘 판매 시작 상품 알림 발송  :08:30, 30m
    판매 마감 1시간 전 알림 발송   :done, 23:00, 30m

    section 배송 추적
    배송 상태 자동 업데이트        :09:30, 45m
    배송 상태 자동 업데이트        :15:00, 45m

    section CS 리포트
    당일 CS 문의 현황 집계         :09:00, 15m
    미답변 CS 에스컬레이션 체크    :14:00, 15m

    section 일일 리포트
    일일 매출·주문 리포트 생성     :22:00, 30m
    리포트 텔레그램 발송           :22:30, 10m

자연어 크론 등록 예시:

hermes cron add "매일 오전 8시 30분에 오늘 판매 시작 예정인 상품이 있는지 확인하고,
해당 상품의 알림 신청자들에게 텔레그램과 이메일로 알림을 발송해"

hermes cron add "매시간 Redis 재고와 PostgreSQL 재고가 불일치하는 상품이 있으면
즉시 텔레그램으로 경보를 보내고 칸반 보드에 인시던트 카드를 생성해"

hermes cron add "매일 오후 10시에 오늘의 매출, 신규 주문, 품절 상품,
CS 문의 현황을 담은 일일 리포트를 만들어 텔레그램 운영 채널에 발송해"

8-2. CS 에이전트의 자동 응대 흐름

CS 에이전트는 고객 문의가 들어오면 먼저 WIKI의 FAQ 문서를 참조해 자동 응답을 시도한다. 처리할 수 없는 경우 사람에게 에스컬레이션한다.

flowchart TD
    CS_IN[고객 문의 수신\n텔레그램 / 이메일 / 앱] --> CLASSIFY{문의 유형 분류}
    
    CLASSIFY -->|배송 조회| TRACKING[배송 추적 API 조회\n결과 자동 답변]
    CLASSIFY -->|주문 상태| ORDER_CHECK[주문 상태 조회\n자동 답변]
    CLASSIFY -->|FAQ 해당| FAQ_REPLY[WIKI FAQ 검색\n자동 답변]
    CLASSIFY -->|환불 요청| REFUND{환불 정책 확인}
    CLASSIFY -->|기타·복잡| ESCALATE[사람에게 에스컬레이션\n텔레그램 알림]
    
    REFUND -->|정책 범위 내| AUTO_REFUND[자동 환불 처리\n완료 안내]
    REFUND -->|예외 케이스| ESCALATE
    
    TRACKING & ORDER_CHECK & FAQ_REPLY & AUTO_REFUND --> LOG[CS 이력 저장\nWIKI 업데이트]
    LOG --> PATTERN[주간 CS 패턴 분석\nFAQ 자동 업데이트 제안]
    PATTERN --> PM_REPORT[PM 에이전트에게\n제품 개선 제안]

8-3. 자기 진화 루프: 운영 경험이 서비스를 개선한다

헤르메스 에이전트의 가장 독특한 특성은 경험에서 스킬을 자동 생성한다는 점이다. 운영 에이전트가 반복적으로 처리한 작업은 자동으로 스킬 파일로 저장되고, 다음에 같은 상황이 발생했을 때 더 빠르고 정확하게 처리된다.

이것은 운영이 진행될수록 서비스가 스스로 안정화되는 구조다.

graph LR
    subgraph "운영 경험 → 스킬 생성"
        OPS[운영 중 발생한\n반복 작업] --> SKILL_AUTO[헤르메스\n자동 스킬 생성]
        SKILL_AUTO --> SKILL_STORE[스킬 파일 저장\n/skills/fanpick/*.md]
    end
    
    subgraph "스킬 → 더 나은 운영"
        SKILL_STORE --> FASTER[동일 상황 재발 시\n더 빠르고 정확한 처리]
        FASTER --> LESS_HUMAN[사람 개입 필요\n횟수 감소]
    end
    
    subgraph "CS 패턴 → 제품 개선"
        CS_PATTERN[반복되는 CS 문의 패턴] --> WIKI_UPDATE[WIKI FAQ 자동 업데이트]
        CS_PATTERN --> PRODUCT_ISSUE[제품 개선 제안\n칸반 카드 생성]
        PRODUCT_ISSUE --> DEV[백엔드·프론트엔드 에이전트\n개선 구현]
    end
    
    OPS --> CS_PATTERN

8-4. 영속 목표(/goal)와 자율 모니터링

헤르메스의 /goal 명령은 에이전트에게 장기 목표를 부여하는 방식이다. 운영 에이전트에게 다음과 같은 영속 목표를 설정하면, 에이전트는 이 목표를 항상 염두에 두고 작업한다.

/goal 팬픽 서비스의 안정적 운영.
세부 목표:
  1. 서버 가용성 99.9% 유지
  2. P1 인시던트 발생 시 10분 내 사람에게 알림
  3. 재고 오차 0건 유지
  4. CS 응답 시간 평균 2시간 이내
  5. 일일 리포트 매일 오후 10시 발송

이 목표들이 위협받는 상황이 감지되면 즉시 행동하거나 사람에게 알려.

8-5. 완전한 자율 운영의 모습

팬픽 서비스가 완전한 자율 운영 체계에 안착했을 때의 하루는 다음과 같다.

오전 8시 30분, 오늘 오후 2시에 오픈하는 신규 굿즈의 판매 예약 알림 신청자 2,847명에게 자동으로 텔레그램과 이메일 알림이 발송된다. 오후 2시, 오픈과 동시에 동시 접속이 급증한다. 운영 에이전트가 서버 응답 시간을 실시간으로 모니터링하다가, 오후 2시 4분에 Product Service의 응답 시간이 임계값을 초과하자 자동으로 수평 스케일아웃을 요청하고 텔레그램으로 현황을 보고한다. 오후 2시 17분, 재고 300개가 소진되어 품절 처리된다. 대기자 914명에게 자동으로 알림이 발송된다.

오후 3시, CS 에이전트가 “내 포카 결과는 언제 나와요?”라는 문의 38건을 자동 처리한다. 모두 WIKI의 FAQ 문서에 있는 내용이라 5분 내 자동 답변이 완료된다.

오후 10시, 운영 에이전트가 오늘의 일일 리포트를 작성해 운영 텔레그램 채널에 발송한다. 총 판매 312건, 매출 1,247만 원, CS 처리 42건(자동 39건, 에스컬레이션 3건), 서버 가용성 99.97%가 담겨 있다.

사람 운영자가 오늘 직접 한 것은 오후 2시 4분 스케일아웃 승인 버튼 하나와, 오후 4시 에스컬레이션된 환불 예외 케이스 3건 처리뿐이다.

9. 전체 흐름 요약

flowchart TD
    subgraph "0단계: 환경 구성"
        ENV[VPS 설정\n헤르메스 설치\n에이전트 프로필 설정\n텔레그램 게이트웨이 연결]
    end

    subgraph "1단계: 기획"
        WIKI_BUILD[LLM WIKI 구성\n도메인 자료 투입]
        PM_PLAN[PM 에이전트\nPRD · 사용자 스토리\n칸반 초기 카드 생성]
        WIKI_BUILD --> PM_PLAN
    end

    subgraph "2단계: 설계"
        ARCH_DESIGN[설계 에이전트\n시스템 아키텍처\nDB 스키마 · API 명세\nADR 문서화]
    end

    subgraph "3단계: 개발"
        PARALLEL[백엔드 에이전트\n+ 프론트엔드 에이전트\n병렬 구현\nGit worktree 활용]
        QA_DEV[QA 에이전트\n테스트 작성 · 실행\n버그 리포트]
        PARALLEL <--> QA_DEV
    end

    subgraph "4단계: 테스트"
        TEST[단위 · 통합 · E2E 테스트\n부하 테스트\n아이돌 굿즈 특화 시나리오]
    end

    subgraph "5단계: 운영 이관"
        HANDOVER[운영 에이전트 설정\n권한 범위 정의\n에스컬레이션 조건 설정\n이관 체크리스트 완료]
    end

    subgraph "6단계: 자율 운영"
        AUTO[크론 자동화\nCS 자동 응대\n인시던트 자동 감지\n일일 리포트\n자기 진화 루프]
    end

    ENV --> WIKI_BUILD
    PM_PLAN --> ARCH_DESIGN
    ARCH_DESIGN --> PARALLEL
    QA_DEV --> TEST
    TEST --> HANDOVER
    HANDOVER --> AUTO
    AUTO -->|"운영 경험 → WIKI 업데이트\n새 스킬 생성 → 더 나은 운영"| AUTO

이 전체 흐름에서 사람의 역할은 목표 설정자, 감독자, 예외 처리자로 점진적으로 좁아진다. 에이전트 팀이 더 많은 운영 경험을 쌓을수록 사람의 개입이 필요한 상황은 줄어들고, 서비스는 스스로 더 안정적으로 발전한다. 이것이 헤르메스 에이전트로 서비스를 만드는 일의 진짜 가치다.

작성일: 2026년 6월 17일

AI, Hermes Agent