Blog

"A IA acelera. Mas só vira produtividade de verdade quando o time consegue confiar no que foi entregue."

Usar IA para escrever código e documentação já é parte do dia a dia de muitos times. O problema é que, em projeto real, a IA pode entregar um “feito” que não cobre todos os detalhes (filtros faltando, edge cases, validações de back-end, erros de permissão, etc.). Pior: às vezes ela parece ter feito tudo, mas deixou um “buraco” que só aparece em homologação — ou em produção.

Este post é um playbook operacional (bem mão na massa) para manter velocidade sem perder controle: planejamento, execução em fatias pequenas, revisão humana, testes e um deploy que não coloca produção em risco.

Para quem é este checklist

• Devs (front/back/fullstack) que usam assistentes de código e querem reduzir retrabalho.
• Tech leads e engenheiros responsáveis por qualidade e segurança.
• Times com CI/CD e múltiplos ambientes (dev/stg/prod) que precisam de um fluxo “à prova de susto”.
• Pessoas que já viveram a dor do: “a IA disse que fez tudo… e não fez”.

O que você vai aprender

• Como evitar o padrão “a IA disse que fez tudo, mas não fez”.
• Como quebrar features para caber no contexto e reduzir “alucinação silenciosa”.
• Como montar um fluxo de validação (front + back) sem depender de “fé”.
• Como fazer deploy com segurança: sem dar acesso direto à produção.
• Como medir se a IA está de fato melhorando o delivery (e não só mudando o tipo de caos).

Desenvolvimento assistido por IA é “assistido”, não “automático”

Chame de “desenvolvimento assistido” quando:

• você mantém responsabilidade técnica (arquitetura, decisão e validação);
• a IA executa partes do trabalho (boilerplate, ajustes, testes, documentação);
• o time tem rituais para detectar erros e mudanças indevidas.

Quando vira “automático”, o risco sobe muito:

• merges sem review;
• deploys fora do CI;
• credenciais expostas;
• mudanças no back-end “sem querer”;
• “otimizações” que não foram pedidas (refactors e troca de estruturas).

Se a sua meta é velocidade com previsibilidade, o caminho é: ritual + evidência.

Quatro princípios que deixam o uso de IA sustentável

1. Responsabilidade é humana
   A IA pode sugerir e implementar, mas quem responde por arquitetura, segurança e qualidade é o time.
2. Pequeno é mais rápido (na prática)
   Tarefas menores reduzem “perda de contexto”, diminuem retrabalho e aceleram review e teste.
3. Prova antes de opinião
   “Compilou” não é “pronto”. O artefato precisa de validação: teste guiado (UI) e teste de contrato (API).
4. Menor privilégio, sempre
   Quanto maior a permissão, maior o custo do erro. Deploy deve acontecer via CI, com credenciais mínimas.

Se você quer um norte mais “formal” para práticas seguras ao longo do SDLC, vale ler o NIST SSDF (Secure Software Development Framework), que enfatiza práticas e evidências ao longo do ciclo de desenvolvimento: NIST SSDF (SP 800-218).

O problema real: contexto curto + entrega “mínima aceitável”

Em squads, aparecem quatro falhas recorrentes:

1. Perda de contexto
   Quanto maior a tarefa, maior a chance de a IA “esquecer” decisões, componentes existentes, padrões do repo e detalhes do domínio.
2. Entrega parcial
   Ela resolve o que você pediu explicitamente, mas deixa pendências “fora do escopo” que deveriam estar junto (ex.: integra tabela, mas não integra filtros; adiciona API, mas não atualiza a UI; cria endpoint, mas não valida permissão).
3. Refactor não solicitado
   A IA pode “melhorar” algo que estava ok: muda estruturas, renomeia métodos, altera validações, reordena lógica. Isso aumenta a superfície de bugs sem aumentar valor.
4. Risco operacional e de segurança
   Quando a IA tem acesso demais (infra, produção, secrets), o custo de um erro cresce exponencialmente.

A solução não é “não usar IA”. É usar com ritual, com limites claros e com mecanismos de prova.

Fluxo recomendado em 6 etapas

1) Planeje antes de codar

Antes de mandar “faz isso”, force o passo de planejamento. O objetivo é a IA enxergar impacto e você conseguir revisar com clareza. Planejamento bom é o que:

• dá para transformar em tarefas pequenas;
• deixa explícito o que não deve mudar;
• define critérios de aceite mensuráveis.

Checklist de planejamento (o que não pode faltar)

