As 4 linhas que todo CLAUDE.md precisa para deixar o Claude 100 vezes melhor

Autoria: Cloud X Berry · Assistir no YouTube

Vídeo de autoria do canal indicado, não da IANIA; todos os direitos pertencem ao criador. Transcrição, resumo e tradução gerados automaticamente; o conteúdo no idioma original é preservado na versão em idioma original.

Idioma original: inglês

Vídeo original: The 4 Lines Every CLAUDE.md Needs that Make Claude 100x Better · Canal: Cloud X Berry · 05:41 · Assistir no YouTube

Tópicos: Agentes de IA, Claude Code, Engenharia de software com IA

Resumo

O vídeo apresenta quatro princípios comportamentais para orientar o Claude Code: não fazer suposições, resolver problemas com o mínimo de código, limitar as alterações ao necessário e verificar se os critérios de sucesso foram atendidos. Cada princípio é explicado com exemplos de tarefas de programação e dos problemas causados por decisões sem confirmação, complexidade desnecessária, mudanças fora do escopo e testes insuficientes. As diretrizes podem servir de base para instruções do agente, mas devem ser complementadas por informações específicas do projeto. O desenvolvedor continua responsável pelas decisões importantes.

Pontos-chave

O agente deve apontar incertezas relevantes e fazer perguntas antes de tomar decisões que possam alterar o resultado.
Convenções já estabelecidas no código podem orientar a implementação sem a necessidade de perguntar sobre cada detalhe.
A solução deve usar o mínimo de código razoável, sem criar abstrações especulativas.
As alterações devem se limitar ao escopo da tarefa; o agente deve limpar apenas os problemas que ele próprio introduziu.
Critérios de sucesso claros e verificáveis ajudam o agente a testar a implementação e corrigir falhas.
Instruções do projeto podem incluir comandos de build, orientações de testes, decisões arquiteturais, requisitos de segurança e convenções.
O desenvolvedor continua responsável pelas decisões que importam.

Capítulos

Início	Capítulo	Resumo
00:00	Não faça suposições	O agente deve esclarecer incertezas importantes antes de escolher uma implementação, sem perguntar sobre detalhes já definidos pelas convenções do projeto.
01:33	Use o mínimo de código necessário	A solução deve atender ao requisito com simplicidade e evitar abstrações sem justificativa clara.
02:34	Altere apenas o necessário	As mudanças devem se concentrar na tarefa solicitada, e o agente deve evitar reformar código não relacionado.
03:37	Defina o sucesso e verifique	O agente deve definir como validar a tarefa, executar testes, corrigir falhas e complementar as instruções com o contexto específico do projeto.

Citações

Eles fazem suposições sem perguntar, transformam requisitos simples em implementações complicadas e modificam código não relacionado. — 00:00

O mínimo de código que resolve o problema, nada especulativo. — 01:33

Toque apenas no que for necessário. Limpe apenas a própria bagunça. — 02:34

Defina critérios de sucesso e repita o ciclo até verificar. — 03:37

Mantenha a solução simples, limite as alterações ao que a tarefa exige e verifique o resultado antes de considerá-la concluída. — 05:10

Conceitos e entidades

Claude Code (ferramenta): Ferramenta de programação com IA mencionada no vídeo como agente que pode seguir princípios comportamentais definidos em instruções.
CLAUDE.md (ferramenta): Arquivo de instruções do projeto que pode conter orientações para o Claude Code.
Andrej Karpathy skills (repo): Projeto do GitHub citado como fonte dos quatro princípios comportamentais apresentados.
Forest Cheng/Andre Karpathy Skills (repo): Repositório do GitHub mencionado como local das diretrizes e de exemplos de aplicação em tarefas de programação.
critérios de sucesso (conceito): Condições explícitas e verificáveis que permitem avaliar se uma tarefa foi concluída corretamente.
alterações focadas (conceito): Princípio de limitar as mudanças ao que a tarefa exige, evitando modificações não relacionadas.

Tradução completa (pt-BR)

00:00 Agentes de programação com IA podem escrever código, corrigir bugs e desenvolver funcionalidades. Mas, se você já os usou em projetos reais, provavelmente notou alguns hábitos frustrantes. Eles fazem suposições sem fazer perguntas, transformam requisitos simples em implementações complicadas, modificam código não relacionado à tarefa e, às vezes, afirmam que tudo funciona sem testar direito. Um projeto do GitHub chamado Andrej Karpathy skills transformou essas observações em quatro princípios comportamentais para o Claude Code. Vamos analisar cada princípio e entender como ele pode mudar a forma como um

00:31 agente de programação com IA aborda seu trabalho. O primeiro princípio é: não faça suposições. Não esconda dúvidas. Apresente as alternativas e seus prós e contras. Imagine pedir a um agente de IA que crie uma funcionalidade para exportar dados de usuários. O agente implementa imediatamente a exportação em JSON, inclui todos os usuários e salva os resultados em um arquivo. A implementação pode funcionar perfeitamente, mas o agente tomou várias decisões que você não especificou. Talvez você quisesse CSV. Talvez os usuários devessem poder exportar apenas os próprios dados. Alguns campos podem conter informações confidenciais que

