Nunca usei Devin
Complete todos os passos em ordem. Não pule o Passo 4.
Quick Start · 7 passos · ~60 min
Do zero ao repositório configurado
Um guia imperativo e sequencial — diz exatamente o que fazer, nessa ordem, sem desvios. Ao final, seu repositório estará clonado, configurado e com o Devin tendo executado uma Spec real.
Escopo deste guia
Este guia assume que você tem acesso ao Devin (Cognition), ao Flosum instalado na sua org e permissão para criar sandboxes. Se ainda não tem, complete os pré-requisitos abaixo antes de começar.
Já conheço Devin
Você pode pular direto para o Passo 5 após o Passo 2.
Tech Lead
No Passo 2, declare um domínio por time. No Passo 4, crie um Blueprint compartilhado com o squad.
Antes de começar
Pré-requisitos
Marque cada item antes de avançar. Pular um pré-requisito aqui vai travar você no meio do guia.
Checklist de acesso e ferramentas
de pré-requisitos confirmadosTudo pronto.
Você confirmou os 7 pré-requisitos. Avance para o Passo 1 →
Passo 1 · ~5 min
Pegue o template
Objetivo: ter o repositório local com a estrutura pronta
1. Faça o fork
Template oficial
github.com/issei/sf-repo
Clique em Fork no canto superior direito.
2. Clone o seu fork
git clone https://github.com/<seu-org>/sf-repo.git cd sf-repo
3. Confira a estrutura
sf-repo/ ├── knowledge-base/ ← você vai editar isso no Passo 2 ├── specs/ ← você vai criar aqui no Passo 5 ├── playbooks/ ← não mexa ainda └── scripts/ ← vai rodar no Passo 7
Atenção:
não renomeie pastas. O Devin referencia esses paths nos playbooks.
Passo 2 · ~10 min
Diga ao Devin onde ele está
Objetivo: preencher a knowledge-base com os dados reais da org e do time
Esta é a etapa mais importante e a mais ignorada. O Devin sem contexto é um dev sem onboarding — vai adivinhar convenções, pisar em metadata de outros times e gerar retrabalho. Três arquivos, dez minutos, diferença enorme.
Abra knowledge-base/metadata-ownership.yaml e substitua
pelo seu contexto real:
domains: - name: CommercePricing # nome do seu domínio team: pricing-squad # nome do seu time objects: [Order, Product2] # objetos que seu time é dono classes_prefix: CP_ # prefixo de naming das suas classes - name: CustomerService team: cs-squad objects: [Case, Contact] classes_prefix: CS_
Time único? Declare um domínio só. O que importa é que exista e que
o prefixo seja real.
Abra knowledge-base/org-inventory.md e liste suas orgs
reais:
## Orgs disponíveis
| Alias | Tipo | Uso |
|-------------|----------|-----------------------------|
| dev-<nome> | Sandbox | Desenvolvimento individual |
| qa | Sandbox | Validação pré-merge |
| preprod | Sandbox | Homologação |
| prod | Produção | Deploy final via Flosum |
Abra knowledge-base/flosum-pipeline-map.md e confirme o
pipeline:
## Pipeline de promoção dev → qa → preprod → prod Responsável pelo deploy: Flosum (nunca o Devin diretamente)
Passo 3 · ~5 min
Conecte as orgs
Objetivo: autenticar as orgs individualmente com Web Login
Login web por alias
# Execute para cada org que vai usar sf org login web --alias dev-<seu-nome> sf org login web --alias qa sf org login web --alias preprod
Por que Web Login e não JWT
Em sandboxes Salesforce cada dev faz login individual. JWT individual por dev é inviável operacionalmente, e centralizar em um usuário sistêmico de CI/CD eliminaria a rastreabilidade de alterações por autor — informação crítica para auditoria e Smart Merge. O Web Login preserva identidade sem comprometer o pipeline.
Verificação
sf org list
Confirme que os aliases aparecem na lista antes de avançar.
Passo 4 · ~10 min
Prepare o Devin
Objetivo: criar o Blueprint e configurar o Agents.md para que o Devin entenda o ambiente desde a primeira sessão
4a
Blueprint
No painel do Devin, crie um Blueprint apontando para a raiz do repositório clonado. Garanta que o ambiente tenha:
- ● Python 3.9+
- ● Node.js 18+
-
● Salesforce CLI (
sf) -
● Acesso ao diretório raiz do
sf-repo
Documentação oficial
docs.devin.ai/onboard-devin/environment/blueprints
4b
Agents.md
O arquivo já existe no template. Edite apenas estas duas linhas:
# Contexto do agente Repositório: sf-repo — domínio: <seu-domínio> Org principal de validação: <alias-da-sua-sandbox>
Verificação — prompt de teste
Leia knowledge-base/org-inventory.md e me diga
quais orgs estão disponíveis.
Se o Devin responder com as orgs que você cadastrou no Passo 2, o ambiente está configurado corretamente.
Tech Lead
Crie um Blueprint compartilhado e distribua o Agents.md já preenchido para o squad. Cada dev faz apenas o login web do Passo 3 individualmente.
Passo 5 · ~10 min
Escreva sua primeira Spec
Objetivo: criar uma Spec real de uma demanda do seu contexto
Use uma demanda real do seu backlog — não um exemplo inventado. A Spec não precisa ser perfeita; precisa ser honesta sobre o que você sabe agora. O Devin vai travar onde a Spec for vaga, e isso é útil — é o sinal para refinar antes de pedir código.
Template completo da Spec
# SPEC: [<TICKET>] <título da demanda> ## 1. Contexto <Por que essa demanda existe? Qual dor de negócio resolve?> ## 2. Requisitos funcionais - <comportamento observável 1> - <comportamento observável 2> ## 3. Regras técnicas - Padrão: conforme /playbooks/02_apex.md - Cobertura mínima: 85% - Prefixo de naming: <prefixo do seu domínio>_ ## 4. Limites (out-of-scope) - NÃO modificar Profiles ou Permission Sets - NÃO tocar em metadata fora de <seu-domínio> ## 5. Critérios de aceite - [ ] <critério testável e mensurável 1> - [ ] check-metadata-ownership.py aprovado ## 6. Guardrails - Auth: sf org login web apenas - Deploy: --check-only em sandbox; promoção via Flosum - Sem destructiveChanges. Sem JWT.
Salvamento
Salve como specs/<TICKET>.md dentro do repositório.
Dica
Se travar no Contexto, comece pelo Critério de aceite. A pergunta "como vou saber que está pronto?" responde o porquê sozinho.
Quer entender por que a Spec tem 6 seções? → Anatomia da Spec no guia completo
Passo 6 · ~10 min
Execute com o Devin
Objetivo: primeira execução real com a Spec criada no passo anterior
Prompt exato a copiar
Leia specs/<TICKET>.md e playbooks/02_apex.md. Implemente apenas em force-app/main/default/. Rode scripts/validation/check-metadata-ownership.py antes de finalizar. Pare e me informe se qualquer guardrail falhar.
O que acompanhar (não é checklist de conclusão)
Se algo falhar — fluxo de decisão
Erro de ownership
Sintoma
check-metadata-ownership.py falha
Ação
Revise metadata-ownership.yaml
(Passo 2a) e re-execute.
Erro de cobertura
Sintoma
Testes abaixo do mínimo definido na Spec.
Ação
Refine a Spec seção 3 (Regras técnicas) — não peça mais código ainda.
Loop sem progresso
Sintoma
Devin tenta corrigir o mesmo erro 2× ou mais.
Ação
Pare. Refine a Spec. Re-execute com o prompt do início deste passo.
Regra de ouro:
nunca itere "no escuro". Se algo falhar duas vezes seguidas, o problema está na
Spec — não no Devin.
Passo 7 · ~5 min
Valide e entregue ao Flosum
Objetivo: validar localmente e acionar o Flosum para promover
Bloco 1 — Validação local
python scripts/validation/check-metadata-ownership.py python scripts/validation/check-destructive-changes.py sf project deploy start --check-only --target-org qa bash scripts/salesforce/run-tests.sh
Bloco 2 — Promoção via Flosum (após PR aprovado e merge na main)
npx @flosum/cli branch sync --branch devin/<ticket>-<slug> npx @flosum/cli package deploy \ --manifest manifest/package-deploy.xml
Aviso crítico
O Devin não executa esta etapa. Flosum é o único deployer oficial
para ambientes compartilhados. Nunca peça ao Devin para rodar o
flosum cli em QA, PreProd ou Prod.
Você terminou o Quick Start
O que fazer agora
Dev individual
Repita o ciclo Spec → Devin → Flosum com sua próxima demanda real. Cada iteração fica mais rápida.
Tech Lead
Faça fork do repositório para cada time. Adapte o
metadata-ownership.yaml por domínio. Distribua o Blueprint configurado.
Todos
Leia a seção de Governança no guia completo para entender ownership em escala com múltiplos times.
Links de aprofundamento
Volte ao guia completo para entender o porquê de cada peça.