Codebase Design

ANÁLISE EDITORIAL

Codebase Design é uma Skill de Matt Pocock que oferece um vocabulário preciso para discutir arquitetura de software. Em vez de prometer uma refatoração automática, ela ajuda a distinguir módulo, interface, implementação, profundidade, ponto de troca, adaptador, alavancagem e localidade. O objetivo é concentrar comportamento atrás de uma interface pequena, testável e compreensível.

A versão auditada está no repositório mattpocock/skills, caminho skills/engineering/codebase-design, commit 9c9f36ccd3995266cd675468af71639c8dde1ec5. O repositório tinha 221.269 estrelas na consulta de 18 de agosto de 2026, não estava arquivado e usa licença MIT.

O pacote local preserva apenas SKILL.md, DEEPENING.md, DESIGN-IT-TWICE.md, LICENSE e ORIGEM.md. Não inclui scripts, executáveis, dependências, agentes, credenciais, dados de projeto ou configuração de instalação.

Imagem editorial exclusiva do Bastidores da IA. Não é captura de ferramenta, interface real, diagrama oficial nem prova de arquitetura validada.

O que esta Skill faz de verdade

A Skill começa fixando um significado operacional para palavras que costumam ser usadas de forma vaga. Um módulo pode ser uma função, classe, pacote ou fatia que atravessa camadas, desde que tenha uma interface e uma implementação. Interface não significa apenas assinatura ou palavra-chave do TypeScript. Ela inclui tudo o que o chamador precisa saber, como invariantes, ordem das operações, modos de falha, configuração e características de desempenho.

O conceito central é profundidade. Um módulo profundo entrega muito comportamento por meio de uma interface pequena. Um módulo raso quase não esconde complexidade, porque o chamador precisa conhecer tantos detalhes quanto a própria implementação. A Skill chama o benefício para o chamador de alavancagem e o benefício para quem mantém o código de localidade. Quando uma correção fica concentrada em um ponto, todos os chamadores se beneficiam.

Outro recurso é o teste de exclusão. Imagine remover o módulo. Se a complexidade desaparece, talvez ele fosse apenas uma passagem desnecessária. Se a mesma complexidade reaparece espalhada por vários chamadores, o módulo estava concentrando conhecimento útil. Esse teste evita avaliar arquitetura pelo número de classes ou linhas.

A Skill também diferencia interface e ponto de troca. O ponto de troca é o lugar em que um comportamento pode variar sem editar o chamador. Um adaptador ocupa esse lugar e satisfaz a interface. A regra prática é exigente: um adaptador pode representar apenas uma abstração hipotética; dois adaptadores justificam um ponto de troca real. Isso desestimula criar camadas preventivas sem variação concreta.

Os documentos complementares aprofundam duas situações. DEEPENING.md classifica dependências em processo, substituíveis localmente, remotas sob controle da equipe e externas. DESIGN-IT-TWICE.md propõe comparar alternativas de interface com agentes paralelos. O fluxo paralelo é opcional e depende do agente hospedeiro. O pacote não inicia agentes sozinho.

Para quem serve

Codebase Design serve a desenvolvedores, líderes técnicos, arquitetos, revisores e equipes que trabalham com agentes de código. Ela é especialmente útil quando uma discussão usa termos como serviço, componente, camada ou fronteira sem deixar claro o que o chamador realmente precisa conhecer.

Também ajuda antes de uma refatoração. Em vez de começar movendo arquivos, a equipe pode escolher um módulo, listar sua interface real, executar o teste de exclusão e identificar o que deveria ficar oculto. O resultado é uma hipótese de desenho que ainda precisa de código, testes e comparação com o comportamento atual.

A finalidade é diferente de Analyzing Release Readiness. A Skill da AWS organiza sinais de risco antes de um merge. Codebase Design trabalha o formato dos módulos e o vocabulário usado para discutir suas interfaces. Ela também complementa o guia de verificação de respostas de IA, porque transforma uma recomendação arquitetural em perguntas revisáveis.

Não é a melhor escolha para quem precisa somente aplicar um formatador, executar lint ou descobrir um erro de sintaxe. Também não substitui uma especificação de produto, um modelo de domínio ou uma medição de desempenho. O documento ensina uma lente de projeto, não um resultado automático.

Compatibilidade e pré-requisitos

O repositório documenta instalação para Codex e outros agentes por meio do Skills CLI, além de um plugin para Claude Code. A pasta segue o formato Agent Skills e contém Markdown. O núcleo da Skill funciona em qualquer agente que consiga descobrir o SKILL.md e ler os dois arquivos de referência.

