DocumentaçãoCommerceAdobe Commerce as a Cloud Service

[Somente SaaS]{class="badge positive" title="Aplicável somente a projetos do Adobe Commerce as a Cloud Service e do Adobe Commerce Optimizer (infraestrutura SaaS gerenciada pela Adobe)."}

Ferramentas de desenvolvedor de codificação de IA para o Adobe Commerce App Builder

Last update: Wed Feb 25 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

Criado para:

  • Intermediário
  • Desenvolvedor

Ao migrar para o Adobe Commerce as a Cloud Service, você pode usar as ferramentas de codificação de IA para converter extensões existentes do PHP do Adobe Commerce em aplicativos do Adobe Developer App Builder. Você também pode usar essas ferramentas para criar novos aplicativos do App Builder.

As ferramentas de codificação de IA oferecem os seguintes benefícios:

  • Fluxo de trabalho de desenvolvimento aprimorado: ferramentas de desenvolvimento integradas do Adobe Commerce.
  • Assistência fornecida por IA: geração e depuração de código com reconhecimento de contexto.
  • Recursos específicos do Commerce: ferramentas especializadas para desenvolvimento do Adobe Commerce App Builder.
  • Fluxos de trabalho automatizados: processos simplificados de desenvolvimento e implantação.

Ao instalar as ferramentas de codificação de IA, você obtém acesso a:

  • Habilidades - um conjunto de habilidades específicas da Adobe Commerce e da App Builder projetado para orientar e informar o desenvolvimento de seus aplicativos.
  • Servidor MCP do desenvolvedor
  • App Builder MCP Server

Atualização para a versão mais recente

Depois de instalar a ferramenta de desenvolvedor de codificação de IA, você poderá atualizar para a versão mais recente executando o seguinte comando:

aio commerce extensibility tools-setup

Isso atualizará as ferramentas para a versão mais recente.

Pré-requisitos

Instalação

NOTE
Se você quiser instalar apenas o serviço de documentação RAG e não todo o pacote de ferramentas de codificação de IA, consulte serviço de documentação RAG.

  1. Instale globalmente a Adobe I/O CLI mais recente:

    code language-bash 
    npm install -g @adobe/aio-cli

  2. Instale os seguintes plug-ins:

    code language-bash 
    aio plugins:install https://github.com/adobe-commerce/aio-cli-plugin-commerce @adobe/aio-cli-plugin-app-dev @adobe/aio-cli-plugin-runtime

  3. Clonar um dos itens a seguir:

    • kit inicial de integração do Commerce - para criar integrações de back-office.

      code language-bash 
      git clone git@github.com:adobe/commerce-integration-starter-kit.git

    • O kit de início de check-out da Commerce para criar ou estender a experiência de check-out, incluindo pagamentos, remessa e impostos.

      code language-bash 
      git clone git@github.com:adobe/commerce-checkout-starter-kit.git

  4. Navegue até o diretório do kit inicial:

    code language-bash 
    cd commerce-integration-starter-kit

  5. Instale as ferramentas de extensibilidade do Commerce AI executando o comando de configuração interativo:

    code language-bash 
    aio commerce extensibility tools-setup

    O processo de instalação solicita que você informe as opções de configuração. Siga as instruções para concluir a instalação. As ferramentas serão instaladas no diretório selecionado.

    • Selecione o kit inicial que deseja usar para o projeto.

      code language-shell-session 
      ? Which starter kit would you like to use?
❯ Integration starter kit
   Checkout starter kit

    • Selecione o agente de codificação de sua preferência. Mais de 40 agentes de codificação são suportados, mas se você não vir seu agente preferido, poderá usar a opção Other para instalar habilidades para qualquer agente de codificação. Consulte a documentação do seu agente de codificação para obter instruções sobre como configurar as habilidades.

      code language-shell-session 
      ? Which coding agent would you like to install skills for?
