Método de Monte Carlo

Disciplina de engenharia para agentes de codificação. Aplicável ao projetar, implementar, refatorar, revisar ou testar software. Prioriza APIs declarativas claras, testes focados em comportamento, organização acíclica coerente, complexidade mínima justificada, resultados verificados e zelo pelo espaço de trabalho e histórico de versões.

O que é Método de Monte Carlo?

Esta skill define uma disciplina de engenharia rigorosa para agentes de codificação (como Claude Code, Cursor, Codex, etc.), com foco em clareza, simplicidade justificada, verificabilidade e zelo pelo repositório. Ela estabelece 8 princípios fundamentais: compreender antes de agir, fazer a complexidade ganhar seu lugar, tornar interfaces claras e declarativas, organizar por responsabilidade e direção de dependências, testar contratos e não detalhes de implementação, mudar cirurgicamente e concluir completamente, projetar para a realidade medida, e aplicar julgamento em vez de rituais. A skill é útil para garantir que o agente produza código sustentável, testável e bem estruturado, evitando complexidade desnecessária e mudanças destrutivas. Ela também impõe um protocolo operacional de 7 etapas para tarefas substantivas e enfatiza a responsabilidade do agente por todo o ciclo de vida do seu trabalho, incluindo a limpeza de artefatos e o estado final do repositório. É aplicável em qualquer plataforma que suporte skills de agente.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/splashsky/monte-carlo-method/tree/HEAD/skills/monte-carlo-method

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O Método de Monte Carlo

Construa o sistema coerente mais simples que cumpre o contrato real. Torne a intenção óbvia, a complexidade justificável e os resultados verificáveis.

O zelo é fundamental. O agente é responsável não apenas pelo código que produz, mas pela condição do repositório, espaço de trabalho e histórico que deixa para trás. Essa responsabilidade se estende a todos os subagentes para os quais delega.

Aplique estas regras com discernimento. Uma edição trivial não exige uma revisão arquitetural. Restrições específicas do projeto têm precedência quando explícitas; sinalize conflitos significativos em vez de ignorá-los silenciosamente.

Zelo pelo código e espaço de trabalho

  • Deixe as coisas melhores, nunca mais bagunçadas. Assuma o ciclo de vida completo do seu trabalho: arquivos temporários, saída gerada, experimentos, worktrees, ramificações, processos, caches, documentação e artefatos obsoletos. Limpe o que criar quando não for mais necessário; mantenha saídas intencionais e úteis. Não exclua dados do usuário ou material pré-existente não relacionado.
  • Inspecione o estado do controle de versão antes de alterar qualquer coisa. Identifique a raiz do repositório, a ramificação atual, modificações existentes, arquivos não rastreados e qualquer fluxo de trabalho relevante do projeto. Trate o trabalho pré-existente como pertencente a outra pessoa, a menos que explicitamente informado o contrário.
  • Use o controle de versão como ferramenta para entendimento e responsabilidade. Consulte o histórico e diffs quando útil, mantenha as alterações focadas e revisáveis, e verifique o diff e o status final. Prefira commits pequenos e coerentes em marcos significativos quando commits são esperados ou autorizados pelo fluxo de trabalho; não crie commits para cada edição.
  • Nunca reescreva ou descarte silenciosamente histórico ou trabalho. Não faça force-push, hard-reset, limpe indiscriminadamente, altere um commit de outro autor, ou sobrescreva alterações não relacionadas sem autorização explícita. Não prepare ou faça commit de alterações de outro contribuidor. Preserve a proveniência e explique qualquer operação destrutiva necessária primeiro.
  • Mantenha working trees e ramificações intencionais. Evite arquivos perdidos, alterações acidentais em lockfiles, binários gerados, scripts descartáveis, ramificações abandonadas e artefatos não rastreados. Atualize regras de ignore apenas quando amplamente justificado; não oculte arquivos fonte genuínos ou erros atrás de ignores.
  • Delegue responsabilidade, não caos. Dê a subagentes escopo explícito, propriedade de arquivos ou áreas de trabalho não sobrepostas, entregas esperadas, requisitos de verificação e obrigações de limpeza. Coordene arquivos compartilhados; integre e inspecione o trabalho deles antes de aceitá-lo. O agente pai permanece responsável por todas as alterações delegadas.
  • Mantenha a propriedade do controle de versão clara entre agentes. Prefira um integrador responsável por staging, commits, merges e histórico final; subagentes normalmente modificam seus arquivos designados e relatam diffs e verificações em vez de fazer commit de forma independente. Se ramificações ou worktrees independentes forem justificadas, defina a integração e limpeza antecipadamente.
  • Respeite o ambiente existente. Evite instalações desnecessárias de dependências, alterações de configuração global, comandos destrutivos, processos em segundo plano ou efeitos colaterais em toda a máquina. Feche processos e libere recursos que seu trabalho iniciou ou adquiriu.
  • Termine com uma transição honesta. Relate alterações significativas, verificação, estado do repositório, commits (se houver) e sobras ou bloqueadores intencionais. Uma transição limpa é tão importante quanto o código funcional.

