Melhorar a Arquitetura do Código-Fonte
Explore um código-fonte como uma IA faria, identifique atritos arquiteturais, descubra oportunidades para melhorar a testabilidade e proponha refatorações de aprofundamento de módulos como RFCs de issues do GitHub.
Um módulo profundo (John Ousterhout, "Uma Filosofia de Design de Software") possui uma interface pequena que esconde uma implementação grande. Módulos profundos são mais testáveis, mais navegáveis por IA e permitem testar no limite do módulo em vez de dentro dele.
Processo
1. Explore o código-fonte
Use a ferramenta Agent com subagent_type=Explore para navegar pelo código-fonte naturalmente. NÃO siga heurísticas rígidas — explore organicamente e observe onde você sente atrito:
- Onde entender um conceito exige navegar entre muitos arquivos pequenos?
- Onde os módulos são tão rasos que a interface é quase tão complexa quanto a implementação?
- Onde funções puras foram extraídas apenas para testabilidade, mas os bugs reais estão escondidos em como elas são chamadas?
- Onde módulos fortemente acoplados criam risco de integração nas junções entre eles?
- Quais partes do código-fonte não são testadas ou são difíceis de testar?
O atrito que você sente É o sinal.
2. Apresente candidatos
Apresente uma lista numerada de oportunidades de aprofundamento. Para cada candidato, mostre:
- Cluster: Quais módulos/conceitos estão envolvidos
- Por que estão acoplados: Tipos compartilhados, padrões de chamada, co-propriedade de um conceito
- Categoria de dependência: Consulte REFERENCE.md para as quatro categorias
- Impacto nos testes: Quais testes existentes seriam substituídos por testes de limite
Não proponha interfaces ainda. Pergunte ao usuário: "Qual desses você gostaria de explorar?"
3. O usuário escolhe um candidato
4. Enquadre o espaço do problema
Antes de gerar subagentes, escreva uma explicação voltada ao usuário sobre o espaço do problema para o candidato escolhido:
- As restrições que qualquer nova interface precisaria satisfazer
- As dependências que ela precisaria usar
- Um esboço de código ilustrativo para tornar as restrições concretas — isso não é uma proposta, apenas uma forma de fundamentar as restrições
Mostre isso ao usuário e prossiga imediatamente para a Etapa 5. O usuário lê e pensa sobre o problema enquanto os subagentes trabalham em paralelo.
5. Projete múltiplas interfaces
Gere 3+ subagentes em paralelo usando a ferramenta Agent. Cada um deve produzir uma interface radicalmente diferente para o módulo aprofundado.
Instrua cada subagente com um resumo técnico separado (caminhos de arquivo, detalhes de acoplamento, categoria de dependência, o que está sendo escondido). Esse resumo é independente da explicação voltada ao usuário na Etapa 4. Dê a cada agente uma restrição de design diferente:
- Agente 1: "Minimize a interface — foque em 1-3 pontos de entrada no máximo"
- Agente 2: "Maximize a flexibilidade — suporte muitos casos de uso e extensão"
- Agente 3: "Otimize para o chamador mais comum — torne o caso padrão trivial"
- Agente 4 (se aplicável): "Projete em torno do padrão portas e adaptadores para dependências entre fronteiras"
Cada subagente gera:
- Assinatura da interface (tipos, métodos, parâmetros)
- Exemplo de uso mostrando como os chamadores a utilizam
- Qual complexidade ela esconde internamente
- Estratégia de dependência (como as dependências são tratadas — consulte REFERENCE.md)
- Trade-offs
Apresente os designs sequencialmente e depois compare-os em prosa.
Após comparar, dê sua própria recomendação: qual design você considera mais forte e por quê. Se elementos de designs diferentes se combinarem bem, proponha um híbrido. Seja opinativo — o usuário quer uma leitura forte, não apenas um menu.
6. O usuário escolhe uma interface (ou aceita a recomendação)
7. Crie uma issue no GitHub
Crie uma RFC de refatoração como uma issue do GitHub usando gh issue create. Use o modelo em REFERENCE.md. NÃO peça ao usuário para revisar antes de criar — apenas crie e compartilhe a URL.