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 skill orquestradora tem um objetivo diferente (analisar, desenvolver, revisar). 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 a skill perder o foco.

• Abra uma sessão para cada skill / cada PBI. Assim o desenvolvimento recebe uma janela limpa, só com o que importa para aquela PBI.
• Ao terminar uma etapa, comece uma sessão nova para a próxima em vez de continuar a anterior. O status.yml e os arquivos de sessão (sessao.md, sessao-dev.md, sessao-review.md) preservam o estado — trocar de chat não custa contexto perdido.
• 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.
• Na CLI interativa isso é automático: a sessão pertence à skill, e a troca de skill fecha uma e abre outra sem você fazer nada. Continuar na mesma skill reaproveita o processo vivo de propósito — é o contexto que você quer manter. Para zerar à mão, use /clear, que encerra a sessão e o contexto de uma vez.

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. As skills já têm o contexto do projeto em .makuco/docs/codebase/; 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 — a skill lê o que precisa.
• Uma tarefa por mensagem — pedidos empilhados geram respostas longas e dispersas.
• Não repita o que já está na base de conhecimento (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.

Veja a tabela de modelos sugeridos em cada página do Fluxo.

4. Use a trilha certa

Nem toda mudança justifica o fluxo 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 análise, especificação e revisão.

E, dentro do fluxo completo: se as PBIs já existem e estão prontas para construir, pule o makuco-analisar e vá direto ao makuco-desenvolver.

5. Capriche na entrada da análise

O makuco-analisar é a peça da qual tudo o resto parte. Uma análise 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 iniciar a análise: o que fazer, objetivo, restrições e contexto.
• Escolha o modo certo: DESCOBERTA quando a oportunidade ainda é nebulosa, SOLUÇÃO quando o problema já está entendido, EXPRESS quando o item já está decidido e escrito num card, e INVESTIGAÇÃO quando algo quebrou e ninguém sabe por quê. A skill sempre pergunta — não deixe no automático.
• Se a feature tem tela, entre com a referência visual já na análise. É o momento mais cedo e mais útil.

6. Revise nos checkpoints

Cada skill para em pontos específicos e espera você. Esses checkpoints existem porque um erro pequeno aprovado ali vira um problema grande algumas etapas depois:

• makuco-analisar — cada PBI é proposta uma a uma, com a tabela INVEST. Aprove, ajuste ou remova.
• makuco-desenvolver — o step-03 para para você aprovar a spec.md + task.md antes de qualquer implementação. Leia os dois arquivos: a qualidade da spec determina a qualidade de tudo que vem depois.
• makuco-code-review — a skill anuncia quais passes vão rodar e sobre quantos arquivos antes de gastar. É o último momento barato para estreitar o escopo.

Quando a validação falhar, corrija a spec e repita. Remendar só o código deixa a spec mentindo, e o erro volta nas próximas tasks.

7. Mantenha o contexto do projeto atualizado

As skills leem .makuco/docs/codebase/* antes de trabalhar. Quanto melhor esse contexto, menos explicação você repete a cada sessão — e o roteamento por gap do makuco-desenvolver depende dele para escolher a skill especialista certa. Contexto raso vira roteamento errado, e roteamento errado propaga as convenções da skill errada.

• Rode o prompt start-makuco logo após o makuco init para gerar a base de conhecimento. Veja Configurações.
• Comece pelo modo índice (barato) e rode a pesquisa completa só no repo em que você vai trabalhar. Uma varredura sobre todos os repos custa N passes — só faça se realmente precisar.
• Mantenha analise.aprovador e research.referencias preenchidos no frontmatter do MAKUCO.md.
• Adicione padrões de código, exemplos e convenções em .makuco/resources/ para as skills aprenderem e se adaptarem ao projeto.

8. Deixe o quality gate bloquear

O makuco-desenvolver não commita uma task com achado aberto, e não marca a PBI concluída com build vermelho. Isso é de propósito. Um achado que você "resolve depois" custa uma ida e volta pelo review, e uma PBI marcada como pronta em cima de um build quebrado envenena a próxima.

Se um gate reportar PULADO, olhe o motivo: geralmente é Docker parado, SONAR_URL/SONAR_TOKEN ausente, ou uma skill não instalada. Um PULADO não bloqueia, mas também não é um APROVADO.