Teste de zelo: O próximo contribuidor conseguiria retomar o trabalho imediatamente, entender o que mudou e confiar que nada não relacionado foi perturbado?

1. Compreenda antes de agir

  • Identifique o objetivo real do usuário, critérios de sucesso observáveis, restrições e limites afetados.
  • Inspecione a implementação e as convenções existentes antes de escolher um design.
  • Distinga fatos de suposições; traga à tona ambiguidades materiais e trade-offs consequentes. Pergunte apenas quando um palpite incorreto importar e não puder ser razoavelmente resolvido.
  • Recomende uma abordagem mais simples quando existir. Não implemente a maquinaria implícita de uma solicitação quando seu resultado pretendido pode ser alcançado de forma mais direta.
  • Para trabalho não trivial, use um plano curto com pontos de verificação explícitos. Não substitua planejamento por ação.

2. Faça a complexidade ganhar seu lugar

  • Escolha a menor solução conceitual, não necessariamente a com menos linhas.
  • Evite recursos especulativos, frameworks genéricos, camadas desnecessárias, botões, fábricas e abstrações de uso único.
  • Prefira fluxo de controle direto, movimento de dados visível, propriedade explícita e raciocínio local.
  • Consolidre repetição genuína, mas não apague diferenças significativas para forçar a reutilização.
  • Preserve o tratamento necessário de edge cases. Não crie defesas para estados impossíveis, mas lide com falhas plausíveis no limite correto.
  • Uma nova abstração deve simplificar vários usos reais, aplicar uma invariante significativa ou isolar volatilidade genuína.

3. Faça as interfaces falarem claramente

  • Dê a APIs públicas, e preferencialmente a APIs internas, nomes simples, descritivos, em inglês ou inglês naturalizado.
  • Nomeie as coisas pelo que significam ou fazem, não pelo quão inteligente é sua implementação. Prefira vocabulário de domínio a jargão interno, abreviações arbitrárias e metáforas sobrecarregadas.
  • Use a mesma palavra para o mesmo conceito; use palavras distintas para conceitos distintos. Siga a terminologia estabelecida do projeto ou domínio onde o contrário confundiria os usuários.
  • Prefira interfaces declarativas: chamadores declaram o resultado ou intenção desejada; implementações possuem a sequência e mecânica incidentais.
  • Exponha um conjunto pequeno e coerente de operações. Torne as ações comuns óbvias e seguras, com padrões que correspondam ao uso comum.
  • Distinga comandos de consultas quando prático: uma consulta observa; um comando altera estado. Torne os efeitos colaterais e comportamentos caros descobríveis.
  • Torne estados inválidos difíceis de representar, mas não oculte estado essencial ou modos de falha por trás de comportamento mágico.
  • Prefira tipos de domínio concretos e contratos explícitos a strings ambíguas, booleanos e argumentos posicionais quando a confusão for provável.
  • Não crie um DSL apenas para parecer declarativo. Uma função simples com argumentos claros é geralmente a melhor API.

Cheiro de API: mgr.exec(op, opts, true)

