Documento de Pesquisa
Uma abordagem sistemática para criar documentação educacional através de pesquisa em níveis.
Propósito
Cria documentos explicativos aprofundados que:
- Constroem entendimento desde fundamentos até especificidades
- Usam divulgação progressiva para guiar o leitor
- Fornecem citações completas para todas as informações
- Usam resumos visuais e tabelas para informações densas
Quando Usar
- O usuário pede explicações abrangentes de sistemas ou funcionalidades
- Precisa documentar como componentes funcionam do início ao fim
- Criando conteúdo educacional sobre arquitetura ou processos
- Perguntas como "Explique como X funciona" ou "Qual é o processo Y?"
Para consultas rápidas de fatos, use fact-find em vez disso.
Modelo de Pesquisa: Scout → Decompor → Pesquisar → Montar → Verificar
A pesquisa acontece em níveis, não de uma vez. Todos os artefatos vão para o sistema de arquivos.
┌─────────────────────────────────────────────────────────────────┐
│ MODELO DE PESQUISA EM NÍVEIS │
└─────────────────────────────────────────────────────────────────┘
NÍVEL 0: SCOUT NÍVEL 1: PESQUISA FOCADA
───────────────── ────────────────────────
┌─────────────┐ ┌─────────────┐
│ Pergunta │ │Sub-pergunta │──▶ Resposta citada
│ Inicial │ │ (fact-find) │ (curta)
└──────┬──────┘ └─────────────┘
│ ┌─────────────┐
▼ │Sub-pergunta │──▶ Resposta citada
┌─────────────┐ Decompor │ (fact-find) │ (curta)
│ Scout │────────────────▶ └─────────────┘
│ Busca │ ┌─────────────┐
└──────┬──────┘ │Sub-pergunta │──▶ RECURSÃO
│ │ (pesquisa) │ (próprio scout/decompor)
▼ └─────────────┘
┌─────────────┐ │
│ Escrever em:│ ▼
│ planejamento/│ ┌─────────────┐
│ <slug>/ │ │ Montar │──▶ Rascunho do documento
│ 00-scout.md │ │ de arquivos │
└─────────────┘ └──────┬──────┘
│
▼
┌─────────────┐
│ Verificar │──▶ Documento final
│ citações │
└─────────────┘
Por que isso funciona:
- Agentes têm dificuldade em admitir incerteza durante a tarefa. O scouting primeiro identifica lacunas antes da pressão para produzir saída.
- Escrever no sistema de arquivos permite colaboração entre agentes (ou reinicializações de contexto para sistemas mono-agente).
- Classificar sub-perguntas evita que perguntas "muito grandes" recebam tratamento superficial.
- A verificação captura alegações alucinadas ou não suportadas antes de finalizar.
Configuração do Workspace
Todos os artefatos de pesquisa vão para ./planning/<slug-da-pergunta>/:
./planning/
└── como-twoliter-constrói-kits/
├── 00-scout.md # Descobertas do scout + sub-perguntas
├── 01-estrutura-kit.md # Resposta da sub-pergunta (fact-find)
├── 02-comando-build.md # Resposta da sub-pergunta (fact-find)
├── 03-buildsys/ # Sub-pergunta que precisou de recursão
│ ├── 00-scout.md
│ ├── 01-analise-spec.md
│ └── 02-docker-build.md
└── FINAL.md # Documento montado
Formato do slug: letras minúsculas, hífens, descritivo (ex.: como-twoliter-constrói-kits)
Para Sistemas Multi-Agente
- Agente líder: Invoca scout, lê saída do scout, decompõe, monta, coordena verificação
- Subagente scout: Realiza a Fase 1 (buscas, examina resultados, escreve
00-scout.md) - Subagentes de pesquisa: Cada sub-pergunta vira uma tarefa; subagente escreve resposta no workspace
- Verificadores: Agentes leves que verificam citações (sem ferramentas necessárias)
- Subagentes podem recursivamente invocar se sua pergunta for muito grande (até limite de profundidade)
Por que delegar o scouting: O contexto do agente líder é valioso. Resultados brutos de busca e conteúdos de arquivos do scouting o poluiriam. O scout escreve descobertas estruturadas em 00-scout.md; o líder lê apenas esse arquivo.
Disciplina de Plano/Lista de Tarefas
Se você tem funcionalidade de lista de tarefas, use-a para garantir a conclusão do fluxo de trabalho:
Antes de cada fase, enumere o trabalho no seu plano:
- Fase 2: Um item por sub-pergunta do scout, com nome do arquivo alvo
- Escrever 01-estrutura-kit.md (sub-pergunta 1)
- Escrever 02-comando-build.md (sub-pergunta 2)
- ...
- Fase 4: Um item por citação a verificar
O padrão: Enumerar → Executar → Confirmar que a contagem corresponde
Isso evita "fazer alguns" em vez de "fazer todos." O plano é um contrato—uma vez que você escreveu "Escrever 01-estrutura-kit.md", está comprometido a criar esse arquivo.
⛔ Antipadrão: Coletar respostas durante o scouting e depois pular para FINAL.md. Mesmo que você "saiba" as respostas, escreva os arquivos individuais. Eles são os artefatos pesquisáveis.
Para Sistemas Mono-Agente
Execute os níveis sequencialmente, usando o sistema de arquivos como sua "memória":
- Scout e escreva
00-scout.md - Pesquise cada sub-pergunta, escrevendo
01-*.md,02-*.md, etc. - Leia todos os arquivos de volta e monte
FINAL.md - Auto-verifique as citações (menos confiável, mas ainda valioso)
Isso permite reinicializações de contexto entre fases, se necessário.
Procedimento
Fase 1: Scout (Conhecer a Forma)
Objetivo: Descobrir o que existe e formular as perguntas certas. Escreva as descobertas em 00-scout.md.
⚠️ Scouting NÃO é pesquisa. Você está mapeando o território, não explorando-o.
mkdir -p ./planning/<slug-da-pergunta>
# Busca ampla para encontrar áreas relevantes
crumbly search "visão geral do sistema"
crumbly search "arquitetura do sistema"
Examine 2-3 resultados principais pela estrutura, não pelo conteúdo:
- Anote nomes de arquivos e cabeçalhos de seções
- Identifique termos-chave e nomes de componentes
- Descubra onde informações detalhadas estão localizadas
- NÃO leia detalhes de implementação ou tente entender "como funciona"
A saída do scout deve conter:
- Nomes de coisas (arquivos, funções, conceitos)
- Onde procurar respostas
- Perguntas a fazer
A saída do scout NÃO deve conter:
- Respostas para as perguntas
- Detalhes de implementação
- Trechos de código ou explicações profundas
Se você terminar o scouting e sentir que "sabe a resposta", scoutou muito fundo. O objetivo é ignorância informada—saber o que você não sabe e onde encontrar.
Capture em 00-scout.md:
# Scout: <Pergunta Original>
## Conceitos-Chave Descobertos
- [Conceito 1]: [Breve descrição]
- [Conceito 2]: [Breve descrição]
## Arquivos Relevantes Encontrados
- `caminho/para/arquivo.md` - [O que cobre]
- `caminho/para/codigo.rs` - [O que cobre]
## Terminologia
- [Termo]: [Definição como usada neste código]
## Sub-Perguntas
### 1. [Texto da sub-pergunta]
- **Tipo:** fact-find | deep-research
- **Por quê:** [Por que esta classificação]
- **Arquivos-chave:** [Arquivos que provavelmente respondem]
### 2. [Texto da sub-pergunta]
...
Classificação de sub-perguntas:
| Se a sub-pergunta... | Tipo | Ação |
|---|---|---|
| Tem uma resposta concreta e específica | fact-find | Responder em 1-2 parágrafos |
| Pergunta "o que é X" ou "onde está Y" | fact-find | Responder em 1-2 parágrafos |
| Pergunta "como X funciona" | deep-research | Recursão (próprio scout/decompor) |
| Envolve múltiplos componentes interagindo | deep-research | Recursão |
| Precisaria de 3+ arquivos fonte para responder | deep-research | Recursão |
Verificação de recursão: Se mais de 2 sub-perguntas são do tipo deep-research, considere se a pergunta original é muito ampla.
Limite de profundidade: A profundidade máxima de recursão é de 2 níveis. Se uma sub-sub-pergunta precisaria de sua própria recursão, ou:
- Force a tratamento fact-find (aceite menos profundidade)
- Sinalize para revisão humana
- Divida a pergunta original em múltiplas tarefas de pesquisa
Fase 2: Pesquisar Sub-Perguntas
Para cada sub-pergunta, escreva em NN-<slug>.md:
Para sub-perguntas fact-find:
# <Sub-Pergunta>
<Resposta direta com citações inline>
O diretório do kit deve conter um arquivo `Twoliter.toml` <sup>[1]</sup> e um `Cargo.toml`
que lista pacotes como dependências <sup>[2]</sup>.
## Fontes
<sup>[1]</sup> [`twoliter/README.md`](../twoliter/README.md) - Seção de requisitos do kit
<sup>[2]</sup> [`kits/bottlerocket-core-kit/Cargo.toml`](../kits/bottlerocket-core-kit/Cargo.toml) - Exemplo de manifesto do kit
Para sub-perguntas deep-research:
Crie um subdiretório e recorra:
./planning/como-twoliter-constrói-kits/03-buildsys/
├── 00-scout.md
├── 01-....md
└── FINAL.md
O FINAL.md da sub-pergunta se torna a resposta.
Se você não puder responder a partir das fontes:
- Escreva "Não foi possível determinar a partir das fontes disponíveis"
- Anote o que você pesquisou
- NÃO adivinhe
Portão de Conclusão da Fase 2 (OBRIGATÓRIO)
⚠️ PARE: Não prossiga para a Fase 3 até que este portão passe.
Antes de montar o FINAL.md, você DEVE:
-
Liste os arquivos do workspace:
ls -la ./planning/<slug-da-pergunta>/ -
Verifique se a contagem de arquivos corresponde à contagem de sub-perguntas:
- Contagem de sub-perguntas em
00-scout.md: N - Contagem de arquivos
NN-*.md(excluindo 00-scout.md): deve ser N - Se as contagens não corresponderem, você pulou sub-perguntas. Volte.
- Contagem de sub-perguntas em
-
Adicione ao seu plano/lista de tarefas:
- Confirmar N arquivos de sub-perguntas escritos
- Listar arquivos: 01-X.md ✓, 02-Y.md ✓, ...
Por que isso importa: Os arquivos de sub-perguntas são a entrega principal. O FINAL.md é apenas uma síntese. Sem arquivos individuais de P&R:
- A pesquisa não é pesquisável por consultas futuras
- Você não pode verificar cada resposta independentemente
- O escritor do documento não pode usá-los como material fonte
Modo de falha comum: Coletar todas as informações durante o scouting, depois pular direto para FINAL.md porque "eu já sei as respostas." Isso derrota o propósito—escreva os arquivos de qualquer maneira.
Fase 3: Montar Rascunho do Documento
Leia todas as respostas das sub-perguntas do workspace. Combine em FINAL.md:
# [Nome do Sistema]
**Palavras-chave:** palavra-chave1, palavra-chave2, palavra-chave3
## Visão Geral
[Resumo visual - diagrama ou tabela mostrando o sistema inteiro]
[1-2 frases de contexto]
## Como [Modelo Subjacente] Funciona
[Sintetize a partir das respostas das sub-perguntas sobre fundamentos]
## [Tópico Principal]
[Sintetize a partir das respostas das sub-perguntas sobre o processo central]
### [Subtópico]
**Objetivo:** [Uma frase]
[Conteúdo com citações trazidas das sub-perguntas]
## Apêndice: [Referência Detalhada]
[Detalhes densos, tabelas, opções de configuração]
## Conflitos e Resoluções
[Se as fontes discordaram, documente como você resolveu]
- [Tópico]: Fonte A disse X, Fonte B disse Y. Resolução: [raciocínio]
(Escreva "Nenhum" se nenhum conflito for encontrado)
## Fontes
[Citações numeradas consolidadas de todas as sub-perguntas]
Diretrizes de Escrita
Seção de Visão Geral:
- Comece com um visual (diagrama ASCII, fluxograma ou tabela resumida)
- Máximo de 2-3 frases de prosa após o visual
- O leitor deve compreender o sistema inteiro em 10 segundos
Tabelas vs prosa:
- Se listar 3+ itens semelhantes → use uma tabela
- Prosa explica relacionamentos; tabelas listam fatos
Citações:
- Use
<sup>[1]</sup>inline com fatos - Cada afirmação factual precisa de uma citação
- Consolide as fontes no final
- Ao montar, renumerar as citações sequencialmente
Documentos longos (limites de tokens de saída):
Claude tem limites de saída (~4K-8K tokens por resposta). Para documentos com mais de ~10 páginas:
- Escreva seção por seção, anexando ao FINAL.md
- Ou: gere um esboço detalhado primeiro, depois expanda cada seção separadamente
- Não tente gerar o documento inteiro em uma resposta
Fase 4: Verificar
Objetivo: Confirmar que as citações suportam suas afirmações. Capturar afirmações não suportadas.
Passo 1: Enumerar Citações (OBRIGATÓRIO)
Antes de invocar qualquer verificador, você DEVE enumerar todas as citações no seu plano/lista de tarefas:
- Conte as citações no FINAL.md (ex.: 12 citações)
- Adicione um item de plano por citação:
- Verificar [1]: "pré-visualização do texto da afirmação..."
- Verificar [2]: "pré-visualização do texto da afirmação..."
- ... (todas as 12)
- Adicione o item final: "Confirmar 12/12 verificadores concluídos"
NÃO prossiga para invocar até que seu plano tenha N+1 itens (N citações + confirmação).
Isso evita o modo de falha de "verificar algumas citações representativas" em vez de todas elas.
Passo 2: Invocar Verificadores
Para Sistemas Multi-Agente:
Invoque verificadores leves com contexto pré-carregado. Cada verificador NÃO precisa de ferramentas—apenas raciocínio.
Verificador de Citação (invoque um por citação):
Prompt:
Você é um revisor cético. Seu trabalho é encontrar problemas, não confirmar correção.
ALEGAÇÃO: "O processo de build começa carregando Twoliter.toml"
FONTE CITADA: twoliter/twoliter/src/project/mod.rs
CONTEÚDO DA FONTE:
[cole linhas relevantes do arquivo]
O conteúdo da fonte realmente SUPORTA esta alegação específica?
Responda com um de:
- SUPORTADO: [breve explicação do que na fonte confirma isso]
- NÃO SUPORTADO: [o que está faltando ou errado]
- PARCIAL: [o que é confirmado vs o que não é]
Seja cético. Se a fonte é tangencialmente relacionada, mas não afirma diretamente
a alegação, isso é PARCIAL ou NÃO SUPORTADO.
Detector de Alegação Não Citada (invoque uma vez por seção do documento):
Prompt:
Você é um revisor cético. Seu trabalho é encontrar problemas.
SEÇÃO:
[cole o texto da seção]
Encontre afirmações factuais que carecem de uma citação <sup>[N]</sup>.
Afirmações factuais incluem: caminhos de arquivo, descrições de comportamento,
valores de configuração, nomes de componentes, etapas de processo.
Opiniões, transições e resumos não precisam de citações.
Liste cada alegação não citada que encontrar. NÃO diga "parece bom" ou "nenhuma encontrada"
a menos que você tenha verificado cada frase. Se você não encontrar nada, explique
o que você verificou para confirmar que não há alegações não citadas.
Agrupe estes: Use spawn_batch para executar todos os verificadores de citação em paralelo. O tamanho do lote DEVE ser igual à contagem de citações.