Estrutura AIAD com uso de Gemini + Antigravity (com Skills e Clean Architecture) — aplicado a Salesforce Commerce Cloud

Quando você usa IA (Gemini) para produzir código de forma recorrente, a diferença entre um projeto escalável e um “Frankenstein” é simples: estrutura + guardrails + skills reutilizáveis.

Aqui não se trata de Vide Coding o termos mais adequado é o AIAD ( AI-assisted development ) que é quando há o uso de AI para o desenvolvimento com a supervisão de um dev humano.

Abaixo está um modelo prático para organizar um repositório que:

guia o Gemini com contexto consistente
usa o Antigravity como “orquestrador” de skills/padrões
aplica Clean Architecture + Design Patterns para desenvolvimento em Salesforce Commerce Cloud (SFCC)

1) Estrutura de arquivos recomendada

A ideia é separar claramente:

Código do produto (SFCC) → cartridges e o que vai para a plataforma
Documentação do sistema → para humanos
Config e skills da IA → para Gemini/Antigravity (com checklists e templates)


sfcc-ai-first/
├─ README.md
├─ GEMINI.md
├─ docs/
│  ├─ architecture.md
│  ├─ sfcc-guidelines.md
│  ├─ decisions/
│  │  └─ 0001-clean-architecture.md
│  └─ runbooks/
│     └─ local-dev.md
├─ .gemini/
│  ├─ settings.json
│  ├─ skills/
│  │  ├─ sfcc-clean-architecture/
│  │  │  ├─ SKILL.md
│  │  │  └─ templates/
│  │  │     ├─ use_case.md
│  │  │     ├─ port.md
│  │  │     ├─ adapter.md
│  │  │     └─ test_plan.md
│  │  └─ sfcc-code-review/
│  │     └─ SKILL.md
│  ├─ hooks/
│  │  ├─ quality.md
│  │  └─ sfcc-lint.md
│  └─ prompts/
│     ├─ implement_feature.md
│     └─ refactor_feature.md
└─ cartridges/
   ├─ app_custom_core/
   │  ├─ cartridge/
   │  │  ├─ controllers/
   │  │  ├─ scripts/
   │  │  │  ├─ domain/
   │  │  │  ├─ application/
   │  │  │  ├─ ports/
   │  │  │  └─ adapters/
   │  │  ├─ templates/
   │  │  └─ hooks/
   │  └─ package.json
   └─ int_custom_integrations/
      └─ cartridge/
         ├─ scripts/
         └─ services/

Por que assim?

.gemini/ fica só com o que é IA-specific (skills, prompts, hooks).
docs/ descreve o sistema (arquitetura SFCC, decisões, runbooks).
cartridges/ contém o que realmente será deployado/zipado para o SFCC.

2) O arquivo mais importante: `GEMINI.md`

Esse arquivo é o “contrato” que reduz variação do código gerado.

Exemplo (resumido):


# GEMINI.md — Regras do Projeto (SFCC)

## Regras Gerais
- Sempre seguir a skill: .gemini/skills/sfcc-clean-architecture/SKILL.md
- Não colocar regra de negócio em controller.
- Preferir services/use cases em scripts/application.

## SFCC Regras
- Controller: apenas valida input, chama Use Case, retorna view/JSON.
- Integrações (SCAPI/OCAPI/APIs externas) devem passar por Port + Adapter.
- Evitar dependência circular entre scripts.

## Qualidade
- Adicionar plano de teste (unit/integration) para toda feature.
- Manter funções pequenas e nomeadas de forma clara.

3) Clean Architecture dentro do SFCC (como “encaixa” no cartridge)

SFCC tem seu “jeito” (controllers, scripts, hooks, jobs). Clean Architecture funciona muito bem se você mapear assim:

Mapeamento de camadas

