reducing-entropy

Visão geral da skill reducing-entropy

A skill reducing-entropy é um apoio de refatoração de uso manual, pensado para encolher uma base de código de forma intencional. Não é um prompt genérico de cleanup e não deve ser acionada automaticamente. Use quando o objetivo real for reduzir peças em movimento, diminuir o volume total de código e adotar um viés de remoção mais forte do que o de uma refatoração comum.

Para quem essa skill é mais indicada

reducing-entropy funciona melhor para quem está:

• refatorando código maduro que só continua crescendo
• revisando planos de “cleanup” que podem estar introduzindo abstrações às escondidas
• decidindo se uma feature, camada ou helper deveria existir em primeiro lugar
• tentando simplificar a arquitetura, e não apenas reorganizá-la

Ela é especialmente relevante em reducing-entropy for Refactoring, onde o instinto errado costuma ser criar nova estrutura em vez de remover a estrutura existente.

O trabalho real que ela resolve

Essa skill ajuda a responder uma pergunta mais difícil do que “que mudança eu devo fazer?”. Ela força perguntas como:

• como a base de código deveria ficar depois da mudança
• se o estado final é de fato menor
• o que pode ser apagado em vez de preservado

Por isso, ela é mais útil do que um prompt genérico de “simplifique este código” quando você quer um viés forte de redução líquida.

O que torna reducing-entropy diferente

O principal diferencial está na métrica de sucesso: quantidade final de código, não esforço de implementação.

Na prática, isso faz a skill favorecer resultados como:

• escrever uma migração pequena que elimina um subsistema grande
• trocar tipos customizados por estruturas de dados mais simples
• remover comportamentos opcionais em vez de generalizá-los
• rejeitar designs “mais limpos” que aumentam o total de código

Restrição importante antes de adotar

Isso não é um padrão seguro para toda tarefa. O repositório deixa explícito que reducing-entropy é manual-only e voltado a intenções explícitas do usuário. Se, numa determinada tarefa, sua equipe valoriza mais extensibilidade, preparação para o futuro ou estabilidade de interfaces do que redução de código, essa skill pode forçar demais a remoção.

O que ler antes de decidir usar

Leia estes arquivos primeiro:

• skills/reducing-entropy/SKILL.md
• skills/reducing-entropy/README.md
• skills/reducing-entropy/references/simplicity-vs-easy.md

Depois, veja um ou dois mindsets de referência adicionais conforme o seu cenário:

• references/data-over-abstractions.md
• references/design-is-taking-apart.md
• references/expensive-to-add-later.md

Essas referências importam porque a skill espera que você fundamente as decisões em pelo menos um mindset de simplificação antes de agir.

Como usar a skill reducing-entropy

Instalação e configuração da reducing-entropy

Se você usa o padrão Skills CLI deste repositório, instale a skill com:

npx skills add softaworks/agent-toolkit --skill reducing-entropy

Depois, abra a pasta da skill instalada e leia SKILL.md antes do primeiro uso. Isso não é uma skill de automação pronta para usar; é um framework de decisão que você aciona de forma deliberada.

Comece pelo mindset de referência obrigatório

Um detalhe prático que muita gente deixa passar: reducing-entropy orienta você a carregar pelo menos um arquivo de references/ antes de prosseguir. Faça isso primeiro e diga qual deles você está usando.

Boas combinações:

• use simplicity-vs-easy.md quando um padrão familiar parecer tentador, mas pesado
• use data-over-abstractions.md quando o código estiver cheio de wrappers, managers ou tipos customizados
• use design-is-taking-apart.md quando as responsabilidades estiverem embaralhadas
• use expensive-to-add-later.md quando remover algo puder entrar em conflito com o custo de recolocar isso no futuro

Essa etapa melhora a qualidade da saída porque dá ao modelo uma lente concreta de simplificação, em vez de uma meta vaga como “deixar mais limpo”.

Que tipo de entrada a reducing-entropy precisa

Para obter uma saída útil, forneça mais do que um link do repositório ou um dump de arquivos. A skill funciona melhor quando você informa:

• o objetivo aprovado pelo usuário
• o comportamento atual que precisa ser preservado
• a parte da base de código que está no escopo
• restrições sobre API, migrações ou prazo
• se é permitido remover coisas entre arquivos, módulos ou features

Exemplo de entrada forte:

“Use reducing-entropy no nosso fluxo de retry de billing. Objetivo: preservar o comportamento atual de retry para falhas do Stripe, mas reduzir o total de código em services/billing/ e workers/retry/. Você pode remover caminhos de configuração mortos e camadas duplicadas de helpers. Não altere respostas públicas de API nem o schema do banco esta semana.”

Isso é muito melhor do que:

“Refatore billing para ficar mais simples.”

Como transformar uma meta vaga em um bom prompt de reducing-entropy

Um bom prompt de reducing-entropy usage normalmente tem cinco partes:

1. ativação explícita
2. escopo-alvo
3. comportamento protegido
4. permissão de remoção
5. formato de saída

Exemplo:

“Apply the reducing-entropy skill. Load one reference mindset first and tell me which one you chose. Analyze src/cache/ and src/session/ for the smallest codebase that still supports current login/session behavior. Prefer deletion over reorganization. Reject options that increase total code even if they look cleaner. Give me:

• the smallest end-state design
• what to delete
• what to merge
• risks
• rough before/after code footprint”

Fluxo de trabalho sugerido para refatoração real

Um fluxo confiável é:

1. ler SKILL.md
2. escolher um mindset de referência
3. inspecionar os limites atuais entre módulos
4. listar o comportamento que precisa sobreviver
5. fazer as três perguntas centrais da skill
6. produzir 2–3 estados finais candidatos
7. comparar essas opções pela redução líquida de código
8. implementar o menor resultado viável
9. revisar se sobraram abstrações e caminhos mortos

Isso evita um modo de falha comum: começar a editar antes de decidir qual é o menor design possível que ainda atende ao caso.

As três perguntas da reducing-entropy que você deve forçar em toda execução

O repositório organiza a skill em torno de três checagens. Na prática, deixe isso explícito no prompt:

• Qual é a menor base de código que resolve isso?
• Essa mudança resulta em menos código no total?
• O que podemos apagar?

Se você não força essas perguntas, a saída costuma escorregar de volta para conselhos padrão de refatoração.

Onde reducing-entropy funciona melhor

Os casos de melhor encaixe incluem:

• colapsar módulos duplicados em um caminho único mais simples
• remover wrappers, factories, managers e abstrações finas
• trocar estruturas customizadas por dados simples mais funções
• apagar features pouco usadas ou configurabilidade excessiva
• simplificar um subsistema embolado antes de adicionar trabalho novo

É por isso que reducing-entropy for Refactoring é o encaixe mais forte: trata-se mais de redesenhar o estado final do que de polir estilo de código local.

Quando não usar reducing-entropy

Evite essa skill quando o trabalho principal for:

• adicionar uma nova capacidade com requisitos futuros incertos
• preservar uma superfície estável de extensão para terceiros
• desenhar preocupações fundamentais que são caras de adaptar depois
• tornar o código mais legível sem permissão para apagar ou fundir comportamentos

Nesses casos, o viés de remoção vira desencontro, não vantagem.

Arquivos práticos do repositório para ler primeiro

Para entender rápido, siga esta ordem de leitura:

1. SKILL.md
2. README.md
3. references/simplicity-vs-easy.md
4. references/design-is-taking-apart.md
5. references/data-over-abstractions.md

Leia adding-reference-mindsets.md apenas se quiser entender como os autores pensam sobre esses arquivos de apoio mais filosóficos.

Dicas que melhoram de verdade a qualidade da saída

Três táticas fazem a maior diferença:

• Peça uma arquitetura mínima de estado final antes de pedir mudanças de código.
• Exija remoções explícitas, não apenas simplificações.
• Faça o modelo estimar o que desaparece: arquivos, funções, classes, branches, configs.

Isso transforma a skill de um empurrãozinho de estilo em um exercício real de redução.

FAQ da skill reducing-entropy

A reducing-entropy é melhor do que um prompt normal de refatoração?

Em geral, sim, quando seu objetivo é simplificação líquida. Um prompt genérico costuma propor camadas mais limpas, nomes melhores ou abstrações mais reutilizáveis. reducing-entropy é melhor quando esses movimentos fariam a base crescer e você quer que o modelo resista a isso.

reducing-entropy é adequada para iniciantes?

Sim, desde que a pessoa iniciante já entenda bem o sistema atual a ponto de definir escopo e comportamento protegido. O framework da skill é simples, mas bons resultados dependem de saber o que pode ser removido com segurança.

reducing-entropy significa apenas apagar código?

Não. Ela pode justificar escrever algum código, se isso permitir apagar muito mais no resultado final. O teste central é o estado final. Pequenos acréscimos são aceitáveis se substituírem estruturas maiores.

