Pular para o conteúdo
Manual Prático de Engenharia · Salesforce + IA + Flosum

DevOps Salesforce com IA:
O Manual Prático para Adotar Devin, Claude e Flosum

Do ambiente vazio ao deploy protegido: as nove seções abaixo mostram como instalar a stack, ligar Devin e Claude Code ao seu org, deixar o Flosum cuidar da esteira e escrever specs que a IA executa sem adivinhar. Escrito para quem já conhece Salesforce e está começando agora em fluxos de IA agiêntica — desenvolvedores, arquitetos técnicos e administradores.

Introdução

Toda organização Salesforce que tenta colocar um agente de IA para codificar direto em produção comete o mesmo erro: trata a IA como se fosse mais um desenvolvedor júnior, sem lhe dar o que um desenvolvedor júnior nunca teria — acesso direto e sem rede de segurança a um org compartilhado por dezenas de equipes.

Este manual resolve isso em quatro camadas: fundação (ambiente instalado corretamente), arquitetura (como Flosum liga Salesforce ao Git e protege o deploy), metodologia (como escrever specs que a IA executa sem alucinar) e governança (como o próprio repositório vira a memória de longo prazo da IA). Siga as seções em ordem — cada uma depende da anterior.

Formato
Guia prático
Profundidade
Guia prático · ~16 min

Prefere o essencial antes? Ler a síntese (~1 min)

Parte 1

Fundação: Setup e Primeira Conexão

1 Guia de Setup Inicial

A ordem de instalação importa. Instalar Java antes do resto é a causa mais comum de ambientes quebrados em times que estão começando. Siga esta sequência:

Passo 1 — Visual Studio Code

Baixe e instale o VS Code em code.visualstudio.com. É o editor-base sobre o qual toda a stack (Salesforce + IA) vai rodar.

Passo 2 — Salesforce CLI + Salesforce Extension Pack

  1. Instale o Salesforce CLI (sf), via instalador oficial ou npm: 
    npm install --global @salesforce/cli
sf --version
  2. Dentro do VS Code, abra a aba de Extensões (Ctrl+Shift+X / Cmd+Shift+X) e instale o Salesforce Extension Pack. Ele traz suporte a Apex, Lightning Web Components, visualização de metadados e o Apex Replay Debugger.

Passo 3 — Java Development Kit (JDK) 21

O Apex Language Server — o motor que dá autocomplete, navegação e debug de Apex dentro do Salesforce Extension Pack — roda sobre uma JVM. Sem o JDK correto instalado, essas funcionalidades simplesmente não aparecem.

  • Instale o JDK 21 (versão recomendada atualmente; 17 e 11 ainda são aceitas). Builds gratuitas como Zulu OpenJDK ou Oracle JDK funcionam bem.
  • O VS Code tenta localizar o Java automaticamente pela variável de ambiente JAVA_HOME. Se não encontrar, aponte manualmente em Settings → salesforcedx-vscode-apex.java.home para a pasta de instalação do JDK 21.

Checklist de validação:

Abra um arquivo .cls qualquer — se aparecer autocomplete e não houver aviso de "Java not found" no canto inferior direito, o ambiente está pronto para a próxima etapa.

2 Conectando a IA ao Ambiente Salesforce

Com o ambiente-base pronto, o próximo passo é dar à IA os dois acessos que ela precisa: ao código (via editor) e ao org vivo (via API). Sem o segundo, a IA só enxerga arquivos estáticos — não consegue confirmar se o que ela está lendo bate com a realidade do org.