❯ Cursor
   Claude Code
   GithubCopilot
   Windsurf
   Gemini CLI
   OpenAI Codex
   Cline
   ...

    • O instalador detectará se você tem NPM ou Fios instalados e fará a seleção apropriada automaticamente. No entanto, se nenhum deles estiver instalado, você será solicitado a selecionar o gerenciador de pacotes. A Adobe recomenda o uso de npm para fins de consistência:

      code language-shell-session 
      ? Which package manager would you like to use?
❯ npm
   yarn

  6. Após instalar com êxito as ferramentas de codificação, o processo de instalação configura:

    • Integração do servidor MCP para desenvolvimento do Adobe Commerce
    • Habilidades do agente para uma experiência de desenvolvimento aprimorada
    • Fluxos de trabalho e ferramentas de desenvolvimento específicos do Commerce

    As ferramentas de habilidades e MCP agora estão instaladas. Se você não vir as habilidades e ferramentas do MCP, reinicie o agente de codificação.

NOTE
Antes de implantar o projeto, será necessário concluir as seguintes tarefas de configuração:
Você pode concluir essas etapas de configuração manualmente ou aproveitar as ferramentas de codificação de IA para orientá-lo pelo processo. Consulte Criar uma integração para obter instruções detalhadas sobre configuração.

Configuração pós-instalação

Faça logon na Adobe I/O CLI

Após instalar o Adobe I/O CLI, faça login sempre que quiser usar o servidor MCP.

aio auth login

Para verificar se você está conectado, execute o seguinte comando:

aio where

Se encontrar problemas, tente fazer logoff e logon novamente em:

aio auth logout
aio auth login
NOTE
Alguns recursos do servidor MCP funcionarão sem fazer logon, mas o serviço RAG (Retrieval-Augmented Generation) não funcionará. O serviço RAG fornece ao agente de codificação de IA acesso em tempo real ao conjunto completo de documentações do Adobe Commerce, permitindo que ele responda a perguntas e gere código com base nas práticas atuais de desenvolvimento, APIs e padrões de arquitetura do Commerce.
Para instalar o serviço RAG de forma independente, consulte Documentação do serviço RAG.

Cursor

  1. Reinicie o Cursor IDE para carregar as novas ferramentas e configuração do MCP.

  2. Verifique a instalação confirmando que as habilidades estão presentes na pasta .cursor/skills/.

  3. Ativar o servidor MCP:

    • Abra as Configurações de MCP do Cursor usando Cmd+Shift+P (macOS) ou Ctrl+Shift+P (Windows e Linux).
    • Tipo Exibir: Abrir Configurações de MCP
    • Localizar Servidor MCP de extensibilidade de comércio na lista
    • Ative o servidor ON para habilitar as ferramentas de codificação

  4. Verifique o status do servidor - o servidor MCP de extensibilidade do Commerce deve aparecer como:

    code language-shell-session 
    Status: Connected/Active
Server: commerce-extensibility
Configuration: Automatically configured via .cursor/mcp.json

  5. Use o prompt a seguir para ver se o agente usa o servidor MCP. Caso contrário, peça explicitamente ao agente para usar as ferramentas MCP disponíveis.

    code language-shell-session 
    What are the differences between Adobe Commerce PaaS and Adobe Commerce as a Cloud Service when configuring a webhook that activates an App Builder runtime action?

Copilot

  1. Reinicie o Visual Studio Code para carregar as novas ferramentas e configuração do MCP.

  2. Verifique a instalação confirmando se o arquivo copilot-instructions.md existe na pasta .github.

  3. Ativar o servidor MCP:

    • Abra o Painel Extensões clicando no ícone Extensões na Barra de Atividades na barra lateral esquerda ou usando Cmd+Shift+X (macOs) ou Ctrl+Shift+X (Windows e Linux).
    • Clique em SERVIDORES MCP - INSTALADOS.
    • Clique no ícone de engrenagem ao lado de Commerce-extensibility MCP Server e selecione Iniciar Servidor, se o servidor estiver parado.
    • Clique no ícone de engrenagem novamente e selecione Mostrar saída.

  4. Verifique o status do servidor. A saída MCP:commerce-extensibility deve corresponder ao seguinte:

    code language-shell-session 
    2025-11-13 12:58:50.652 [info] Starting server commerce-extensibility