O fluxo opcional Design It Twice exige suporte a agentes paralelos. Se o hospedeiro não oferece esse recurso, ainda é possível comparar duas ou três alternativas sequencialmente. O limite deve ser declarado, pois uma comparação feita por um único contexto não tem a mesma independência operacional de trabalhos separados.

Antes do primeiro uso, escolha um recorte concreto do código. É preciso ter ao menos os arquivos do módulo, seus chamadores, testes existentes e dependências relevantes. Sem esse escopo, termos como profundidade e localidade viram opinião genérica.

A Skill não exige runtime próprio, banco, token ou serviço externo. Entretanto, o agente hospedeiro pode precisar de permissão para ler o repositório. Editar código, criar agentes, executar testes ou acessar documentação externa são ações separadas e dependem das permissões configuradas no ambiente.

Instalação controlada

A documentação do projeto apresenta o comando npx skills@latest add mattpocock/skills --skill=codebase-design. O instalador permite escolher o agente e o escopo. Como npx baixa e executa um pacote, use primeiro em um projeto de teste e confira a origem do pacote antes de confirmar.

Abra o diretório oficial no commit auditado, leia o SKILL.md original e compare a licença MIT. O commit fixado torna a revisão reproduzível.

Selecione somente codebase-design no primeiro teste. Instalar o repositório inteiro adiciona vários fluxos com comportamentos diferentes, alguns voltados a issues, documentação ou implementação. Uma instalação ampla dificulta saber qual instrução foi acionada.

Depois de instalar, confirme que SKILL.md, DEEPENING.md e DESIGN-IT-TWICE.md ficaram juntos. Copiar apenas o arquivo principal quebra os links relativos usados nas seções avançadas. O ZIP do Bastidores preserva esse conjunto para inspeção, mas não executa o instalador.

Configuração antes do primeiro uso

Defina um módulo candidato e descreva a interface atual em linguagem de chamador. Liste métodos, parâmetros, invariantes, ordem necessária, erros e restrições de desempenho. Não comece pela estrutura de pastas, porque uma pasta pode conter vários módulos e um módulo pode atravessar várias pastas.

Em seguida, liste os chamadores reais e o comportamento que se repete neles. Essa comparação mostra se o módulo concentra conhecimento ou apenas repassa dados. Registre também os testes existentes e em qual interface eles observam o resultado. Testes presos a detalhes internos são um sinal, não uma prova, de desenho inadequado.

Classifique cada dependência conforme DEEPENING.md. Cálculo em memória pode ficar dentro do módulo. Banco local substituível pode usar uma implementação de teste realista. Serviço remoto da própria equipe pode justificar uma porta com adaptadores de produção e teste. Serviço externo exige cautela com mocks e contratos que a equipe não controla.

Por fim, combine o que não será alterado no primeiro uso. Preserve comportamento público, dados e contratos externos. A primeira entrega deve ser uma análise ou proposta, não uma refatoração silenciosa. Se houver edição, ela precisa de escopo, diff, testes e rollback próprios.

Primeiro uso seguro

1. Escolha um módulo pequeno, com dois ou três chamadores conhecidos.
2. Peça ao agente para descrever a interface completa, incluindo erros e invariantes.
3. Execute mentalmente o teste de exclusão e anote onde a complexidade reapareceria.
4. Identifique o comportamento que poderia ficar oculto atrás de uma interface menor.
5. Liste dependências e classifique cada uma antes de propor adaptadores.
6. Verifique se existe variação real. Não crie uma porta só porque pode ser útil no futuro.
7. Peça duas alternativas de interface, sem editar o código.
8. Compare as alternativas por alavancagem, localidade, ponto de troca e testabilidade.
9. Escolha um exemplo de uso e um modo de falha para testar a proposta.
10. Somente depois transforme a alternativa aprovada em um patch pequeno e reversível.

O primeiro uso funciona melhor como revisão guiada. Um relatório útil mostra a interface atual, o conhecimento vazando para chamadores, a hipótese de módulo mais profundo e as evidências que ainda faltam. Evite pedir apenas “melhore a arquitetura”, porque esse pedido não define escopo nem critério de aceite.

Resultado esperado

O resultado esperado é uma descrição clara do módulo e de sua interface real. A análise deve apontar o que fica visível aos chamadores, quais detalhes poderiam ser ocultados, onde está o ponto de troca e quais adaptadores existem de fato. Ela também deve explicar o ganho de alavancagem e localidade sem usar contagem de arquivos como substituto.

