🧠 Fundamentos Karpathy

O LLM lê uma instrução ambígua, escolhe uma interpretação na hora e sai codando sem avisar você.

É a origem da maioria dos retrabalhos: você descobre a suposição errada só quando o PR chega.

Ambiguidade silenciosa; custo do retrabalho; loop confiança-cego.

Antes de qualquer código, listar as suposições adotadas para que o usuário possa corrigi-las.

Custa 30 segundos do usuário e evita refazer 30 minutos de código.

"Assumindo X, Y, Z"; checkpoint pré-implementação; reversibilidade barata.

Em vez de escolher silenciosamente, listar 2-3 interpretações possíveis e pedir confirmação.

Devolve o controle ao usuário sem travar o fluxo. Faz a ambiguidade virar uma decisão consciente.

Branching de interpretação; decisão informada; antiprasse de "achismo".

Se o usuário pede algo subótimo e há um caminho mais simples ou seguro, o LLM deve apontar.

Concordância automática gera dívida técnica silenciosa. O LLM é coautor, não digitador.

Pushback construtivo; tradeoff transparente; senioridade simulada.

Quando algo não fecha, o LLM deve nomear o que não está claro e perguntar, em vez de "preencher os buracos".

Confusão escondida vira bug semanas depois. Confusão explícita vira esclarecimento em segundos.

Nomear a confusão; parada cooperativa; custo do "achei que era X".

Apresentar prós e contras de cada caminho antes de implementar, em vez de só executar.

Decisões cegas amarram o futuro. Tradeoffs explícitos viram decisões reversíveis.

Custo-benefício; reversibilidade; opções vs imposição.

A tendência do LLM a entregar 1000 linhas quando 100 bastam, com abstrações, factories e camadas que ninguém pediu.

Código inchado tem mais superfície de bug, mais leitura e mais custo de manutenção. Sempre.

Volume vs valor; complexidade acidental vs essencial; "performance teatral".

Não adicionar funcionalidades "por via das dúvidas" ou "para o futuro" se o usuário não pediu.

Especulação inflada vira código morto. 90% nunca é usado, mas todos pagam o custo.

YAGNI; escopo fechado; valor por linha entregue.

Não criar funções, classes ou hooks abstraídos quando há apenas um caller. Inline é mais legível.

Abstração prematura é dívida disfarçada de elegância. Espere o terceiro uso real.

Rule of three; abstração prematura; legibilidade > "limpeza".

Não envolver código em try/catch ou validações para cenários que nunca podem acontecer naquele contexto.

Tratar o impossível esconde bugs reais e enche o código de ruído defensivo.

Defensive coding excessivo; "fail loud"; trust the boundary.

Antes de entregar, perguntar: um engenheiro sênior olharia esse código e diria "isto pode ser metade do tamanho"?

É o checkpoint mais barato contra superengenharia. 30 segundos de reflexão evita 3 horas de refactor.

Self-review; readability test; razão linha/intenção.

Identificar quando o primeiro draft pode ser comprimido em uma fração do tamanho sem perder clareza.

Código menor tem menos bugs por construção. A segunda versão quase sempre é a boa.

Compressão por reescrita; segundo draft; eliminar intermediários.

Mesmo que o LLM ache que pode "melhorar" código adjacente, não deve tocar. Foco é o pedido.

Mudanças não solicitadas inflam diffs, dificultam review e introduzem regressões fantasmas.

Scope creep; respeito ao diff; "no surprises".

Seguir convenções do projeto (nomes, padrões, estilo) mesmo que o LLM preferisse de outro jeito.

Inconsistência estilística é dívida cognitiva. Código uniforme se lê em metade do tempo.

Style mimicry; convenção sobre opinião; integração silenciosa.

Se o LLM encontra código não usado fora do escopo da tarefa, deve apenas avisar o usuário, não apagar.

"Não usado" pode ser usado por outro time, build flag ou ferramenta externa. Deletar = bomba-relógio.

Dead code aparente; consentimento explícito; janela de blast radius.

Quando uma mudança deixa imports, variáveis ou funções sem uso, o LLM remove. Se o órfão é pré-existente, deixa.

Bagunça gerada pela própria mudança é responsabilidade dela. Bagunça herdada não.

Cleanup proporcional; ownership da bagunça; cargo de cada PR.

Não "melhorar" comentários, espaçamento ou ordem de imports fora da área da mudança.

Mudanças cosméticas ofuscam mudanças reais no diff. O reviewer perde o sinal no ruído.

Diff signal-to-noise; mudança cosmética; respeito ao git blame.

Antes de entregar o diff, conferir que cada linha mudada justifica-se diretamente pelo pedido do usuário.

É o critério mais simples para descartar mudanças que se infiltraram sem intenção.

Trace-back por linha; diff defensivo; auditoria pré-PR.

A diferença entre "implementa validação" (imperativo) e "esses testes devem passar" (declarativo).

Declarativo dá ao LLM um critério de parada. Imperativo gera entrega sem certeza.

Critério de aceitação; fim explícito; meta-driven prompting.

Pedir os testes antes da implementação. O LLM escreve teste, vê falhar, depois implementa até passar.

É a forma mais barata de garantir que o entregue resolve o que foi pedido.

Red-Green-Refactor; spec executável; verificação automática.

Com critério verificável, o LLM pode rodar testes, ajustar, rodar de novo — sem intervenção a cada passo.

Karpathy: "LLMs são excepcionalmente bons em looping até bater uma meta específica."

Self-correction loop; agente autônomo; convergência por feedback.

"Faz funcionar" é fraco. "Comando X retorna Y em menos de 200ms para input Z" é forte.

Critério fraco gera entrega ambígua. Critério forte permite verificação objetiva.

Definition of done; SMART criteria; mensuração binária.

Para tarefas com múltiplos passos, cada passo tem um critério de "passou" antes de seguir adiante.

Sem checkpoints, erros se acumulam silenciosamente até o fim. Com checkpoints, falham cedo e barato.

Step-verify-step; fail-fast; controle granular.

Para corrigir bug: primeiro escrever teste que reproduz, depois fazer passar. Garante que o bug não volta.

É a forma mais robusta de provar que o bug foi corrigido — e prevenir regressão futura.

Regression test; reprodução isolada; bug-driven test.