Boas Práticas

O Makuco entrega mais quando você adota alguns hábitos no dia a dia. As práticas abaixo melhoram a qualidade das entregas e, ao mesmo tempo, reduzem o consumo de tokens, o que deixa o fluxo mais rápido e mais barato.

1. Uma sessão por propósito

Cada etapa do fluxo tem um objetivo diferente (descobrir, especificar, planejar, codificar). Misturar tudo numa única conversa enche a janela de contexto com informação irrelevante para a tarefa atual, o que aumenta o custo de cada mensagem e faz o agente perder o foco.

• Abra uma sessão para cada planejamento / PBI. Assim o agente de código recebe uma janela de contexto limpa, só com o que importa para aquele passo.
• Ao terminar uma etapa, comece uma sessão nova para a próxima em vez de continuar a anterior.
• VSCode + Copilot: depois de cada geração de código, crie um chat novo, apague o antigo e dê reload no VSCode. O Copilot mantém memória em cache que pode carregar contexto desatualizado e gerar código fora dos padrões do projeto.

Sessão enxuta = menos tokens por mensagem + respostas mais aderentes ao projeto.

2. Seja direto nos seus prompts

Cada palavra que você escreve no prompt vira token de entrada, e cortesias, rodeios e contexto repetido só inflam a conta sem melhorar a resposta. Vá direto ao ponto: diga o que fazer, em qual arquivo e com qual restrição. O agente já tem o contexto do projeto no MAKUCO.md; não precisa reexplicá-lo a cada mensagem.

Evite — verboso e cheio de rodeios:

Então, eu estava analisando o nosso sistema de autenticação e acho que talvez possa haver
algum tipo de problema na parte que faz a validação do token, porque os usuários parecem
estar sendo deslogados antes da hora, mas eu não tenho certeza absoluta de qual é a causa
exata disso. Será que dá para investigar o que está acontecendo e ver se tem algo de errado
na lógica de expiração, e se tiver, ajustar para que funcione como deveria?

Prefira — direto e específico:

Token expira cedo demais em src/auth/token.ts. Verifique a comparação de expiração e corrija.

Outras formas de encurtar o prompt sem perder sinal:

• Aponte o arquivo em vez de colar o código inteiro, o agente lê o que precisa.
• Uma tarefa por mensagem — pedidos empilhados geram respostas longas e dispersas.
• Não repita o que já está no MAKUCO.md (stack, padrões, convenções).
• Corte saudações, agradecimentos e hedging ("será que talvez", "se não for incômodo").

Prompt enxuto = menos tokens de entrada + resposta mais focada no que você realmente pediu.

3. Escolha o modelo certo para a tarefa

Nem toda tarefa precisa do modelo mais caro. Usar um modelo grande para um ajuste trivial é desperdício; usar um pequeno em algo complexo gera retrabalho. Cada agente sugere um perfil de modelo:

Veja a tabela de modelos sugeridos em cada agente: por exemplo makuco-codegen e makuco-quick.

4. Use a trilha certa

Nem toda mudança justifica o pipeline completo. Escolher a trilha adequada evita gastar tempo e tokens com etapas desnecessárias.

• Quick Mode — para mudanças pequenas: ≤ 3 arquivos, causa raiz conhecida, sem novas dependências ou decisões de arquitetura.
• Fluxo completo — para features relevantes, que se beneficiam de descoberta, especificação e revisão.

5. Capriche na especificação

A especificação é a peça da qual todos os outros agentes partem. Uma spec vaga se propaga como retrabalho por todo o fluxo, cada correção tardia custa mais tokens do que um detalhe a mais no começo.

• Forneça o máximo de detalhes ao makuco-specify: o que fazer, objetivo, restrições e contexto.
• Revise os requisitos gerados antes de seguir para o planejamento e a codificação.
• Quando a validação falhar, corrija a spec e repita. Não remende só o código.

6. Mantenha o contexto do projeto atualizado

Os agentes leem o contexto do projeto antes de trabalhar. Quanto melhor esse contexto, menos explicação você precisa repetir a cada sessão.

• Rode o comando start-makuco logo após o makuco init para gerar a base de conhecimento do projeto. Ele mapeia o código em .makuco/docs/codebase/ e preenche o MAKUCO.md automaticamente. Veja os detalhes em Configurações.
• Mantenha o MAKUCO.md atualizado com stack, arquitetura, padrões e convenções do projeto.
• Adicione padrões de código, exemplos e convenções em .makuco/resources/ para os agentes aprenderem e se adaptarem ao projeto.

7. Revise entre as etapas

Cada agente entrega o resultado para o próximo. Revisar a saída antes de passar adiante impede que um erro pequeno vire um problema grande algumas etapas depois. Corrigir cedo é sempre mais barato.