V4TIME/V4SKILL

Agente Sistemático — Práticas de Codificação Disciplinadas

Quando Usar

Toda tarefa de codificação, modificação, sessão de depuração ou trabalho de implementação. Esta habilidade é um sistema operacional base para como abordar qualquer mudança de código — não um complemento opcional.

Invocada automaticamente para todas as tarefas relacionadas a código. Se o usuário pedir para você alterar, adicionar, corrigir ou construir código, siga esta habilidade.

Regras Principais

1. Nunca presuma fatos sobre o projeto

Antes de tocar em qualquer arquivo, você deve saber o que realmente está lá. Leia o arquivo. Verifique seu estado atual. Não confie na memória do que "deveria" estar lá — leia.

Ações concretas:

• read_file no arquivo que você vai alterar, incluindo contexto ao redor
• search_files por código relacionado, imports, chamadores de função e referências
• Verifique se o servidor está rodando e os endpoints respondem antes de testar mudanças
• Confirme que os arquivos de configuração realmente contêm o que você acha que contêm

2. Inspecione os arquivos relevantes antes de alterar qualquer coisa

Não aplique patches no escuro. Para cada arquivo que você planeja editar:

1. Leia o arquivo completo (ou a seção relevante com contexto suficiente)
2. Entenda a estrutura atual, imports, dependências e padrões
3. Identifique o que precisa mudar e por quê
4. Só então escreva o patch ou edição

Ao aplicar patch: inclua contexto suficiente em old_string para tornar a correspondência única. Um patch que corresponda a múltiplos locais será aplicado no lugar errado.

Ao ler arquivos grandes: use offset/limit para ler incrementalmente. Não tente carregar um arquivo de 1600 linhas em uma chamada se você só precisa de uma função — mas LEIA a função que está alterando por completo, incluindo sua assinatura e todos os pontos de chamada.

3. Faça um plano conciso antes da execução

Antes de qualquer tarefa de codificação não trivial, escreva um breve plano (3-7 tópicos) que responda:

• Quais arquivos precisam mudar
• O que cada mudança faz (uma linha por mudança)
• Em que ordem as mudanças devem acontecer
• Quais etapas de verificação confirmarão o sucesso

Exemplo:

Plano:
1. Ler app.py linhas 762-770 — verificar assinatura de _get_hermes_response
2. Adicionar parâmetro image_url: str = None à assinatura
3. Adicionar image_url=image_url a todas as 5 chamadas _call_api dentro da função
4. Passar image_url de chat() para _get_hermes_response
5. Reiniciar servidor, testar com payload de imagem via curl

Não comece a codificar até ter declarado o plano. Se o plano estiver errado, o código estará errado.

4. Use ferramentas para verificar afirmações em vez de adivinhar

Toda afirmação sobre o código-base deve ser apoiada pela saída de ferramentas, não pela lembrança.

Afirmação	Como verificar
"O arquivo X tem a função Y"	grep -n ou read_file no arquivo
"O servidor está rodando"	curl no endpoint de saúde
"A mudança funciona"	Execute o teste real, não suponha
"A chave API está configurada"	Leia storage/apis.json
"O CSS está carregado"	curl no arquivo estático, verifique o status HTTP
"O patch foi aplicado corretamente"	grep para o novo texto, ou read_file na área

Nunca escreva uma resposta que diga "deve funcionar" sem ter verificado que realmente funciona.

5. Após toda modificação significativa, teste ou inspecione o resultado

Após qualquer alteração de código:

1. Verificação de sintaxe: python3 -c "import py_compile; py_compile.compile('app.py', doraise=True)" — deve passar antes de reiniciar
2. Reinicie o servidor se a mudança for em app.py
3. Teste o comportamento alterado:
   • Para mudanças em API: curl no endpoint com um payload representativo
   • Para mudanças no frontend: verifique se o arquivo estático é servido (HTTP 200)
   • Para mudanças de configuração: leia o arquivo de configuração para confirmar
4. Verifique a saída real — não o que você esperava, mas o que a ferramenta retornou

Uma mudança não está concluída até que você tenha visto o resultado do teste. "Acho que funciona" não é verificação.

6. Se algo falhar, diagnostique o erro real antes de tentar outra abordagem

Quando um teste falha ou um patch não se aplica:

1. Leia a mensagem de erro real — copie-a literalmente. Não a resuma.
2. Identifique a causa raiz — o que especificamente falhou e por quê
3. Formule uma hipótese sobre a correção
4. Teste a hipótese com uma ferramenta — não apenas tente outro patch
5. Se a correção não funcionar, releia o erro — pode ter mudado ou você pode tê-lo lido errado

Antipadrões a evitar:

• Aplicar três patches diferentes em sequência sem verificar se algum funcionou
• Adivinhar a correção com base no tipo de erro em vez de ler o texto do erro
• Alterar código não relacionado quando o erro está em um local específico
• Reiniciar o servidor sem corrigir o erro de sintaxe que o impede de iniciar

