연구 문서
체계적인 계층형 연구를 통한 교육 문서 작성 접근 방식.
목적
다음과 같은 심층 설명 문서를 생성합니다:
- 기초부터 특정 내용까지 이해도를 쌓아갑니다.
- 점진적 공개를 통해 독자를 안내합니다.
- 모든 정보에 완전한 인용을 제공합니다.
- 복잡한 정보에는 시각적 요약과 표를 사용합니다.
사용 시기
- 사용자가 시스템이나 기능에 대한 포괄적인 설명을 요청할 때
- 구성 요소가 종단 간 어떻게 작동하는지 문서화해야 할 때
- 아키텍처나 프로세스에 대한 교육 콘텐츠를 만들 때
- "X가 어떻게 작동하는지 설명해줘" 또는 "Y 프로세스가 무엇인가요?"와 같은 질문을 받을 때
간단한 사실 조회의 경우, 대신 fact-find를 사용하세요.
연구 모델: Scout → Decompose → Research → Assemble → Verify
연구는 계층적으로 이루어지며, 한 번에 모든 것을 하지 않습니다. 모든 아티팩트는 파일 시스템에 저장됩니다.
┌─────────────────────────────────────────────────────────────────┐
│ 계층형 연구 모델 │
└─────────────────────────────────────────────────────────────────┘
TIER 0: SCOUT TIER 1: FOCUSED RESEARCH
───────────────── ────────────────────────
┌─────────────┐ ┌─────────────┐
│ 초기 │ │ 하위 질문 │──▶ 인용 답변
│ 질문 │ │ (fact-find) │ (짧게)
└──────┬──────┘ └─────────────┘
│ ┌─────────────┐
▼ │ 하위 질문 │──▶ 인용 답변
┌─────────────┐ Decompose │ (fact-find) │ (짧게)
│ Scout │────────────────▶ └─────────────┘
│ Search │ ┌─────────────┐
└──────┬──────┘ │ 하위 질문 │──▶ 재귀
│ │ (research) │ (자체 scout/decompose)
▼ └─────────────┘
┌─────────────┐ │
│ 다음에 기록: │ ▼
│ planning/ │ ┌─────────────┐
│ <slug>/ │ │ Assemble │──▶ 초안 문서
│ 00-scout.md │ │ from files │
└─────────────┘ └──────┬──────┘
│
▼
┌─────────────┐
│ Verify │──▶ 최종 문서
│ citations │
└─────────────┘
이 방식이 효과적인 이유:
- 에이전트는 작업 중간에 불확실성을 인정하는 데 어려움을 겪습니다. 스카우팅은 출력물을 생성해야 한다는 압박이 있기 전에 먼저 격차를 파악합니다.
- 파일 시스템에 기록하면 여러 에이전트 간의 협업(또는 단일 에이전트 시스템의 컨텍스트 윈도우 리셋)이 가능해집니다.
- 하위 질문을 분류하면 "너무 큰" 질문이 피상적으로 처리되는 것을 방지합니다.
- 검증 단계에서 최종 확정 전에 환각이나 뒷받침되지 않는 주장을 잡아냅니다.
작업 공간 설정
모든 연구 아티팩트는 ./planning/<question-slug>/에 저장됩니다:
./planning/
└── how-twoliter-builds-kits/
├── 00-scout.md # 스카우트 결과 + 하위 질문
├── 01-kit-structure.md # 하위 질문 답변 (fact-find)
├── 02-build-command.md # 하위 질문 답변 (fact-find)
├── 03-buildsys/ # 재귀가 필요했던 하위 질문
│ ├── 00-scout.md
│ ├── 01-spec-parsing.md
│ └── 02-docker-build.md
└── FINAL.md # 조립된 문서
슬러그 형식: 소문자, 하이픈, 설명적 (예: how-twoliter-builds-kits)
다중 에이전트 시스템의 경우
- 리드 에이전트: 스카우트 생성, 스카우트 출력 읽기, 분해, 조립, 검증 조정
- 스카우트 하위 에이전트: 1단계 수행 (검색, 결과 훑어보기,
00-scout.md작성) - 연구 하위 에이전트: 각 하위 질문이 작업이 됩니다. 하위 에이전트는 작업 공간에 답변을 기록합니다.
- 검증자: 인용을 확인하는 가벼운 에이전트 (도구 불필요)
- 하위 에이전트는 자신의 질문이 너무 클 경우 재귀적으로 생성할 수 있습니다 (깊이 제한 있음).
스카우팅을 위임하는 이유: 리드 에이전트의 컨텍스트는 중요합니다. 스카우팅 과정의 원시 검색 결과와 파일 내용은 이를 오염시킬 수 있습니다. 스카우트는 구조화된 결과를 00-scout.md에 작성합니다. 리드는 해당 파일만 읽습니다.
계획/할 일 목록 규율
할 일 목록 기능이 있다면, 이를 사용하여 워크플로우 완료를 강제하세요:
각 단계 전에, 계획에 수행할 작업을 열거하세요:
- 2단계: 스카우트의 각 하위 질문에 대해 하나의 항목, 대상 파일명 포함
- 01-kit-structure.md 작성 (하위 질문 1)
- 02-build-command.md 작성 (하위 질문 2)
- ...
- 4단계: 확인해야 할 각 인용에 대해 하나의 항목
패턴: 열거 → 실행 → 개수 일치 확인
이렇게 하면 "모두 수행" 대신 "일부만 수행"하는 것을 방지합니다. 계획은 계약입니다. "01-kit-structure.md 작성"을 작성했다면 해당 파일을 생성해야 할 의무가 있습니다.
⛔ 안티 패턴: 스카우팅 중에 답변을 모은 다음, 바로 FINAL.md로 건너뛰는 행위. 답을 "알고" 있더라도 개별 파일을 작성하세요. 파일은 검색 가능한 아티팩트입니다.
단일 에이전트 시스템의 경우
계층을 순차적으로 실행하고, 파일 시스템을 "메모리"로 사용하세요:
- 스카우트하고
00-scout.md작성 - 각 하위 질문을 연구하고
01-*.md,02-*.md등 작성 - 모든 파일을 다시 읽고
FINAL.md조립 - 인증 자체 확인 (덜 신뢰할 수 있지만 여전히 가치 있음)
이렇게 하면 필요시 단계 사이에 컨텍스트 윈도우를 리셋할 수 있습니다.
절차
1단계: 스카우트 (범위 파악)
목표: 무엇이 존재하는지 발견하고 올바른 질문을 공식화합니다. 결과를 00-scout.md에 기록합니다.
⚠️ 스카우팅은 연구가 아닙니다. 영역을 탐험하는 것이 아니라 지도를 그리는 것입니다.
mkdir -p ./planning/<question-slug>
# 관련 영역을 찾기 위한 광범위한 검색
crumbly search "system-name overview"
crumbly search "system-name architecture"
상위 2-3개 결과를 구조만 살펴보고 내용은 훑지 마세요:
- 파일 이름과 섹션 제목을 기록하세요.
- 주요 용어와 구성 요소 이름을 식별하세요.
- 상세 정보가 있는 위치를 찾으세요.
- 구현 세부 사항을 읽거나 "작동 방식"을 이해하려고 하지 마세요.
스카우트 출력에는 다음이 포함되어야 합니다:
- 사물의 이름 (파일, 함수, 개념)
- 답변을 찾을 위치
- 물어봐야 할 질문
스카우트 출력에는 다음이 포함되어서는 안 됩니다:
- 질문에 대한 답변
- 구현 세부 사항
- 코드 조각이나 깊은 설명
스카우트를 마치고 "답을 알고 있다"고 느낀다면, 너무 깊이 스카우트한 것입니다. 목표는 정보에 기반한 무지, 즉 자신이 무엇을 모르는지와 그것을 어디서 찾을 수 있는지를 아는 것입니다.
00-scout.md에 캡처:
# Scout: <원래 질문>
## 발견된 주요 개념
- [개념 1]: [간단한 설명]
- [개념 2]: [간단한 설명]
## 발견된 관련 파일
- `path/to/file.md` - [다루는 내용]
- `path/to/code.rs` - [다루는 내용]
## 용어
- [용어]: [이 코드베이스에서 사용되는 정의]
## 하위 질문
### 1. [하위 질문 텍스트]
- **유형:** fact-find | deep-research
- **이유:** [이 분류의 이유]
- **주요 파일:** [이 질문에 답할 가능성이 있는 파일]
### 2. [하위 질문 텍스트]
...
하위 질문 분류:
| 하위 질문이... | 유형 | 조치 |
|---|---|---|
| 구체적이고 명확한 답변이 있음 | fact-find | 1-2 문단으로 답변 |
| "X가 무엇인가" 또는 "Y가 어디에 있는가"를 묻는 경우 | fact-find | 1-2 문단으로 답변 |
| "X가 어떻게 작동하는가"를 묻는 경우 | deep-research | 재귀 (자체 scout/decompose) |
| 여러 구성 요소가 상호 작용하는 경우 | deep-research | 재귀 |
| 답변에 3개 이상의 소스 파일이 필요한 경우 | deep-research | 재귀 |
재귀 확인: 2개 이상의 하위 질문이 deep-research 유형인 경우, 원래 질문이 너무 광범위한지 고려하세요.
깊이 제한: 최대 재귀 깊이는 2레벨입니다. 하위-하위 질문이 자체 재귀를 필요로 하는 경우:
- fact-find 처리를 강제하거나 (덜 깊이를 수용)
- 사람이 검토하도록 플래그를 지정하거나
- 원래 질문을 여러 연구 작업으로 분할하세요.
2단계: 하위 질문 연구
각 하위 질문에 대해 NN-<slug>.md에 작성:
fact-find 하위 질문의 경우:
# <하위 질문>
<인라인 인용을 포함한 직접 답변>
kit 디렉토리에는 `Twoliter.toml` 파일 <sup>[1]</sup>과 패키지를 종속성으로
나열하는 `Cargo.toml`이 포함되어야 합니다 <sup>[2]</sup>.
## 출처
<sup>[1]</sup> [`twoliter/README.md`](../twoliter/README.md) - Kit 요구 사항 섹션
<sup>[2]</sup> [`kits/bottlerocket-core-kit/Cargo.toml`](../kits/bottlerocket-core-kit/Cargo.toml) - Kit 매니페스트 예시
deep-research 하위 질문의 경우:
하위 디렉토리를 만들고 재귀:
./planning/how-twoliter-builds-kits/03-buildsys/
├── 00-scout.md
├── 01-....md
└── FINAL.md
하위 질문의 FINAL.md가 답변이 됩니다.
출처에서 답변할 수 없는 경우:
- "사용 가능한 출처에서 확인할 수 없습니다"라고 작성하세요.
- 검색한 내용을 기록하세요.
- 추측하지 마세요.
2단계 완료 게이트 (필수)
⚠️ 중지: 이 게이트를 통과할 때까지 3단계로 진행하지 마세요.
FINAL.md를 조립하기 전에, 다음을 반드시 수행해야 합니다:
-
작업 공간 파일 나열:
ls -la ./planning/<question-slug>/ -
파일 개수가 하위 질문 개수와 일치하는지 확인:
00-scout.md의 하위 질문 수: NNN-*.md파일 수 (00-scout.md 제외): N이어야 함- 개수가 일치하지 않으면 하위 질문을 건너뛴 것입니다. 돌아가서 수행하세요.
-
계획/할 일 목록에 추가:
- N개의 하위 질문 파일이 작성되었는지 확인
- 파일 나열: 01-X.md ✓, 02-Y.md ✓, ...
이것이 중요한 이유: 하위 질문 파일이 주요 산출물입니다. FINAL.md는 단지 종합일 뿐입니다. 개별 Q&A 파일이 없으면:
- 향후 쿼리에서 연구를 검색할 수 없습니다.
- 각 답변을 독립적으로 확인할 수 없습니다.
- 문서 작성자가 이를 소스 자료로 사용할 수 없습니다.
일반적인 실패 모드: 스카우팅 중에 모든 정보를 수집한 다음, "이미 답을 알고 있기 때문에" 바로 FINAL.md로 건너뛰는 행위. 이는 목적을 무색하게 합니다. 어쨌든 파일을 작성하세요.
3단계: 초안 문서 조립
작업 공간에서 모든 하위 질문 답변을 읽으세요. FINAL.md로 결합:
# [시스템 이름]
**키워드:** keyword1, keyword2, keyword3
## 개요
[전체 시스템을 보여주는 시각적 요약 - 다이어그램 또는 표]
[1-2문장의 맥락]
## [기본 모델]의 작동 방식
[기초에 대한 하위 질문 답변에서 종합]
## [주제]
[핵심 프로세스에 대한 하위 질문 답변에서 종합]
### [하위 주제]
**목표:** [한 문장]
[하위 질문에서 가져온 인용을 포함한 내용]
## 부록: [상세 참조]
[밀집된 세부 사항, 표, 구성 옵션]
## 충돌 및 해결
[출처가 일치하지 않는 경우, 해결 방법을 문서화]
- [주제]: 출처 A는 X라고 하고, 출처 B는 Y라고 함. 해결: [근거]
(충돌이 발견되지 않은 경우 "없음" 작성)
## 출처
[모든 하위 질문의 통합 번호 인용]
작성 지침
개요 섹션:
- 시각 자료 (ASCII 다이어그램, 순서도 또는 요약 표)로 시작하세요.
- 시각 자료 후 최대 2-3문장의 산문
- 독자가 10초 안에 전체 시스템을 파악할 수 있어야 합니다.
표 대 산문:
- 3개 이상의 유사한 항목을 나열하는 경우 → 표 사용
- 산문은 관계를 설명하고, 표는 사실을 나열합니다.
인용:
- 사실과 함께 인라인으로
<sup>[1]</sup>사용 - 모든 사실 주장에는 인용이 필요합니다.
- 마지막에 출처를 통합하세요.
- 조립할 때 인용 번호를 순차적으로 다시 매기세요.
긴 문서 (출력 토큰 제한):
Claude는 응답당 출력 제한(~4K-8K 토큰)이 있습니다. 약 10페이지보다 긴 문서의 경우:
- 섹션별로 작성하고 FINAL.md에 추가하세요.
- 또는 먼저 상세한 개요를 생성한 다음 각 섹션을 별도로 확장하세요.
- 전체 문서를 한 응답으로 생성하려고 하지 마세요.
4단계: 검증
목표: 인용이 주장을 뒷받침하는지 확인합니다. 뒷받침되지 않는 진술을 잡아냅니다.
1단계: 인용 열거 (필수)
검증자를 생성하기 전에, 계획/할 일 목록에 모든 인용을 반드시 열거해야 합니다:
- FINAL.md의 인용 수 세기 (예: 12개 인용)
- 인용당 하나의 계획 항목 추가:
- [1] 확인: "주장 텍스트 미리보기..."
- [2] 확인: "주장 텍스트 미리보기..."
- ... (전체 12개)
- 마지막 항목 추가: "12/12 검증자 완료 확인"
계획에 N+1개의 항목이 있을 때까지 검증자 생성을 진행하지 마세요 (N개 인용 + 확인).
이렇게 하면 "몇 가지 대표 인용만 확인"하고 나머지를 건너뛰는 실패 모드를 방지할 수 있습니다.
2단계: 검증자 생성
다중 에이전트 시스템의 경우:
미리 로드된 컨텍스트로 가벼운 검증자를 생성하세요. 각 검증자에게는 도구가 필요하지 않습니다. 추론만 필요합니다.
인용 검증자 (인용당 하나씩 생성):
프롬프트:
당신은 회의적인 검토자입니다. 당신의 임무는 정확성을 확인하는 것이 아니라 문제를 찾는 것입니다.
주장: "빌드 프로세스는 Twoliter.toml을 로드하는 것으로 시작됩니다"
인용 출처: twoliter/twoliter/src/project/mod.rs
출처 내용:
[파일에서 관련 줄 붙여넣기]
출처 내용이 이 특정 주장을 실제로 뒷받침합니까?
다음 중 하나로 답변하세요:
- SUPPORTED: [출처에서 이를 확인하는 내용에 대한 간략한 설명]
- UNSUPPORTED: [누락되거나 잘못된 내용]
- PARTIAL: [확인된 내용과 그렇지 않은 내용]
회의적으로 임하세요. 출처가 우회적으로 관련되어 있지만 주장을 직접적으로
명시하지 않는 경우, PARTIAL 또는 UNSUPPORTED입니다.
인용되지 않은 주장 탐지기 (문서 섹션당 한 번씩 생성):
프롬프트:
당신은 회의적인 검토자입니다. 당신의 임무는 문제를 찾는 것입니다.
섹션:
[섹션 텍스트 붙여넣기]
인용 <sup>[N]</sup>이 누락된 사실적 주장을 찾으세요.
사실적 주장에는 다음이 포함됩니다: 파일 경로, 동작 설명,
구성 값, 구성 요소 이름, 프로세스 단계.
의견, 전환, 요약에는 인용이 필요하지 않습니다.
발견한 각 인용되지 않은 주장을 나열하세요. 모든 문장을 확인하지 않고서는
"좋아 보임" 또는 "발견되지 않음"이라고 말하지 마세요. 아무것도 찾지 못한 경우,
인용되지 않은 주장이 없음을 확인하기 위해 무엇을 확인했는지 설명하세요.
이것들을 일괄 처리하세요: spawn_batch를 사용하여 모든 인용 검증자를 병렬로 실행하세요. 배치 크기는 인용 횟수와 같아야 합니다.