01:02 não deveriam ser incluídas. O problema é que o agente escolheu uma implementação antes de entender os requisitos. Esse princípio incentiva o agente a identificar incertezas importantes e fazer perguntas antes de tomar decisões que possam afetar o resultado. Ele deve esclarecer o formato de saída, os campos necessários e o escopo esperado da exportação quando esses detalhes não estiverem claros no projeto. Isso não significa fazer perguntas sobre cada pequeno detalhe. Se o código existente já estabelece uma convenção, o agente deve segui-la. O importante

01:33 é saber quando há informações suficientes para prosseguir e quando uma suposição pode levar à implementação errada. O segundo princípio é: use o mínimo de código necessário para resolver o problema, sem especular. Outro problema comum é a complexidade desnecessária. Digamos que você precise de uma função que calcule um desconto percentual. O cálculo em si é simples, mas um agente de IA pode introduzir várias classes, interfaces abstratas e objetos de configuração para implementá-lo. Esses padrões podem ser úteis em sistemas maiores, mas, para um cálculo simples, podem acrescentar

02:04 complexidade sem trazer nenhum benefício real. Cada abstração adicional gera mais código para entender, testar e manter. Esse princípio incentiva o agente a resolver o requisito real usando a implementação razoável mais simples. Se o projeto precisar futuramente de várias estratégias de desconto ou de um mecanismo de preços configurável, você poderá introduzir essas abstrações quando os requisitos justificarem isso. Até lá, não há necessidade de criar uma arquitetura em torno de possibilidades que talvez nunca se concretizem. O objetivo não é evitar um bom design.

02:34 É evitar introduzir complexidade antes de haver um motivo claro para isso. O terceiro princípio é: altere apenas o que for necessário. Limpe apenas a bagunça que você mesmo criou. Suponha que você peça a um agente para corrigir um bug na validação de e-mails. Em vez de fazer a alteração necessária, ele também modifica a validação de nomes de usuário, renomeia variáveis, reformata funções próximas e altera arquivos não relacionados. Agora, você tem um diff muito maior para revisar, embora a tarefa original envolvesse um único bug específico. Isso gera trabalho desnecessário e torna

03:05 mais difícil identificar quais alterações podem introduzir regressões. O princípio aqui é manter as modificações focadas na tarefa solicitada. Cada linha alterada deve ter um motivo claro para estar ali. Se o agente introduzir uma importação não utilizada ou uma variável sem uso ao corrigir o bug, deve limpar as próprias alterações. No entanto, não deve começar a reescrever código não relacionado só porque percebe algo que poderia melhorar. Isso é especialmente importante em bases de código consolidadas, nas quais alterações aparentemente inofensivas podem afetar outros recursos ou tornar as revisões de código

03:37 desnecessariamente difíceis. Alterações menores e focadas são mais fáceis de entender, testar e manter. O quarto princípio é: defina critérios de sucesso e repita o processo até verificar o resultado. Escrever o código é apenas parte da conclusão de uma tarefa. O agente também precisa determinar se a implementação realmente funciona. Digamos que você esteja corrigindo um bug de autenticação em que a troca de senha deveria invalidar as sessões existentes. Simplesmente modificar a lógica de autenticação não prova que o problema foi corrigido. Uma abordagem melhor

04:07 é definir primeiro o comportamento esperado, escrever um teste que reproduza o bug, implementar a correção e executar o teste novamente. O agente também deve verificar os casos extremos relevantes e executar os testes existentes para garantir que a alteração não tenha quebrado outras funcionalidades. Se um teste falhar, deve investigar a falha, fazer a correção necessária e testar novamente. Esse princípio dá ao agente uma definição concreta de conclusão, em vez de permitir que ele decida que a tarefa terminou simplesmente porque gerou o código. Também reduz a necessidade de você orientar cada etapa individual. Quando os critérios de sucesso

04:39 são claros e verificáveis, o agente pode conduzir o processo de implementação e validação com mais autonomia. Colocando os quatro princípios em prática. Você pode encontrar essas diretrizes no repositório do GitHub Forest Cheng/Andre Karpathy Skills, que apresenta os princípios comportamentais junto com exemplos de como aplicá-los a tarefas de programação. Eles oferecem uma base útil para suas instruções do Claude Code, mas não substituem o contexto específico do projeto. Seu agente ainda pode precisar de comandos de build, instruções de teste,