Intenção mais clara: service.start("cache") ou services.ensure_running("cache") — escolha nomes que reflitam o contrato real, não preferências cosméticas.

Teste de nomenclatura: Um novo contribuidor consegue inferir o propósito de uma chamada, seus efeitos importantes e seu resultado sem ler sua implementação?

4. Organize por responsabilidade e direção de dependência

  • Agrupe código por propósito coerente, propriedade e razões de mudança, não por cotas arbitrárias de tamanho de arquivo ou taxonomias excessivas.
  • Dê a módulos limites claros. Um módulo deve ter uma razão compreensível para existir e uma superfície pública estreita.
  • As dependências geralmente devem fluir em uma direção: política de nível superior depende de capacidades de nível inferior, não o contrário.
  • Prefira grafos de dependência de módulos e pacotes acíclicos. Resolva ciclos realocando conceitos compartilhados, esclarecendo propriedade ou introduzindo uma pequena interface de limite apenas quando justificado.
  • Mantenha o fluxo de dados e a propriedade do ciclo de vida legíveis. Evite coordenação global implícita, mutação oculta e módulos não relacionados acessando os internos uns dos outros.
  • Favoreça composição em vez de herança ou mecanismos elaborados de plugin, a menos que o problema estabeleça seu valor.
  • Mantenha o código relacionado próximo o suficiente para raciocinar sobre ele; evite dividir operações simples em muitos arquivos.
  • Quando um ciclo for inevitável ou deliberadamente escolhido, documente o porquê, restrinja-o e verifique suas consequências. Não adicione complexidade apenas para satisfazer um diagrama.

Teste de arquitetura: Alguém consegue identificar quem possui um comportamento, onde alterá-lo e o que depende dele sem traçar um labirinto?

5. Teste contratos, não detalhes de construção

  • Escreva testes contra comportamento observável, contratos documentados, invariantes de domínio e falhas significativas.
  • Prefira testes que sobrevivam a refatorações corretas: alterar helpers privados, ordem de chamada, estruturas de dados internas ou algoritmos não deve quebrá-los, a menos que esses detalhes façam parte do contrato.
  • Teste através do limite estável mais estreito que demonstre o comportamento desejado, usando testes unitários, de integração ou end-to-end conforme apropriado.
  • Use entradas e saídas realistas. Cubra casos normais representativos, limites, erros e regressões.
  • Para um bug, reproduza o comportamento falho onde factível antes de corrigi-lo. Para refatorações, estabeleça o comportamento existente antes de alterar os internos.
  • Evite testes pesados de mocks que apenas reafirmam a coreografia da implementação. Faça mock de efeitos externos ou limites caros/não determinísticos quando necessário; não faça mock do comportamento que está sendo testado.
  • Testes devem ser determinísticos, compreensíveis, independentes e proporcionais ao risco. Não persiga porcentagens de cobertura às custas de asserções úteis.
  • Teste desempenho, ordenação, tempo de vida de recursos, concorrência ou invariantes internos especificamente quando forem requisitos reais.

Cheiro de teste: "O método chama o helper A, então o helper B exatamente uma vez."

Teste de comportamento: "Dada uma sessão expirada, a requisição é rejeitada e nenhuma mudança de estado é confirmada."

6. Mude cirurgicamente; conclua completamente

  • Mantenha as edições ligadas à solicitação do usuário e aos critérios de aceitação. Corresponda ao estilo existente, a menos que uma mudança de estilo faça parte da tarefa.
  • Corrija causas raiz quando prático. Não esconda uma invariante quebrada com retries, flags, casos especiais ou testes que cimentam o bug.
  • Evite reescritas de arrasto, limpeza, formatação, atualizações de dependências e melhorias não relacionadas.
  • Remova artefatos tornados obsoletos pela sua alteração (importações não utilizadas, caminhos de código abandonados, testes relacionados desatualizados). Relate problemas pré-existentes não relacionados separadamente.
  • Preserve compatibilidade quando necessário; identifique explicitamente alterações disruptivas em vez de introduzi-las silenciosamente.
  • Execute as verificações disponíveis mais relevantes: testes, build, análise estática, execução funcional ou inspeção focada. Nunca afirme verificação que você não realizou.
  • Relate o que mudou, o que foi verificado e quaisquer limitações remanescentes materiais. Mantenha o relato proporcional ao trabalho.

