장사왕 스프린트 대시보드

테마

Story: LLM 연동 & 프롬프트 엔진 ​

메타 ​

항목값
Story IDE-04-S-01
EpicE-04 AI 진단 엔진
상태draft
우선순위P0
규모M
담당 개발자BE (하록님)

사용자 스토리 ​

As a 장사왕 시스템, I want LLM API 연동 및 프롬프트 관리 엔진, So that 광고 데이터를 기반으로 AI 진단을 생성할 수 있다.

수락 기준 (Acceptance Criteria) ​

AC-01: LLM 클라이언트 설정 ​

항목내용
GivenLLM API 키 설정 완료
When진단 요청
ThenLLM API 호출 및 응답 수신

상세 스펙:

  • API 선택: Claude API 또는 OpenAI (환경변수로 전환 가능)
  • 타임아웃: 5초
  • 재시도: 1회 (실패 시 폴백)
  • 온도: 0.3 (일관성 확보)

AC-02: 프롬프트 템플릿 관리 ​

항목내용
Given캠페인 데이터 + 셀러 컨텍스트
When프롬프트 생성 요청
Then완성된 프롬프트 문자열 반환

프롬프트 구조:

[시스템 프롬프트] - 고정
[셀러 컨텍스트] - 동적 (적용 이력, 성과 패턴)
[광고 데이터] - 동적 (캠페인 정보, 지표)
[출력 형식] - 고정 (JSON 스키마)

AC-03: 응답 파싱 및 검증 ​

항목내용
GivenLLM 응답 수신
When파싱 시도
Then유효한 DiagnosisResult 객체 반환

응답 스키마:

typescript
interface DiagnosisResult {
  badge: "🟢" | "🟡" | "🔴";
  diagnosis: string;        // 2-3문장
  suggestion: {
    type: string;           // bid_reduction, budget_realloc 등
    action: string;         // 구체적 행동
    expectedEffect: string; // 예상 효과
  } | null;
}

검증 항목:

  • badge: 유효한 이모지 3종 중 하나
  • diagnosis: 빈 문자열 아님, 최대 200자
  • suggestion.type: 허용된 타입 목록 내

AC-04: 할루시네이션 가드레일 ​

항목내용
GivenLLM 응답에 비정상 내용 포함
When검증 실패
Then폴백 결과 반환 + 로깅

가드레일:

  • 숫자 검증: 입력 데이터에 없는 구체적 수치 언급 시 경고
  • 길이 제한: diagnosis 200자 초과 시 truncate
  • 금지어: "확실히", "반드시", "100%" 등 과장 표현 필터링

태스크 분해 ​

Task 1: LLM 클라이언트 설정 AC-01 ​

  • [ ] 1.1: LLM SDK 설치 (Anthropic/OpenAI)
  • [ ] 1.2: 환경변수 설정 (API 키, 모델명, 타임아웃)
  • [ ] 1.3: 기본 호출 함수 생성
  • [ ] 1.4: 재시도 로직 구현

Task 2: 프롬프트 엔진 AC-02 ​

  • [ ] 2.1: 시스템 프롬프트 템플릿 작성
  • [ ] 2.2: 셀러 컨텍스트 주입 함수
  • [ ] 2.3: 광고 데이터 포맷팅 함수
  • [ ] 2.4: 프롬프트 조합 함수

Task 3: 응답 파싱 AC-03 ​

  • [ ] 3.1: JSON 파싱 로직
  • [ ] 3.2: DiagnosisResult 타입 정의
  • [ ] 3.3: 스키마 검증 (Zod)

Task 4: 가드레일 AC-04 ​

  • [ ] 4.1: 응답 검증 함수
  • [ ] 4.2: 필터링/정제 로직
  • [ ] 4.3: 폴백 결과 생성

Task 5: 테스트 ​

  • [ ] 5.1: 단위 테스트 (프롬프트 생성, 파싱)
  • [ ] 5.2: 통합 테스트 (실제 API 호출 - 샌드박스)

Dev Notes (AI Agent 최적화) ​

영향 받는 소스 트리 ​

src/
├── ai/
│   ├── llm-client.ts              # 🆕 LLM API 클라이언트
│   ├── prompt-engine.ts           # 🆕 프롬프트 생성 엔진
│   ├── response-parser.ts         # 🆕 응답 파싱 + 검증
│   ├── templates/
│   │   └── diagnosis.prompt.ts    # 🆕 진단 프롬프트 템플릿
│   └── types/
│       └── diagnosis.ts           # 🆕 타입 정의
└── tests/
    └── ai/
        └── llm-client.spec.ts     # 🆕 테스트

프롬프트 템플릿 (초안) ​

typescript
const SYSTEM_PROMPT = `
당신은 쿠팡 광고 분석 전문가입니다.
셀러의 광고 데이터를 분석하여 Status Badge와 진단 메시지를 생성합니다.

규칙:
1. Badge는 🟢(양호), 🟡(주의), 🔴(위험) 중 하나만 사용
2. 진단은 2-3문장으로 간결하게, 한국어로 작성
3. 가능하면 구체적인 행동 제안 포함
4. 순이익 관점에서 판단
5. 입력 데이터에 없는 수치를 만들어내지 마세요

출력 형식 (JSON):
{
  "badge": "🟢" | "🟡" | "🔴",
  "diagnosis": "진단 메시지",
  "suggestion": {
    "type": "bid_reduction" | "budget_realloc" | "campaign_pause" | null,
    "action": "구체적 행동",
    "expectedEffect": "예상 효과"
  }
}
`;

충돌 감지 ​

항목상태설명
기존 코드 충돌✅ 없음신규 모듈
패키지 의존성🟡 추가@anthropic-ai/sdk 또는 openai

의존성 ​

의존설명상태
LLM API 선정Claude / GPT 결정 필요미정
API 키 발급환경변수 설정미완

Dev Agent Record ​

항목값
생성 AgentClaude Opus 4.5
생성일2026-01-27
마지막 수정2026-01-27
검증자-

검증 결과: 🔄 PENDING (PO 승인 대기) 검증일: -

생성일: 2026-01-27마지막 수정: 2026-01-27

장사왕 Product Team

© 2026 장사왕