05:10 decisões de arquitetura, requisitos de segurança e convenções que não sejam óbvios pelo código existente. O essencial é incluir informações que ajudem o agente a tomar decisões melhores, em vez de encher a configuração de regras que ele já consegue inferir. Ao usar um agente de programação com IA, concentre-se em quatro coisas. Garanta que ele entenda o requisito. Mantenha a solução simples. Limite as alterações ao que a tarefa exige e verifique o resultado antes de considerá-la concluída. Esses princípios ajudam a lidar com alguns dos hábitos mais frustrantes da programação assistida por IA,

05:41 mantendo o desenvolvedor responsável pelas decisões que importam.

Transcrição original

[00:00] AI coding agents can write code, fix bugs, and build features. But, if you’ve used them on real projects, you’ve probably noticed a few frustrating habits. They make assumptions without asking questions, turn simple requirements into complicated implementations, modify unrelated code, and sometimes claim everything works without properly testing it. A GitHub project called Andrej Karpathy skills turned those observations into four behavioral principles for Claude code. Let’s look at each principle and understand how it can change the way an

[00:31] AI coding agent approaches your work. The first principle is, don’t assume. Don’t hide confusion. Surface trade-offs. Imagine asking an AI agent to build a feature that exports user data. The agent immediately implements JSON export, includes every user, and saves the results to a file. The implementation might work perfectly, but it has made several decisions you never specified. Maybe you wanted CSV. Perhaps users should be able to export only their own data. Some fields might contain sensitive information that

[01:02] shouldn’t be included. The problem is that the agent chose an implementation before understanding the requirements. This principle encourages the agent to identify important uncertainties and ask questions before making decisions that could affect the result. It should clarify the output format, the required fields, and the expected scope of the export when those details aren’t already clear from the project. That doesn’t mean asking questions about every small detail. If the existing code base already establishes a convention, the agent should use it. The important

[01:33] distinction is knowing when it has enough information to proceed and when an assumption could lead to the wrong implementation. The second principle is, minimum code that solves the problem, nothing speculative. Another common problem is unnecessary complexity. Let’s say you need a function that calculates a percentage discount. The calculation itself is straightforward, but an AI agent might introduce several classes, abstract interfaces, and configuration objects to handle it. Those patterns can be useful in larger systems, but for a simple calculation, they may introduce

[02:04] complexity without providing any real benefit. Every additional abstraction creates more code to understand, test, and maintain. This principle encourages the agent to solve the actual requirement using the simplest reasonable implementation. If the project later needs multiple discount strategies or a configurable pricing engine, you can introduce those abstractions when the requirements justify them. Until then, there’s no need to build an architecture around possibilities that might never happen. The goal isn’t to avoid good design.

[02:34] It’s to avoid introducing complexity before there’s a clear reason for it. The third principle is touch only what you must. Clean up only your own mess. Suppose you ask an agent to fix a bug in email validation. Instead of making the required change, it also modifies username validation, renames variables, reformats nearby functions, and changes unrelated files. Now, you have a much larger diff to review, even though the original task involved one specific bug. This creates unnecessary work and makes

[03:05] it harder to identify which changes might introduce regressions. The principle here is to keep modifications focused on the requested task. Every changed line should have a clear reason for being there. If the agent introduces an unused import or a dead variable while fixing the bug, it should clean up its own changes. However, it shouldn’t start rewriting unrelated code simply because it notices something it could improve. This is especially important in established code bases where seemingly harmless changes can affect other features or make code reviews

[03:37] unnecessarily difficult. Smaller, focused changes are easier to understand, test, and maintain. The fourth principle is define success criteria, loop until verified. Writing the code is only part of completing a task. The agent also needs to establish whether the implementation actually works. Let’s say you’re fixing an authentication bug where changing a password should invalidate existing sessions. Simply modifying the authentication logic doesn’t prove that the problem is fixed. A better approach

[04:07] is to define the expected behavior first, write a test that reproduces the bug, implement the fix, and run the test again. The agent should also check relevant edge cases and run existing tests to make sure the change hasn’t broken other functionality. If a test fails, it should investigate the failure, make the necessary correction, and test again. This principle gives the agent a concrete definition of completion, rather than allowing it to decide that a task is finished simply because it has generated the code. It also reduces the need for you to guide every individual step. When success

[04:39] criteria are clear and verifiable, the agent can work through the implementation and validation process more independently. Putting the four principles into practice. You can find these guidelines in the Forest Cheng/Andre Karpathy Skills GitHub repository, which provides the behavioral principles along with examples of how they apply to coding tasks. They provide a useful foundation for your Claude code instructions, but they don’t replace project-specific context. Your agent may still need build commands, testing instructions,

[05:10] architectural decisions, security requirements, and conventions that aren’t obvious from the existing code. The key is to include information that helps the agent make better decisions, rather than filling its configuration with rules it can already infer. When you use an AI coding agent, focus on four things. Make sure it understands the requirement. Keep the solution simple. Limit changes to what the task requires, and verify the result before calling it complete. These principles help address some of the most frustrating habits in AI-assisted

[05:41] programming, while keeping the developer responsible for the decisions that matter.