Domain (scripts/domain/)
Regras puras: validações, cálculos, políticas, objetos do domínio (sem SFCC APIs quando possível).
Application (scripts/application/)
Use cases: orquestram fluxo (ex.: “Aplicar Segmento no Carrinho”, “Sincronizar Cliente”).
Ports (scripts/ports/)
Interfaces/contratos: “CustomerRepository”, “SegmentProvider”, “CartGateway”.
Adapters (scripts/adapters/)
Implementações SFCC: acesso a dw/*, services, OCAPI/SCAPI, custom objects, etc.
Controllers/Hooks (controllers/, hooks/)
Apenas borda de entrada, sem regra.

4) Exemplo de Skill: Design Pattern + Clean Architecture para SFCC

A skill abaixo é a “receita” que o Gemini segue sempre que você pedir uma feature SFCC.

📄 .gemini/skills/sfcc-clean-architecture/SKILL.md


# Skill: SFCC Clean Architecture + Design Patterns

## Objetivo
Implementar features no Salesforce Commerce Cloud mantendo:
- Clean Architecture (domain/application/ports/adapters)
- Design Patterns: Strategy, Adapter, Facade, Repository (quando aplicável)
- Controllers e Hooks sem regra de negócio

---

## Regras de Estrutura (Obrigatórias)
- Código de negócio em: cartridges/**/scripts/application e scripts/domain
- Contratos em: scripts/ports
- Integrações SFCC/externas em: scripts/adapters
- Controller/Hook: apenas:
  1) ler input
  2) chamar Use Case
  3) retornar resposta

---

## Quando usar cada Pattern (guia rápido)

### Strategy
Use quando houver variação de regra (promoção, elegibilidade, segmentação, cálculo).
Entregáveis:
- interface (ex.: SegmentRule)
- implementações (ex.: VIPSegmentRule, DefaultRule)
- testes de cada variação

### Adapter
Use para integrar com:
- SCAPI / OCAPI
- services HTTP
- SDK/integração legada
Entregáveis:
- Port (contrato)
- Adapter (implementação)

### Facade
Use para simplificar chamadas complexas do SFCC (dw APIs, múltiplos passos).
Entregáveis:
- uma classe/serviço com métodos pequenos
- logs padronizados (sem poluir controllers)

### Repository
Use quando persistência ficar espalhada (Customer, CustomObject, Order).
Entregáveis:
- Port de repositório
- Adapter com a implementação
- mocks simples em testes

---

## Checklist obrigatório (para aceitar a mudança)
- [ ] Use Case criado em scripts/application/use_cases/
- [ ] DTO/shape de input/output documentado (mesmo que informal)
- [ ] Port criado se há dependência externa
- [ ] Adapter implementando o Port
- [ ] Controller/Hook sem regra
- [ ] Plano de testes adicionado em templates/test_plan.md ou tests/
- [ ] Logs e erros padronizados

---

## Prompt padrão
"Implemente a feature em SFCC usando Clean Architecture.
Controller apenas chama o Use Case. Se houver integração, crie Port + Adapter.
Se houver variação de regra, use Strategy. Inclua plano de testes."

5) Exemplo prático (feature SFCC): “Aplicar Segmento do Data Cloud no Carrinho”

Cenário

Um conector traz “segmentos” do cliente
Dependendo do segmento, você aplica uma regra no carrinho (ex.: benefício, flag, recomendação)

Como a skill recomenda implementar

Controller (borda)

recebe request
chama use case
retorna JSON

Use Case

carrega cliente
consulta segmentos via SegmentProviderPort
escolhe estratégia de aplicação
aplica mudanças via CartGatewayPort

Ports

SegmentProviderPort
CartGatewayPort

Adapters

SFCCSegmentProviderAdapter (ou DataCloudSegmentAdapter)
SFCCCartGatewayAdapter (usa dw.order.BasketMgr etc.)

Strategy

SegmentRuleStrategy com implementações por segmento

6) Templates Markdown (para a IA não inventar estrutura)

Exemplo de template para “Use Case”:

📄 .gemini/skills/sfcc-clean-architecture/templates/use_case.md


# Use Case: <NOME>

## Objetivo
Descreva em 1 frase o que faz.

## Input
- campos esperados (request params / body)

## Output
- formato de retorno (view/json/status)

## Regras
- regras principais do domínio

## Dependências (Ports)
- <PortA>
- <PortB>

## Fluxo
1) ...
2) ...
3) ...

## Erros
- casos de erro e como retornar

E um template para “Port”:

📄 .gemini/skills/sfcc-clean-architecture/templates/port.md


# Port: <NOME>

## Responsabilidade
O que esta interface abstrai?

## Métodos
- methodA(args) -> result
- methodB(args) -> result

## Observações
- comportamento esperado
- timeout/retry (se for externo)

7) Como isso acelera o desenvolvimento com IA no SFCC

O Gemini recebe fronteiras (onde pode colocar lógica, onde não pode).
Você reduz o “código espalhado” típico de cartridges grandes.
Integrações (SCAPI/OCAPI/services) viram módulos substituíveis e testáveis.
Patterns entram como “decisões padronizadas”, não improviso.

Pesquisar Posts