Uma proposta forte inclui pelo menos um exemplo de chamada, invariantes, ordem, erros e estratégia de teste. Se a interface fica menor, a análise precisa mostrar qual complexidade foi absorvida pela implementação. Caso contrário, a proposta pode apenas renomear ou deslocar o problema.

O resultado não precisa recomendar mudança. Em alguns casos, o teste de exclusão mostra que a camada atual é rasa e pode ser removida. Em outros, a dependência ainda tem um único adaptador e não justifica uma porta. Declarar que a abstração não se paga é uma conclusão válida.

Permissões e riscos

• Leitura de código: o agente pode acessar detalhes internos, comentários, contratos e nomes de domínio. Limite o escopo ao necessário.
• Refatoração prematura: uma interface elegante no papel pode quebrar comportamento implícito. Exija testes e migração incremental.
• Abstração hipotética: criar portas sem variação real adiciona indirection e reduz localidade.
• Teste excessivamente interno: mover testes sem preservar comportamento observável pode apagar cobertura útil.
• Agentes paralelos: o fluxo opcional distribui contexto entre agentes. Revise quais arquivos cada um pode ler e quais ações pode executar.
• Terminologia rígida: o vocabulário ajuda a conversa, mas não deve apagar termos do domínio do produto.
• Confiança indevida: análise estática não comprova desempenho, compatibilidade ou ausência de regressão.
• Edição e execução: a Skill não precisa escrever nem testar para ensinar o modelo. Trate qualquer mutação como etapa separada.

Erros comuns

• A Skill não aparece: confirme o diretório do agente, o nome codebase-design e se os arquivos de referência foram instalados junto.
• Interface vira sinônimo de TypeScript: inclua invariantes, erros, ordem, configuração e desempenho na análise.
• Tudo vira módulo profundo: aplique o teste de exclusão. Camada de passagem pode merecer remoção.
• Uma implementação gera uma porta: procure uma segunda variação concreta, como produção e teste realista.
• Mock para qualquer dependência: prefira implementação local quando ela reproduz o comportamento relevante.
• Arquitetura avaliada por linhas: profundidade é alavancagem na interface, não razão entre linhas internas e externas.
• Design It Twice não funciona: o hospedeiro pode não oferecer agentes paralelos. Compare alternativas sequencialmente e registre a limitação.
• Instalação duplicada: não combine plugin gerenciado e cópia pelo Skills CLI sem verificar caminhos e precedência.
• Refatoração sem base: preserve comportamento com testes e um diff pequeno antes de remover módulos antigos.
• Recomendação sem evidência: cite chamadores, testes e dependências que sustentam cada conclusão.

Versão auditada e download local

A referência desta página é o commit 9c9f36ccd3995266cd675468af71639c8dde1ec5, consultado em 18 de agosto de 2026. O repositório oficial tinha 221.269 estrelas e licença MIT. O SKILL.md não declara uma versão própria, por isso o commit é a identificação reproduzível desta curadoria.

O ZIP local possui 5 arquivos, 7.047 bytes e SHA-256 89c79f4deb8b6ac0406af3e57c594efca3bbc64ce2af618e446020d5ee286830. Ele preserva a Skill, as duas referências, a licença e o registro de origem. Não contém script, executável, dependência, agente, token, credencial ou código de usuário.

Use o download local auditado para conferir a versão curada. Para instalação e atualizações, abra o repositório oficial em ação separada. O catálogo de Skills do Bastidores mantém download e repositório como ações distintas.

Resultado esperado e limite final

Ao final, você deve conseguir explicar qual é o módulo, o que sua interface exige, que comportamento fica oculto, onde a variação realmente acontece e como os testes observam o resultado. Se essa explicação não cabe em termos concretos, a análise ainda não está pronta para orientar uma mudança.

Codebase Design não valida uma arquitetura, não mede desempenho e não garante que uma refatoração seja segura. Ela melhora a qualidade das perguntas e das alternativas. A decisão final ainda depende de requisitos, código atual, testes, telemetria, revisão humana e um caminho de reversão.

Fontes primárias

• Repositório oficial mattpocock/skills
• Diretório Codebase Design no commit auditado
• SKILL.md auditado
• Referência Deepening
• Referência Design It Twice
• Documentação oficial da Skill
• Licença MIT no commit auditado