2025-11-13 12:58:50.652 [info] Connection state: Starting
2025-11-13 12:58:50.652 [info] Starting server from LocalProcess extension host
2025-11-13 12:58:50.657 [info] Connection state: Starting
2025-11-13 12:58:50.657 [info] Connection state: Running

(...)

2025-11-13 12:58:50.753 [info] Discovered 10 tools

  5. Use o prompt a seguir para ver se o agente usa o servidor MCP. Caso contrário, peça explicitamente ao agente para usar as ferramentas MCP disponíveis.

    code language-shell-session 
    What are the differences between Adobe Commerce PaaS and SaaS when configuring a webhook that activates an App Builder runtime action?

Exemplo de prompt

O exemplo de prompt a seguir usa o kit inicial de integração para criar um aplicativo para enviar notificações quando um pedido é feito.

Implement an Adobe Commerce SaaS application that will send an ERP notification when a customer places an order. The ERP notification must be sent as a POST HTTP call to <ERP URL> with the following details in the request JSON body:

Order ID -> orderID
Order Total -> total
Customer Email ID -> emailID
Payment Type -> pType

O exemplo de prompt a seguir usa o kit inicial de check-out para criar um aplicativo que fornece métodos de envio personalizados.

Implement an Adobe Commerce SaaS application that provides custom shipping methods.
The extension should:
1. Return shipping options based on the destination postal code
2. If postal code is in California, add an "Express California" option for $15
3. If postal code is outside US, add an "International Standard" option for $25
4. The carrier code should be "MYSHIP"

Comandos do Prompt

Além do prompt, você pode usar o comando /search-commerce-docs para pesquisar a documentação em conversas com seu agente. Por exemplo:

/search-commerce-docs "How do I subscribe to Commerce events?"

Habilidades

Embora as habilidades sejam invocadas automaticamente ao conversar com seu agente de codificação, você também pode chamá-las manualmente usando os seguintes comandos:

  • /architect - Projeta a arquitetura para extensões do Adobe Commerce usando o App Builder e o kit inicial selecionado. Use o ao planejar integrações, selecionar eventos, projetar fluxos de dados ou tomar decisões arquitetônicas.
  • /developer - Implementa extensões do Adobe Commerce seguindo os padrões App Builder e a estrutura de arquivos. Use ao gerar código, atualizar arquivos de configuração ou implementar ações de tempo de execução.
  • /devops-engineer - Implanta e opera App Builder extensões. Use ao implantar aplicativos, configurar ambientes, solucionar problemas de implantação, configurar CI/CD ou solucionar erros de integração.
  • /product-manager - Coleta e documenta os requisitos para as extensões do Adobe Commerce. Use ao iniciar um novo projeto, definir critérios de aceitação, esclarecer objetivos de negócios ou criar a documentação REQUIREMENTS.md.
  • /technical-writer - Cria uma documentação abrangente para aplicativos do App Builder. Use ao gravar README.md, guias do usuário, documentação da API, logs de alterações ou para garantir a integridade da documentação.
  • /tester - Cria testes abrangentes para aplicativos do App Builder. Use ao escrever testes de unidade, testes de integração, validar a segurança ou garantir a qualidade e a cobertura do código.
  • /tutor (experimental) - Ensina conceitos de desenvolvimento de aplicativos Adobe Commerce com explicações e exemplos claros. Use para aprender App Builder, entender eventos ou precisar de orientação sobre padrões de desenvolvimento.

Práticas recomendadas

A Adobe recomenda seguir as seguintes práticas recomendadas ao usar as ferramentas de codificação de IA:

Modo de plano

