Skip to content
Practical Engineering Manual · Salesforce + AI + Flosum

DevOps Salesforce with AI:
The Practical Manual for Adopting Devin, Claude and Flosum

From empty environment to protected deploy: the nine sections below show how to install stack, connect Devin and Claude Code your org, let Flosum take care of the mat and write specs that the AI executes without guessing. Written for those who already know Salesforce and is now beginning in agile AI streams — developers, technical architects and administrators.

Introduction

Organisation Salesforce trying to get an AI agent to code directly into production makes the same mistake: it treats AI as if it were another junior developer, without giving it what a junior developer would never have — direct access and no security network to an org shared by dozens of teams.

This manual solves it in four layers: foundation (installed environment correctly), architecture (as Flosum links Salesforce to Git and protects the deploy), methodology (how to write specs that the AI performs without hallucinating) and governance (as the repository itself becomes the long-term memory of the AI). Follow the sections in order — each depends on the previous one.

Format
Practical guide
Depth
Practical guide · ~16 min

You prefer the essentials first? Read synthesis (~1 min)

Part 1

Foundation: Setup and First Connection

1 Initial Setup Guide

The installation order matters. Install Java before the rest is the most common cause of broken environments on teams that are starting. Follow this sequence:

Step 1 — Visual Studio Code

Download and install VS Code in code.visualstudio. with. It is the base editor on which the entire stack (Salesforce + AI) will run.

Step 2 — Salesforce CLI + Salesforce Extension Pack

  1. Install Salesforce CLI (sf), via official installer or npm: 
    npm install --global @salesforce/cli
sf --version
  2. Inside the VS Code, open the Extensions tab (Ctrl+Shift+X / Cmd+Shift+X) and install the Salesforce Extension Pack. It supports Apex, Lightning Web Components, metadata visualization and the Apex Replay Debugger.

Step 3 — Java Development Kit (JDK) 21

The Apex Language Server — the engine that gives Apex autocomplete, navigation and debug inside the Salesforce Extension Pack — runs on a JVM. Without the correct JDK installed, these features simply do not appear.

  • Install JDK 21 (currently recommended version; 17 and 11 are still accepted). Free builds like Zulu OpenJDK or Oracle JDK They work well.
  • VS Code tries to locate Java automatically by the environment variable JAVA_HOME. If not, point manually at Settings → salesforcedx-vscode-apex.java.home for JDK 21 installation folder.

Validation checklist:

Open a file .cls any — if it appears autocomplete and there is no warning of "Java not found" in the lower right corner, the environment is ready for the next step.

2 Connecting AI to Salesforce Environment

With the base environment ready, the next step is to give the AI the two accesses it needs: code (via editor) and live org (via API). Without the second, AI only sees static files — it cannot confirm if what it is reading matches the reality of the org.

Step 1 — Install the AI extension in the editor

  • Claude Code: in the VS Code Extensions tab, search for "Claude Code" and click install (also works in VS Code forks). Alternatively, install via terminal: 
    npm install -g @anthropic-ai/claude-code
    and turn claude inside the integrated VS Code terminal. A Claude plan (Pro, Max, Team or Enterprise) or an API key is required.
  • Devin: because it is a standalone agent working in cloud sandbox, Devin's main connection happens through his app/web, integrated into his GitHub/GitLab repository — not as a local extension running on your machine. Use Devin Desktop when you need a local interactive session.

Step 2 — Authenticate in Salesforce

All authentication goes through Salesforce CLI, which both Claude Code and Devin can invoke via terminal: 

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

This opens the browser to the stream Salesforce standard Auth and record a reusable local alias.

Step 3 — Connecting a Salesforce MCP Server

A code editor, alone, reads only files. For AI to be able to consult metadata and records real from org, she needs an MCP server (Model Context Protocol) Salesforce connected — whether the Salesforce local development server (using CLI authentication) or a hosted MCP server. It is this server that exposes tools such as "list objects", "describe fields" and "turn SOQL" to the model.

