Configurações

O que o Makuco cria

Ao rodar makuco init, o Makuco adiciona ao seu projeto:

• A pasta .makuco/, onde ficam organizados os artefatos do fluxo (PRD, PBIs, specs, tasks, reviews e aprendizados) e os templates prontos.
• As skills, os agentes e os prompts dentro da pasta da ferramenta escolhida — .claude/ (Claude Code) ou .github/ (VSCode + Copilot).
• O arquivo MAKUCO.md na raiz.
• A pasta repos/ na raiz do workspace.

Você não precisa editar esses arquivos à mão.

Estrutura de saída

.makuco/
├── docs/
│   ├── modules/module_NNN_<nome>/feature_NNN_<nome>/
│   │   ├── status.yml            # fonte da verdade do fluxo
│   │   ├── feature.md            # PRD                   ┐
│   │   ├── decisions.md          # decisões travadas     │ makuco-analisar
│   │   ├── pbis.md               # as PBIs validadas     │
│   │   ├── discovery.md          # só no modo DESCOBERTA │
│   │   ├── rca.md                # só no INVESTIGAÇÃO    │
│   │   ├── refutacao.md          # só no INVESTIGAÇÃO    │
│   │   ├── anexos/               # só no modo EXPRESS    │
│   │   ├── sessao.md             # estado da sessão      ┘
│   │   └── pbis/pbi-NNN-<slug>/
│   │       ├── pbi.md            # a PBI                 ┐ makuco-analisar
│   │       ├── DESIGN.md         # contrato de UI        │ (só quando tem tela)
│   │       ├── EXPERIENCE.md     # contrato de UX        │
│   │       ├── references/       # referências visuais   ┘
│   │       ├── spec.md           # spec de dev           ┐ makuco-desenvolver
│   │       ├── task.md           # as tasks              │
│   │       ├── sessao-dev.md     # estado da sessão      ┘
│   │       ├── review.md         # achados + veredito    ┐ makuco-code-review
│   │       ├── sessao-review.md  # estado da sessão      ┘
│   │       └── learnings.md      # aprendizados          — makuco-documentation
│   ├── codebase/       # contexto do repo (ver abaixo)
│   ├── architecture/   # ADRs, C4, ERDs
│   └── product/        # contexto de negócio
├── integrations/
│   ├── azure-devops.yml      # só se você optou pelo tracker
│   ├── quality-gate.yml      # só se você ligou os gates opcionais (Sonar/complexidade)
│   ├── observability.yml     # sempre — nasce comentado, preenchido pelas investigações
│   └── context-sources.yml   # só se você declarou uma fonte de contexto
├── reviews/{slug}.md               # review de diff avulso (sem PBI, sem status.yml)
├── quick/NNN-<slug>/{TASK.md, SUMMARY.md}   # artefatos do Quick Mode
├── HANDOFF.md          # dev pausado: o que falta
└── STATE.md            # decisões, bloqueios, lições aprendidas e ideias adiadas

O papel do MAKUCO.md

Na v3 o MAKUCO.md é o ponto de entrada do workspace: o índice dos repositórios + a configuração e as políticas das skills. Ele não guarda síntese do projeto — isso vive em .makuco/docs/codebase/.

---
analise:
  aprovador: nenhum   # papel genérico (ex.: "Head de Produto") | nome de pessoa | nenhum
research:
  referencias: []     # docs de referência do time, relativos à raiz do workspace; [] = não existem
---
 
# MAKUCO.md
 
<!-- makuco:repos:start -->
 
## Repositórios
 
...
 
<!-- makuco:repos:end -->

Anatomia de uma entrada do índice

Cada repositório é uma entrada de até três níveis. É o roteador que as skills leem para decidir onde ir — por isso vem papel de negócio primeiro, stack depois:

- **<nome>** — `repos/<nome>` — <papel de negócio em uma frase> — <stack curto>
  → docs: `repos/<nome>/.makuco/docs/codebase/OVERVIEW.md` (<N> módulos)
  - <módulo> — `<caminho>` — <papel em uma linha>

Na prática:

- **pedidos-api** — `repos/pedidos-api` — Backend de pedidos: catálogo, carrinho, checkout e
  integrações de pagamento — Java 21/Spring Boot 3.5, PostgreSQL, Kafka
  → docs: `repos/pedidos-api/.makuco/docs/codebase/OVERVIEW.md` (12 módulos)
  - pedido — `pedido/` — Núcleo de negócio: carrinho, checkout, status do pedido
  - catalogo — `catalogo/` — Produtos, preços e disponibilidade
  - core, common-data — `core/`, … — Bibliotecas compartilhadas

