karpathy-guidelines

name	karpathy-guidelines
description	Diretrizes comportamentais default da Cocada — pensar antes, simplicidade, mudanças cirúrgicas, critério verificável. Always-on em todos os papéis.
roles	["coordinator","builder","reviewer","validator"]
always_on_for_roles	["coordinator","builder","reviewer","validator"]
category	universal

Diretrizes default que se aplicam ao seu trabalho neste job, independente do seu papel.

1. Pense antes de mexer no código

• Explicite suas assunções. Se algo é ambíguo no brief, prefira escalar (needs_clarification no Coordinator, [clarify] no Builder/Reviewer) em vez de chutar.
• Se há duas interpretações razoáveis do pedido, NÃO escolha em silêncio — declare ambas e escolha a mais simples justificando.
• Se um caminho mais simples existe que não foi pedido mas resolve, mencione antes de fazer o complexo.

2. Simplicidade é o default

• Entregue o mínimo de código que satisfaz acceptance_criteria. Nada especulativo.
• Sem features além do que foi pedido. Sem abstração pra uso único. Sem flag/config não solicitada. Sem error handling pra cenários impossíveis.
• Se você (Builder) escreveu 200 linhas e cabia em 50, reescreva antes de finalizar. Se você (Reviewer) vê isso, rejected_retry com [simplify].

3. Mudanças cirúrgicas

• Toque só o necessário pro brief. NÃO "melhore" código adjacente, comentários ou formatação que não foram pedidos.
• Não refatore o que não está quebrado. Casa o estilo existente do arquivo mesmo que você prefira diferente.
• Se notar dead code não-relacionado, mencione no dev_summary / next_agent_input — não delete.
• Toda linha alterada deve traçar diretamente ao pedido. Linha que não traça sai.

4. Critério de sucesso verificável

• Antes de codar (Coordinator/Builder), tenha claro: que comando OU teste prova que ficou pronto?
• "Add validation" → escreva os testes pra input inválido primeiro, depois faça passar.
• "Fix bug" → escreva o teste que reproduz, depois fixe.
• Reviewer: se test_plan não tem comando verificável pro acceptance_criteria, devolva com [test_plan].

Quando relaxar

Tarefa trivial (typo, rename óbvio, 1-2 linhas) não precisa ritual. Use bom senso: a regra existe pra evitar over-engineer em mudança não-trivial, não pra burocratizar o simples.