Step 4 — Validate connection

The simplest and most revealing test: ask AI, in natural language, something that would only have the correct answer if it was actually connected to the org:

"List the custom objects of this org."

"How many records are there in the Account table?"

If the answer comes with real object names from your org (non-generic) or a number that matches a SELECT COUNT() FROM Account manual, chain editor → CLI → org → IA It's validated from end to end.

Which AI to use in each situation

Scene Most suitable tool
Interactive scheduler, line-to-line review, decisions requiring constant judgment Claude Code — runs in its editor, with diff revision at each change
Well delimited Ticket that can run alone (e.g. update 40 classes to a new log pattern) Devin — standalone agent in sandbox, delivers a Pull Request ready for review
Exploitation of architecture, ambiguous refactoring Claude Code
Batch repetitive tasks, delegated via Slack/Jira without step-by-step supervision Devin
Prices and usage limits frequently change in both products — always confirm on each other's official page before dimensioning team cost.
Part 2

Architecture: The Pieces Behind Integration

3 Depth Architecture: Flosum Cloud Agent

Salesforce speaks Metadata API (XML, SOAP/REST calls authenticated against an org). Git speaks repository objects (blobs, commits, HTTP/SSH protocol). These two languages do not understand themselves — that is where the Flosum Cloud Agent (also documented as Flosum Agent in official Flosum materials).

It is a service built on Node.js, usually hosted outside the org Salesforce (on platforms like Heroku), which works as a bidirectional translator:

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

→ In the Salesforce → Git:

When a developer commits a component within Flosum, the managed package (which lives within your org Salesforce) sends the message to the Agent. Agent translates metadata payload into the file structure and commits the Git provider expects, and effective push.

← In Git → Salesforce:

When something is changed directly in the repository (or in response to a merge), the Agent receives the event, translates back into the metadata format and synchronizes the state within Flosum, which in turn can shoot deploy to a target org via Metadata API.

Because it matters to AI:

Tools like Claude Code and Devin have been trained and optimized to work on common Git repositories — not on the Salesforce Metadata API directly. Agent is what makes your org "readable" as a normal Git repository, allowing AI to operate without having to understand the authentication and serialization details of the Salesforce platform.

4 The Metadata Pattern: Why Structure Matters For the AI

Generating AI models have been trained in a massive amount of repositories Public salesforce following a convention: Salesforce DX, with source code root in: 

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

This structure is not just an aesthetic convention — it is the mental map that the model uses to predict where a file should be. When a repository deviates from it (custom folders, legacy metadata format, diverging API names of file names), the AI passes to hallucinate paths: suggests editing a file that does not exist, creates a component in the wrong folder, or fails to see the dependency between an Apex class and the custom object it handles.

Practical rule:

If your project still uses legacy metadata format, convert before exposing the repository to AI: 

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

Keep API names identical to file names, and avoid custom folders outside the tree force-app/main/default/. Each exception to the convention is one more point where the AI will "guess" — and guess at a shared production org has real cost.

5 IC/CD Flow: from Merge to Protected Deploy

After an AI (or a human) opens a Pull Request and it is approved and merged into the integration branch, the automatic flow assumes:

  1. 1
    Postmerge webhook: Git (GitHub, GitLab, Bitbucket) provider fires a webhook as soon as the merge happens.
  2. 2
    Flosum Cloud Agent receives the event and notify Flosum within the org, which recognizes the new revision in the corresponding branch.
  3. 3
    Pipeline is automatically triggered — in Flosum, a pipeline is a configurable sequence of steps (validation, deploy, rollback) that can be triggered automatically at each commit in a linked branch or repository without manual intervention.
  4. 4
    Deployment with dynamic scope: using Delta Deployments, the pipeline sends only the components that have actually changed — not the whole package — reducing deploy time and risk surface.
  5. 5
    Before touching the target org, two protections come into action:
    Overwrite Protection

    Compares what is being deployed against the actual current state of destination org. If someone has changed that same component directly in the org (outside the Git stream) or other branch has already modified it, the deploy is signaled instead of simply overwriting.

    Smart Merge

    Makes a semantic comparison (field to field, method to method — not line to line as a git diff common) between the conflicting versions. This allows two teams to change fields different from the same object or different methods of the same class have both changes preserved, instead of overwriting the other.