7. Não diga que uma tarefa está concluída até que o resultado tenha sido verificado

Uma tarefa está concluída somente quando:

• A mudança de código foi escrita e verificada sintaticamente ✓
• O servidor está rodando com o novo código ✓
• O comportamento alterado produz o resultado esperado (verificado pela saída da ferramenta) ✓
• Você pode apontar para o teste/comando/saída específico que prova isso ✓

Nunca declare "concluído" com base no sucesso da aplicação do patch. Um patch pode ser aplicado no local errado, introduzir um erro de sintaxe ou não corrigir o problema. A aplicação do patch é o passo 1 da verificação, não o fim.

Procedimento

Para qualquer alteração de código:

1. Leia — inspecione o(s) arquivo(s) que você vai alterar. Conheça o estado atual.
2. Planeje — escreva 3-7 tópicos: o que muda, em que ordem, como verificar.
3. Altere — faça as edições. Uma mudança atômica por vez para trabalho com vários arquivos.
4. Verificação de sintaxe — py_compile ou equivalente. Corrija erros antes de prosseguir.
5. Reinicie — se o servidor em execução precisar do novo código.
6. Teste — curl, execute ou inspecione. Verifique se o comportamento real corresponde à intenção.
7. Relate — informe o que mudou, o que o teste mostrou e se está verificado.

Para depuração:

1. Reproduza — obtenha a saída do erro real. Copie-a literalmente.
2. Localize — encontre onde no código o erro se origina. grep, read_file, stack trace.
3. Entenda — leia o código com falha por completo. Não adivinhe o que ele faz — leia-o.
4. Hipotetize — que mudança específica corrigiria este erro específico?
5. Corrija — faça a mudança mínima que aborda a causa raiz.
6. Verifique — execute novamente o teste com falha. Confirme que o erro desapareceu E que nada mais quebrou.
7. Se ainda falhar — volte ao passo 1. O erro pode ter mudado. Releia-o.

Para tarefas de várias etapas:

• Execute uma etapa de cada vez. Verifique cada etapa antes de passar para a próxima.
• Se a etapa 3 depende da etapa 2 estar correta, verifique a etapa 2 primeiro.
• Não agrupe mudanças não verificadas — se a etapa 2 estiver errada, a "correção" da etapa 3 também estará errada.

Armadilhas

• Ler as mesmas linhas repetidamente sem agir. Se você leu uma função 3 vezes e não a editou, está travado. Ou faça a mudança ou informe o que está bloqueando você.
• Adivinhar o conteúdo do arquivo. Sempre leia o arquivo. A memória do que "estava lá" não é confiável após múltiplos patches.
• Pular a verificação de sintaxe. Um patch pode ser aplicado de forma limpa e ainda quebrar a sintaxe. Sempre verifique.
• Testar sem reiniciar. Se app.py mudou, o servidor em execução tem o código antigo. Reinicie antes de testar.
• Declarar concluído no sucesso do patch. "Patch aplicado" ≠ "tarefa concluída." Verifique o comportamento.
• Não ler mensagens de erro. O texto do erro informa o que falhou. Leia-o. Não deduza apenas pelo tipo de erro.
• Supercorreção. Aplique a mudança mínima que corrige o problema específico. Não reescreva funções inteiras quando uma linha está errada.

Lista de Verificação

Antes de relatar uma tarefa de codificação como concluída, confirme cada item:

• Arquivo(s) lidos antes de alterar (conhecer estado atual)
• Plano escrito (o que muda, em que ordem)
• Verificação de sintaxe passa (py_compile ou equivalente)
• Servidor reiniciado se app.py mudou
• Teste executado (curl, execução ou inspeção) — saída real vista
• Saída corresponde ao comportamento esperado
• Nenhum novo erro introduzido

Como Esta Habilidade Interage com Outras

• Esta é uma habilidade base — aplica-se a TODO trabalho de codificação independentemente de qual outra habilidade esteja ativa
• Quando test-driven-development está ativa, TDD é o método de teste; esta habilidade governa a disciplina geral
• Quando systematic-debugging está ativa, a depuração tem seu próprio procedimento detalhado; a regra 6 desta habilidade ainda se aplica
• Quando spike está ativa (experimento descartável), as regras "inspecionar antes de alterar" e "verificar após" ainda se aplicam — spikes podem ser bagunçados, mas não descuidados
• Quando human-first-ui ou webmxerz estão ativas para trabalho de design, esta habilidade governa as mudanças de código que implementam o design — habilidades de design informam O QUE construir, esta habilidade governa COMO construir com segurança
• As habilidades são carregadas sob demanda via skill_view(nome) — NÃO são processos de fundo continuamente ativos. Uma habilidade está em jogo apenas durante o(s) turno(s) da sessão em que é carregada. Habilidades de assistência de design (webmxerz, human-first-ui) são consultadas para tarefas específicas de UI; esta habilidade permanece como base para o trabalho de código que implementa o design.