Posso usar reducing-entropy em trabalho greenfield?

Em geral, não como guia principal. Ela é mais forte para podar ou simplificar uma base existente do que para desenhar uma nova do zero.

Como a reducing-entropy se compara a um cleanup comum?

Um cleanup comum costuma otimizar legibilidade local ou organização. A reducing-entropy skill otimiza menos conceitos, menos estruturas e menos código total. Esses objetivos se sobrepõem, mas não são a mesma coisa.

Quais são os principais riscos antes de instalar?

Os riscos principais são:

• apagar flexibilidade de que você realmente precisa
• simplificar demais diante de requisitos futuros
• medir contagem de linhas de forma mecânica demais
• remover estrutura que existe por motivos operacionais reais

É por isso que o arquivo de referência expensive-to-add-later.md importa. Ele traz uma exceção fundamentada ao viés puro de remoção.

reducing-entropy serve para qualquer repositório?

Não. Ela se encaixa melhor onde o crescimento do código é o problema. É menos adequada para sistemas altamente regulados, plataformas públicas ou produtos muito extensíveis, nos quais estrutura explícita pode fazer parte do próprio requisito.

Como melhorar a skill reducing-entropy

Dê limites mais nítidos para a reducing-entropy

A forma mais rápida de melhorar o reducing-entropy usage é definir o que não pode mudar. Sem isso, o modelo pode propor remover comportamento valioso.

Exemplos de limites úteis:

• “Preserve API shape.”
• “No schema changes.”
• “Keep test coverage expectations.”
• “User-visible behavior must stay identical.”

Limites claros permitem que a skill seja agressiva com segurança.

Peça comparações de estado final, não uma resposta única

Em vez de pedir uma recomendação só, peça duas ou três opções de estado final ranqueadas por:

• redução total de código
• custo de migração
• risco de quebrar comportamento
• carga de manutenção

Isso expõe trade-offs e ajuda você a rejeitar um design “mínimo” que ainda seja arriscado demais para o momento.

Forneça sinais da base que revelem entropia

A skill melhora quando você aponta sinais de inchaço, como:

• lógica duplicada entre módulos
• classes wrapper com comportamento mínimo
• branches de configuração para modos não usados
• camadas de helpers que só repassam chamadas
• tipos customizados onde dados simples resolveriam

Esses indícios ajudam o modelo a mirar oportunidades reais de simplificação em vez de fazer edições cosméticas.

Fique atento aos modos de falha mais comuns

As saídas ruins mais comuns são:

• reorganizar o código em mais arquivos
• adicionar abstrações para “preparar para crescer”
• preservar caminhos mortos de compatibilidade
• propor nomes mais limpos sem reduzir a estrutura
• tratar “menos churn” como se fosse o objetivo

Se isso acontecer, reafirme a métrica central: menos código total na base final.

Use os arquivos de referência de forma estratégica

Os resultados melhoram quando você escolhe o mindset certo para o problema:

• use data-over-abstractions.md para questionar designs pesados em classes
• use design-is-taking-apart.md para separar responsabilidades misturadas
• use simplicity-vs-easy.md quando a solução familiar estiver acoplada demais
• use expensive-to-add-later.md para defender as poucas coisas que realmente vale manter

Essa é uma das partes mais fortes do repositório e vale usar de forma explícita, não passiva.

Peça candidatos à remoção por categoria

Um padrão de prompt com alto retorno é:

“List deletion candidates by category: feature, abstraction, config, compatibility path, helper, type, and file.”

Essa estrutura força o modelo a olhar além de edições locais no código e encontrar oportunidades mais amplas de redução.

Itere depois da primeira saída

Depois da primeira rodada, faça perguntas de acompanhamento como:

• “What remains that exists only to support the old design?”
• “Which abstractions are now redundant?”
• “What can be merged further without changing behavior?”
• “What would you remove if you had to cut this module by 30%?”

Essas perguntas de segunda rodada costumam revelar onde estão os ganhos reais.

Valide pela complexidade líquida, não só por contagem de linhas

Contagem de linhas importa aqui, mas não use isso no automático. As melhores melhorias também reduzem:

• conceitos a aprender
• saltos entre módulos para rastrear comportamento
• casos especiais
• caminhos de branching
• superfície de dependências

Uma base menor, mas ainda embolada, é só uma vitória parcial. O melhor uso do reducing-entropy guide combina remoção com desacoplamento.