That pair — Overwrite Protection + Smart Merge — is what makes it safe to delegate deploys to a mostly automated flow in a multiple-squad enterprise org by moving the same objects in parallel.

Part 3

Methodology: Think Before Writing Prompt

6 Spec-Driven Development: The Manifesto of New Mentality

In 2024 and 2025, the entire industry went through the same cycle: loose prompts generated plausible code that diverged from real intent — which came to be called vibe coding. The answer to this, adopted today by tools such as GitHub Spec Kit, AWS Kiro and Claude Code's own skills, has a name: Spec-Driven Development (SDD).

"You don't write HOW anymore. You write WHAT AND WHY — and the IA solves the implementation."

This requires a real change of habit:

  • •
    The developer deliverable ceases to be code and becomes the specification. Code has become cheap to generate; clear intention remains the scarce resource.
  • •
    Ambiguity is not a time saving — it is a technical debt that the AI will pay for you in the wrong way. A vague prompt as "improves this flow of approval" invites the AI to make business decisions that are not hers to make.
  • •
    In a shared Salesforce org, a wrong assumption does not only generate a bug — it generates an incident. Validation rules, flows and integrations are all interconnected; AI has no way of knowing that a field is used by external integration if no one has documented it anywhere.
  • •
    Writing spec is the new "think before coding". The time I was going to draw the solution on the head now goes to write it so that another (artificial) intelligence can execute it without reinterpreting it.

In practice, this means: before opening a session of Devin or Claude Code for a non-trivial task, you write a short and objective spec — not a 10-page document, but enough to eliminate questions that the AI would have to guess on its own.

7 Specification Template: The Agreement Between You and AI

A flawed spec costs in two ways: human rework and Unnecessary consumption of AI computing. Autonomous agent tools like Devin charge (or historically charged, and still use as internal measurement unit) by ACU — Agent Computer Unit, a standard measurement of virtual machine time, model inference and network consumed by task. The more vague the spec, the more the AI needs to explore, test hypotheses and redo work — and more ACUs (or equivalent computing on any agile tool) it burns. Clear scope is not bureaucracy: it is computing economy.

Use this model as a starting point — adapt, but do not remove any of the six sections: 

# 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.

Why this structure reduces computing cost:

A Impact Matrix eliminates the "blind exploration" phase where the AI would have to sweep the entire repository trying to guess what's relevant.

The Acting Limits They prevent it from opening changes in neighboring components "just in case."

And Acceptance Criteria Verifiables eliminate round-and-round cycles of "not quite what I wanted."

Part 4

Governance: The Repository as Brain

8 The Repository As AI Brain

A Git repository, for an agile AI, is not just where the code lives — it is the single long-term memory She has between sessions. If the business context is not in the repository, it does not exist for the AI. Structure the repository as follows: 

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

The folder knowledge-base/ loads what XML metadata will never count alone: which team owns the object Opportunitywhich external systems consume the field Account.SAP_ID__c via integration, or what "MRR" means in the company vocabulary. Without this map, the AI treats every component as equally safe to change — which is exactly the opposite of reality in a mature org.

The AGENTS file. root md:

File AGENTS.md deserves special attention: it is no longer a single supplier convention and today is an open standard, maintained by the Agency AI Foundation (Linux Foundation project), natively read by Claude Code, Codex, Cursor, Copilot, Gemini and others. In it, document exact commands (sf project deploy validate, sf apex run test --code-coverage), the API version Salesforce in use, and links to folders knowledge-base/ and playbooks/.

An important alert:

Recent search (ETH Zürich, 2026) showed that context files automatically generated by type commands /init may, in some cases, worsen the agent’s hit rate — while files written and healed by humans help consistently. Treat the AGENTS.md as a living document you write and review, not as artifact generated once and forgotten.

9 Governance and Skills: Playbooks and Reusable Skills

The last two folders close the governance cycle — and are not the invention of this manual: they directly mirror concepts that Devin and Claude already use natively.

playbooks/ operational procedures

A playbook documents a procedure that the team repeats: how to rollback a deploy in production, the steps of an urgent hotfix, the seasonal release preparation checklist. Devin, for example, has his own native concept of Playbook — a reusable and shared prompt for recurring multi-stage tasks, with sections such as Procedure, Specifications (post-conditions) and Forbidden Actions. By keeping your playlists versioned in the repository, you have a unique source: the same text documents the human process and directly feeds the session of an AI agent.

.agents/kills/ — reusable code standards

Here live company-specific standards that you do not want to reexplain in every prompt: how to structure an Apex trigger handler, the Custom Metadata Types nomenclature convention, the mandatory error treatment standard. That's not an abstract concept -- that's exactly how Devin treats his Skills (step-by-step instructions in the repository, distinct from individual prompts) and how Claude himself organizes Skills as reusable instruction folders. Packing the company code pattern in this way means that any AI session — of any team developer — is part of the same quality standard instead of reinventing conventions to each task.

🏁 Conclusão

From Static Page to Live Manual

The nine sections above cover the complete cycle: install the environment, connect the real org AI, understand As Flosum connects Salesforce to Git safely, write specs that reduce rework and computing cost, and structure the repository for it to function as AI long-term memory.

Treat this page as AGENTS.md of his own documentation: a living document, revised as his team discovers new frictions — not an artifact published once and forgotten.

Talk to a Salesforce Architect ↑ Back to Summary

In short

The four-layer manual

Putting an AI agent to write code in a shared org Salesforce is only safe in four layers: foundation, architecture, methodology and governance. There are nine sections, in order — each one depends on the previous one.

  • Foundation — VS Code, Salesforce CLI and JDK 21 in the right order; then IA connected to live org by an MCP Server, not just to files.
  • Architecture — Flosum Cloud Agent translates metadata into Git in both directions; Delta Deployment, Overwrite Protection and Smart Merge protect the target org.
  • Methodology — Spec-Driven Development: You write WHO and WHY. Impact Matrix and Acting Limits cut rework and wasted computing.
  • Governance — the repository is the long-term memory of the AI: knowledge-base, AGENTS.md, playbooks and skill versions.

Frequently Asked Questions

Frequently Asked Questions

Where to start to use AI in Salesforce development?

In the order of installation: VS Code, Salesforce CLI and Salesforce Extension Pack and then JDK 21 — installing Java before the rest is the most common cause of broken environment. Then authenticate the org with "sf org login web" and connect an MCP Salesforce Server, for AI to consult real metadata instead of just reading static files.

When to use Claude Code and when to use Devin?

Claude Code for interactive work in the editor: pair programming, diff review with each change, ambiguous refactoring and architectural exploration. Devin for well-defined ticket that can run alone in sandbox and come back as Pull Request — repetitive batch tasks, delegated by Slack or Jira.

What is Flosum Cloud Agent for?

It's a Node service. js hosted out of the org that translates in both directions between the Salesforce Metadata API and the Git protocol. It is he who makes the org readable as a common Git repository — the format for which Claude Code and Devin were optimized.

How to prevent AI from hallucinating paths or breaking a shared org?

Three Layer Locks: a repository in Salesforce DX source format (force-app/main/default), a spec with Impact Matrix and Acting Limits before opening the agent session, and deploy protected by Overwrite Protection and Smart Merge on the Flosum pipeline.

What is Spec-Driven Development in practice?

It is to stop writing the HOW and start writing the WHO and WHY: a short spec with business context, observable objective, impact matrix, scope limits and verifiable acceptance criteria. Vague scope makes the agent explore, test hypotheses and rework — which costs human time and computing.