# Deep Research

> 코드베이스 대상 딥리서치. 조사 주제와 항목 목록을 받아 researcher 서브에이전트를 병렬로 띄우고, 검증 스크립트와 evaluator로 결과를 검증한 뒤 synthesizer가 최종 리포트를 합성한다. 사용자가 딥리서치·심층 조사·병렬 리서치를 요청할 때 사용.

- Skill: `devbrother2024/deep-research` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add devbrother2024/deep-research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/devbrother2024/deep-research/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: devbrother2024 (https://skillmd.com/u/devbrother2024)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/devbrother2024/deep-research

---


# 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 — 준비

1. `mkdir -p {results_dir}`
2. **재개 확인**: `{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 판정 요약)
- 재시도가 있었다면 몇 회, 어떤 항목