O loop abre com uma jogada que decide tudo o que vem depois: olhar. Antes de mudar qualquer coisa, leia o estado atual, o escopo e as fontes confiáveis — e inspecione os artefatos reais com os seus próprios olhos. O jeito mais barato de arruinar um ciclo inteiro é partir de um palpite.
Leia a versão simples, ou abra a camada técnica em qualquer seção.
1
A grande ideia: olhe antes de saltar
Cada volta do loop tem cinco passos — LEARN → ANALYZE → EXECUTE uma unidade delimitada → VERIFY no limite real → DECIDE. Esta lição é sobre o primeiro. LEARN significa parar e descobrir como as coisas realmente estão agora mesmo antes de tocar em qualquer coisa.
Isso parece óbvio, e é exatamente o passo que as pessoas pulam. Sob pressão de tempo, é tentador lembrar como o código costumava ser, imaginar o que o arquivo provavelmente diz e começar a digitar. O loop proíbe isso. Você lê o estado atual, relê o escopo (o "pronto" mensurável da lição anterior), traz as fontes confiáveis de que precisa e abre os artefatos reais — o arquivo, o log, a saída do teste, a página — antes de decidir uma única coisa.
Por que tão rígido? Porque um palpite no início envenena todos os passos depois dele. Você vai analisar uma lacuna que não existe, executar uma mudança contra um arquivo que já não corresponde à sua memória e "verificar" contra a coisa errada. Uma suposição ruim no passo 1 pode queimar um ciclo inteiro. Alguns segundos de observação são o seguro mais barato que você vai comprar na vida.
Mais uma regra que vale por todo este curso: quando o LEARN precisa de um fato do mundo externo — um número de versão atual, o que uma ferramenta de fato faz, se algo ainda é verdade — você não recorre à memória e torce. Você o obtém de uma fonte confiável. Neste conjunto, os fatos vivos da web sempre vêm da Bright Data CLI (você vai conhecê-la na lição 11), nunca de um palpite, e nunca de uma lembrança defasada.
Pense nisso como… um cirurgião antes da primeira incisão. Ele não opera pelo prontuário que lembra da semana passada — ele re-examina o paciente hoje, confirma o local, conta os instrumentos. Olhar não é um atraso antes do trabalho "de verdade"; ele é o trabalho que torna o resto seguro. Onde a analogia falha: um cirurgião olha uma vez; no loop você faz LEARN de novo no início de cada passada, porque o estado mudou no instante em que você o tocou pela última vez.
O que "estado" significa com precisão
Estado é tudo de que a próxima decisão depende, e é mais do que "o código". Inclui o artefato que você pretende mudar (conteúdo do arquivo, corpos de função atuais, config), o limite que vai julgar a mudança (resultados de teste, um processo em execução, uma resposta HTTP, um build), o contrato de escopo (o done-when) e quaisquer fatos externos em que o trabalho se apoia (a API real de uma biblioteca, um preço atual, uma especificação). O LEARN lê os quatro — não apenas os que você por acaso lembra.
Ler, não rodar ainda o ciclo
O LEARN é estritamente observacional. Você não está fazendo uma mudança aqui e ainda não está decidindo qual será a mudança — isso é o ANALYZE (lição 4). Manter o LEARN puro importa: se você começa a editar enquanto ainda está descobrindo o estado, perdeu a verdade de base que tentava estabelecer. Observe primeiro; classifique depois; aja por último.
A regra anti-suposição
Trate toda crença que você guarda de memória como defasada por padrão e confirme-a contra o artefato. "O handler retorna JSON" → abra o handler. "Os testes passam" → rode-os. "O pacote está na v3" → verifique, via Bright Data se isso vive na web. A disciplina não é pessimismo; é recusar deixar uma afirmação não verificada na raiz de uma árvore de decisão.
2
O que o LEARN de fato lê
O LEARN não é uma coisa só — é um checklist curto de entradas. Leia o estado atual do artefato, releia o escopo (seu "pronto" mensurável), traga fontes confiáveis para qualquer fato externo e inspecione os artefatos reais em vez de confiar num resumo deles. Eis a anatomia.
Quatro entradas alimentam o LEARN; sua saída — um retrato fundamentado da realidade — é o que o ANALYZE tem permissão de raciocinar em cima.
ler estado atualreler escoposó fontes confiáveisinspecione, não resumaobserve, não edite
3
Em uma imagem: leia antes de agir
A regra inteira cabe numa única linha de fluxo. A realidade entra; você a observa; só então decide. O atalho proibido — a seta vermelha pontilhada — pula direto de "tenho uma tarefa" para "vou agir", pulando a observação. Esse atalho é exatamente o que o loop existe para impedir.
Leia da esquerda → direita. O caminho sólido observa primeiro; o caminho vermelho pontilhado é o que o loop proíbe.
A regra única
Nenhuma decisão no loop pode se apoiar num fato que você não olhou. Se você não consegue apontar onde o viu, ainda não o sabe — você o presumiu.
4
Presumir vs inspecionar, de três formas
Este é o cerne da lição, então vamos fixá-lo de três formas diferentes: uma imagem lado a lado dos dois hábitos, um pequeno simulador que você pode martelar para sentir como presumir desvia enquanto inspecionar se mantém fiel, e um passo a passo da própria decisão de ler-antes-de-agir.
Mesma tarefa, dois hábitos. A única diferença é de onde veio o retrato — e essa diferença se acumula.
Sinta na prática. Abaixo, a mesma tarefa volta rodada após rodada (o loop roda muitas passadas). O agente da esquerda presume que o estado não mudou e segue agindo sobre o primeiro retrato; o agente da direita reinspeciona a cada rodada. Aperte Próxima rodada algumas vezes e veja a distância se abrir.
Presume o estado
Agente da memória
Olhou uma vez na rodada 1, depois confiou nesse retrato para sempre. Nunca relê o artefato.
Crenças defasadas
0
O retrato está fresco — acabou de olhar.
Aguardando a primeira rodada.
Inspeciona a cada rodada
Agente LEARN
Reabre o artefato no início de toda rodada, então seu retrato nunca pode ficar defasado.
Crenças defasadas
0
O retrato está fresco — acabou de olhar.
Aguardando a primeira rodada.
Rodadas decorridas: 0
O mundo muda a cada rodada (outros agentes fazem commit, logs rotacionam, a página atualiza). Só o agente que reolha mantém um retrato fiel.
Agente da memória — nunca relê
let picture = read_state(); // só na rodada 1functiononRound() {
// age sobre o PRIMEIRO retrato para sempre — desvia conforme a realidade mudareturn decide(picture);
}
Agente LEARN — relê a cada rodada
functiononRound() {
const picture = read_state(); // fresco a cada passada — nunca defasadoreturn decide(picture);
}
A correção é quase ofensivamente pequena: mover a chamada read_state() para dentro do loop. Essa é toda a diferença entre um agente cujo retrato apodrece e um cujo retrato está sempre atual. O LEARN é essa chamada, feita de propósito, no topo de cada passada.
Percorra a decisão. Quando uma tarefa chega, o LEARN roda um portão minúsculo: eu de fato conheço o estado atual? Cada "não" te manda de volta a olhar; só um "sim" limpo te deixa prosseguir. Escolha uma situação e percorra-a passo a passo.
Traçar situação:
Leia de cima → baixo. Cada "não" te leva de volta a olhar; só uma passada limpa conquista o direito de agir.
Passo 0 de 4
Comece aqui
Uma tarefa chega
Aperte Próximo para percorrer o caso acabou de inspecionar. Troque a situação acima para ver como um palpite é mandado de volta a olhar.
5
Leia o estado, de ponta a ponta
Como é "ler o estado atual" na prática, num repositório real? É um pequeno pipeline próprio — cinco leituras rápidas que te levam de "não faço ideia" a "consigo ver exatamente como as coisas estão". Siga o sumário descendo a página.
★
Por onde uma passada de LEARN percorre
Você cai num repositório desconhecido com uma tarefa: "faça o handler de busca rejeitar consultas vazias". Antes de decidir qualquer coisa, seus olhos percorrem cinco leituras: oriente-se (o que é este projeto?), abra o artefato que vai mudar, confira o limite que vai te julgar, releia o escopo e fundamente qualquer fato externo. Cada leitura troca um palpite por um fato.
Pense nisso como… entrar numa cozinha onde você nunca cozinhou, pouco antes da correria do jantar. Você não começa a picar — você descobre a disposição, abre a geladeira para ver o que de fato tem, confere se o fogão funciona, relê a comanda do pedido e confirma um ingrediente sobre o qual está em dúvida. Aí, sim, você cozinha.
Leia da esquerda → direita: cada caixa é uma leitura, não uma edição. Nada é mudado até as cinco estarem feitas.
1Abra o artefato que você pretende mudarler
Não imagine o handler — abra-o. O corpo atual pode já validar a entrada, pode não existir, pode ter outro nome completamente. Você só sabe qual depois de ler os bytes que estão no disco hoje.
2Confira o limite que vai te julgarrodar
Rode os testes agora, antes de mudar qualquer coisa. Um teste que falha sem você ter causado é parte do estado; uma suíte já vermelha conta uma história bem diferente de uma que está verde. Essa linha de base é o que o VERIFY (lição 6) compara depois.
3Releia o contrato de escopoler
"Rejeitar consultas vazias" — isso inclui só espaços em branco também? Retornar um 400, ou resultados vazios? O done-when da lição 2 resolve isso. Reler o escopo na hora do LEARN te impede de resolver um problema ligeiramente diferente do que foi combinado.
4Fundamente qualquer fato externoverificar
Se a correção depende do que uma biblioteca de fato faz, ou de uma convenção atual, você confirma a partir de uma fonte confiável — a Bright Data CLI para qualquer coisa na web (lição 11), nunca uma API meio lembrada. Um fato externo não verificado é só mais uma suposição vestindo um tom de voz confiante.
⌗
No código: as leituras, tornadas reais
Eis como essas leituras ficam na forma dos comandos reais que uma passada de LEARN roda. Note que cada linha é uma leitura — nada edita, nada faz commit. Isto é observação, capturada.
uma passada de LEARN — só leituras, zero escritas
# 0 · oriente-se — o que é, afinal, este repo?
ls -1 ; cat README.md
git log --oneline -5 # histórico recente = parte do estado# 1 · abra o artefato que você planeja mudar
grep -rn "def search" services/search/
sed -n '1,40p' services/search/handler.py
# 2 · confira o limite ANTES de tocar em qualquer coisa
pytest services/search/ -q # linha de base: já está verde?# 3 · releia o contrato de escopo (o pronto mensurável)
cat GOAL.md # o done-when mora aqui# 4 · fundamente um fato externo a partir de uma fonte CONFIÁVEL
brightdata search "flask request.args empty value handling"
Acesse você mesmo
Ache o ponto de entrada com grep -n "def search" services/search/handler.py, depois leia só o topo com sed -n '1,40p' services/search/handler.py em vez de carregar o arquivo inteiro na cabeça.
Pegue a linha de base dos testes com pytest -q (ou o runner do seu projeto) antes de editar — essa saída é estado. Para qualquer fato da web, o caminho é sempre a Bright Data CLI: brightdata search "…" ou brightdata scrape <url>; nunca WebSearch/WebFetch, nunca o MCP da Bright Data. Essa regra é ensinada por completo na lição 11.
6
Três formas honestas de inspecionar
"Olhar o estado" não é uma técnica só. Dependendo do que você precisa saber, você recorre a uma ferramenta diferente — e cada uma faz uma troca entre quão rápida é, quão fundo vai e quanto da realidade de fato toca. Nenhuma é "a" resposta certa; a habilidade é escolher de propósito.
A
Buscar (grep / find)
Varra a árvore inteira por um nome, uma string, uma definição — para achar onde algo mora antes de lê-lo.
# onde está definido? onde é usado?
grep -rn "def search" services/
grep -rn "normalize(" services/
Prós
+Rápido: varre um repo enorme num piscar.
+Mapeia o terreno antes de você se comprometer a ler.
Contras
–Mostra a localização, não o comportamento — nunca a história completa.
–Fácil casar com a coisa errada e se sentir seguro.
Escolha quandoVocê ainda não sabe onde está o código ou a config relevante. Comece aqui, depois abra o que isso apontar.
B
Ler o artefato
Abra o arquivo de verdade e leia os bytes reais — o corpo atual, não a versão na sua memória.
# leia a coisa real, hoje
sed -n '1,60p' services/search/handler.py
cat services/search/config.yaml
Prós
+Verdade de base para estrutura e intenção.
+Pega o que mudou desde a última vez que você olhou.
Contras
–Mais lento; fácil se afogar num arquivo grande.
–Diz o que o código deveria fazer, não o que ele faz.
Escolha quandoVocê sabe onde está e precisa da estrutura e lógica reais antes de decidir uma mudança.
C
Rodar / observar a saída
Execute o limite real — testes, o processo, uma chamada HTTP — e observe o que de fato acontece.
# o que ele REALMENTE faz agora?
pytest services/search/ -q
curl -s "localhost:8000/search?q="
Prós
+Toca a realidade: comportamento real, falhas reais.
+Dá a linha de base contra a qual o VERIFY vai julgar.
Contras
–Precisa de um ambiente executável; o mais lento de preparar.
–Diz que falha, não onde no código.
Escolha quandoO comportamento é a pergunta — "ele de fato rejeita entrada vazia?". Ler não responde isso; rodar responde.
Agora eu mais preciso saber…
Combine-as — elas respondem perguntas diferentes
Uma passada real de LEARN normalmente usa as três em sequência: buscar para localizar, ler para entender a estrutura, rodar para confirmar o comportamento. Pular qualquer uma deixa um ponto cego — ler sem rodar é a armadilha clássica, porque o código pode parecer perfeitamente correto e ainda falhar no limite. A quarta "forma", para fatos que vivem fora do repo, nunca é adivinhar: é a Bright Data CLI, o único caminho uniforme que todo agente tem para evidência viva da web.
7
O retrato do estado: leia num relance
Depois de olhar, ajuda manter o estado numa só visão — o que você de fato conhece, o que é só parcial, o que ainda é desconhecido e o que você está (perigosamente) presumindo. Isto é um relatório de status do seu próprio entendimento. Aperte Atualizar para tirar uma nova leitura, ou ligue o Ao vivo para vê-lo se mover conforme uma execução avança.
Pense nisso como… um painel de sala de controle antes de acionar qualquer chave. Verde significa que você confirmou; âmbar significa que você olhou pela metade; vermelho significa que você está voando às cegas. Você não age nas linhas vermelhas — vai olhá-las primeiro.
Estado do conhecimento — tarefa do search-handler RHG
repo: rhg-platform · branch: fix/empty-query · passada de LEARN
O estado está bem compreendido
olhou agora mesmo
Fatos confirmados
7/9
▲+2 olhados
Suposições restantes
1
▼−3 verificadas
Limite lido
verde
▲linha de base fixada
Escopo relido
sim
▲done-when claro
Estado do conhecimento por item
O que precisamos saber
Estado
Confiança
Como olhamos
Conhecido (olhado) Parcial Desconhecido Presumido (perigo)
Um modelo, duas visões
Um único array de "coisas que precisamos saber" alimenta tanto a tabela quanto o selo de resumo. Cada atualização confirma um pouco mais (uma suposição vira conhecida assim que você de fato olha), recalcula o estado de cada item, depois re-deriva o banner: qualquer desconhecido → vermelho, qualquer presumido → âmbar, senão verde. Os deltas são coloridos pelo significado — menos suposições é bom (verde) mesmo que a seta aponte para baixo.
Por que "presumido" é um estado próprio
A maioria dos painéis tem conhecido / desconhecido. O LEARN acrescenta um terceiro, mais afiado: presumido — uma crença que você trata como fato sem ter olhado. Ele aparece em âmbar, não verde, de propósito. Uma suposição é uma dívida; o retrato a mantém visível até você quitá-la inspecionando.
8
Capture o que você observa, antes de classificar
Enquanto você faz LEARN, vai notar coisas — uma função confusa, um teste que falha, uma dependência faltando, um trecho de código arriscado. A disciplina é: anote cada uma como observação crua primeiro, na coluna Observado. Não a julgue ainda. Só depois de terminar de olhar você confirma que é real, e mais tarde a classifica (isso é trabalho do ANALYZE, próxima lição). Capturar primeiro te impede de agir sobre uma coisa vista pela metade.
Aperte a seta de um cartão para movê-lo um passo, ou arraste-o. As contagens permanecem honestas — toda observação está em exatamente uma coluna.
Pense nisso como… o mural de evidências de um detetive. Você fixa cada pista conforme a encontra — sem teoria ainda. Fixar não é concluir. Só quando o mural está cheio você começa a traçar as linhas. Decida cedo demais e você vai dobrar a próxima pista para caber na teoria.
Observações em aberto: 0 · Classificadas: 0
Observado0
Confirmado0
Classificado (→ ANALYZE)0
Observações são estado, não decisões
O quadro é uma máquina de estados minúscula. Cada observação é um objeto com um campo col que só pode ser observed, confirmed ou classified. As colunas na tela não são a fonte da verdade — o array é. Manter Observado separado de Classificado impõe a lição no nível dos dados: uma coisa precisa ser vista e confirmada antes de ganhar uma categoria. Classificar (prioridade, tipo, o que fazer) é trabalho do ANALYZE na lição 4; o LEARN apenas coleta.
Como a interface é reconstruída a partir do estado a cada mudança, as contagens nunca podem desviar, e um cartão fisicamente não pode estar em duas colunas. Mesmo formato de qualquer kanban — Jira, Linear, Trello — menos a rede. Um array, um render, eventos nativos de arrastar.
9
Onde o LEARN se encaixa no loop
O LEARN não é um passo de configuração de uma vez só — é o portão pelo qual cada passada do loop passa primeiro. Para sentir isso, conduza o loop você mesmo abaixo. Note que você não pode pular direto para o EXECUTE: a única jogada disponível desde o início é LEARN. A máquina recusa os atalhos ilegais, exatamente como a disciplina faz.
O nó preenchido de clay é onde você está agora. Nós apagados não são alcançáveis daqui.
Passo atual
LEARN
Leia o estado real, o escopo e as fontes confiáveis. Você não pode analisar nem executar até ter olhado.
Jogadas permitidas
Registro de passos
O loop como um objeto
A ordem não é uma sugestão — é uma tabela de transição. A partir de LEARN o único evento legal é analyze; você não pode execute antes de analisar nem verify antes de executar. Experimente: os botões ilegais ficam acinzentados. Modelar o loop assim é o que torna "olhe primeiro" estrutural, em vez de uma coisa que você precisa lembrar.
const loop = {
LEARN: { analyze: 'ANALYZE' },
ANALYZE: { execute: 'EXECUTE' },
EXECUTE: { verify: 'VERIFY' },
VERIFY: { decide: 'DECIDE' },
DECIDE: { again: 'LEARN' } // a próxima passada faz LEARN de novo
};
O loop retorna a LEARN, nunca o pula. Cada passada reestabelece o estado, porque o ato de executar na passada anterior mudou esse estado.
10
Exemplo resolvido: aprender um repo pequeno antes de mudá-lo
Vamos amarrar tudo numa tarefa concreta, do início ao fim — só a parte do LEARN. A tarefa: "No serviço RHG, faça /search rejeitar uma consulta vazia com um 400 em vez de retornar todos os resultados." Veja como uma passada cuidadosa de LEARN transforma quatro palpites em quatro fatos antes de uma única linha ser escrita.
palpite → fato 1"O handler está em handler.py"
grep -rn "def search" services/ retorna services/search/api.py:42 — nada de handler.py. O palpite errou por um arquivo; agir nele teria significado editar o lugar errado. Fato: o handler mora em api.py.
palpite → fato 2"Ele provavelmente retorna cedo com entrada vazia"
sed -n '40,58p' services/search/api.py mostra que não — um q vazio segue direto para index.lookup(""), que retorna tudo. Fato: não há guarda nenhuma; essa é a lacuna real.
palpite → fato 3"Os testes estão verdes"
pytest services/search/ -q → 11 passed, e já existe um teste test_empty_query_returns_400 que está pulado. Fato: o limite está verde e uma especificação para a correção já existe, esperando para ser des-pulada. O VERIFY agora tem seu alvo.
palpite → fato 4"O Flask dá parâmetros vazios como None"
Em dúvida, então confirme do único jeito permitido — brightdata search "flask request.args.get empty string default" — que mostra que um ?q= ausente devolve None mas ?q= devolve "". Fato: a guarda precisa pegar ambosNone e string vazia. Uma resposta só de memória teria perdido o caso da string vazia.
O que o LEARN produziu
Quatro fatos, zero edições: o arquivo real (api.py:42), a lacuna real (sem guarda), o limite real (verde, com uma especificação pulada) e um fato externo fundamentado (pegar ambos None e ""). O ANALYZE agora pode raciocinar sobre a realidade em vez de uma história. Isso é uma passada de LEARN feita direito — e levou menos de um minuto.
A passada, como ela cairia em LOOP-LOG.md
Uma passada de LEARN deixa um rastro que o humano pode observar depois (esta é a observabilidade sobre a qual todo o conjunto roda — você vai vê-la na lição 7). Só leituras; toda afirmação tem uma fonte.
# LEARN — fix/empty-query
grep -rn "def search" services/ # → api.py:42 (não handler.py)
sed -n '40,58p' services/search/api.py # → sem guarda de q vazio
pytest services/search/ -q # → 11 passed; 1 skipped (a especificação)
brightdata search "flask request.args empty string"# → None E "" possíveis# estado estabelecido → entregar ao ANALYZE. nenhum arquivo mudado.
11
Verificação rápida: fixou?
Lembrar vence reler. Responda cada uma de memória antes de espiar — a opção que você escolher é corrigida na hora, com uma nota do porquê. Sem pistas na formatação; as respostas estão espalhadas de propósito.
Q1Qual é a única tarefa do passo LEARN?
Q2Você precisa de um fato atual que vive na web. O que você faz?
Q3Por que rodar os testes antes de mudar qualquer coisa?
Q4Durante o LEARN você nota um teste que falha. Qual é a primeira jogada certa?
Q5Por que o loop roda o LEARN de novo no início de cada passada?
Pontuação: 0 / 5
Seu agente é seu professor. Travado em por que "presumido" é tratado como perigoso, ou quer rodar uma passada real de LEARN no seu próprio repo? Pergunte. A seguir — uma vez que o estado esteja fundamentado — vem transformar esse retrato em uma jogada priorizada: ANALYZE: classificar a lacuna, avaliar, escolher UMA unidade.