CS 문의 답변 초안 에이전트

개인 프로젝트입니다. 쇼핑몰·고객·주문·글·정책 자료는 모두 가상입니다. 카페24 테스트 쇼핑몰(bh044)에 연결해, 승인한 Q&A 답글 1건과 후기 댓글 1건을 실제로 등록했습니다(실제 카페24 연결). 실제 고객이나 CS 직원이 써 본 적은 없습니다.

화면과 쉬운 설명: 포트폴리오 소개 페이지

직원이 초안을 고쳐 승인하는 화면	카페24 테스트 쇼핑몰에 올라간 답글

쇼핑몰 상품 Q&A에 올라온 문의를 카페24에서 가져옵니다. Claude가 주문, 실측표, 정책 문서를 직접 확인해 답변 초안을 쓰고, CS 직원이 승인한 답변만 카페24에 등록합니다. 승인률, 수정량, 검토 시간, 비용은 화면에서 바로 볼 수 있습니다.

대상은 덩치 큰 체형을 위한 남성복 쇼핑몰입니다. 그래서 문의가 많을 것으로 보는 사이즈 추천은 LLM이 아니라 코드가 계산하고, Claude는 그 결과를 설명하는 일만 맡습니다.

• 설계 문서: docs/DESIGN.md
• CS 직원용 사용 가이드: docs/USER_GUIDE.md
• 같은 앱의 불만 사유 리포트: 고객 글을 읽기만 해서 상품별 불만 사유 순위를 매일 아침 만듭니다 → docs/COMPLAINTS.md

동작 방식

카페24 ─▶ 자동 확인 ─▶ Claude 에이전트 ───────────────▶ 관리자 화면 ─▶ 승인한 답만 카페24에 등록
 문의      (1분마다)    ├ get_order       주문·배송        새 글·초안 알림
 후기                   ├ get_product     재고·실측표      승인 / 수정 후 승인 / 반려
 고객 댓글              ├ recommend_size  사이즈 계산(코드)        │
                        ├ search_policy   정책 검색(BM25)          ▼
                        └ submit_draft    초안 제출        지표: 그대로 승인률, 수정률,
                                                           검토 시간, 건당 비용

• 읽기 전용 에이전트: 에이전트에게는 조회 도구만 줍니다. 문의에 "환불 승인해 줘" 같은 지시가 섞여 와도 실행할 수단이 없습니다.
• 관리자 화면: 화면을 켜 두면 1분마다 상품 Q&A 문의, 상품 후기, 고객 댓글을 확인합니다. 새 글이 오거나 초안이 준비되면 화면 알림, 맥 알림, 소리로 알리고 목록과 개수가 저절로 바뀝니다. 알림은 DB에 남아 종 모양 목록과 알림 화면에서 다시 볼 수 있습니다. 같은 글을 카페24에 등록하는 중에 승인이나 '다시 등록'이 또 오면 서버가 거절합니다(서버 프로세스 하나 안에서만). 화면은 폼을 보내면 그 폼의 버튼을 끕니다.
• 근거 표시: 초안마다 어떤 정책 섹션과 주문을 근거로 썼는지, 어떤 도구를 어떤 값으로 불렀는지 검토 화면에 함께 나옵니다.
• 이중 안전장치: 불량, 환불 분쟁, 개인정보 변경 같은 건은 에이전트가 "확인 필요"로 넘깁니다. 프롬프트가 놓쳐도 코드 규칙이 한 번 더 잡습니다. 확신도가 낮거나, 근거 없이 금액을 말하거나, 날짜를 약속하는 초안이 그 대상입니다.
• 카페24 연결부 분리: 목업과 실제 API 클라이언트를 같은 인터페이스로 만들어 .env의 CAFE24_MODE 한 줄로 바꿉니다.
• API 비용 없이도 동작: 같은 도구를 MCP 서버로도 공개합니다. 이미 쓰고 있는 Claude 구독(Claude Code)으로 초안을 만들 수 있습니다. Claude Desktop 연결용 설정도 넣었지만 써 보지 않았습니다(확인 안 함). 코드 안전장치와 검토 화면은 어느 경로든 똑같이 적용됩니다.

