fable-deepresearch — 2단계 검증형 딥리서치 파이프라인

여러 발표·강의·보고서·콘텐츠 준비 세션에서 확립한 방식을 재현 가능한 절차로 옮긴 것이다. 핵심 사상: "조사 → 초안"이 아니라 "광각 조사 → 초안 → 정밀 재검증 → 수정"의 2패스. 1차 조사가 아무리 좋아도 초안에 들어간 사실은 시점이 다르거나(stale) 출처가 벤더 마케팅일 수 있으므로, 산출물 확정 전에 반드시 공식 문서 직독 기반의 전수 검증을 한 번 더 돌린다.

전체 흐름

Phase 0  질문 정제 (필수 커버 항목 번호 목록화)
Phase 1  광각: deep-research 워크플로 실행 → 결과 심층 추출 → 개인 자산 연결
   ↓     (사용자에게 1차 산출물 — 목차/뼈대/보고서 — 전달, 피드백 수령)
Phase 2  정밀: 커스텀 워크플로 = 팁 발굴 에이전트 N개 + 사실 전수검증 에이전트 M개 (병렬)
Phase 3  종합: verdict 반영 수정 + 팁 뱅크 생성 + 버전 산출물 + 보존/전달

Phase 1과 2는 워크플로가 백그라운드로 도는 동안 다른 준비 작업(지식 허브 확인, 파일 구조 준비)을 병행한다.

Phase 0 — 질문 정제 (품질의 절반이 여기서 결정된다)

사용자 요청을 하나의 리서치 질문 문단으로 재작성하라. 반드시 포함할 것:

1. 용도와 형식: "30분 발표 준비용", "기고문 초안용", "의사결정 보고서용" 등 — 조사 깊이와 각도가 여기 맞춰진다
2. 필수 커버 항목을 번호 목록으로 (실전에서 5개가 적당): deep-research의 Scope 단계가 질문을 5개 검색 각도로 분해하는데, 커버 항목이 번호로 명시돼 있어야 각도가 사용자 요구와 정렬된다
3. 최종 보고서 언어 ("한국어로 최종 보고서 작성")
4. 사용자가 강조한 것(예: "실패 사례 예방")은 항목으로 승격 + "네가 추천하는 추가 주제"류 열린 항목 1개

질문이 불명확하면(대상/범위/용도 미상) 조사 시작 전에 2~3개만 물어라. 명확하면 바로 실행.

예시 (이 형식을 따르라 — <제품/주제>를 실제 대상으로 치환):

<제품/주제>의 <핵심 기능/영역>을 "잘 쓰는 법"에 대한 30분 발표 준비용 심층 조사. 필수 커버 항목: (1) 최근 1~2년 공식 발표 내용 및 로드맵, (2) 본질적으로 이해해야만 알 수 있는 실전 꿀팁 — 셋팅, 프롬프트, 용어, (3) 실무자들이 도움된다고 평가한 사례와 한계, (4) 실패 사례의 원인과 예방법, (5) 발표에 포함하면 좋을 추가 주제 추천. 한국어로 최종 보고서 작성.

Phase 1 — 광각: deep-research 워크플로

Workflow({ name: "deep-research", args: "<Phase 0에서 정제한 질문>" })

백그라운드로 실행된다. 구조(참고): Scope(5각도 분해) → Search(각도별 병렬 WebSearch) → Fetch(URL dedup 후 상위 소스 정독, 반증 가능한 클레임 추출) → Verify(클레임당 3표 적대적 검증, 2/3 반박 시 킬) → Synthesize(중복 병합, 신뢰도 순위, 인용 부착).

기다리는 동안 할 일