Passo 1 — Instalar a extensão de IA no editor

  • Claude Code: na aba de Extensões do VS Code, busque "Claude Code" e clique em instalar (funciona também em forks do VS Code). Alternativamente, instale via terminal: 
    npm install -g @anthropic-ai/claude-code
    e rode claude dentro do terminal integrado do VS Code. É necessário um plano Claude (Pro, Max, Team ou Enterprise) ou uma chave de API.
  • Devin: por ser um agente autônomo que trabalha em sandbox na nuvem, a conexão principal do Devin acontece pelo app/web dele, integrado ao seu repositório GitHub/GitLab — não como uma extensão local rodando sobre a sua máquina. Use o Devin Desktop quando precisar de uma sessão interativa local.

Passo 2 — Autenticar na organização Salesforce

Toda a autenticação passa pelo Salesforce CLI, que tanto Claude Code quanto Devin conseguem invocar via terminal: 

sf org login web --alias minha-org --set-default

Isso abre o navegador para o fluxo OAuth padrão da Salesforce e grava um alias local reutilizável.

Passo 3 — Conectar um MCP Server de Salesforce

Um editor de código, sozinho, só lê arquivos. Para a IA conseguir consultar metadados e registros reais do org, ela precisa de um servidor MCP (Model Context Protocol) Salesforce conectado — seja o servidor de desenvolvimento local da Salesforce (que reaproveita a autenticação do CLI) ou um servidor MCP hospedado. É esse servidor que expõe ferramentas como "listar objetos", "descrever campos" e "rodar SOQL" para o modelo.

Passo 4 — Validar a conexão

O teste mais simples e mais revelador: peça à IA, em linguagem natural, algo que só teria resposta correta se ela estivesse realmente conectada ao org:

"Liste os objetos customizados desta org."

"Quantos registros existem na tabela Account?"

Se a resposta vier com nomes de objetos reais do seu org (não genéricos) ou com um número que bate com um SELECT COUNT() FROM Account manual, a cadeia editor → CLI → org → IA está validada de ponta a ponta.

Qual IA usar em cada situação

Cenário Ferramenta mais indicada
Pair programming interativo, revisão linha a linha, decisões que exigem julgamento constante Claude Code — roda no seu editor, com revisão de diff a cada mudança
Ticket bem delimitado que pode rodar sozinho (ex.: atualizar 40 classes para um novo padrão de log) Devin — agente autônomo em sandbox, entrega um Pull Request pronto para revisão
Exploração de arquitetura, refatoração ambígua Claude Code
Tarefas repetitivas em lote, delegadas via Slack/Jira sem supervisão passo a passo Devin
Preços e limites de uso mudam com frequência nos dois produtos — confirme sempre na página oficial de cada um antes de dimensionar custo de equipe.
Parte 2

Arquitetura: As Peças por Trás da Integração

3 Arquitetura em Profundidade: o Flosum Cloud Agent

Salesforce fala API de Metadados (XML, chamadas SOAP/REST autenticadas contra um org). Git fala objetos de repositório (blobs, commits, protocolo HTTP/SSH). Essas duas linguagens não se entendem sozinhas — é aí que entra o Flosum Cloud Agent (também documentado como Flosum Agent nos materiais oficiais da Flosum).

Ele é um serviço construído em Node.js, normalmente hospedado fora do org Salesforce (em plataformas como Heroku), que funciona como tradutor bidirecional:

Org Salesforce  →  Pacote gerenciado Flosum  →  Flosum Cloud Agent (Node.js)  →  GitHub / GitLab / Bitbucket / Azure DevOps

→ No sentido Salesforce → Git:

Quando um desenvolvedor faz commit de um componente dentro do Flosum, o pacote gerenciado (que vive dentro do seu org Salesforce) envia a mensagem para o Agent. O Agent traduz o payload de metadados para a estrutura de arquivos e commits que o provedor Git espera, e efetiva o push.

← No sentido Git → Salesforce:

Quando algo é alterado direto no repositório (ou em resposta a um merge), o Agent recebe o evento, traduz de volta para o formato de metadados e sincroniza o estado dentro do Flosum, que por sua vez pode disparar deploy para um org-alvo via API de Metadados.

Por que isso importa para IA:

Ferramentas como Claude Code e Devin foram treinadas e otimizadas para trabalhar sobre repositórios Git comuns — não sobre a API de Metadados da Salesforce diretamente. O Agent é o que torna seu org "legível" como um repositório Git normal, permitindo que a IA opere sem precisar entender os detalhes de autenticação e serialização da plataforma Salesforce.

4 O Padrão de Metadados: Por Que a Estrutura Importa Para a IA

Modelos de IA generativa foram treinados em uma quantidade massiva de repositórios Salesforce públicos que seguem uma convenção: o formato de origem do Salesforce DX, com a raiz do código-fonte em: 

force-app/
└── main/
    └── default/
        ├── classes/
        ├── triggers/
        ├── lwc/
        ├── aura/
        ├── objects/
        ├── flows/
        ├── layouts/
        └── permissionsets/

Essa estrutura não é só uma convenção estética — é o mapa mental que o modelo usa para prever onde um arquivo deveria estar. Quando um repositório se desvia dela (pastas customizadas, formato de metadados legado, nomes de API divergentes dos nomes de arquivo), a IA passa a alucinar caminhos: sugere editar um arquivo que não existe, cria um componente na pasta errada, ou falha em enxergar a dependência entre uma classe Apex e o objeto customizado que ela manipula.

Regra prática:

Se seu projeto ainda usa o formato de metadados legado, converta antes de expor o repositório à IA: 

sf project convert source -r caminho/do/metadata/legado -d force-app

Mantenha nomes de API idênticos aos nomes de arquivo, e evite pastas customizadas fora da árvore force-app/main/default/. Cada exceção à convenção é um ponto a mais onde a IA vai "adivinhar" — e adivinhar em um org de produção compartilhado tem custo real.

5 Fluxo de CI/CD: do Merge ao Deploy Protegido

Depois que uma IA (ou um humano) abre um Pull Request e ele é aprovado e mesclado na branch de integração, o fluxo automático assume:

  1. 1
    Webhook de pós-merge: o provedor Git (GitHub, GitLab, Bitbucket) dispara um webhook assim que o merge acontece.
  2. 2
    Flosum Cloud Agent recebe o evento e notifica o Flosum dentro do org, que reconhece a nova revisão na branch correspondente.
  3. 3
    O Pipeline é acionado automaticamente — no Flosum, um pipeline é uma sequência configurável de passos (validação, deploy, rollback) que pode ser disparada automaticamente a cada commit em uma branch ou repositório vinculado, sem intervenção manual.
  4. 4
    Deployment com escopo dinâmico: usando Delta Deployments, o pipeline envia apenas os componentes que de fato mudaram — não o pacote inteiro — reduzindo tempo de deploy e superfície de risco.
  5. 5
    Antes de tocar no org-alvo, duas proteções entram em ação:
    Overwrite Protection

    Compara o que está sendo implantado contra o estado atual real do org de destino. Se alguém alterou aquele mesmo componente diretamente no org (fora do fluxo Git) ou outra branch já o modificou, o deploy é sinalizado em vez de simplesmente sobrescrever.

    Smart Merge

    Faz uma comparação semântica (campo a campo, método a método — não linha a linha como um git diff comum) entre as versões em conflito. Isso permite que duas equipes alterando campos diferentes do mesmo objeto ou métodos diferentes da mesma classe tenham ambas as mudanças preservadas, em vez de uma sobrescrever a outra.

Esse par — Overwrite Protection + Smart Merge — é o que torna seguro delegar deploys a um fluxo majoritariamente automatizado num org enterprise com múltiplas squads mexendo nos mesmos objetos em paralelo.

Parte 3

Metodologia: Pensar Antes de Escrever o Prompt

6 Spec-Driven Development: o Manifesto da Nova Mentalidade