• Escopo funcional: o que o usuário final vai ver/conseguir fazer.
• Impacto em dados: migrations? seeds? ajustes de schema?
• Impacto em permissões: RBAC/ABAC, endpoints e telas afetadas.
• Impacto em integrações: APIs externas, autenticação, tokens.
• Observabilidade: logs, métricas, tratamento de erro.
• Critérios de aceite: como provar que está pronto.
• Riscos: o que pode dar errado e como detectar cedo.

Mapa de impacto (modelo simples)

Prompt de planejamento (modelo)

Planeje a implementação da feature X.

Entregáveis:
- Lista de arquivos/pastas que devem mudar (front, back, infra, docs).
- Critérios de aceite objetivos.
- Riscos e pontos que exigem validação manual.
- Checklist de testes (front + API).
- O que NÃO deve ser alterado.

Restrições:
- Não implemente nada ainda.
- Se faltar informação, liste perguntas.

“Definition of Ready” da sua tarefa (para reduzir retrabalho)

Antes de abrir a fatia para a IA (ou para alguém do time), valide:

• Existe critério de aceite objetivo (não “ficar bom”).
• Existe exemplo de entrada/saída (quando é API/integração).
• Existe referência visual (quando é UI).
• Existe regra de permissão e perfil (quando envolve acesso).

2) Fatias pequenas: como quebrar sem perder o fio

A regra mais útil: uma fatia = uma unidade testável.

Se você não consegue testar uma fatia em 5–10 minutos, ela está grande demais.

Heurística rápida para “tamanho certo”

Técnica: fatia vertical mínima

Em vez de “fazer o módulo todo”, busque um fluxo fim a fim pequeno:

1. UI exibe informação mínima
2. API retorna o mínimo necessário
3. Permissão aplicada
4. Teste guiado e teste de contrato

Exemplo prático (muito comum): “cálculo de margens por rota”.

Uma fatia vertical mínima poderia ser:

• endpoint retorna margens por rota (com permissão owner-only)
• tela exibe margens (com estado vazio/loading)
• cálculo da “melhor margem” aparece no resumo
• evidência: vídeo/print + chamada no Postman

A partir daí, você cria novas fatias: exportação, ajustes visuais, PDF, etc.

Exemplos de boas fatias (mundo real)

• “Aplicar RBAC na listagem: perfis A e B só veem rotas próprias.”
• “Exibir margens na tela e calcular melhor margem no resumo.”
• “Adicionar exportação PDF e validar layout mínimo.”
• “Criar endpoint X + testes de contrato + documentação do endpoint.”

Exemplo de fatias ruins (evite)

• “Concluir módulo de operações inteiro.”
• “Fazer a integração completa do app.”
• “Refatorar a área toda para ficar melhor.”

3) Execute por fatia, com prova embutida

Para cada fatia, combine:

1. o que fazer
2. como provar que funcionou
3. como evitar mudanças indevidas

Prompt de execução (modelo)

Implemente a tarefa abaixo.

Tarefa:
- ...

Critérios de aceite:
- ...

Restrições:
- Não refatore código fora do escopo.
- Reutilize componentes existentes quando possível.
- Não altere contratos de API sem avisar.

Depois de implementar:
- Liste como validar manualmente.
- Cite quais arquivos foram alterados.
- Sugira testes automatizados mínimos (unit/integration/e2e).

Prompt de “correção dirigida” (quando faltou um pedaço)

Quando você detectar o “fez a tabela, mas não fez o filtro”, evite pedir “faz tudo de novo”. Seja específico:

A implementação ficou incompleta.

Ajuste somente os itens abaixo (sem refactor fora do escopo):
- ...
- ...

Depois, liste:
- arquivos alterados
- como validar

Dica que reduz “feito, mas não fez”

No final da execução, peça sempre:

• “Liste o que você não implementou e por quê”.
• “Liste os riscos que você enxerga no que foi feito”.
• “Liste as assunções que você fez”.

Isso força a IA a “expor” lacunas.

4) Review que pega “alucinação silenciosa”

A IA pode “otimizar” coisas que não precisavam mudar. Esse é o tipo de bug que passa despercebido em revisão apressada.

Checklist de review (prático e rápido)

Escopo e arquitetura:

• Mudou só o necessário?
• Reutilizou componentes/padrões existentes (em vez de duplicar)?
• Não criou dependência nova sem justificativa?
• Não alterou contratos de API sem versionar/documentar?

Regra de negócio:

• Cobre os critérios de aceite?
• Cobriu filtros, estados vazios, paginação, ordenação?
• Validou permissão (RBAC/ABAC) em todos os endpoints/telas afetados?

