devbrother2024 Deep Research — 코드베이스 딥리서치 오케스트레이션
메인 에이전트(너)는 이 절차의 지휘자다. 조사·판정·합성은 전부 서브에이전트가 한다. 너는 결과 파일의 본문을 읽지 않는다 — 경로와 검증 결과만 다룬다.
입력
{topic}: 조사 주제 (사용자 요청에서 추출){items}: 조사 항목 목록 (사용자가 준 항목. 없으면 주제를 3~5개 항목으로 분해해 사용자에게 확인){results_dir}:.agents/context/deep-research/results(고정){report_path}:.agents/context/deep-research/report.md(고정)
산출물을 .agents/context/ 아래에 두는 이유: 이 자리가 에이전트 산출물의 통제소라는 컨벤션을 따르기 위해서다. 프로젝트에 이미 다른 컨벤션이 있으면 {results_dir}/{report_path}를 그에 맞게 바꿔도 된다 — 다만 한 번 정하면 Step 0~5에서 일관되게 써야 한다.
Step 0 — 준비
mkdir -p {results_dir}- 재개 확인:
{results_dir}에 이미 존재하는 항목 결과 파일은 건너뛴다. 남은 항목만 조사한다.
Step 1 — 리서처 fan-out
남은 항목마다 researcher 서브에이전트를 하나씩 병렬로 띄운다.
- 동시 실행 한도를 넘어 spawn이 실패하면, 실행 중인 에이전트가 끝나기를 기다렸다가 남은 항목을 이어서 띄운다.
- 아래 프롬프트를 변수만 치환해 그대로 사용한다. 구조와 문구를 수정하지 않는다.
## 조사 항목
{item_name}: {item_description}
## 조사 주제 맥락
{topic}
## 출력 파일
{results_dir}/{item_slug}.md
이 저장소의 코드를 직접 읽어 조사하고, 에이전트 지침의 결과 파일 형식대로 위 경로에 저장하라.
결론마다 근거(파일:줄번호)를 붙이고, 확신이 없으면 [미검증]으로 표시하라.
{item_slug}: 항목 이름을 소문자·하이픈으로 변환 (예: "상태 관리" → state-management... 한글이면 item-1, item-2 순번 사용)
Step 2 — 기계 검증 (스크립트)
모든 리서처가 끝나면, 이 SKILL.md와 같은 디렉토리에 있는 검증 스크립트를 실행한다:
python3 {이 스킬 디렉토리}/scripts/validate_research.py --results-dir {results_dir} --repo-root .
- 스크립트는 ① 결론마다 출처 표기가 있는지 ② 인용된 파일:줄번호가 실제 존재하는지 검사한다.
- FAIL인 파일이 있으면: 해당 파일을 삭제하고 그 항목의 리서처만 다시 띄운다. 재실행 프롬프트에는 검증 실패 메시지를 덧붙인다. 최대 2회 재시도. 그래도 FAIL이면 그 항목은 "검증 실패"로 리포트에 남긴다.
Step 3 — 판단 검증 (evaluator)
evaluator 서브에이전트를 띄워 아래 프롬프트로 검증시킨다. 변수만 치환해 그대로 사용한다. (evaluator 에이전트가 없는 환경이면 이 단계를 건너뛰고, 최종 보고에 "판단 검증 생략"을 명시한다.)
{results_dir}/ 안의 리서치 결과 파일들을 검증하라.
각 결론이 인용한 근거(파일:줄번호)를 직접 열어 읽고, 결론이 그 근거로 실제 뒷받침되는지 판정하라.
근거가 결론을 뒷받침하지 못하는 항목을 [파일명] [결론] [이유] 형식으로 보고하라.
코드와 결과 파일을 수정하지 말고 판정만 반환하라.
- evaluator가 "뒷받침 안 됨"으로 판정한 결론이 있으면 해당 항목 리서처를 판정 사유와 함께 1회 재실행한다.
Step 4 — 합성 (synthesizer)
synthesizer 서브에이전트를 띄운다. 변수만 치환해 그대로 사용한다.
## 주제
{topic}
## 입력 파일
{results_dir}/ 안의 모든 .md 파일
## 출력 파일
{report_path}
입력 파일들을 읽어 에이전트 지침의 리포트 형식대로 합성하라.
원본의 근거 표기와 [미검증] 표시를 유지하라.
Step 5 — 보고
사용자에게 다음만 보고한다 (결과 파일 본문을 읽어 요약하지 않는다):
- 리포트 경로:
{report_path} - 항목별 검증 결과 (기계 검증 PASS/FAIL, evaluator 판정 요약)
- 재시도가 있었다면 몇 회, 어떤 항목