Usando o Claude Code

O Claude Code lê, escreve e valida mapas do Mapper Idea para você. Você descreve o que quer em linguagem natural, e o Claude edita os arquivos .mi, roda o CLI mi e mostra o resultado no Freemapper. Este capítulo traz o que instalar, os comandos do plugin do Mapper Idea e exemplos de prompts.

O que é preciso

• O Claude Code, com uma conta do Claude: https://claude.com/claude-code

• Os plugins do Mapper Idea para o Claude Code (agent-kit e iadd): https://github.com/mapperidea/claude-plugins

• O CLI do Mapper Idea (mi) instalado e autenticado com um usuário autorizado. Sem ele, o Claude escreve mapas, mas não valida nem gera nada. Os links estão na página Dicas.

• O Freemapper (opcional), para ver os mapas mudando enquanto o Claude trabalha e para abrir o Claude Code dentro dele.

Instalando os plugins

Dentro do Claude Code:

/plugin marketplace add mapperidea/claude-plugins
/plugin install agent-kit@mapperidea-iadd
/plugin install iadd@mapperidea-iadd

Ou no terminal:

claude plugin marketplace add mapperidea/claude-plugins
claude plugin install agent-kit@mapperidea-iadd
claude plugin install iadd@mapperidea-iadd

Abra uma sessão nova depois de instalar: uma sessão que já estava aberta não enxerga os comandos novos e responde Unknown skill. Para atualizar depois, use /plugin marketplace update mapperidea-iadd.

Comandos

Comando	O que faz
/iadd:init	Prepara o projeto: converte os mapas FreeMind (.mm) que já existem para .mi, identifica o mapa principal e instala os três agentes, perguntando a você o que é do seu domínio. Rode uma vez, na raiz do projeto.
/iadd:init <agente>	Instala ou reinstala um agente só: domain-mapper, generator-author, cli-runner ou todos. Pergunta antes de substituir qualquer coisa.
/iadd:mi ou /iadd:mapperidea	O especialista em .mi: lê, escreve, valida e explica mapas de negócio, mapas de arquitetura, geradores, ícones e tipos. O Claude também o chama sozinho quando o assunto é um mapa .mi.
/agent-kit:agent-creator	Um assistente que entrevista você e escreve um agente novo do Claude Code para o seu projeto.

Não é preciso digitar os comandos para usá-los: pedir em linguagem natural ("converte meus mapas .mm para .mi") já basta, e o Claude escolhe o certo.

Os três agentes

O /iadd:init instala três agentes em .claude/agents/. Cada um é dono de uma parte do trabalho, para que quem modela não gere e quem gera não mude o modelo:

Agente	É dono de	Mexe em
domain-mapper	O mapa de negócio: entidades, atributos, relações, regras	Só os arquivos .mi de negócio
generator-author	Os geradores: como o mapa vira código na sua stack	Só os arquivos .mi de gerador
cli-runner	A validação e a geração de verdade, pelo CLI mi	Roda o mi, não edita mapa

Você conversa com o Claude normalmente e ele passa a tarefa ao agente certo. O que o plugin escreve no seu projeto (agentes, a memória deles, guias, hooks) é seu: continua funcionando sem o plugin e é feito para ser editado e commitado.

O Claude no Freemapper

O Freemapper pode deixar o Claude Code ver os mapas abertos: o nó selecionado, o texto de um mapa, uma imagem da tela. Ligue em Preferências > Ambiente > Integração com IA:

• Permitir que um assistente de IA veja e navegue nos mapas abertos inicia um servidor local, que só este computador alcança, protegido por um token.

• Permitir também que o assistente altere os mapas acrescenta as ferramentas que inserem, alteram e removem nós. Toda alteração aparece na tela e pode ser desfeita com Ctrl+Z; nada é salvo até você, ou o Claude, salvar o mapa.

Reinicie o Freemapper depois de mudar essas opções. Aí há dois jeitos de usar o Claude:

• Dentro do Freemapper: Visualizar > Assistente de IA (Alt+9) abre um painel com o Claude Code rodando na pasta do projeto, já ligado aos mapas. O painel pode ir para uma janela própria, tem uma aba por projeto e pode usar outras contas do Claude pelos perfis.

• No seu terminal: o item Integração com IA: copiar o comando do Claude Code copia um comando; cole num terminal uma vez e, daí em diante, o Claude Code enxerga os mapas abertos no Freemapper.

Quando o Claude altera um arquivo .mi no disco, o Freemapper recarrega o mapa e seleciona o nó que mudou.

Exemplos de prompts

São pontos de partida: troque os nomes pelos do seu mapa. Quanto mais preciso o pedido (qual mapa, qual pacote, qual classe), menos o Claude precisa adivinhar.

Modelando o negócio

Acrescenta a entidade Fornecedor no pacote vendas, com CNPJ (chave), razão social e e-mail,
e uma relação com Cidade.

Lê a história em docs/historias/cancelar-pedido.md e atualiza o mapa de negócio com o que
estiver faltando. Mostra as mudanças antes de gravar.

Explica a classe Pedido do main.mi, atributo por atributo, e aponta o que parece
inconsistente.

Escrevendo geradores

Escreve um gerador que cria uma interface TypeScript para cada classe de um pacote, com os
tipos dos atributos convertidos para os tipos do TypeScript.

No gerador de entidade Java, faz os atributos marcados como chave virarem @Id.

Que função eu uso num gerador para transformar PedidoCliente em pedido_cliente?

Validando e gerando

Envia os mapas e valida a classe Pedido com o gerador struct.

Gera a entidade Quarkus de Pedido em src/main/java/vendas/ e confere se o arquivo tem
erro EMI.

O mi generate devolve um arquivo vazio para Cliente. Descobre por quê.

No Freemapper

Explica o nó selecionado.

Embaixo desta classe, acrescenta os atributos data de nascimento, telefone e ativo.

Mostra no mapa onde está a classe Cliente e abre o ramo dela.

Tira uma imagem do mapa e me diz quais classes não têm atributo chave.

Dicas

• Diga o que o Claude não deve mudar ("só o pacote vendas", "não mexe nos geradores").

• Peça a validação: um mapa só é conferido quando o mi generate <projeto> struct xml roda na classe. Os agentes sabem disso, mas pedir deixa explícito.

• O Claude pergunta antes de rodar o mi push, porque ele envia os mapas para a nuvem do Mapper Idea. Para pular a pergunta, diga no próprio pedido, como em "envia os mapas e gera...".

• Depois de gerar, procure EMI na saída: um erro do CLI impresso na saída vai parar dentro do arquivo gerado.

• Para uma dúvida sobre uma função XPath, o Claude pode abrir a página da função neste guia, como mi:lower-case-add-underline.

• Os manuais do plugin, com o método inteiro (docs/pipeline-iadd.md) e como escrever um gerador do zero, vêm com o plugin; peça ao Claude que os abra.