Qualidade e segurança:

• Logs/erros estão úteis (sem vazar dados sensíveis)?
• Não adicionou credenciais no código?
• Tratamento de erro não mascara falhas (ex.: catch vazio)?
• Alterações de config/infra são intencionais?

Dica: review “por diff” funciona melhor do que “ler arquivo inteiro”. Um bom checklist de code review começa por entender entradas, permissões e fluxo de dados.

Se quiser aprofundar review de segurança, vale usar como referência o OWASP Cheat Sheet de Secure Code Review: Secure Code Review Cheat Sheet.

Proteja a branch principal e torne review obrigatório

Do ponto de vista de processo, duas regras reduzem muito risco:

• branch principal protegida (sem push direto)
• aprovação obrigatória no MR/PR

No GitLab, você consegue:

• proteger branches (impedindo push direto e exigindo fluxo via MR): Protected branches
• definir regras de aprovação para merge requests: Merge request approval rules

O objetivo é simples: “ninguém (e nenhuma IA) passa direto”.

CODEOWNERS: um truque simples para revisão mais assertiva

Se o seu repo permite, use CODEOWNERS para exigir aprovação de quem “dona” o módulo quando ele for alterado.

Um exemplo simples:

# Exemplo (ajuste para o seu repo)
src/backend/ @backend-team
src/frontend/ @frontend-team
infra/ @devops-team

5) Teste explícito (front e back)

Se você só “olhou o código”, você não testou. E com IA isso pesa ainda mais, porque o código pode estar coerente e mesmo assim falhar no fluxo real.

Matriz de testes (o mínimo que pega 80% dos problemas)

Front-end (teste guiado):

• Fluxo principal (happy path) completo.
• Estados vazios (sem dados) e loading.
• Permissões (RBAC): usuário vê só o que pode.
• Exportações: CSV/Excel/PDF geram conteúdo correto.
• Responsividade e layout crítico (principalmente se houve feedback visual).

Back-end (teste de contrato):

• Autenticação funciona (tokens/refresh).
• Filtros retornam dados corretos.
• Paginação e ordenação.
• Erros retornam status coerente (400/401/403/500) com mensagem útil.
• Não vazou informação (ex.: usuário A consegue ver dados do usuário B).

Prompt para gerar roteiro de testes (modelo)

Crie um roteiro de testes para validar a feature X.

Inclua:
- Casos happy path (front + API)
- Casos de permissão (RBAC)
- Casos de erro (400/401/403/500)
- Casos de edge (dados vazios, paginação, filtro)
- Evidências mínimas a coletar (prints/logs)

Onde a IA mais “passa batido”: back-end

No front, você vê na tela se está errado. No back, um erro pode ficar invisível sem Postman/tests.

Regra de ouro: toda fatia que muda API precisa de teste de contrato (manual ou automatizado).

Se o seu time precisa de um baseline de requisitos de segurança para web/APIs, o OWASP ASVS é um ótimo ponto de partida: OWASP ASVS.

6) Deploy seguro: “a IA não sobe nada em produção”

O padrão mais seguro é:

• IA trabalha em branch de desenvolvimento;
• abre merge request;
• CI roda testes/build;
• só o pipeline tem credenciais de deploy;
• produção só recebe artefato validado.

Isso segue o princípio de menor privilégio: dar somente as permissões necessárias para cada tarefa, e nada além. No contexto de AWS, por exemplo, isso é explicitamente recomendado como prática de IAM: Least-privilege permissions.

Use ambientes efêmeros para revisar antes de merge (Review Apps)

Se você usa GitLab, “Review Apps” são ambientes temporários criados por branch/MR para validar mudanças sem precisar “subir em produção” ou travar um ambiente fixo:

• Review Apps (GitLab CI)

O ganho aqui é enorme:

• review de UI vira “clicável”, não “imaginável”;
• QA testa antes de merge;
• stakeholders validam fluxo sem precisar instalar local;
• o ambiente some depois (reduz custo e bagunça).

Um esqueleto (ilustrativo) de job de review em .gitlab-ci.yml:

review_app:
  stage: review
  script:
    - echo "Deploy do ambiente de review"
  environment:
    name: review/$CI_COMMIT_REF_NAME
    on_stop: stop_review_app
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

stop_review_app:
  stage: review
  script:
    - echo "Derrubando ambiente de review"
  environment:
    name: review/$CI_COMMIT_REF_NAME
    action: stop
  when: manual

Dica: mantenha o script real de deploy no CI, não na mão do agente.