A linha do repo é limitada a ~250 caracteres: ela roteia, não resume. As linhas de continuação são opcionais — a ausência delas é normal e significa "esse repo ainda não foi pesquisado", nunca erro.

Os sub-bullets são um atalho, não uma camada nova: quando um deles já nomeia o módulo que a task toca, a skill vai do MAKUCO.md direto para codebase/modules/<slug>.md e pula o OVERVIEW.md.

Gerar a base de conhecimento (start-makuco)

O makuco init cria o MAKUCO.md em branco. Para preenchê-lo com a realidade do seu projeto, rode o prompt start-makuco logo na sequência. Ele dispara a skill makuco-project-research, que analisa o código e gera a base de conhecimento que todas as skills leem antes de trabalhar.

• Claude Code — selecione o prompt start-makuco na sessão.
• VSCode + Copilot — selecione o prompt start-makuco no chat.

O contexto é lido em camadas

A saída é em camadas de propósito, para que quem lê carregue só o necessário:

Os oito arquivos técnicos: stack.md, structure.md, architecture.md, conventions.md, integrations.md, concerns.md, testing.md e risks.md (o registro de risco, desde a 3.3.0).

As skills leem de cima para baixo e param assim que têm o suficiente — nunca carregam uma camada inteira para achar um módulo.

Os dois modos da pesquisa

As camadas custam valores muito diferentes, então a skill pergunta o modo e o escopo antes de ler qualquer coisa (a menos que a sua invocação já responda isso):

A pesquisa completa cobre um repo. Uma varredura sobre todos os repos de repos/ existe apenas quando você a escolhe explicitamente, nunca como consequência de um gap detectado. E ela é retomável: uma etapa já feita e atualizada não roda de novo.

O que a pesquisa entrega

Desde a 3.3.0, a mesma passada da pesquisa entrega também:

Um exemplo de abertura de arquivo:

---
analisado_em: 2026-09-14
commit: a1b2c3d
---
 
# Stack tecnológica
 
> ⚠️ **Armadilha** — `pnpm install` na imagem ignora o `allowBuilds`: o `pnpm-workspace.yaml` está no
> formato do pnpm 11 e o `Dockerfile` prepara o pnpm 9 (`pnpm-workspace.yaml`, `Dockerfile:12`). Build
> verde; a dependência nativa fica sem script de build em runtime.

Todo template abre com as mesmas regras inegociáveis, e elas valem para tudo o que a pesquisa grava:

• Sai em PT-BR, cabeçalhos inclusive. O vocabulário de domínio do projeto fica como o time escreve.
• Afirmação sem caminho de arquivo não entra.
• Seção sem achado é omitida, nunca preenchida com placeholder.
• Comando nunca é inventado. Sai do manifesto, da configuração ou do CI — ou a célula fica vazia. Um nível de gate sem script declarado fica vazio em vez de pegar o comando do nível acima.
• Desempenho e escala só com número. Gargalo sem medição não entra no registro de risco, nem como "não medido". Área frágil é nomeada arquivo por arquivo, com o número que a torna verificável.

A matriz de cobertura lista toda camada do projeto, não só as que têm teste: camada sem teste aparece marcada, e vira achado no registro de risco. Marcar uma camada como segura para rodar em paralelo exige a evidência ao lado; o que a leitura não resolveu fica como indeterminado.

O tamanho é conferido antes de gravar. Cada template declara o próprio teto em tokens e em palavras, e o arquivo é reduzido antes de chegar ao disco — cortando a prosa descritiva, nunca as tabelas nem o guia de mudança. O orçamento da pesquisa é de 18.000 tokens para o conjunto, sem contar modules/.

Documentos gerados por uma versão anterior

A detecção de gap passou a distinguir três estados, não dois:

Ao ser invocada num repo com documentos desatualizado, a skill diz qual arquivo está desatualizado e por quê, e pergunta uma vez:

1. Completar — deriva as seções ausentes e as insere, preservando o resto do arquivo
2. Deixar como está — nada é gravado

Recusar não muda nada no disco. Uma regravação completa continua disponível, mas só quando você pede. E um repo pesquisado antes da 3.3.0 aparece com risks.md ausente e o resto no disco: fechar essa lacuna custa uma etapa, não uma pesquisa nova do repo inteiro.