Em 2024 e 2025, a indústria inteira passou pelo mesmo ciclo: prompts soltos geravam código plausível que divergia da intenção real — o que passou a ser chamado de vibe coding. A resposta a isso, hoje adotada por ferramentas como GitHub Spec Kit, AWS Kiro e as próprias skills do Claude Code, tem nome: Spec-Driven Development (SDD).

"Você não escreve mais o COMO. Você escreve o QUÊ e o PORQUÊ — e a IA resolve a implementação."

Isso exige uma mudança real de hábito:

  • •
    O entregável do desenvolvedor deixa de ser código e passa a ser a especificação. Código se tornou barato de gerar; intenção clara continua sendo o recurso escasso.
  • •
    Ambiguidade não é economia de tempo — é dívida técnica que a IA vai pagar por você, do jeito errado. Um prompt vago como "melhora esse fluxo de aprovação" convida a IA a tomar decisões de negócio que não são dela para tomar.
  • •
    Em um org Salesforce compartilhado, uma suposição errada não gera só um bug — gera um incidente. Validation rules, flows e integrações estão todos interligados; a IA não tem como saber que um campo é usado por uma integração externa se ninguém documentou isso em lugar nenhum.
  • •
    Escrever a spec é o novo "pensar antes de codificar". O tempo que antes ia para desenhar a solução na cabeça agora vai para escrevê-la de forma que outra inteligência (artificial) consiga executá-la sem reinterpretar.

Na prática, isso significa: antes de abrir uma sessão de Devin ou Claude Code para uma tarefa não trivial, você escreve uma spec curta e objetiva — não um documento de 10 páginas, mas o suficiente para eliminar as perguntas que a IA teria que adivinhar sozinha.

7 Template de Especificação: o Contrato Entre Você e a IA

Uma spec malfeita custa caro de duas formas: retrabalho humano e consumo desnecessário de computação da IA. Ferramentas de agente autônomo como o Devin cobram (ou historicamente cobraram, e ainda usam como unidade interna de medição) por ACU — Agent Compute Unit, uma medida normalizada de tempo de máquina virtual, inferência de modelo e rede consumidos por tarefa. Quanto mais vaga a spec, mais a IA precisa explorar, testar hipóteses e refazer trabalho — e mais ACUs (ou computação equivalente em qualquer ferramenta agiêntica) isso queima. Escopo claro não é burocracia: é economia de computação.

Use este modelo como ponto de partida — adapte, mas não remova nenhuma das seis seções: 

# SPEC-[ID]: [Título curto e específico da tarefa]

## 1. Contexto de Negócio
Por que essa mudança existe? Qual problema de negócio ela resolve?
Quem pediu e qual a urgência real?

## 2. Objetivo (O Quê)
Descreva o resultado final observável, não a implementação.
Ex: "Todo Account sem segmento definido deve ser classificado
automaticamente como 'Não Classificado' ao ser salvo."

## 3. Justificativa (Por Quê)
Qual dor específica isso resolve? O que acontece se não for feito?

## 4. Matriz de Impacto
| Componente (API Name) | Tipo | Ação Esperada | Risco / Dependência |
|---|---|---|---|
| Account.Segmento_Mercado__c | Custom Field | Criar | Baixo — campo novo |
| AtualizaSegmentoTrigger | Apex Trigger | Modificar | Médio — 3 testes existentes |
| Fluxo_Onboarding_Cliente | Flow | Somente leitura/referência | Alto — não alterar nesta spec |

## 5. Limites de Atuação (Escopo)
### Dentro do escopo
- Criar o campo e a lógica de valor-padrão
- Atualizar os testes Apex diretamente afetados

### Fora do escopo (a IA NÃO deve tocar)
- Qualquer Flow relacionado a onboarding
- Layouts de página não mencionados acima
- Perfis e permission sets não listados

## 6. Critérios de Aceite
- [ ] Ao salvar um Account sem valor em Segmento_Mercado__c, o
      sistema deve atribuir automaticamente "Não Classificado".