Ao conversar com seu agente de codificação, você deve selecionar o modo Plano para criar um plano de implementação detalhado para seu projeto.

O método para selecionar o modo Plano varia de acordo com o agente que você está usando. Consulte a documentação do agente para obter instruções. Por exemplo:

Lista de verificação

Antes de iniciar qualquer sessão de desenvolvimento:

  • Verificar REQUIREMENTS.md
  • Verificar se as ferramentas de MCP estão funcionando
  • Revisar a fase e as metas atuais
  • Comece com código de amostra ou projetos com andaime

Durante o desenvolvimento:

  • Confiar no protocolo de quatro fases
  • Solicitar planos de implementação para desenvolvimento complexo
  • Usar ferramentas MCP quando disponíveis
  • Testar cada recurso após a implementação
  • Teste localmente primeiro, depois implante e teste novamente
  • Aproveitar as ferramentas de codificação para testar o suporte
  • Questionar a complexidade desnecessária
  • Implante de forma incremental para um desenvolvimento mais rápido

Ao iniciar o novo chat:

  • Fornecer entrega de sessão adequada
  • Arquivos de chave de referência com @
  • Definir objetivos claros para a sessão
  • Usar limites com base em fase

Fluxo de trabalho (WRK)

Ao desenvolver com as ferramentas de codificação de IA, comece com códigos de amostra ou projetos com andaimes. Essa abordagem garante que você esteja construindo uma base sólida em vez de começar do nada, enquanto também otimiza o fluxo de trabalho de desenvolvimento de IA.

Isso também permite que você aproveite os modelos do Adobe e crie com base em padrões e arquiteturas comprovados, mantendo estruturas e convenções de diretório estabelecidas.

Consulte os seguintes recursos para começar:

Por que você deve usar esses recursos

  • Padrões comprovados: os kits iniciais incorporam as práticas recomendadas e as decisões de arquitetura da Adobe
  • Desenvolvimento mais rápido: reduz o tempo gasto na preparação e configuração
  • Consistência: garante que o aplicativo siga as convenções estabelecidas
  • Capacidade de manutenção: mais fácil de manter e atualizar ao seguir padrões padrão
  • Documentação: os kits iniciais vêm com exemplos e documentação
  • Suporte da comunidade: é mais fácil obter ajuda ao usar as abordagens padrão
  • Eficiência do contexto de IA: use padrões e estruturas familiares para trabalhar, reduzindo a necessidade de explicações extensas e melhorando a precisão da geração de código
  • Uso reduzido do token: faça referência a padrões existentes em vez de gerar tudo do zero, resultando em conversas mais eficientes e menos resumos de contexto

Protocolo

O protocolo de quatro fases a seguir é aplicado automaticamente pelas habilidades instaladas. As ferramentas devem seguir esse protocolo automaticamente ao desenvolver aplicativos:

  • Fase 1: Análise e esclarecimento dos requisitos
    • Quando você for solicitado a esclarecer perguntas, forneça respostas completas.
  • Fase 2: Planejamento de arquitetura e aprovação do usuário
    • Quando um plano for apresentado, revise-o cuidadosamente antes de aprová-lo.
  • Fase 3: Geração e implementação de código
  • Fase 4: Documentação e validação

Solicitar planos de implementação para desenvolvimento complexo

Para um desenvolvimento complexo envolvendo várias ações de tempo de execução, pontos de contato ou integrações, solicite explicitamente que as ferramentas de IA criem um plano de implementação detalhado. Quando você vir um plano de alto nível na Fase 2 que envolve vários componentes, peça um plano de implementação detalhado para separá-lo em tarefas gerenciáveis:

Create a detailed implementation plan for this complex development.

Aplicativos Adobe Commerce complexos geralmente envolvem:

  • Várias ações em tempo de execução
  • Configuração de evento em vários pontos de contato
  • Integração com sistemas externos
  • Requisitos de gerenciamento de estado
  • Teste em vários componentes

