POC

Proof of Concept — teste de viabilidade técnica. Responde a uma única pergunta: isso é possível com o esforço e as ferramentas que temos? Não busca qualidade de produção, busca evidência.

Quando fazer um POC?

• Há incerteza técnica real: uma integração nunca testada (ex. Evolution Go + Odoo), um fornecedor novo, um modelo de IA aplicado a um caso específico.
• O custo de errar no PRD é alto — melhor investir 1–3 dias validando antes de comprometer uma sprint inteira.
• Não é necessário se o padrão já existe em outro projeto do time (ex. outro módulo de loyalty já resolvido no Hipermais).

O que contém

PRD

Product Requirements Document — o porquê e o quê, em linguagem de negócio. É escrito ou revisado pelo PO, e lido por todo o time antes de tocar em código.

Estrutura padrão

Quem aprova

O PRD é aprovado pelo PO/stakeholder de negócio antes de criar a tarefa de SPEC no sistema de gestão que você usar. Sem aprovação, o SPEC não é gerado — evita retrabalho quando o negócio muda de ideia no meio da implementação.

SPEC

Technical Specification — traduz o PRD em decisões técnicas concretas. É escrito pelo Tech Lead ou um dev sênior, com ou sem ajuda de IA, mas sempre revisado por um humano antes de virar issues.

Estrutura padrão

Exemplo de cenário em Gherkin

# Critério de aceite PRD-14: resgate de pontos
Scenario: Cliente resgata pontos suficientes
  Given o cliente tem 500 pontos acumulados
  And o prêmio custa 300 pontos
  When o cliente confirma o resgate
  Then o sistema desconta 300 pontos
  And é gerado um cupom válido por 30 dias
  And o evento é registrado em purchase_history

Esses cenários são copiados tal como estão para a issue do GitHub e referenciados no PR — são o critério objetivo que o Agente revisor usa para aprovar ou pedir mudanças.

Gestão de projeto

Seu sistema de gestão de tarefas — seja uma ferramenta paga (ClickUp, Jira, Linear, Azure DevOps...) ou um sistema interno — é a única fonte de verdade do status. Não importa qual você use: o que importa é que o SPEC fique documentado e que cada issue do GitHub corresponda 1:1 a uma tarefa.

Estados do quadro

Convenções da tarefa

Essas regras valem independentemente da ferramenta usada para gerenciar tarefas:

Fluxo Git / GitHub

Uma issue, uma branch, um PR, dois ambientes. A rastreabilidade vai da tarefa no sistema de gestão até o commit em main — sempre passando por homologação.

Ambientes

main e staging são branches permanentes e nunca recebem push direto; tudo o mais é temporário e é apagado ao ser mergeado.

Nomenclatura de branches

Commits (Conventional Commits + rastreabilidade de IA)

feat(loyalty): adicionar validação de pontos suficientes

Implementa o cenário "Cliente resgata pontos suficientes"
do SPEC #142. Valida saldo antes de gerar o cupom.

[ai-assisted: claude-sonnet]
Refs: #142

Issues

• São criadas a partir do desdobramento do SPEC, uma por subtarefa do sistema de gestão — nunca se escreve uma issue sem ter passado pelo SPEC (exceto bugs de produção).
• Título com o ID da tarefa: [142] Validar pontos suficientes antes do resgate.
• Descrição inclui o cenário Gherkin correspondente, copiado do SPEC.

Pull Requests

Template obrigatório — o Agente revisor o usa como checklist automático:

## O que resolve
Closes #142

## Cenário(s) cobertos
- [ ] Cliente resgata pontos suficientes
- [ ] Cliente tenta resgatar com saldo insuficiente

## Uso de IA
- [ ] Código gerado/assistido por IA
- [ ] Modelo: ___
- [ ] Revisado linha por linha pelo autor humano

## Checklist
- [ ] Testes unitários adicionados
- [ ] Sem segredos ou credenciais no diff
- [ ] Migrações testadas em local

GitHub Actions / CI-CD

Todo push a um PR contra staging dispara o mesmo pipeline. Nada chega a main sem antes passar por homologação.

name: PR para Staging
on:
  pull_request:
    branches: [staging]