- [ ] O campo deve ser visível apenas para os profiles "Vendas" e
      "Administrador do Sistema".
- [ ] Nenhum teste Apex existente pode cair abaixo de 90% de cobertura.

Por que essa estrutura reduz custo de computação:

A Matriz de Impacto elimina a fase de "exploração cega" em que a IA teria que varrer o repositório inteiro tentando adivinhar o que é relevante.

Os Limites de Atuação evitam que ela abra mudanças em componentes vizinhos "por precaução".

E Critérios de Aceite verificáveis eliminam ciclos de ida-e-volta de "não era bem isso que eu queria".

Parte 4

Governança: O Repositório Como Cérebro

8 O Repositório Como Cérebro da IA

Um repositório Git, para uma IA agiêntica, não é só onde o código mora — é a única memória de longo prazo que ela tem entre sessões. Se o contexto de negócio não está no repositório, ele não existe para a IA. Estruture o repositório assim: 

meu-repo-salesforce/
├── force-app/
│   └── main/default/           # código-fonte (ver Seção 4)
├── knowledge-base/
│   ├── mapa-propriedade-metadados.md   # quem é dono de quê
│   ├── integracoes-externas.md         # o que consome cada objeto
│   └── glossario-negocio.md            # termos de negócio ↔ API Names
├── specs/
│   └── SPEC-001-classificacao-conta.md # specs no formato da Seção 7
├── playbooks/                  # ver Seção 9
├── .agents/skills/             # ver Seção 9
├── AGENTS.md
└── README.md

A pasta knowledge-base/ carrega o que o metadado XML nunca vai contar sozinho: qual time é dono do objeto Opportunity, quais sistemas externos consomem o campo Account.SAP_ID__c via integração, ou o que "MRR" significa no vocabulário da empresa. Sem esse mapa, a IA trata todo componente como igualmente seguro de alterar — o que é exatamente o oposto da realidade em um org maduro.

O arquivo AGENTS.md na raiz:

O arquivo AGENTS.md merece atenção especial: deixou de ser convenção de um único fornecedor e hoje é um padrão aberto, mantido pela Agentic AI Foundation (projeto da Linux Foundation), lido nativamente por Claude Code, Codex, Cursor, Copilot, Gemini e outros. Nele, documente comandos exatos (sf project deploy validate, sf apex run test --code-coverage), a versão de API Salesforce em uso, e links para as pastas knowledge-base/ e playbooks/.

Um alerta importante:

Pesquisa recente (ETH Zürich, 2026) mostrou que arquivos de contexto gerados automaticamente por comandos tipo /init podem, em alguns casos, piorar a taxa de acerto do agente — enquanto arquivos escritos e curados por humanos ajudam de forma consistente. Trate o AGENTS.md como documento vivo que você escreve e revisa, não como artefato gerado uma vez e esquecido.

9 Governança e Habilidades: Playbooks e Skills Reutilizáveis

As duas últimas pastas fecham o ciclo de governança — e não são invenção deste manual: elas espelham diretamente conceitos que Devin e Claude já usam nativamente.

playbooks/ — procedimentos operacionais

Um playbook documenta um procedimento que a equipe repete: como fazer rollback de um deploy em produção, os passos de um hotfix urgente, o checklist de preparação de release sazonal. O Devin, por exemplo, tem seu próprio conceito nativo de Playbook — um prompt reutilizável e compartilhável para tarefas multi-etapa recorrentes, com seções como Procedimento, Especificações (pós-condições) e Ações Proibidas. Ao manter seus playbooks versionados no repositório, você tem uma fonte única: o mesmo texto documenta o processo para humanos e alimenta diretamente a sessão de um agente de IA.

.agents/skills/ — padrões de código reutilizáveis

