improve-codebase-architecture (mattpocock/skills)

Avaliação

Codex CLI 0.166 (gpt-6-astra, raciocínio baixo) em um PC Windows dedicado a testes, um projeto temporário novo e HOME/TMPDIR/caches temporários por execução, skill instalada (tratamento), ausente (controle) ou ausente com o requisito central da skill condensado em uma frase anexada ao prompt (grupo de uma frase), 2 execuções por grupo por tarefa, rede desligada, gravações em /tmp bloqueadas. Os prompts nunca mencionam a skill (exceto o texto indicado abaixo). Três tarefas em um pequeno backend de loja em Python com atritos inseridos de propósito (validadores/helpers de dinheiro superficiais, um serviço de inventário que apenas repassa chamadas ao seu repositório, um único adaptador de pagamento, lógica de desconto duplicada no carrinho e nos pedidos, testes que cobrem apenas os helpers): uma revisão de arquitetura do código inteiro escrita como report.html, o mesmo, limitado a pagamento e inventário, e “por que é penoso testar place_order” respondida no chat. Os prompts do grupo com skill começam com $improve-codebase-architecture (invocação explícita); os prompts do controle e de uma frase não a nomeiam.

Comparação entre os braços

Medido com Codex CLI em 18 execuções, com pontuação por verificações baseadas em regras e sem juiz LLM. Total 23.0 / 30, veredito Situacional.

Veredito: Situacional (23.0 / 30). Fonte: mattpocock/skills, skills/engineering/improve-codebase-architecture, skills/engineering/codebase-design, fixada no commit 4ae2317. Instalação: npx skills@latest add mattpocock/skills --skill improve-codebase-architecture. Licença: MIT (LICENSE do repositório).

O que é

A skill improve-codebase-architecture de mattpocock/skills. Ela procura 'oportunidades de aprofundamento' em uma base de código: módulos rasos cuja interface é tão complexa quanto a implementação, camadas de repasse, costuras hipotéticas de adaptador único, lógica duplicada, comportamento testado apenas por meio de auxiliares. Ela escreve um relatório HTML com um antes/depois por candidato e uma recomendação principal. Apoia-se em uma skill irmã, codebase-design, para o vocabulário. Apenas Markdown, sem scripts.

Como testamos

Codex CLI 0.166 (gpt-6-astra, raciocínio baixo) em um PC Windows dedicado a testes, um projeto temporário novo e HOME/TMPDIR/caches temporários a cada execução, skill instalada (tratamento) ou ausente (controle) ou ausente com o requisito central da skill comprimido em uma frase anexada ao prompt (grupo de uma frase), 2 execuções por grupo por tarefa, rede desligada, gravações em /tmp bloqueadas. Os prompts nunca mencionam a skill (exceto pelo texto indicado abaixo).

Três tarefas em um pequeno backend de loja em Python com atritos plantados (validadores/auxiliares de dinheiro rasos, um serviço de estoque que apenas repassa para o repositório dele, um único adaptador de pagamento, lógica de desconto duplicada no carrinho e nos pedidos, testes que só cobrem auxiliares): uma revisão de arquitetura da base de código inteira escrita como report.html, a mesma limitada a pagamento e estoque, e 'por que place_order é penoso de testar' respondida no chat. Os prompts do grupo com a skill começam com $improve-codebase-architecture (invocação explícita); os prompts de controle e de uma frase não a nomeiam.