Evite credenciais long-lived no CI (prefira tokens de curta duração)

Um salto de maturidade é trocar segredos fixos por credenciais temporárias via identidade federada (ex.: OIDC), reduzindo risco de vazamento e abuso.

No GitHub Actions, por exemplo, dá para assumir roles na AWS sem armazenar chaves fixas, usando OIDC:

• GitHub Actions + OIDC + AWS
• AWS Security Blog: IAM roles para GitHub Actions via OIDC

Snippet ilustrativo (GitHub Actions):

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/ci-deploy-role
          aws-region: us-east-1
      - run: ./deploy.sh

Segurança de supply chain: o “próximo nível” quando a IA entra forte

Quando você acelera o ritmo de mudanças, aumenta também a necessidade de garantir integridade do build e do artefato.

O framework SLSA é uma referência útil para pensar em controles de supply chain (proveniência do build, integridade, prevenção de tampering):

• SLSA.dev

Você não precisa “virar nível 4” amanhã. Mas dá para começar com perguntas simples:

• Quem pode disparar deploy?
• O artefato de produção veio do CI?
• Existe trilha de auditoria do que foi construído e por quem?

O “pacote” de artefatos que faz a IA funcionar no mundo real

Para transformar IA em previsibilidade, você precisa de artefatos (evidências) que sustentem o delivery. Em segurança de software, frameworks como o NIST SSDF reforçam a importância de manter registros/evidências de práticas ao longo do ciclo.

Na prática, para cada feature relevante, tente produzir:

• Plano curto (escopo, impacto, riscos, critérios de aceite).
• MR/PR com descrição objetiva e checklist de validação.
• Evidência de teste (prints, vídeo curto, logs).
• Mudança de documentação (README/endpoint/observações).
• Plano de rollback (nem que seja “reverter o MR”).

Templates prontos para copiar e colar

1) Template de fatia (ticket) “IA-friendly”

### Contexto
- (1–3 linhas) Qual problema estamos resolvendo?

### Escopo
- ✅ Deve fazer:
  - ...
- ❌ Não deve fazer:
  - ...

### Critérios de aceite
- [ ] ...
- [ ] ...

### Impacto
- Front:
- Back:
- Dados:
- Permissões:
- Logs/monitoramento:

### Como testar (manual)
1. ...
2. ...
3. ...

### Observações
- Links / prints / endpoints

2) Template de descrição de MR/PR (com prova)

## O que foi feito
- ...

## Por que isso foi feito
- ...

## O que NÃO foi feito (fora do escopo)
- ...

## Como validar
1. ...
2. ...

## Checklist
- [ ] CI verde
- [ ] Teste manual do happy path
- [ ] Teste de permissão (RBAC)
- [ ] Sem segredos no código
- [ ] Logs/erros ok

3) Checklist final “antes de merge”

• A feature atende os critérios de aceite.
• Nenhum refactor “de brinde” entrou no diff.
• Teste de contrato da API foi executado (ou existe teste automatizado).
• Branch principal está protegida (sem push direto).
• MR/PR aprovado por pelo menos 1 reviewer.
• Deploy será via CI (sem acesso direto a produção).

Como medir se o processo está melhorando (e não só mudando o tipo de problema)

Se você quer saber se “IA + ritual” está funcionando, pare de medir “linhas de código” e comece a medir flow e estabilidade.

Um conjunto de métricas muito usado na indústria é o das métricas DORA, que equilibram velocidade com confiabilidade. Um bom ponto de partida é o guia oficial: DORA metrics.

Métricas simples para começar (sem tool nova)

• Lead time (MR aberto → em produção): está caindo?
• Retrabalho por MR: quantos commits “apaga incêndio” depois do review?
• Defeitos escapados: bugs que passaram para homolog/produção.
• Tempo de review: está dentro do esperado ou virou gargalo?

Se você já usa GitLab, a plataforma também documenta como mede/define DORA metrics: GitLab DORA metrics.

Resumo final (o que realmente importa)

Se você quiser manter velocidade e confiança, trate IA como um acelerador, não como piloto automático.

O checklist que mais funciona no dia a dia:

• Planeje (mapa de impacto + critérios de aceite).
• Fatie (tarefas pequenas e testáveis).
• Execute (uma fatia por MR).
• Revise (diff + checklist, sem “refactor de brinde”).
• Teste (front + contrato de API).
• Faça deploy seguro (CI com menor privilégio, sem acesso direto a produção).

Leituras relacionadas

• GitLab Repository Graph e estratégia de branches
• OAuth na vida real: checklist para destravar acesso a APIs