Troubleshooting & FAQ

Erros comuns na instalação e no uso do Makuco — e como resolver.

Respostas rápidas para os problemas mais comuns. Se o seu não estiver aqui, confira Instalação e Configurações.

Instalação

Base de conhecimento

Makuco MCP & quality gate

Azure DevOps

Uso no dia a dia

CLI interativa

Não resolveu?

Revise Instalação, CLI Interativa e Configurações, ou procure o time responsável pelo Makuco.

Instalação

O makuco init não gerou os arquivos esperados

Quero atualizar os ativos sem perder o que eu customizei

O makuco init apagou o índice de repositórios do MAKUCO.md

Base de conhecimento

O MAKUCO.md traz conteúdo genérico que não condiz com o projeto

As skills ignoram a stack e as convenções do projeto

A pesquisa de projeto está custando caro demais

O makuco-desenvolver está roteando para a skill especialista errada

Makuco MCP & quality gate

O Makuco MCP não estabelece conexão

Perda do token do SonarQube

A análise do SonarQube não localiza o projeto

Um gate apareceu como PULADO no resumo — isso é problema?

O quality gate está bloqueando por um problema que já existia antes

Azure DevOps

Não quero usar tracker — o Makuco funciona sem?

A skill não reconhece o tipo de work item do meu projeto

O tipo resolvido diverge do que eu informei

O work item não foi movido para concluído

Uso no dia a dia

Onde foi o makuco-discovery / makuco-codegen / makuco-reviewer?

Pedi para o code review corrigir os achados e ele recusou

O review aprovou mas a documentação não foi atualizada

O review rodou só alguns passes — está incompleto?

O Copilot gera código fora dos padrões do projeto

Consumo excessivo de tokens

Quando usar o fluxo completo em vez do Quick Mode

Validação falhou: corrigir o código ou a spec?

Perdi a sessão no meio de uma PBI — recomeço tudo?

CLI interativa

makuco: o runtime Bun não foi instalado.

não tem .claude/ — rode makuco init neste projeto antes

instale o Claude Code ou aponte CLAUDE_CODE_EXECUTABLE

O turno falha e a CLI diz que eu provavelmente não estou autenticado

A lateral não aparece

Apertei Esc ou Ctrl-C e a CLI continuou trabalhando

Dei /clear e o agente começou a trabalhar de novo sozinho

O /clear não zerou o número do /usage

O /usage abriu vazio

Uma skill que eu tenho não aparece como comando /

A CLI não identifica o próximo passo

A seleção de texto do terminal parou de funcionar