1. Varredura de arquitetura do repositório inteiro — Revise este pequeno backend de loja em busca de melhorias de arquitetura: onde a reestruturação tornaria o código mais fácil de mudar e de testar? Escreva suas descobertas como um relatório HTML autocontido chamado report.html nesta pasta (não abra um navegador nem inicie um servidor…
2. Somente pagamentos e estoque — Olhe apenas as partes de pagamento e estoque deste backend e me diga quais reestruturações compensariam. Escreva suas descobertas como um relatório HTML autocontido chamado report.html nesta pasta (não abra um navegador nem inicie um servidor) e não altere nenhum código…
3. Por que place_order é difícil de testar? — Parece penoso escrever um teste de verdade para place_order neste backend. Por quê, e que reestruturação resolveria isso? Não altere nenhum arquivo; responda na sua mensagem final.

A pontuação é programática (testes ocultos / detecção de problemas plantados / verificações de restrições / renderização+OCR quando aplicável), 0–5 por execução. Nenhum juiz LLM decidiu qualquer pontuação.

Resultados

O prompt de uma frase dado ao terceiro grupo: "Procure oportunidades de aprofundamento: módulos rasos cuja interface é tão complexa quanto a implementação (aplique o teste de exclusão: excluí-lo concentraria a complexidade ou apenas a moveria?), camadas de repasse, costuras de adaptador único que são apenas hipotéticas, lógica duplicada entre módulos e lógica testada apenas por meio de auxiliares em vez da interface real; apresente cada candidato com arquivos, problema, solução, benefícios, um antes/depois, e nomeie uma recomendação principal."

Pontuação média: 3.2 sem a skill vs 4.12 com ela (delta +0.92). Tokens por execução: 115k vs 208k (1.80x); tempo 112s vs 135s. Grupo de uma frase: 3.91 (ganho da skill sobre o prompt de uma frase: +0.2; ganho do próprio prompt de uma frase sobre nenhuma skill: +0.72); tokens do prompt de uma frase: 120k por execução, então a skill custa 1.73x o prompt de uma frase.

O que aconteceu

• A revisão da base de código inteira é onde ela aparece: a skill e a versão em uma frase encontraram 6/6 pontos plantados com vocabulário de arquitetura, antes/depois e uma recomendação principal nas quatro execuções; o Codex sozinho encontrou 2/6 em uma execução e 5 de 6 verificações na outra, e nenhuma das execuções tinha uma 'recomendação principal' clara.
• A revisão focada (somente pagamento e estoque) é difícil para todo mundo: o melhor grupo encontrou um dos dois pontos plantados em média. Controle 2/4 verificações, uma frase 3/4, skill 3/4. A skill não foi melhor que a frase.
• Em 'por que place_order é difícil de testar', os três grupos encontraram as causas plantadas (PaymentAdapter escondido, estoque compartilhado no nível do módulo, lógica de desconto duplicada, testes que param nos auxiliares). A resposta da skill usou o vocabulário dela ('interface', 'localidade'); a do controle era igualmente correta em palavras simples.
• Pontuação média 3.20 controle, 3.91 uma frase, 4.12 skill. A skill acrescenta 0.21 sobre a frase com 1.7x os tokens (208k vs 120k por execução) porque também lê a skill irmã; o grupo de uma frase custa o mesmo que o controle (115k).
• Como a skill instala duas pastas de skill, as execuções com ela criaram arquivos extras na pasta .agents do projeto; eles foram excluídos da verificação de 'nenhum arquivo de código alterado' (uma primeira passada os reprovou por engano e um bug específico de Windows na verificação foi corrigido antes dos números finais).

Pontuações por dimensão

Limites deste teste

• Um pequeno fixture em Python com problemas de manual plantados; se o relatório é útil em um repositório real grande não é medido.
• A qualidade do relatório, os falsos positivos e o estilo HTML (ele carrega Tailwind e Mermaid de CDNs quando aberto em um navegador) não foram pontuados; o comportamento de subagente que a skill descreve não foi exercitado.
• O prompt de uma frase repete a própria checklist da skill, então é um limite superior para um prompt curto.
• n = 2 por grupo por tarefa: diferenças abaixo de cerca de 1 ponto são ruído.
• A pontuação baseada em regras mede o que as verificações conseguem ver; não julga bom gosto nem se o resultado é o melhor possível.

Segurança

Veja security.md. Scan: 0 CRITICAL / 0 HIGH / 0 MEDIUM. Veredito: seguro para executar (sandbox sem rede). Um scan limpo não prova que uma skill é segura.

Conclusão

Comparada a não fazer nada, a skill melhora claramente uma revisão da base de código inteira, principalmente por forçar a estrutura e o vocabulário do relatório, e custa 1.8x tokens. Uma única frase que lista os mesmos cheiros de código obtém a maior parte do ganho, então vale instalar principalmente se você quer o formato de relatório idêntico todas as vezes.