Onde os arquivos ficam

• Repositório único (repos/ sem sub-pasta de repo) → .makuco/docs/codebase/ na raiz.
• Multi-repo (repos/ com ao menos um repo) → repos/<nome>/.makuco/docs/codebase/.

As skills resolvem esse caminho por repo com fallback: preferem repos/<nome>/.makuco/docs/codebase/*, senão a raiz.

A pasta repos/

A repos/ é onde ficam, lado a lado, os repositórios que compõem o produto — clonados pelo makuco init ou manualmente com git clone.

meu-workspace/
├── MAKUCO.md                  # índice dos repos + políticas — sempre na raiz
├── .makuco/                   # o fluxo, para o workspace inteiro
│   ├── docs/modules/          # módulos/features do fluxo Makuco
│   ├── templates/
│   ├── integrations/
│   ├── STATE.md
│   └── docs/codebase/         # só usado no layout de repositório único
└── repos/
    ├── README.md
    ├── minha-api/
    │   ├── .makuco/docs/codebase/   # contexto DESTE repo
    │   └── src/ …
    └── meu-front/
        ├── .makuco/docs/codebase/
        └── src/ …

O que é por repo e o que é do workspace

Um workspace multi-repo não tem um Makuco por repositório. Só o contexto de código é por repo — o fluxo continua único, na raiz:

Adicionar um repositório depois

1. Clone dentro de repos/ (ou rode makuco init e responda sim no prompt de clonagem).
2. Rode makuco init novamente para reindexar o MAKUCO.md — respondendo não ao sobrescrever, para não descartar as descrições já preenchidas.
3. Rode a skill makuco-project-research para preencher a descrição de cada repositório.

Rode o start-makuco ao entrar num projeto novo ou sempre que a base estiver desatualizada ou incompleta. 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.

Verbosidade das skills

O arquivo global ~/.makuco/config.yml controla a verbosidade da comunicação, aplicada pela skill makuco-caveman. Níveis: off · lite · full · ultra.

agents:
  default:
    verbosity: lite
  makuco-desenvolver:
    verbosity: ultra
  makuco-code-review:
    verbosity: lite
  makuco-analisar:
    verbosity: lite

Fontes de contexto do projeto

O projeto pode apontar as bases de conhecimento que o time já mantém — um servidor MCP, uma pasta de arquivos no disco, um endereço web — e os agentes passam a consultá-las durante os passos. Há dois caminhos, e os dois seguem as mesmas regras de consulta.

Nenhum dos dois guarda segredo. O Makuco não instala a fonte, não configura acesso, não guarda credencial, não escreve nela e não confere se ela está no ar antes de usar. Quem clona o projeto herda as fontes e providencia o próprio acesso na máquina dele.

Publicar uma fonte como skill

Publique no Hub uma skill cujo nome comece com context-source- — por exemplo context-source-base-do-time. Duas coisas fazem o trabalho:

• a description diz para que a base serve. É dela que sai a escolha de qual fonte consultar, e é o mesmo papel do purpose do arquivo de declaração;
• o corpo da skill diz como se pergunta àquela base, com o espaço que a explicação precisar: vocabulário, exemplos de pergunta, o que a base cobre e o que não cobre. É o mesmo papel do usage, sem o aperto de um campo de uma linha.

Escrita uma vez, por quem conhece a base, a skill chega sozinha aos projetos da unidade pela entrega de artefatos que já existe, e makuco unit sync propaga a correção. Como o diretório de skills é versionado com o repositório, quem clona o projeto herda a fonte sem refazer nada.

Não há gerador, esqueleto nem comando novo: é uma skill como qualquer outra. Uma fonte publicada por uma unidade pode ser consumida por outra — o que conta é o prefixo, não a origem.

Quando as duas existem

O nome da skill sem o prefixo e o name da entrada no arquivo identificam a mesma fonte. Batendo, prevalece a skill. Isso dá um caminho legítimo: declare no arquivo enquanto a unidade não publica, e a skill assume quando publicar, sem ninguém apagar nada.

Silenciar uma fonte

Fonte que ninguém naquele projeto alcança entra na lista do frontmatter do MAKUCO.md:

fontes_de_contexto:
  silenciadas: [context-source-base-do-time]

O nome sai por inteiro: a skill deixa de ser aberta, e a entrada de mesmo nome no arquivo de declaração também deixa de ser consultada. Como está no MAKUCO.md, a decisão fica versionada e visível no diff — é do projeto, não de uma pessoa.

Fonte que existe só no arquivo de declaração continua sendo desligada apagando a linha.

Gates de qualidade (opcional)

Os agentes sempre rodam o gate local, rápido: build, lint e testes do próprio projeto, antes de cada commit e no fechamento da PBI. Dois gates extras — SonarQube e verificação de complexidade — usam o makuco-mcp em Docker e, desde a 3.3.0, vêm desligados: são ligados por projeto.

Como ligar:

• no makuco init, responda sim à pergunta sobre os gates de qualidade — a CLI grava o arquivo abaixo com os dois ligados;
• ou crie o arquivo depois, à mão, e ligue só o que quiser.

# .makuco/integrations/quality-gate.yml
sonar: true        # gate 5 — SonarQube no fechamento da PBI
complexity: true   # gate 3 — complexity-check por task, antes do commit
# sonar_project_key: meu-projeto   # opcional; padrão: sonar.projectKey do sonar-project.properties

Pré-requisitos, só quando ligado: Docker em execução (as duas ferramentas rodam em container) e, para o Sonar, SONAR_URL e SONAR_TOKEN configurados (veja Configurar o Makuco MCP) e um sonar-project.properties na raiz do repositório. O makuco-mcp continua instalado mesmo com os gates desligados, e também renderiza os diagramas PlantUML.

Observabilidade

O arquivo .makuco/integrations/observability.yml diz ao modo INVESTIGAÇÃO o que o projeto consegue observar. O makuco init o cria sempre, inteiro comentado, sem nenhuma pergunta, e nunca o sobrescreve depois.

Cada bloco é um papel, não um produto:

# .makuco/integrations/observability.yml
source:  { provider: github,  access: 'cli:gh',  scope: 'org/checkout-api' }
tracker: { provider: azure-devops, access: 'mcp:azure-devops' }
logs:    { provider: datadog, access: 'cli:dog', scope: 'service:checkout' }
metrics: { provider: datadog, access: 'cli:dog' }
runtime: { provider: none }
edge:    { provider: cloudflare, access: none, notes: 'sem acesso; pedir ao time de plataforma' }

Os papéis são source, tracker, logs, metrics, code_index, runtime e edge. Você não precisa preencher nada à mão: papel comentado é descoberto na hora. Na primeira investigação que precisar dele, a skill procura nos docs de codebase e no ambiente, pergunta a você uma vez e grava a resposta aqui. provider: none é uma resposta válida: vira lacuna declarada no laudo, com teto de confiança.

Configurar o Makuco MCP

O Makuco MCP integra o fluxo com o SonarQube. Este passo só é necessário quando o projeto liga o gate do Sonar em Gates de qualidade. Para habilitá-lo, informe o endereço do Sonar e um token de acesso.

1. Criar o token no SonarQube

No SonarQube, abra My Account → Security e gere um token do tipo User Token. Copie o valor gerado. Ele só aparece uma vez.

2. Informar as credenciais

Use SONAR_URL (endereço do seu SonarQube) e SONAR_TOKEN (o token criado acima).

• Claude Code — no arquivo .claude/settings.local.json, dentro do bloco env:

  {
    "env": {
      "SONAR_URL": "https://sonar.exemplo.com",
      "SONAR_TOKEN": "seu-user-token"
    }
  }

• VSCode + Copilot — crie um arquivo .env na raiz do projeto (a mesma pasta do mcp.json) com:

  SONAR_URL=https://sonar.exemplo.com
  SONAR_TOKEN=seu-user-token

3. Conferir o projeto no Sonar

Garanta que existe um arquivo sonar-project.properties na raiz do projeto, apontando para a chave do projeto no SonarQube. Esse arquivo é pré-requisito do gate do SonarQube, mas não o liga: o gate só roda no fechamento do makuco-desenvolver quando sonar: true está em .makuco/integrations/quality-gate.yml — veja Gates de qualidade.

Lista completa de ferramentas em Servidores MCP → Makuco MCP.

Configurar o Makuco Docs MCP

O Makuco Docs MCP já vem pronto para uso — na primeira vez que uma skill precisar de contexto de produto, ela mesma pergunta qual produto usar e salva a resposta, sem configuração manual.

Detalhes em Servidores MCP → Makuco Docs MCP.

Configurar o Azure DevOps

Opcional. Sem ele, o Makuco opera 100% local-only. Passo a passo em Azure DevOps.