docs(troubleshooting): rb8001 web_search 미수행 사례 정리(로그/원인/개선안/체크리스트)

troubleshooting/251022_claude_rb8001_web_search_미수행.md

@@ -0,0 +1,61 @@
+# rb8001: web_search 의도 처리 시 안내문만 반환(기업 검색 미수행)
+
+- 일시(KST): 2025-10-22 23:50
+- 작성자: Claude (51124)
+- 범위: rb8001 Slack DM 요청 → 기업 검색 응답 품질
+
+---
+
+## 증상
+- 사용자가 “이 기업을 검색해줘.” 입력 시, 실제 검색(결과/링크/출처) 없이 일반적인 “기업 정보 검색 안내”만 반환.
+- 기업명 지시어(“이 기업”) 해소 없이 일반론으로 응답 → 사용자 의도와 불일치.
+
+## 로그 근거
+- 의도 판정 및 처리 흐름(23:50:02~09):
+  - `rb8001/logs/rb8001.log:66624` — [DecisionEngine] 의도 분석 시작: '이 기업을 검색해줘.'
+  - `rb8001/logs/rb8001.log:66625` — [DecisionEngine] 매칭됨 - 의도: web_search
+  - `rb8001/logs/rb8001.log:66630` — [DecisionEngine] web_search detected
+  - `rb8001/logs/rb8001.log:66641` — Router result: success True, 결과 content가 “기업 정보 검색에 대해 안내해 드릴게요 …” (일반 안내)
+  - `rb8001/logs/rb8001.log:66643` — Slack 전송 성공
+
+## 원인(가설)
+- 지시어 해소 미흡: “이 기업”에 해당하는 기업명을 이전 메시지/스레드/파일에서 추출하지 못함.
+- web_search 파이프라인 미호출: `DecisionEngine → router_helper.handle_web_search()`가 실제 외부 검색 호출(Tavily/뉴스 스킬 등) 대신 LLM 안내문 생성 경로로 단축.
+- 구성/키 누락 가능성: `TAVILY_API_KEY` 미설정 또는 `SKILL_NEWS_URL`/검색 서비스 엔드포인트 미활성화로 검색 호출이 비활성화되었을 수 있음.
+
+## 개선안(실행 항목)
+1) 지시어 해소(“이 기업” 해석)
+- 스레드/직전 메시지/업로드된 파일 메타에서 기업명을 역추적.
+- 미확정 시 단문 보충질문: “어떤 기업을 찾으시나요? (예: 컴퍼니엑스)”
+
+2) 검색 파이프라인 강제
+- `router_helper.handle_web_search()`에서 Tavily(또는 내부 뉴스 스킬) 호출을 필수화하고, 결과 3건 최소 확보 후 요약.
+- 구성 확인: `TAVILY_API_KEY`, `SEARCH_MAX_RESULTS`(예: 5), 타임아웃/재시도(백오프) 적용.
+
+3) 결과 형식 표준화(출처 포함)
+- 제목 · 간략 요약 · 출처 도메인 · 날짜(UTC→KST 변환) · 클릭 가능 URL 포함.
+- 0건일 때 보충질문 또는 대안 소스(DART/KED/SEC) 자동 제시.
+
+4) 국내/해외 소스 분기
+- 한국어/국내 맥락이면 DART/KED/크레딧뷰 등 1순위, 해외는 SEC/Hoovers/Thomasnet 보조.
+
+5) 로깅/메트릭
+- `search_query`, `results_count`, `sources[]`, `response_ms` 로깅.
+- OpenSearch 인덱스(dataprepper-static)에 검색 이벤트 기록.
+
+## 체크리스트(코드/설정)
+- 코드
+  - `rb8001/app/router/router.py` — web_search 분기에서 `router_helper.handle_web_search()` 경로로 강제, 결과 미존재 시 보충질문.
+  - `rb8001/app/commands/skill_commands.py` — `_call_tavily_api()` 정상 동작/타임아웃/재시도 확인.
+- 설정
+  - `.env` — `TAVILY_API_KEY`, `SEARCH_MAX_RESULTS`, 네트워크 아웃바운드 허용 확인.
+- 검증
+  - “컴퍼니엑스 검색해줘”, “이 기업 검색해줘”(직전 메시지에 기업명 포함) 각각 3건 이상 결과/링크 포함 응답 확인.
+
+## 교훈 ✍️
+- 지시어(“이/그/저 …”)는 스레드 문맥 또는 보충질문으로 해소해야 사용 의도를 정확히 충족.
+- 검색 의도는 안내문이 아니라 “결과+출처”가 핵심 가치. 외부 호출 실패 시에도 대안·재시도·보충질문이 필요.
+- 결과는 시간축과 출처를 반드시 포함해 재현 가능성을 높인다.
+
+---
+문서 규칙: `DOCS/300_architecture/312_문서_작성_원칙.md` 준수