Setup e Configuração¶

Este guia descreve como configurar o ambiente local para usar o amIA como desenvolvedor. Ao final, você terá o Claude Code conectado ao MCP Server do amIA e estará pronto para executar commands de codificação assistida no seu projeto.

O que você vai precisar

Uma conta corporativa no Azure AD / Microsoft Entra ID com acesso à plataforma amIA e o arquivo .mcp.json do seu projeto (fornecido pelo time amIA).

1. Pré-requisitos¶

1.1 Pré-requisitos universais¶

Todos os desenvolvedores precisam instalar o Claude Code CLI independentemente do tipo de projeto.

Software	Versão mínima	Windows	macOS	Linux
Node.js	20 LTS	`winget install OpenJS.NodeJS.LTS`	`brew install node`	nodesource.com/blog/installing-node-js-tutorial-using-a-package-manager
Claude Code CLI	Qualquer	`npm install -g @anthropic-ai/claude-code`	`npm install -g @anthropic-ai/claude-code`	`npm install -g @anthropic-ai/claude-code`

Verifique a instalação:

node --version    # deve exibir v20.x.x ou superior
claude --version  # deve exibir a versão instalada do Claude Code

1.2 Pré-requisitos por fonte de Work Items¶

O projeto usa uma das três fontes de work items abaixo. O time amIA informará qual é a sua.

amIA (padrão)Azure DevOps (ADO)TFS on-premises

Nenhuma instalação adicional necessária. Os work items são geridos nativamente pela plataforma.

Instale a Azure CLI e o plugin de DevOps:

WindowsmacOSLinux

winget install Microsoft.AzureCLI

brew install azure-cli

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

Após instalar, adicione o plugin e autentique:

# Instalar plugin Azure DevOps
az extension add --name azure-devops

# Autenticar com sua conta corporativa
az login

# Configurar organização e projeto padrão
az devops configure --defaults \
  organization=https://dev.azure.com/<sua-org> \
  project="Nome do seu projeto"

Verifique a autenticação:

az account show

Instale Python 3.10 ou superior e o pacote httpx:

WindowsmacOSLinux

winget install Python.Python.3.12
pip install httpx

brew install python@3.12
pip install httpx

sudo apt install python3.12 python3-pip
pip install httpx

A configuração das credenciais TFS é feita separadamente. Solicite ao time amIA o guia de Integração TFS e siga as instruções após concluir este setup.

1.3 Sistemas operacionais suportados¶

Sistema Operacional	Versão mínima
Windows	10 (build 19041+) / 11
macOS	12 Monterey
Ubuntu / Debian	20.04 LTS
Outras distros Linux	compatíveis com Node.js 20 LTS

2. Configuração do repositório¶

Passo 1 — Obter o arquivo `.mcp.json`¶

Solicite ao time amIA o arquivo .mcp.json do seu projeto. Copie-o para a raiz do repositório:

<raiz-do-projeto>/
├── .mcp.json        ← colar aqui
├── src/
└── ...

Não edite o .mcp.json

Este arquivo aponta para o MCP Server hospedado pela plataforma. Alterações podem impedir a conexão.

Passo 2 — Abrir o Claude Code no repositório¶

Abra o terminal na raiz do repositório e inicie o Claude Code:

cd <raiz-do-projeto>
claude

Diretório de trabalho

O Claude Code deve ser aberto exatamente na raiz onde o .mcp.json foi colocado. Abrir em um subdiretório impede a leitura do arquivo de configuração.

Passo 3 — Autenticar no MCP Server¶

No chat do Claude Code, execute:

/mcp

Selecionar o MCP amia -> Authenticate

Saída esperada:

Authentication successful. Connected to amia.

Primeira autenticação

Na primeira execução, o browser será aberto automaticamente para login com Azure AD. Faça login com sua conta corporativa e retorne ao terminal — a conexão será concluída automaticamente. As sessões seguintes não exigem login novamente.

Passo 4 — Executar o setup do amIA¶

Com a conexão estabelecida, execute o setup do seu time.

ProjetosAMS

Execute o setup informando o ID do projeto:

/amia:coder.project_setup {ID do Projeto}

O comando gerará o arquivo AMIA.md na raiz do repositório com os metadados do projeto.

Onde encontrar o ID do projeto

O ID está na URL do projeto no Portal amIA: https://engineering-workspace.amcom.com.br/project/{ID}/...

Execute o setup informando o ID do cliente para o qual a sessão de atendimento será realizada:

/amia:ams_support_setup {ID do Cliente}

O comando gerará o arquivo amIA.md na raiz do repositório e conectará o .mcp.json ao workspace do cliente, liberando acesso a ferramentas de plataforma vinculadas ao cliente (ex.: base de conhecimento).

Onde encontrar o ID do cliente

O ID está na URL do cliente no Portal amIA, na área do módulo AMS: https://engineering-workspace.amcom.com.br/clients/{ID}/...

Passo 5 — Reiniciar o Claude Code¶

Feche e reabra o Claude Code. Os commands /amia:... estarão disponíveis a partir desta sessão.

3. Configuração adicional por fonte de Work Items¶

Azure DevOps (ADO)¶