• 개인 자산 연결: 사용자의 지식 허브에서 주제 관련 기존 자산(경험담, 과거 글, 자격)을 확인해 산출물의 "개인 경험" 슬롯 후보를 만든다. grep -il '키워드' ~/.claude/knowledge/summaries/*.jsonl (이 경로가 없으면 생략)
• dev docs 폴더 준비: dev/active/{task-name}/

완료 후 반드시 할 3가지 (가장 흔한 실수 방지)

1. 알림의 result는 잘려 있다 — 반드시 output 파일 전체를 확인하라. 파일이 크면(9만 토큰급) Read 페이지네이션 대신 python으로 구조 추출이 빠르다:

   python3 -c "import json; d=json.load(open('<task-output-file>')); r=d['result']; ..."

2. journal.jsonl에 최종 종합에서 탈락한 디테일이 많다 — 특정 세부(지원 목록, 수치, 절차)가 필요하면 워크플로 transcript 디렉토리의 journal에서 grep으로 클레임을 캐라:

   grep -o '"claim":"[^"]*\(키워드1\|키워드2\)[^"]*"' journal.jsonl | sort -u

   실전에서 '지원 항목 전체 목록', '단계 수 제한' 같은 발표의 핵심 디테일이 전부 여기서 나왔다.
3. caveats와 openQuestions를 사용자에게 그대로 전달하라 — 특히 "검증 통과한 커뮤니티/독립 소스 없음" 같은 커버리지 공백은 숨기지 말고 "이 부분은 본인 경험/직접 테스트로 채우는 게 최선"이라고 안내한다. 이것이 신뢰를 만든다.

1차 산출물

• dev/active/{task}/research-report.md: 조사 방법 요약(각도 수·소스 수·검증 통계) + 주제별 구조화된 findings(수치·verbatim 인용 포함) + 검증 한계 & 오픈 퀘스천 + 주요 소스 목록
• 사용자 요청 형식의 초안(목차/뼈대 등)을 만들어 전달하고 피드백을 받는다

Phase 2 — 정밀: 팁 발굴 + 사실 전수검증 커스텀 워크플로

발동 시점: 초안에 피드백이 왔을 때, 또는 "팁을 더 상세하게", "사실인지 점검해" 요구가 있을 때. 처음부터 Phase 1과 별도로 예약해 두는 것을 권한다 — 1패스 조사만으로 산출물을 확정하지 마라.

템플릿: references/phase2-workflow-template.js 를 읽고 주제에 맞게 치환해서 Workflow({script})로 실행하라. 핵심 설계 원칙:

팁 발굴 에이전트 (영역별 N개, 권장 5~7개)

• 영역은 제품 표면/사용자 여정 단위로 쪼갠다 (예: 저작/데이터준비/자동화/공유/관리자/API 등 대상별로)
• 스키마에 wow_factor 필드를 강제하라 — "실무자가 '오 이런것도?' 할 이유"를 쓰게 하면 기능 소개 수준의 밋밋한 팁이 걸러진다. 이 필드가 팁 품질을 결정한다
• 스키마에 verified_2026(현재 연도) boolean을 두어 "현재 공식 문서로 확인했는가"를 자기 신고하게 한다 — 낡은 블로그 지식 차단 장치
• 프롬프트에 읽을 공식 문서 URL을 직접 지정하라 ("반드시 조사할 것: help.x.com/..."). 검색부터 시키면 블로그 요약을 읽고 끝낸다. "WebFetch로 원문을 직접 읽어라"를 명시
• detail은 "설정 경로·정확한 수치·프롬프트 예시 포함 2~5문장"으로 요구 — 한 줄 팁 금지

사실 전수검증 에이전트 (클레임 그룹별 M개, 실전 12개)

• 초안의 모든 사실 주장을 추출해 주제별 그룹으로 묶어 배분한다 (그룹당 에이전트 1개)
• 스키마: {claim, verdict: confirmed|outdated|wrong|unclear, current_state, source}
• 프롬프트 핵심 3가지:
  1. "복합 주장을 개별 result로 쪼개서 판정하라" — 실전에서 12개 그룹이 58개 개별 판정으로 분해되며 "문장 안의 절반만 틀린" 경우를 잡아냈다
  2. "반드시 공식 문서 원문을 WebFetch로 직접 읽고 판단하라"
  3. "현재 문서에서 확인 불가면 unclear" — 이것이 구버전 자료에서 유래한 유령 주장(예: 예전엔 맞았지만 지금은 지원되는 'X 미지원' 류)을 걸러내는 장치다. unclear는 wrong이 아니라 단정 금지 신호
• 시점 명시: "202X년 X월 현재 기준" + "오래된 자료(1~2년 전)는 현재 문서와 대조하라"

공통 프리앰블 (COMMON)

모든 에이전트 프롬프트 앞에 공유: 역할(무슨 산출물을 위한 리서처인지), 소스 우선순위 (공식 help 문서 > 공식 블로그/릴리스 노트 > 벤더 보도자료 > 커뮤니티), 시점 규칙.

실행 형태

두 배치는 독립이므로 Promise.all([parallel(팁...), parallel(검증...)])로 동시 실행. 스키마(schema 옵션)를 반드시 걸어라 — 자유 텍스트로 받으면 후처리가 무너진다.

Phase 3 — 종합·보존·전달

verdict 반영 규칙

산출물에 '사실 검증 반영 내역(v1→v2)' 섹션을 남겨라 — 무엇이 확정/수정/제외됐는지. 후속 작업자(슬라이드 제작 등)를 위한 금지 표현 목록도 여기서 나온다.

팁 뱅크 생성 (수작업 금지)

워크플로 JSON 출력을 python으로 markdown 변환해 전량 보존하라 — 손으로 옮기면 출처가 유실된다:

python3 -c "
import json
d = json.load(open('<task-output-file>'))
# tips 딕셔너리를 영역별 섹션으로, 각 팁은 [검증마크] 제목 / detail / wow_factor / 출처 형식으로
# facts 중 비확정 건은 '수정 사항' 섹션으로 상단 배치
" # → dev/active/{task}/tips-bank.md

파일 셋 (dev/active/{task}/)

• research-report.md — Phase 1 구조화 보고서
• tips-bank.md — Phase 2 팁 전량 + 사실검증 결과 (후속 제작의 사실의 유일한 출처로 선언)
• {산출물}-v1.md, -v2.md ... — 버전 유지, v간 변경 내역 명시
• (후속 작업을 다른 에이전트에 넘길 경우) {작업}-instructions.md — 자기완결 지시서: 입력 파일 표, 글쓰기 규칙, 금지 표현, 섹션별 지시, QA 절차, 미결 사항(사용자 확인 필요 항목)

전달

• 파일 생성 후 open + open -R (사용자 글로벌 규칙), SendUserFile로 파일 전송
• 최종 메시지 구조: 결과 선행(검증 통계 "58건 중 55건 확정") → 요청사항별 반영 내역 → '와' 포인트 하이라이트 몇 개(전체 나열 금지) → 검증에서 잡아낸 것 → 남은 오픈 퀘스천/다음 단계

품질 원칙 (회고에서 배운 것)

• 벤더 주장 라벨링: '세계 최초', 'N백만 사용자' 등 검증 불가 마케팅 수치는 반드시 "벤더 발표 기준" 표기를 산출물까지 관철하라
• 시점 민감성: forward-looking 일정(로드맵)은 "예정, 변경 가능" 표기 + "발표/발행 직전 재확인" 항목을 산출물에 남겨라. 조사 기준일을 모든 문서 상단에 박아라
• verbatim 증거: 핵심 수치·제약은 원문 인용(영어 그대로)을 evidence로 보존하라 — 나중에 "이거 어디서 나왔어?"에 즉답할 수 있어야 한다
• 커버리지 공백의 정직한 처리: 검증 통과 소스가 없는 영역(커뮤니티 후기 등)은 지어내지 말고 사용자의 직접 경험/테스트로 채우도록 안내
• 뉘앙스 구분: '작성 vs 조회', 'GA vs 베타', '클라우드 vs 온프레미스' 같은 이분 구분이 무너지면 사실이 틀려진다 — 검증 에이전트 프롬프트에 구분 확인을 명시하라

흔한 함정 (실전에서 밟았거나 밟을 뻔한 것)

1. 알림 result만 보고 종합 → 잘린 결과로 작업하게 됨. 반드시 output 파일 원본 확인
2. journal.jsonl 무시 → 종합에서 탈락한 핵심 디테일(목록·수치) 유실
3. 1~2년 전 커뮤니티 글을 사실로 채택 → Phase 2 검증에서 unclear/outdated로 걸러지지만, Phase 2를 생략하면 그대로 산출물에 남는다. Phase 2를 생략하지 마라
4. 팁이 기능 소개 수준 → wow_factor 필드 + "비자명한 팁" 기준 + 읽을 문서 직접 지정으로 해결
5. 산출물에 검증 내역 미기록 → 후속 작업자가 탈락한 주장을 다시 넣는 사고
6. Workflow 도구가 없는 환경 → 같은 구조를 Agent 도구 병렬 호출로 대체 (팁 N개 + 검증 M개를 한 메시지에 동시 스폰, 스키마 대신 출력 형식을 프롬프트로 강제)