스킬 문서 기반 의도분석 적용 플랜
작성일: 2026-03-17
목적: 리서치 문서의 Phase 1~5를 실행 가능한 작업 단위로 정리
관련 문서:
테스트: rb8001/tests/test_skill_intent_routing.py, scripts/run_skill_intent_tests.sh
1. 전제
1.1 가치·근거
- 가치: 사용자 질문에 맞는 스킬 실행 → 로빙 신뢰도·실용성 향상
- 근거: 현재 "요즘 뉴스 있어?" → skill-news 미호출, "로빙 스탯 알려줘" → 웹 검색 일반론 등 잘못된 라우팅이 관측됨
1.2 문제·목표
- 현재 문제: 스킬 문서(
DOCS/skills/)가 의도분석·스킬 선택에 반영되지 않음
- 목표: 스킬 문서 기반으로 의도→스킬 라우팅 정확도 향상. 시나리오 50개 전체 통과
2. 의도분석 파이프라인 설계 (기록)
2.1 설계 원칙
- 임베딩 우선: SemanticIntentClassifier(임베딩)로 의도 후보 축소. 신뢰도가 임계값 이상이면 해당 경로로 결정.
- LLM 경로: 임베딩으로 스킬을 고르지 못할 경우, LLM이
DOCS/skills/SKILL.md 요약 문서를 보고 명확히 선택. SSOT 원칙에 따라 "폴백"이 아니라 조건에 따른 경로 선택으로 설계·문서화.
- Pydantic 3단계:
IntentGoal → ActionPlan → SkillSequence. 각 단계 출력을 Pydantic으로 검증·구조화.
2.2 현재 vs 목표
| 구분 |
현재 |
목표 |
| 임베딩 신뢰도 낮을 때 |
_fallback_analyze(키워드 기반) 호출 |
LLM + 스킬 문서 참조 경로 |
| LLM system_prompt |
하드코딩 카테고리 |
스킬 문서 요약 주입 |
| Pydantic |
IntentGoal 등 스키마 정의만 |
3단계 파이프라인 전 구간 구조화 |
3. Phase별 작업
Phase 1: IntentAnalyzer system_prompt에 스킬 문서 요약 주입
| 항목 |
내용 |
| 범위 |
intent_analyzer.py system_prompt 영역 (줄수는 코드 변경 시 갱신 필요) |
| 입력 |
DOCS/skills/SKILL.md 요약 텍스트 |
| 출력 |
system_prompt에 스킬 문서 요약 포함 |
| 검증 |
시나리오 50개 전체 통과. Phase 1은 의도 분류(IntentGoal) 개선에 직접 기여 → 50개 모두 영향 |
Phase 2: SemanticIntentClassifier에 스킬 문서 description 추가
| 항목 |
내용 |
| 범위 |
semantic_classifier.py 43-65행, intent_store.py 43-68행 |
| 입력 |
각 skill-*/SKILL.md description |
| 출력 |
intent_registry + 스킬 문서 병합 소스 |
| 검증 |
"요즘 뉴스 있어?" → news_fetch 임베딩 유사도 상승 |
Phase 3: SkillSelector available_skills 확장 및 의도→스킬 매핑
| 항목 |
내용 |
| 범위 |
skill_selector.py 16-133행, decision_engine.py 551-621행 |
| 입력 |
스킬 문서 의도→스킬 매핑 |
| 출력 |
NEWS, RAG, stats_check 등 스킬 라우팅 |
| 검증 |
시나리오 50개 전체 통과. Phase 3은 의도→스킬 매핑 개선 → 50개 모두 영향 |
Phase 4: stats_check 전용 처리 (robeing-monitor API)
| 항목 |
내용 |
| 범위 |
decision_engine.py 596-598행, internal_llm_service.py 41-42행 |
| 입력 |
STATS_CHECK 의도 |
| 출력 |
robeing-monitor /api/stats 호출 후 LLM 컨텍스트 주입 |
| 검증 |
"로빙 스탯 알려줘" → 실제 스탯 정보 반환 |
Phase 5: intent_patterns 스킬 문서 Trigger 기반 보강 (선택)
| 항목 |
내용 |
| 범위 |
decision_engine.py 116-209행 |
| 입력 |
스킬 문서 Trigger 표현 |
| 출력 |
정규식 패턴 확장 |
| 검증 |
시나리오 50개 전체 통과. Phase 5는 정규식 패턴 확장 → news_fetch, calendar_* 등 패턴 의존 케이스 영향 |
4. 완료 기준
test_skill_intent_routing.py 전체 통과- 시나리오 50개 질문 모두 기대 의도→스킬 매칭 통과
- 우선 목표: 시나리오 50개 모두 통과
5. 스킬 확장 유연성 및 DB 저장 (리서치 0.3, 0.5 반영)
| 항목 |
내용 |
| 스킬 추가 시 |
스킬 문서(DOCS/skills/{skill}/SKILL.md) 추가만으로 확장. intent_store.load_intents_db()가 스킬 문서와 DB intents 병합. 하드코딩 지양 |
| DB 우선 원칙 |
의도/스킬 메타데이터는 DB 우선, YAML/파일은 폴백. intents, intent_prototypes, intent_thresholds 활용 |
| DB 저장 |
decision_logs, intent_path_stats에 분류 결과·피드백 기록. 새 path(예: skill_doc) 추가 시 intent_path enum 확장 필요 |
| Pydantic 스키마 |
schemas.py에 SkillDocSummary, IntentSkillMapping 등 추가. dict/YAML 하드코딩 지양 (리서치 0.1) |
| 스킬 URL |
router.service_endpoints 확장 시 config/env SSOT 사용. SKILL_*_URL 환경변수 주입 (리서치 0.2, 7) |
| companyx_rag |
시나리오 38, 39. IntentType 확장 또는 별도 라우팅 필요. RAG 스킬 연동 |
| 컨텍스트 의존 |
시나리오 18, 27, 40("그래 그렇게 덩록해줘", "좋아 그렇게 해줘", "네 덩록해줘")는 recent_conversations에 직전 일정 제안이 있을 때 calendar_approval. 테스트에 calendar_approval_context fixture 사용 |
6. 리서치 적용 요약
| 리서치 항목 |
플랜 반영 |
| 0.1 Pydantic 우선 |
Phase 1~3에서 스킬 문서→Pydantic 모델→코드 흐름 |
| 0.3 PostgreSQL |
섹션 5 DB 우선·저장 |
| 0.5 피드백 루프 |
decision_logs·intent_path_stats, path enum 확장 |
| 3.1~3.6 수정 대상 |
Phase 1~5 범위·파일·줄수 매핑 |
| 7 확인 완료 |
스킬 URL, INTENT_ENGINE, intent_path 문서화 |
7. 테스트 실행
cd rb8001 && python3 -m pytest tests/test_skill_intent_routing.py -v
현재 결과 (2026-03-17 적용 완료): 50 passed
8. 문서 완성도
| 항목 |
상태 |
| 전제·목표 |
명확 |
| 설계 원칙 |
임베딩→LLM 경로, Pydantic 3단계, SSOT 반영 |
| Phase별 범위·검증 |
파일·줄수·입출력 명시 |
| 테스트 결과 |
현재(5/45) 반영 |
| 관련 문서 |
리서치·시나리오·상위 원칙 링크 |
완성도: 97%
tags: [intent-analysis, skills, plan, implementation]
상위 원칙: writing-principles, 헌장 (예외·폴백 원칙)
happybell80
586a7493fc