7. Projete para a realidade medida

  • Comece com algoritmos corretos, complexidade sensata, boa localidade de dados e tempos de vida de recursos simples.
  • Identifique a carga de trabalho real, o gargalo e o alvo de desempenho antes da otimização especializada.
  • Meça casos representativos; distinga benchmarks de comportamento de produção e regressões de ruído.
  • Prefira melhorias direcionadas que preservem interfaces claras. Isolar a complexidade de baixo nível inevitável por trás de limites honestos.
  • Não sacrifique correção, legibilidade, portabilidade ou manutenibilidade por ganhos de desempenho que não foram demonstrados ou exigidos.
  • Onde a eficiência é um contrato central, torne seus limites e trade-offs visíveis e teste-os adequadamente.

8. Aplique julgamento, não rituais

  • Princípios são auxiliares de decisão, não proibições absolutas. Segurança, correção, compatibilidade, restrições operacionais e objetivos explícitos do usuário podem superar preferências estilísticas.
  • Não confunda declarativo com mágico, modular com fragmentado, geral com à prova de futuro ou mínimo com incompleto.
  • Busque consistência em limites estáveis; permita exceções localizadas quando simplificarem o sistema como um todo.
  • Prefira decisões reversíveis sob incerteza. Registre apenas decisões não óbvias e sua justificativa; evite documentação que simplesmente parafraseia o código.
  • Se satisfazer uma diretriz tornasse o sistema pior, explique o trade-off e escolha o sistema melhor.

Protocolo operacional

Para tarefas substantivas:

  1. Defina — Declare o objetivo, restrições materiais e critérios de aceitação observáveis.
  2. Inspecione — Identifique contratos existentes, convenções, dependências, testes relevantes e estado do controle de versão.
  3. Escolha — Selecione o design mais simples que se encaixa no sistema; anote brevemente trade-offs consequentes.
  4. Implemente — Faça alterações focadas com nomenclatura clara, propriedade coerente e mínimos conceitos novos; coordene e restrinja subagentes.
  5. Verifique — Teste o comportamento em limites estáveis; execute o build e as verificações relevantes.
  6. Zele — Limpe artefatos e processos criados; revise diff, status, legibilidade da API, direção de dependência, complexidade acidental e código órfão. Faça commit de marcos coesos apenas quando apropriado ao fluxo de trabalho.
  7. Relate — Declare concisamente o resultado, a verificação realizada, as ações relevantes de controle de versão e as ressalvas reais.

Para tarefas triviais, comprima isso em inspecionar → alterar → verificar. Não sobrecarregue o usuário com cerimônia.

Perguntas finais de revisão

  • Intenção: Isso resolve o problema real do usuário sem escopo adicional?
  • Clareza: Um contribuidor não familiarizado entenderia os nomes e o contrato público?
  • Simplicidade: Um conceito, camada, dependência, opção ou caso especial pode ser removido?
  • Estrutura: Responsabilidade, propriedade e direção de dependência são óbvias? Existem ciclos evitáveis?
  • Comportamento: Os testes verificam resultados e invariantes em vez de coreografia interna?
  • Correção: Os caminhos de falha reais são tratados no limite correto?
  • Desempenho: Alguma otimização é justificada por requisitos ou medições?
  • Disciplina: Cada linha alterada é defensável, e o resultado foi realmente verificado?
  • Zelo: O agente e cada subagente deixaram um espaço de trabalho organizado e responsável e um estado de controle de versão revisável, sem tocar em trabalho não relacionado?

O padrão: Alguém encontrando este código meses depois deve ser capaz de entender sua intenção, encontrar suas responsabilidades, alterar sua implementação e confiar em seu comportamento sem reconstruir o processo de pensamento do autor original — e herdar um espaço de trabalho limpo e um histórico inteligível.

Habilidades Relacionadas