lab-rule-scaffold-poc

매니저가 처리한 유저챗에서 AI 에이전트용 규칙을 자동 생성하는 두 가지 파이프라인을 비교하는 실험입니다.

---

배경

Channel Talk의 ALF(AI 에이전트)에 규칙을 부여할 때, 지금까지는 카테고리가 고정된 COS Rule Draft 방식을 사용했습니다. 이 실험은 행동 패턴 기반으로 카테고리를 귀납적으로 도출하는 Rule Scaffold 방식을 새로 제안하고, 같은 인풋에 대해 두 결과를 비교합니다.

---

두 파이프라인 비교

	Rule Scaffold (신규 제안)	COS Rule Draft (기존 방식)
카테고리	데이터에서 귀납적으로 도출	9개 고정 카테고리
단계	extract → group → generate	analyze → write → reconcile
이번 실험 결과	11개 그룹 → 11개 규칙	7개 카테고리 → 7개 규칙
결과 뷰어	out/rules_report.html (보라색)	out/cos_report.html (초록색)

---

인풋

data/userchats.json — 총 145건의 유저챗

[
  {
    "channel_id": "...",
    "chat_id": "69d4ada684e1811f1b91",
    "chat_text": "[user]: 안녕하세요\n[alf]: 안녕하세요! 무엇을 도와드릴까요?\n[manager]: 안녕하세요, 담당자입니다."
  }
]

• chat_text의 발화자: [user] (고객), [alf] (봇), [manager] (매니저)
• 두 파이프라인 모두 [manager] 발화가 있는 35건만 처리

---

아웃풋

Rule Scaffold (out/3_rules.json)

행동 유사도 기반으로 귀납적으로 도출한 11개 규칙.

[
  {
    "group_id": "G1",
    "behavior_theme": "과금 구조 수치 직접 조회 및 해설",
    "source_chat_ids": ["69d4ada684e1811f1b91", ...],
    "rule": {
      "title": "과금 구조 수치 해설",
      "situation_condition": "고객이 과금 금액이나 청구 내역에 대해 구체적인 수치를 물어볼 때",
      "action_instruction": "내부 데이터를 직접 조회하여 정확한 수치를 제공한다.",
      "instruction": "..."
    }
  }
]

COS Rule Draft (out/4_cos_rules.json)

고정 카테고리별로 생성한 7개 규칙.

{
  "lang": "ko",
  "drafts": [
    {
      "category_id": "tone_manner",
      "display_name": "톤 & 매너",
      "title": "톤 & 매너: 인사·공감·클로징 기본 규칙",
      "instruction": "...",
      "source_chat_ids": ["69d4ada684e1811f1b91", ...]
    }
  ]
}

결과 뷰어

out/rules_report.html과 out/cos_report.html을 브라우저에서 직접 열면 됩니다. 각 규칙을 클릭하면 원본 유저챗을 나란히 확인할 수 있습니다.

---

실행 방법

사전 준비

# 의존성 설치 (uv 필요: https://docs.astral.sh/uv)
uv sync

# API 키 설정
cp .env.example .env
# .env에 PRISM_API_KEY 입력

Pipeline 1: Rule Scaffold

uv run rule-scaffold
# 결과: out/1_extractions.json, out/2_groups.json, out/3_rules.json

옵션:

uv run rule-scaffold --help

# 주요 옵션
--input PATH       유저챗 JSON 경로 (기본: data/userchats.json)
--out-dir DIR      결과 저장 폴더 (기본: out/)
--concurrency N    동시 LLM 콜 수 (기본: 4)
--limit N          앞에서 N건만 처리 (테스트용)
--dry-run          실제 LLM 없이 배선만 확인

Pipeline 2: COS Rule Draft

uv run python run_cos_pipeline.py
# 결과: out/4_cos_rules.json

뷰어 생성

결과 HTML 뷰어는 이미 out/에 포함되어 있습니다. 재생성이 필요하면:

# rules_report.html은 Rule Scaffold 파이프라인 실행 후 자동 생성됨
# cos_report.html은 아래 스크립트로 생성
uv run python gen_cos_report.py

---

파일 구조

.
├── data/
│   └── userchats.json          # 인풋: 유저챗 145건
├── out/
│   ├── 1_extractions.json      # Rule Scaffold: 상황/행동 추출 결과
│   ├── 2_groups.json           # Rule Scaffold: 그룹화 결과
│   ├── 3_rules.json            # Rule Scaffold: 최종 규칙 11개
│   ├── 4_cos_rules.json        # COS Rule Draft: 최종 규칙 7개
│   ├── rules_report.html       # Rule Scaffold 결과 뷰어
│   └── cos_report.html         # COS Rule Draft 결과 뷰어
├── src/rule_scaffold/          # Rule Scaffold 파이프라인 소스
│   ├── pipeline.py             # 오케스트레이터 + CLI
│   ├── extract.py              # Step 2: 상황/행동 추출
│   ├── group.py                # Step 3: 행동 유사도 기반 그룹화
│   ├── generate.py             # Step 4: 규칙 생성
│   ├── llm.py                  # LLM 클라이언트
│   ├── prompts.py              # 프롬프트
│   └── data.py                 # 유저챗 로딩/파싱
├── run_cos_pipeline.py         # COS Rule Draft 파이프라인 (standalone)
├── pyproject.toml
└── .env.example

---

모델 / API

• 모델: claude-sonnet-4-6
• 엔드포인트: https://prism.ch.dev (Prism 경유)
• 인증: PRISM_API_KEY 환경변수