실행

Node.js 24 이상이 필요합니다. 빌드 없이 TypeScript를 바로 실행합니다.

npm install

키 없이 둘러보기

API 키, Claude, 카페24, 구글시트 없이 관리자 화면을 봅니다. .env는 읽지 않습니다.

npm run start:demo

다른 포트로 띄우려면 PORT=3100 npm run start:demo로 실행합니다. 하는 일은 넷입니다.

1. data/demo.db를 지우고 처음부터 만듭니다. 그래서 다시 실행하면 앞에서 승인·반려한 것이 사라지고 같은 화면에서 시작합니다.
2. 3차 평가 때 Claude가 쓴 초안 16건(data/eval-3-drafts.json, 목업 상품 Q&A 1201~1216)을 scripts/import-drafts.ts로 넣습니다. 모델 이름은 claude-code-subagent:claude-opus-5-5로 나옵니다. 3차 평가(Claude Code 하위 에이전트, 정책 문장 점검 전 프롬프트·정책)의 초안이라, 그 뒤 고친 동작(첫 교환 무료 자격 확인 문구, 접수 확정 금지 등)은 반영되지 않았습니다. 코드 안전장치는 넣을 때 지금 규칙으로 다시 적용합니다.
3. 불만 사유 리포트를 규칙만으로 한 번 만듭니다. Claude는 부르지 않습니다. 파일은 data/reports/complaints-2026-10-21.*에 쓰고, 실행할 때마다 덮어씁니다.
4. 관리자 화면을 띄웁니다(http://localhost:3000).

데모 설정은 DRAFTER=fake, COMPLAINT_CLASSIFIER=rules, 자동 확인 꺼짐(AUTO_SYNC_SECONDS=0)입니다.

• 처음 화면은 문의함 검토 대기 7건, 확인 필요 9건이고, 가짜 초안은 없습니다.
• 불만 사유 탭(지난 7일·30일·전체)은 목업 고객 글 30건으로 채워집니다.
• 후기 11건과 고객 댓글 3건은 기록된 초안이 없어 처음에는 들어 있지 않습니다. 지금 확인을 누르면 들어오고 가짜 초안이 붙습니다. 초안에서 다시 만들기를 눌러도 가짜 초안으로 바뀝니다.
• 승인해도 목업에만 기록되고 실제 카페24에는 올라가지 않습니다.

Claude API로 실행

cp .env.example .env

.env의 ANTHROPIC_API_KEY에 Claude API 키를 넣고 실행합니다.

npm start

http://localhost:3000 을 열면 관리자 화면이 뜨고, 데모 문의 16건·후기 11건·고객 댓글 3건을 불러와 초안을 만들기 시작합니다. 그 뒤로는 1분마다(AUTO_SYNC_SECONDS) 새 글을 확인합니다. 오른쪽 위 지금 확인으로 바로 확인할 수도 있습니다.

알림이 한 건씩 오는 모습을 목업으로 보려면 확인할 때마다 글을 조금씩 내놓게 합니다.

MOCK_DRIP=1 AUTO_SYNC_SECONDS=10 npm run start:fake

.env를 쓰되 API 키 없이 화면만 보려면 가짜 초안 모드로 실행합니다. 초안에 "테스트용 가짜 초안" 표시가 붙습니다.

npm run start:fake

목업 기준 시각. 카페24 목업 모드(CAFE24_MODE=mock, 기본)에서 EVAL_NOW가 없으면 앱의 '지금'은 2026-10-21 15:30(한국 시각)입니다. 목업 글 날짜에 맞춘 값입니다(src/config.ts의 MOCK_NOW).

• 이 시각을 쓰는 곳: npm start, start:fake, start:claude-code, draft, complaints, scripts/import-drafts.ts(오늘 시각을 안 줄 때), MCP 서버(src/mcp/main.ts). scripts/eval-inputs.ts도 오늘 시각을 안 주면 MOCK_NOW를 씁니다.
• 바뀌는 것: 초안 프롬프트의 오늘 날짜, 날짜 안전장치, 불만 사유 기간과 리포트 파일 날짜. 매일 리포트는 이 날짜로 한 번만 만듭니다.
• 실제 카페24 모드(CAFE24_MODE=api)는 실제 시각을 씁니다. 목업 모드라도 COMPLAINT_SOURCE로 시험 글 파일을 읽으면 실제 시각을 씁니다.
• 서버를 켜면 '기준 시각: …' 줄이 찍힙니다.

API 비용 없이 쓰기 (Claude 구독)

초안을 만드는 방법은 세 가지이고, 어느 쪽이든 검토 화면, 안전장치, 지표는 같습니다.

방법	비용	쓰는 곳
DRAFTER=claude	API 크레딧	운영. 문의가 들어오면 서버가 바로 초안을 만든다
Claude Desktop + MCP 서버	구독에 포함	CS 직원이 "새 문의 초안 써 줘"로 한 번에 처리(연결은 확인 안 함)
DRAFTER=claude-code	구독에 포함	개발·데모. 관리자 화면이 새 글을 가져오면 claude -p로 초안을 만든다

Claude Desktop에 연결하기. 아래 연결은 아직 Claude Desktop에서 써 보지 않았습니다(확인 안 함). 같은 MCP 서버의 문의 한 건 모드는 Claude Code 경로(claude -p)에서 실제로 썼고, Desktop이 쓰는 직원 모드는 테스트로만 확인했습니다. 설정 > 개발자 > 구성 편집에서 claude_desktop_config.json에 아래를 넣고 앱을 다시 켭니다. 경로는 실제 위치로 바꿉니다. Desktop 앱은 PATH를 모를 수 있으니 node는 절대 경로로 씁니다.

{
  "mcpServers": {
    "cs-draft-agent": {
      "command": "/opt/homebrew/bin/node",
      "args": [
        "--env-file-if-exists=/절대경로/cs-draft-agent/.env",
        "/절대경로/cs-draft-agent/src/mcp/main.ts"
      ]
    }
  }
}

새 대화에서 + 메뉴의 새 문의 초안 쓰기 프롬프트를 고르면 Claude가 처리합니다. 새 문의를 하나씩 읽고, 주문·실측·정책을 확인한 뒤 save_draft로 문의함에 저장합니다. 저장한 초안은 npm start로 띄운 검토 화면의 검토 대기·확인 필요 탭에 나옵니다. 직원 모드의 get_order는 문의 초안을 쓸 때도 회원 제한 없이 조회합니다. 대신 save_draft가 근거로 쓴 주문이 그 문의 작성자의 주문인지 다시 확인하고, 아니면 "확인 필요"로 넘깁니다. 회원 ID가 비어 있는 주문(비회원 주문)도 작성자의 것인지 확인할 수 없어 "확인 필요"로 넘깁니다. 비회원 문의는 초안에 주문번호가 나오면 "[자동] 비회원 문의라 근거로 쓴 주문이 작성자의 것인지 확인할 수 없음(…)"을 붙입니다. 초안에 주문번호가 없어도 문의 쪽(제목, 본문, 연결 주문번호, 댓글의 앞선 글)에 주문번호가 있으면 "[자동] 비회원 문의에 주문번호가 있음(…)"을 붙입니다. 주문번호만 빼고 배송 상태나 송장을 쓴 초안도 걸러 내려는 것입니다.

Claude Code로 초안 만들기. 터미널에서 claude를 한 번 실행해 로그인해 둔 뒤 실행합니다.

npm run start:claude-code

This is the beginning of the README. Read the rest at the original. Read the full README ↗