Usar ferramentas MCP

NOTE
Antes de usar as ferramentas do MCP, verifique se você está conectado à Adobe I/O CLI.

A ferramenta usa como padrão as ferramentas MCP, mas, em determinadas circunstâncias, pode usar comandos CLI. Para garantir o uso da ferramenta MCP, solicite-os explicitamente em seu prompt.

Se você vir comandos CLI sendo usados e quiser usar ferramentas MCP, use o seguinte prompt:

Use only MCP tools and not CLI commands
  • Ferramentas do MCP: aio-app-deploy, aio-app-dev, aio-dev-invoke
  • Comandos da CLI: implantação de aplicativo aio, desenvolvimento de aplicativo aio

Os comandos da CLI podem ser usados para os seguintes cenários:

  • Cenários complexos de implantação
  • Depuração de problemas específicos
  • Quando as ferramentas MCP têm limitações
  • Operações pontuais que não se beneficiam da integração do MCP

Desenvolvimento

Questionar a complexidade desnecessária criada pelas ferramentas de IA.

Quando arquivos desnecessários forem adicionados (validator.js, transformer.js, sender.js) para pontos de extremidade somente leitura simples, use os seguintes prompts:

Why do we need these files for a simple read-only endpoint?
Perform a root cause analysis before adding complexity
Verify if simpler solutions exist

Testes

Use as seguintes práticas recomendadas ao testar:

Testar cada recurso após a implementação

Após concluir o desenvolvimento de um recurso no seu plano de implementação, teste-o imediatamente. Os testes antecipados evitam problemas compostos e facilitam a depuração.

  • Não espere até que todos os recursos estejam concluídos
  • Teste incremental para capturar problemas antecipadamente
  • Validar a funcionalidade antes de passar para o próximo recurso

Testar localmente primeiro

Sempre testar localmente primeiro usando a ferramenta aio-app-dev. Isso fornece feedback imediato e permite ciclos de iteração mais rápidos, depuração mais fácil e nenhuma sobrecarga de implantação.

  1. Iniciar servidor de desenvolvimento local:

    code language-bash 
    aio-app-dev

  2. Testar ações localmente:

    code language-bash 
    aio-dev-invoke action-name --parameters '{"test": "data"}'

Implante e teste novamente

Depois que o teste local for bem-sucedido, implante e teste no ambiente de tempo de execução. Os ambientes de tempo de execução podem ter um comportamento diferente do desenvolvimento local.

  1. Implantar para tempo de execução:

    code language-bash 
    aio-app-deploy

  2. Testar ações implantadas

  3. Usar navegador da Web ou solicitações HTTP diretas

  4. Verificar logs de ativação para depuração

Aproveitar as ferramentas de codificação para testar o suporte

Solicitar ajuda com testes. As ferramentas podem ajudar na depuração, análise de log e criação de dados de teste apropriados para suas ações específicas de tempo de execução.

Testar ações de tempo de execução:

Help me test the customer-created runtime action running locally

Falhas de depuração:

Why did the subscription-updated runtime action activation fail?

Verificar logs:

Help me check the logs for the last stock-monitoring runtime action invocation

Criar cargas de teste:

Generate test data for this Commerce event

Create a test payload for the customer_save_after event

Localizar pontos de extremidade de tempo de execução:

What's the URL for this deployed action?

Manipular autenticação:

How do I authenticate with this external API?

Solução de problemas:

Help me debug why this action is returning 500 errors

Depuração

Pare e avalie quando as coisas dão errado. Se você encontrar problemas:

  • Parar e avaliar - Não continuar em um estado interrompido
  • Verificar logs - Use logs de ativação para identificar problemas
  • Simplifique — elimine a complexidade para isolar problemas
  • Teste incremental - Corrija um problema de cada vez
  • Validar - Teste cada correção antes de continuar

Implantação

Use as seguintes práticas recomendadas ao implantar:

Implantar de forma incremental