jobs:
  lint-test-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npm run lint
      - run: npm run test -- --coverage
      - run: npm run build

  agent-review:
    needs: lint-test-build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Executar revisor de IA
        run: node ./scripts/agent-review.js
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          PR_NUMBER: ${{ github.event.pull_request.number }}

  deploy-staging:
    needs: [lint-test-build, agent-review]
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh staging

name: Promover para Produção
on:
  pull_request:
    branches: [main]

jobs:
  deploy-prod:
    # só roda se o PR vier de staging (evita saltos diretos)
    if: github.event.pull_request.merged == true && github.head_ref == 'staging'
    runs-on: ubuntu-latest
    environment: production # exige aprovação manual configurada no GitHub
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh production

Agente revisor

Um job de CI que roda um agente de IA em cada PR. Não substitui o revisor humano — filtra o óbvio para que o humano revise o que importa.

O que o Agente revisa

• Que cada cenário Gherkin do SPEC tenha um teste correspondente no diff.
• Que o PR marque corretamente o checkbox de uso de IA e o modelo usado.
• Convenções do projeto: nomenclatura, estrutura de pastas, padrões já usados no repo (lê o CLAUDE.md da raiz).
• Riscos evidentes: falta de tratamento de erros, queries N+1, segredos hardcoded.
• Consistência entre o PRD/SPEC referenciado e o que foi realmente implementado.

O que NÃO faz

• Não aprova de forma final nem faz merge — só deixa comentários e um status de check no PR.
• Não decide escopo nem prioridade — isso vive no PRD e no sistema de gestão.
• Não substitui o QA manual em fluxos críticos (pagamentos, resgate de pontos, autenticação).

Prompt base do agente (resumo)

Você é o revisor técnico automático do time.
Você tem: o SPEC do ticket, os cenários Gherkin,
o diff completo do PR e o CLAUDE.md do repo.

Devolva APENAS:
1. Cenários sem cobertura de teste (lista)
2. Riscos de segurança ou performance (lista, com linha)
3. Desvios entre o SPEC e a implementação
4. Veredito: APROVADO | MUDANCAS_SOLICITADAS

Não opine sobre estilo se o linter já cobre isso.

Governança de IA

Regras mínimas para usar Claude Code, Codex, Gemini ou qualquer outro LLM de forma consistente no time — pensadas para 3–6 devs, não para um comitê de compliance.

Qual ferramenta usar para quê

Não importa a marca do modelo — importa que o critério esteja escrito e que todo o time o siga. Parametrize esta tabela de acordo com o que você tiver contratado:

O que não entra num prompt

• Credenciais, API keys, tokens ou strings de conexão — nem mesmo "de teste".
• Dados pessoais de clientes sem anonimizar (nomes, telefones, endereços, histórico de compra real).
• Código ou documentos sob NDA de outro cliente, caso o time trabalhe para vários.
• Segredos de infraestrutura (certificados, chaves de Traefik/Cloudflare, backups de banco de dados).

Níveis de risco

Feature flags e rollback

• Toda mudança de risco médio ou alto é implantada atrás de uma feature flag — desligá-la não deveria exigir um novo deploy.
• Commits e PRs pequenos: além de mais fáceis de reverter, um diff enxuto é onde o Agente e o modelo rendem melhor — eles têm mais dificuldade de raciocinar bem sobre mudanças enormes.
• Meta: de "detectamos o problema em prod" a "revertido" em menos de 10 minutos.

Métricas mínimas do Agente

Não precisa de dashboard. Basta revisar, uma vez por mês, o campo "Veredito do Agente" dos últimos PRs:

• Se ele pede mudanças em menos de 10% dos PRs, provavelmente está sendo permissivo demais — revise o prompt dele.
• Se ele pede mudanças em mais de 50% e a maioria são falsos positivos (ruído, não problemas reais), também é preciso ajustar o prompt — está gastando tempo do time sem agregar.
• O ponto saudável está no meio: poucos comentários, mas os que ele faz são reais.

Onboarding de um dev novo

• Lê o CLAUDE.md do repo antes de tocar em código.
• Lê esta metodologia completa (30 minutos, uma única vez).
• Seu primeiro PR é pequeno, de risco baixo, e guiado por um dev sênior.
• Tem acesso configurado às ferramentas de IA aprovadas pelo time — não usa contas pessoais para código do projeto.

Cenário completo

Um caso real, de ponta a ponta, seguindo a metodologia: adicionar resgate de pontos por cupom no Clube Hipermais.