Aqui vivem os padrões específicos da empresa que você não quer reexplicar em todo prompt: como estruturar um handler de trigger Apex, a convenção de nomenclatura de Custom Metadata Types, o padrão obrigatório de tratamento de erro. Isso não é um conceito abstrato — é exatamente como o Devin trata suas Skills (instruções passo a passo versionadas no repositório, distintas de prompts avulsos) e como o próprio Claude organiza Skills como pastas de instruções reutilizáveis. Empacotar o padrão de código da empresa dessa forma significa que qualquer sessão de IA — de qualquer desenvolvedor do time — parte do mesmo padrão de qualidade, em vez de reinventar convenções a cada tarefa.

🏁 Conclusão

Da Página Estática ao Manual Vivo

As nove seções acima cobrem o ciclo completo: instalar o ambiente, conectar a IA ao org real, entender como Flosum liga Salesforce ao Git com segurança, escrever specs que reduzem retrabalho e custo de computação, e estruturar o repositório para que ele funcione como memória de longo prazo da IA.

Trate esta página como o AGENTS.md da sua própria documentação: um documento vivo, revisado à medida que sua equipe descobre novos atritos — não um artefato publicado uma vez e esquecido.

🚀 Falar com um Arquiteto Salesforce ↑ Voltar ao Sumário

Em síntese

O manual em quatro camadas

Colocar um agente de IA para escrever código num org Salesforce compartilhado só é seguro em quatro camadas: fundação, arquitetura, metodologia e governança. São nove seções, na ordem — cada uma depende da anterior.

  • Fundação — VS Code, Salesforce CLI e JDK 21 na ordem certa; depois a IA ligada ao org vivo por um MCP Server, não só aos arquivos.
  • Arquitetura — o Flosum Cloud Agent traduz metadados em Git nos dois sentidos; Delta Deployment, Overwrite Protection e Smart Merge protegem o org-alvo.
  • Metodologia — Spec-Driven Development: você escreve o QUÊ e o PORQUÊ. Matriz de Impacto e Limites de Atuação cortam retrabalho e computação desperdiçada.
  • Governança — o repositório é a memória de longo prazo da IA: knowledge-base, AGENTS.md, playbooks e skills versionados.

Perguntas frequentes

Perguntas frequentes

Por onde começar para usar IA no desenvolvimento Salesforce?

Pela ordem de instalação: VS Code, Salesforce CLI e Salesforce Extension Pack e, só então, o JDK 21 — instalar Java antes do resto é a causa mais comum de ambiente quebrado. Depois autentique o org com "sf org login web" e conecte um MCP Server de Salesforce, para a IA consultar metadados reais em vez de só ler arquivos estáticos.

Quando usar Claude Code e quando usar Devin?

Claude Code para trabalho interativo no editor: pair programming, revisão de diff a cada mudança, refatoração ambígua e exploração de arquitetura. Devin para ticket bem delimitado que pode rodar sozinho em sandbox e voltar como Pull Request — tarefas repetitivas em lote, delegadas por Slack ou Jira.

Para que serve o Flosum Cloud Agent?

É um serviço Node.js hospedado fora do org que traduz nos dois sentidos entre a API de Metadados da Salesforce e o protocolo Git. É ele que torna o org legível como um repositório Git comum — o formato para o qual Claude Code e Devin foram otimizados.

Como evitar que a IA alucine caminhos ou quebre um org compartilhado?

Três travas em camadas: repositório no formato de origem Salesforce DX (force-app/main/default), uma spec com Matriz de Impacto e Limites de Atuação antes de abrir a sessão do agente, e deploy protegido por Overwrite Protection e Smart Merge no pipeline Flosum.

O que é Spec-Driven Development na prática?

É deixar de escrever o COMO e passar a escrever o QUÊ e o PORQUÊ: uma spec curta com contexto de negócio, objetivo observável, matriz de impacto, limites de escopo e critérios de aceite verificáveis. Escopo vago faz o agente explorar, testar hipóteses e refazer trabalho — o que custa tempo humano e computação.