Implante somente ações modificadas para acelerar o desenvolvimento. Essa abordagem reduz o risco de romper a funcionalidade existente e fornece feedback mais rápido sobre as alterações.

  • Usar ferramentas MCP para implantar ações específicas

    code language-bash 
    aio-app-deploy --actions action-name

  • Implantar ações individuais após o teste localmente

  • Implante de forma incremental e evite implantações completas de aplicativos durante o desenvolvimento

Limpeza em tempo de execução

Após grandes alterações, aproveite as ferramentas para limpar ações órfãs. Deixar que a ferramenta de IA lide com o processo de limpeza sistematicamente. Ele pode identificar com eficiência as ações órfãs, verificar seu status e removê-las com segurança sem intervenção manual.

Help me identify and clean up orphaned runtime actions

Solicite a ferramenta de IA para listar as ações implantadas e identificar as não usadas

List all deployed actions and identify which ones are no longer needed

Faça com que as ferramentas de IA removam ações órfãs usando comandos apropriados

Remove the orphaned actions that are no longer part of the current implementation

Monitoramento

Use as seguintes práticas recomendadas ao monitorar seu aplicativo:

Fique atento aos indicadores de qualidade do contexto

  • Contexto adequado: a IA lembra decisões recentes, faz referência a arquivos corretos
  • Contexto insatisfatório: a IA solicita informações fornecidas anteriormente, repete problemas resolvidos

Rastrear a velocidade de desenvolvimento

  • Alta velocidade: progresso claro, esclarecimentos mínimos necessários
  • Baixa velocidade: explicações repetidas, confusão de IA, progresso lento

Monitorar a eficiência de custos

Rastrear padrões de uso de token:

  • Eficiente: baixo uso de token, poucos resumos de contexto
  • Ineficiente: alto uso de token, vários resumos, trabalho repetido

O que evitar

Evite os seguintes antipadrões ao usar as ferramentas de codificação de IA:

  • Não ignore a fase de esclarecimento. Sempre verifique se a Fase 1 foi concluída antes da implementação.
  • Não ignore os testes após cada recurso - Teste de forma incremental, não espere até que tudo esteja concluído.
  • Não adicione complexidade sem análise da causa raiz - Questione adições desnecessárias de arquivos e solicite uma investigação adequada.
  • Não declarar sucesso sem teste de dados reais - Sempre testar com dados reais, não apenas casos de borda.
  • Não se esqueça da limpeza do tempo de execução - Sempre limpe as ações órfãs após grandes alterações.

Fornecendo feedback

Os desenvolvedores interessados em fornecer feedback sobre as ferramentas de codificação de IA podem usar o comando /feedback.

Esse comando permite fornecer feedback de texto e enviar logs para a Adobe. Todos os registros enviados serão limpos para remover informações privadas ou pessoais.

TIP
A experiência do usuário varia um pouco dependendo do IDE que você está usando. O processo a seguir descreve a experiência no cursor.

  1. Em seu agente, digite /feedback e selecione o comando commerce-extensibility/feedback.

  2. Forneça seu feedback sobre a ferramenta no campo Feedback que aparece na parte superior do IDE e pressione a tecla Enter.

    Campo de entrada do comando de comentários do cursor {width="600" modal="regular"}

  3. No campo Salvar Localmente, digite yes ou no e pressione Enter para indicar se deseja salvar uma cópia local dos logs.

    Campo local para salvar comando de comentários do cursor {width="600" modal="regular"}

    Se você selecionou Sim, poderá examinar os logs na pasta chats depois de enviar seus comentários.

  4. O comando commerce-extensibility/feedback aparece no campo de entrada do chat do agente. Pressione Enter ou clique em Enviar para enviar seus comentários para a Adobe.

NOTE
Se você não vir o comando /feedback, talvez precise atualizar para a versão mais recente.
recommendation-more-help
0519caf3-99f4-44ba-8e03-411a5b7764c8