Se o projeto usa work items no Azure DevOps, confirme que a Azure CLI está autenticada e configurada conforme o Passo 1.2 acima. O agente usará az boards automaticamente ao processar stories.

Para verificar:

az devops project list

A lista de projetos da organização deve aparecer sem erros.

TFS on-premises¶

Se o projeto usa work items no TFS, é necessário um passo adicional de configuração de credenciais. Solicite ao time amIA o guia de Integração TFS e siga as instruções antes de iniciar o desenvolvimento.

Este setup ocorre uma única vez por projeto. Nas execuções seguintes, o agente opera de forma totalmente automática.

4. Verificação final¶

Antes de iniciar o desenvolvimento, confirme que todos os itens estão em ordem:

[ ] claude --version exibe a versão instalada
[ ] .mcp.json está na raiz do repositório
[ ] /mcp retorna Authentication successful. Connected to amia.
[ ] AMIA.md foi gerado pelo /amia:code.project_setup
[ ] (ADO) az account show retorna a conta corporativa autenticada
[ ] (TFS) Guia de Integração TFS concluído

5. Troubleshooting¶

`/amia:code.project_setup` ou `/amia:ams_support_setup` retorna "Command not found"¶

Causa: O Claude Code não detectou o .mcp.json ou não está conectado ao MCP Server.

Solução: 1. Confirme que o /mcp retorna Authentication successful. Connected to amia. antes de executar o setup 2. Confirme que o .mcp.json está na raiz do repositório (não em subdiretório) 3. Confirme que o Claude Code foi aberto nessa mesma raiz 4. Feche e reabra o Claude Code

`/mcp` não retorna `Authentication successful`¶

Causa: Sessão Azure AD expirada ou autenticação não concluída na primeira execução.

Solução: 1. Feche o Claude Code completamente 2. Reabra na raiz do repositório 3. Execute /mcp — o browser será aberto novamente para autenticação 4. Complete o login com sua conta corporativa e retorne ao terminal

`/amia:code.project_setup` não aceita o project_id¶

Causa: O ID informado está incorreto ou o projeto não está configurado na plataforma.

Solução: 1. Confirme o ID com o time amIA ou localize-o na URL do Portal: https://engineering-workspace.amcom.com.br/project/{ID}/... 2. Se o projeto foi criado recentemente, aguarde alguns minutos e tente novamente

`/amia:ams_support_setup` não aceita o client_id ou não conecta ao workspace do cliente¶

Causa: O ID informado está incorreto, o cliente não está configurado no módulo AMS da plataforma, ou o atendente não está vinculado a esse cliente.

Solução: 1. Confirme o ID com o gestor AMS ou localize-o na URL do Portal, na área do módulo AMS: https://engineering-workspace.amcom.com.br/clients/{ID}/... 2. Confirme que o atendente logado está vinculado ao cliente no Portal (aba de atendentes do cliente) 3. Se o cliente foi criado recentemente, aguarde alguns minutos e tente novamente

`az: command not found` ao processar story com work items ADO¶

Causa: Azure CLI não instalado.

Solução: Instale conforme a seção 1.2 Pré-requisitos por fonte de Work Items e execute az login.

`az login` retorna "No subscriptions found"¶

Causa: A conta Azure AD não tem acesso à organização DevOps do projeto.

Solução: Solicite ao gestor do projeto que conceda acesso à organização Azure DevOps. Após receber o acesso, execute az login novamente.

`AMIA.md` gerado mas commands `/amia:` retornam erro de projeto¶

Causa: O project_id gravado no AMIA.md não corresponde ao projeto ativo na plataforma.

Solução: 1. Exclua o arquivo AMIA.md da raiz do repositório 2. Execute /amia:code.project_setup {ID correto} novamente

`amIA.md` gerado mas ferramentas do workspace do cliente (ex.: base de conhecimento) não respondem¶

Causa: O clientId gravado na URL do .mcp.json não corresponde ao cliente ativo na plataforma, ou a conexão não foi recarregada após o setup.

Solução: 1. Confirme, no .mcp.json, que a URL do servidor amia contém ?clientId={ID correto} 2. Reinicie o Claude Code para recarregar a conexão MCP 3. Execute /amia:ams_support_setup {ID correto} novamente caso o clientId esteja incorreto

Browser não abre para autenticação (ambiente Linux sem interface gráfica)¶

Causa: Ambiente sem GUI (ex: SSH remoto, terminal de servidor).

Solução: 1. Autentique em uma máquina com interface gráfica usando a mesma conta 2. Ou execute claude auth login antes de abrir o Claude Code no repositório 3. Se nenhuma das opções for viável, solicite suporte ao time AMia para configurar autenticação alternativa

Erro de certificado SSL ao conectar ao MCP Server (Windows corporativo)¶

Causa: Certificado raiz corporativo não instalado na cadeia de confiança do sistema.

Solução: 1. Solicite ao time de infraestrutura o certificado raiz corporativo (.cer ou .crt) 2. Instale via certmgr.msc → "Autoridades de Certificação Raiz Confiáveis" 3. Reinicie o Claude Code

Próximo passo¶

Com o ambiente configurado, siga para Primeiro Projeto para executar seu primeiro command de codificação assistida.