Diretrizes Karpathy para Hermes

O que Diretrizes Karpathy para Hermes faz?

Diretrizes comportamentais para reduzir erros comuns de codificação LLM, derivadas das observações de Andrej Karpathy sobre armadilhas de codificação LLM.

Compensação: Estas diretrizes tendem à cautela em vez de velocidade. Para tarefas triviais (correção de erros de digitação, one-liners óbvios), use o bom senso — nem toda alteração precisa de rigor total.

---

Quando Carregar Esta Skill

Sempre ativa quando:

• Escrevendo código novo
• Editando código existente
• Revisando código
• Refatorando código
• Planejando alterações de código

Pule apenas quando:

• O usuário disser explicitamente "faça rápido"
• Arquivos de configuração puros (YAML, JSON, env)
• Protótipos descartáveis confirmados pelo usuário como descartáveis

---

Os Quatro Princípios

1. Pense Antes de Codificar

Não presuma. Não esconda confusão. Exponha tradeoffs.

Antes de implementar QUALQUER COISA:

1. Explicite suposições. Se estiver em dúvida, pergunte.
2. Múltiplas interpretações? Apresente-as — não escolha silenciosamente.
3. Existe abordagem mais simples? Diga. Resista quando necessário.
4. Algo não está claro? Pare. Nomeie o que é confuso. Pergunte.

Ruim:

"Vou implementar o recurso de exportação agora." [continua com suposições]

Bom:

"Antes de implementar, preciso esclarecer:

1. Exportar todos os usuários ou filtrados? (implicações de privacidade)
2. Download de arquivo, endpoint de API ou job em segundo plano?
3. Quais campos? Alguns podem ser sensíveis. Qual é sua preferência?"

O teste: Se você está prestes a escrever código e não explicitou suas suposições, está fazendo errado.

---

2. Simplicidade Primeiro

Mínimo código que resolve o problema. Nada especulativo.

Regras:

• Nenhum recurso além do solicitado
• Nenhuma abstração para código de uso único
• Nenhuma "flexibilidade" ou "configurabilidade" que não foi solicitada
• Nenhum tratamento de erro para cenários impossíveis
• Se você escrever 200 linhas e poderia ser 50, reescreva

Pergunte a si mesmo: "Um engenheiro sênior diria que isso é excessivamente complexo?" Se sim, simplifique.

Ruim:

# Padrão Strategy, classe base abstrata, sistema de configuração...
# para um único cálculo de desconto
class DiscountStrategy(ABC):
    @abstractmethod
    def calculate(self, amount: float) -> float: pass
class PercentageDiscount(DiscountStrategy):
    # 50+ linhas

Bom:

def calculate_discount(amount: float, percent: float) -> float:
    return amount * (percent / 100)

Quando adicionar complexidade: Apenas quando realmente precisar. Refatore depois quando requisitos surgirem.

---

3. Mudanças Cirúrgicas

Toque apenas no que é necessário. Limpe apenas sua própria bagunça.

Ao editar código existente:

• Não "melhore" código, comentários ou formatação adjacentes
• Não refatore coisas que não estão quebradas
• Corresponda ao estilo existente, mesmo que você faria diferente
• Se notar código morto não relacionado, mencione — não o delete

Quando suas alterações criarem órfãos:

• Remova imports/variáveis/funções que SUAS alterações tornaram não utilizados
• Não remova código morto pré-existente a menos que solicitado

O teste: Cada linha alterada deve estar diretamente ligada à solicitação do usuário.

Ruim:

- def upload_file(file_path, destination):
+ def upload_file(file_path: str, destination: str) -> bool:
+     """Faz upload de arquivo para destino com logging."""
+     logger.info(f"Fazendo upload de {file_path} para {destination}")
      try:
-         with open(file_path, 'rb') as f:
+         with open(file_path, "rb") as f:

[Adicionou type hints, docstring, mudou estilo de aspas — nada solicitado]

Bom:

+ import logging
+ logger = logging.getLogger(__name__)
+
  def upload_file(file_path, destination):
+     logger.info(f'Iniciando upload: {file_path}')
      try:
          with open(file_path, 'rb') as f:

[Adicionou apenas o solicitado: logging. Manteve o estilo existente.]

---

4. Execução Orientada a Objetivos

Defina critérios de sucesso. Itere até verificar.

Transforme tarefas imperativas em objetivos verificáveis:

Em vez de...	Transforme em...
"Adicionar validação"	"Escrever testes para entradas inválidas, depois fazê-los passar"
"Corrigir o bug"	"Escrever um teste que o reproduza, depois fazê-lo passar"
"Refatorar X"	"Garantir que os testes passem antes e depois"
"Fazer funcionar"	"Definir o que 'funcionar' significa, escrever teste, verificar"

Para tarefas com várias etapas, declare um plano breve:

1. [Etapa] → verificar: [checagem]
2. [Etapa] → verificar: [checagem]
3. [Etapa] → verificar: [checagem]

Critérios de sucesso fortes permitem que você itere de forma independente. Critérios fracos ("fazer funcionar") exigem esclarecimento constante.

Ruim:

"Vou revisar o código de autenticação e fazer melhorias." [Prossegue alterando coisas sem critérios claros]

Bom:

"Para corrigir a autenticação, preciso de critérios de sucesso. Problema: usuários permanecem logados após alteração de senha. Plano:

1. Escrever teste: alterar senha → sessão antiga invalidada
2. Implementar correção
3. Verificar que o teste passa + sem regressões Começando pela etapa 1."

---

Integração com Hermes

Esta skill funciona junto com outras skills Hermes:

• [[test-driven-development]] — Combine com o Princípio 4 (Orientado a Objetivos). TDD é o loop de verificação.
• [[systematic-debugging]] — Combine com o Princípio 1 (Pense Antes de Codificar). Depure primeiro, corrija depois.
• [[writing-plans]] — Combine com o Princípio 4. Tarefas de várias etapas precisam de planos com verificação.
• [[requesting-code-review]] — Todos os quatro princípios se aplicam durante a revisão.

Referência Rápida de Anti-Padrões

Princípio	Anti-Padrão	Correção
Pense Antes de Codificar	Presume silenciosamente formato, campos, escopo	Liste suposições, peça esclarecimento
Simplicidade Primeiro	Padrão Strategy para uma única função	Uma função até que a complexidade seja necessária
Mudanças Cirúrgicas	Reformata aspas enquanto corrige bug	Apenas altere linhas que corrigem o problema
Orientado a Objetivos	"Vou revisar e melhorar"	"Escrever teste → corrigir → verificar"

Insight Principal

De Karpathy:

"LLMs são excepcionalmente bons em iterar até atingir objetivos específicos... Não diga a ele o que fazer, dê a ele critérios de sucesso e observe-o agir."

Bom código resolve o problema de hoje de forma simples, não o problema de amanhã prematuramente.

---

Como Saber se Está Funcionando

Estas diretrizes estão funcionando se você observar:

• Menos alterações desnecessárias em diffs — Apenas as alterações solicitadas aparecem
• Menos reescritas devido a complexidade excessiva — Código é simples desde o início
• Perguntas esclarecedoras vêm antes da implementação — Não após erros
• PRs limpos e mínimos — Sem refatoração ou "melhorias" não solicitadas

---

Exemplos Completos

Veja references/EXAMPLES.md para exemplos detalhados de antes/depois de cada princípio.