Forem: Wescley Serrão Ribeiro Pinto

Como Construí um Sistema de Sustentação com IA para um Ecossistema Multi-Serviço usando Claude Code

Wescley Serrão Ribeiro Pinto — Fri, 17 Apr 2026 13:55:46 +0000

De horas de investigação manual em 8 repositórios à resolução automatizada de bugs em menos de 20 minutos.

O Problema

Se você já trabalhou em um produto que cresceu de um monolito para uma constelação de microsserviços, conhece a sensação: um bug é reportado e, antes mesmo de pensar em corrigi-lo, você precisa descobrir onde no ecossistema ele vive.

Um ecossistema multi-repo com 8 serviços independentes, cada um com sua própria stack, banco de dados e pipeline de deploy:

Regra central: o app mobile nunca chama microserviços diretamente — tudo passa pelo API Gateway (proxy pattern). Isso é ótimo para a arquitetura, mas significa que um único bug na ponta do usuário pode atravessar 3 ou 4 serviços.

Um cenário típico de sustentação costumava ser assim:

Bug chega: "usuário não consegue completar uma recarga de saldo"
É o app mobile? O API Gateway? O serviço de pagamentos? O processador de saldo? Um webhook de gateway de pagamento externo?
Abrir cada repo, navegar na estrutura de pastas, rastrear o fluxo, ler o código
Encontrar a causa raiz 45 minutos depois
Corrigir, mas quebrar acidentalmente o contrato com o próximo serviço downstream
Descobrir isso na sexta à tarde

Eu precisava de um sistema que fizesse o que um engenheiro sênior com conhecimento profundo do ecossistema faz — mas em minutos, não horas. E precisava ser confiável, não um autocomplete glorificado.

A Solução: Agentes de IA Especializados Orquestrados pelo Claude Code

Em vez de jogar uma IA de propósito geral no codebase e torcer pelo melhor, construí um sistema de sustentação estruturado em quatro camadas:

Codebase Maps — Documentação detalhada para cada serviço
Ecosystem Overview — Fluxos de integração entre todos os serviços
Agentes Especializados — Cada um com uma única responsabilidade
Skills & Convenções — Conhecimento reutilizável sobre os padrões de cada stack

Vou percorrer cada uma.

Camada 1: Codebase Maps

Essa é a fundação. Sem ela, nada mais funciona.

Para cada serviço, escrevi um documento dedicado que cobre:

Estrutura de pastas com o propósito de cada diretório
Arquivos-chave — os 10-20 arquivos onde 80% dos bugs vão ser encontrados
Padrões — quais design patterns o serviço usa (Strategy, Factory, Provider, etc.)
Pontos de integração — como ele conversa com outros serviços, como são os contratos
Mecanismo de auth — JWT, Keycloak, API tokens ou endpoints públicos
"Onde Procurar por Bugs" — uma seção curada mapeando categorias de sintomas a caminhos específicos de arquivos

Essa última seção é a mais valiosa. Em vez de dizer à IA "se vira", eu entrego os mesmos atalhos mentais que um desenvolvedor sênior constrói depois de meses no projeto.

Veja como uma seção "Onde Procurar por Bugs" se parece na prática:

### Onde Procurar por Bugs

| Sintoma | Comece Aqui |
|---------|-------------|
| Falhas de login | auth/strategies/, services/api.ts (interceptors) |
| Pagamento não finaliza | contexts/payment.tsx, services/api.ts (gateway instance) |
| Tela não carrega dados | screens/{feature}/, hooks/usePartnerFeatures.ts |
| Dados errados por tipo de usuário | utils/featureFlags.ts (check titular vs dependente) |
| Erros de agendamento | contexts/appointment.tsx, services/api.ts (appointment instance) |

Mantenho 6 codebase maps cobrindo todos os 8 serviços. Eles variam de 200 a 500 linhas cada — detalhados o suficiente para dar contexto real à IA, concisos o suficiente para caber em uma única leitura de janela de contexto.

Insight chave: esses documentos NÃO são gerados a partir do código. Eles capturam conhecimento que não está no código — o "porquê", as pegadinhas, o conhecimento tribal. Coisas como "esse endpoint de webhook não tem auth de propósito porque gateways de pagamento externos o chamam" ou "valores estão em centavos nesse serviço mas em reais nas APIs legadas — sempre dividir por 100".

Camada 2: Ecosystem Overview

Enquanto os codebase maps são profundos (verticais), o ecosystem overview é amplo (horizontal). Ele mapeia cada fluxo de integração de ponta a ponta.

Esse documento também contém tabelas de referência transversais:

Auth por serviço — qual tipo de token, qual mecanismo, quais roles
Bancos de dados — qual serviço é dono de quais tabelas
Filas SQS — FIFO vs Standard, produtor, consumidor, propósito
Serviços externos — gateways de pagamento, provedores de telemedicina, APIs de endereço
Glossário de conceitos-chave — os termos específicos do domínio que conectam tudo

O overview é carregado automaticamente em cada sessão de IA. Os codebase maps são carregados sob demanda quando um serviço específico precisa de investigação. Isso equilibra uso de contexto com profundidade de conhecimento.

Camada 3: Agentes Especializados

Aqui é onde fica interessante. Em vez de um agente de IA "faz tudo", construí quatro com separação estrita de papéis:

Bug Hunter (Apenas Análise)

Papel: Investigar a causa raiz. Nunca escrever código.

Como funciona:

Lê o ecosystem overview para entender qual fluxo de integração está envolvido
Identifica qual(is) serviço(s) são afetados
Lê o(s) codebase map(s) específico(s) — usa a seção "Onde Procurar por Bugs"
Navega até os arquivos-fonte reais para confirmar a hipótese
Produz um diagnóstico estruturado

Formato de saída:

- Serviço(s) afetado(s): [quais serviços]
- Fluxo impactado: [Login, Pagamento, Agendamento, etc.]
- Causa raiz provável: [descrição técnica]
- Arquivo(s) suspeito(s): [caminho exato + linha aproximada]
- Classificação: frontend | backend | integração
- Evidências: [trechos de código que confirmam a análise]
- Recomendação de fix: [o que precisa mudar, sem implementar]

Por que é read-only: Separar análise de implementação previne o modo de falha comum onde uma IA "corrige" um bug adicionando optional chaining em tudo sem entender por que o valor está null em primeiro lugar.

Dev Front (Implementação Frontend)

Papel: Implementar fixes no app mobile (React Native + Expo) e no dashboard admin (React + Refine).

Recebe o diagnóstico do Bug Hunter, lê o codebase map relevante, lê todos os arquivos que vai modificar antes de editar, implementa o fix mínimo e roda validação de TypeScript.

Conhece as convenções de cada frontend: Zustand para state persistido vs Context API para state de fluxo no app mobile, hooks do Refine com o data provider correto no dashboard admin, as 4 diferentes instâncias do Axios para grupos diferentes de serviços, etc.

Dev Back (Implementação Backend)

Papel: Implementar fixes em todos os 6 serviços backend.

Mesmo workflow do Dev Front, mas cobrindo Express.js (JavaScript legado, sem TypeScript), Hono com decorators e Prisma, AdonisJS com Lucid ORM, funções Lambda com SQS e endpoints serverless.

Ele respeita os padrões muito diferentes entre serviços: factory pattern com makeController() no API Gateway, roteamento baseado em decorators (@Route, @Get, @Guard) no serviço de agendamentos, soft-delete com deleted_at no serviço de pagamentos, checagens de idempotência no processador de saldo.

QA Reviewer (Apenas Validação)

Papel: Revisar o fix. Nunca escrever código. Máximo 3 ciclos de revisão por bug.

Esse é o agente mais importante. Ele executa um checklist estruturado:

Corretude:

O fix endereça a causa raiz (não apenas o sintoma)?
Há edge cases não cobertos?
Funciona para ambos os tipos de usuário? (nosso sistema distingue entre titulares primários e dependentes com conjuntos de features diferentes)

Regressões:

Arquivos relacionados foram impactados negativamente?
O contrato de request/response da API foi preservado?
O middleware de auth está intacto?

Caça a Silent Failures (esse é o diferencial):

Catch blocks adicionados: têm logging E feedback ao usuário?
Fallbacks adicionados: são explícitos com logging quando ativados?
Condicionais adicionadas: o branch else trata a falha?
Optional chaining adicionado: resolve o crash mas esconde a causa raiz?

Cada achado é classificado:

✅ Fix correto, sem novas silent failures
⚠️ Correto mas frágil (não bloqueante)
❌ Fix introduz silent failure (BLOQUEANTE — volta para o dev)

Por que o agente de QA importa mais: Sem ele, os agentes dev tendem a produzir fixes "tecnicamente funcionam" que mascaram problemas. Um catch block sem logging? O erro some silenciosamente. Optional chaining em um valor que nunca deveria ser null? Você escondeu um problema de dados. O agente de QA pega esses padrões sistematicamente.

Camada 4: Skills & Convenções

Skills são módulos de conhecimento reutilizáveis que os agentes consultam proativamente. Tenho três:

Ecosystem Knowledge: Referência rápida para mapeamento de serviços, fluxos de integração e conceitos de domínio. Cada agente carrega essa primeiro.

Frontend Conventions: Padrões para cada frontend — como estruturar componentes, qual abordagem de state management usar, como lidar com chamadas de API, anti-patterns a evitar.

Backend Conventions: Padrões específicos por stack — como escrever rotas em cada framework, convenções de ORM, posicionamento de middleware de auth, padrões de formato de resposta.

Essas skills previnem que os agentes "reinventem" padrões a cada bug. Em vez de adivinhar como adicionar uma nova rota no serviço de agendamentos, o agente dev sabe usar decorators @Route + @Get + @Guard('ROLE') porque a skill de convenções diz isso.

O Pipeline em Ação

Veja o que acontece quando um bug é reportado:

Reporte de bug → Bug Hunter (2-3 min)
                    ↓ diagnóstico
               Dev Front e/ou Dev Back (3-5 min)
                    ↓ fix implementado
               QA Reviewer (1-2 min)
                    ↓
               APROVADO → pronto
               REPROVADO → volta para o Dev (máx 3 ciclos)

Tempo total para um ciclo completo: menos de 10 minutos.

Vou percorrer um exemplo real (anonimizado):

Reporte de bug: "Usuários do plano tipo B não conseguem ver a tela de recarga de saldo"

Análise do Bug Hunter (2 minutos):

Identificou a checagem de feature flag do app mobile: estava lendo partner.features para todos os usuários, mas usuários do plano tipo B são dependentes que precisam de partner.dependent_features
Rastreou o fluxo: o componente da tela chamava checkIsEnabledFeature('reload'), que internamente consultava o conjunto errado de features para usuários dependentes
Classificado como: frontend — o backend estava retornando dados corretos, o app mobile estava lendo o campo errado
Apontou: utils/featureFlags.ts:47 e screens/Payment/Reload/index.tsx:23

Fix do Dev Front (3 minutos):

Leu ambos os arquivos + o contexto que fornece a flag do tipo de usuário
Modificou o utilitário de checagem de feature para ramificar em isDependent
Rodou tsc --noEmit — passou
Reportou o fix com diff exato

Revisão do QA (1 minuto):

Confirmou: fix endereça a causa raiz, não o sintoma
Confirmou: funciona para titulares E dependentes
Confirmou: nenhuma silent failure introduzida (sem catch blocks, sem optional chaining — branch condicional limpo)
Resultado: APROVADO

Antes desse sistema, esse bug teria levado 30-60 minutos de investigação manual em múltiplos repos, mais tempo de revisão.

Os Guardrails

IA autônoma escrevendo código no seu codebase precisa de redes de segurança. Eis o que coloquei em prática:

Hooks de proteção de arquivos: Certos arquivos são bloqueados para edição por IA — configs de ambiente, Docker Compose, schemas de banco. Esses arquivos requerem mãos humanas.

Nenhuma operação destrutiva: Agentes nunca podem fazer git push, git reset --hard ou disparar deploys. Eles trabalham localmente, e um humano revisa antes de qualquer coisa chegar em um branch remoto.

Princípio do fix mínimo: As diretrizes de dev declaram explicitamente: "fix mínimo — não refatore código adjacente, não adicione comentários desnecessários." Isso previne scope creep onde a IA "melhora" código que funciona e introduz regressões.

Validação mandatória: Todo fix precisa passar pela compilação de TypeScript (tsc --noEmit) antes do agente dev considerá-lo feito. A única exceção é o API Gateway legado em JavaScript.

Output estruturado: Cada agente produz saída em um formato mandatório. O Bug Hunter deve fornecer classificação e evidências. Os agentes Dev devem documentar serviços impactados. O agente de QA deve rodar o checklist completo. Sem mão-de-obra.

O Que Aprendi

1. A qualidade da documentação é o multiplicador

Gastei mais tempo escrevendo codebase maps do que configurando agentes. Esse investimento se paga todos os dias. Um mapa de serviço bem documentado com seções "Onde Procurar por Bugs" dá à IA a mesma intuição que um desenvolvedor sênior tem — sem os meses de construção de contexto.

Se sua ferramenta de IA para codar está produzindo resultados genéricos ou errados, o problema quase certamente é contexto, não o modelo.

2. Separação de responsabilidades se aplica a agentes de IA também

Um agente que analisa, implementa E revisa o próprio trabalho é como um desenvolvedor que escreve código, revisa o próprio PR e faz deploy para produção. O loop de feedback é apertado demais, e os erros se acumulam.

O Bug Hunter não pode mascarar uma causa raiz escrevendo um fix rápido. Os agentes Dev não podem aprovar o próprio trabalho. O agente de QA não pode ajustar silenciosamente o código em vez de sinalizar um problema. Cada restrição torna o sistema geral mais confiável.

3. O agente de QA é a peça mais valiosa

Sem caça explícita a silent failures, fixes gerados por IA tendem a padrões "fazer o erro sumir": catch blocks vazios, optional chaining generalizado, valores default que escondem problemas de dados. O checklist estruturado do agente de QA pega exatamente esses padrões.

O sistema de classificação (correto / frágil / introduz silent failure) força julgamento explícito em vez de "parece bom pra mim".

4. Skills previnem deriva de padrões

Sem documentos de convenções reutilizáveis, cada fix de bug reinventa como as coisas deveriam ser estruturadas. O agente dev pode usar um padrão de state management diferente do que existe no codebase, ou adicionar uma rota em um estilo que não casa com as convenções do serviço.

Skills ancoram os agentes aos padrões reais do projeto, não aos padrões de treinamento do modelo.

5. O mapa do ecossistema importa mais que os docs de serviço individuais

Bugs cross-service são os mais difíceis. Saber que valores estão em centavos no serviço de pagamentos mas em reais nas APIs legadas, que webhooks de gateways externos intencionalmente não têm auth, que o processador de saldo checa histórico de transações para idempotência antes de creditar — essas são as pegadinhas que causam investigações de 2 horas.

O ecosystem overview captura esse conhecimento de integração em um só lugar. Sem ele, agentes podem "corrigir" um bug adicionando auth em um webhook que sistemas externos chamam, quebrando o fluxo de pagamento inteiro.

6. O limite de 3 ciclos no QA previne loops infinitos

Sem ele, o agente de QA e o agente dev podem ficar em ping-pong: QA reprova, dev corrige, QA encontra um novo problema no fix, dev corrige, QA encontra outro. Três ciclos é o ponto certo — se um fix não consegue passar em revisão em 3 tentativas, precisa de atenção humana.

O Setup em Números

Métrica	Valor
Serviços cobertos	8
Codebase maps	6 documentos (200-500 linhas cada)
Fluxos de integração documentados	7 fluxos ponta a ponta
Agentes especializados	4 (análise, frontend, backend, QA)
Skills reutilizáveis	3 (ecosystem, frontend, backend conventions)
Análise média de causa raiz	5-10 minutos
Implementação média de fix	2-8 minutos
Revisão média de QA	1-2 minutos
Ciclo completo (análise → fix → aprovado)	< 20 minutos
Tempo anterior de investigação manual	30-90 minutos

Como Replicar Isso

Se você está lidando com um ecossistema multi-serviço similar e quer construir algo assim:

Comece pela documentação, não pelos agentes. Escreva codebase maps para seus serviços mais críticos primeiro. Inclua a seção "Onde Procurar por Bugs" — é a peça de documentação de maior ROI que você já vai escrever.

Mapeie seus fluxos de integração. Mesmo antes da IA entrar em cena, ter um único documento que rastreia dados através dos serviços economiza um tempo enorme de investigação para desenvolvedores humanos também.

Separe análise de implementação. Mesmo que você construa apenas dois agentes, faça um que seja read-only e outro que escreve. O analista read-only produz diagnósticos melhores porque não pode encurtar a investigação pulando para um fix.

Invista na camada de QA. Caça a silent failures é o diferencial entre "IA que produz código" e "IA que produz código confiável". Construa um checklist específico para os padrões comuns de falha do seu codebase.

Codifique suas convenções. Se seu time tem regras não escritas sobre como estruturar código em cada serviço, escreva-as. Elas se tornam as skills que mantêm a saída da IA consistente com seus padrões existentes.

Estabeleça limites rígidos. Arquivos protegidos, nenhuma operação git destrutiva, validação TypeScript mandatória, formatos de output estruturados. Esses guardrails não são opcionais — são o que torna o sistema confiável o suficiente para uso diário.

Considerações Finais

Isso não é sobre substituir desenvolvedores. É sobre construir um sistema que lida com o overhead investigativo de ecossistemas multi-serviço — o context-switching entre repos, o rastreamento de fluxos de dados através de fronteiras, a caça por causas raiz em codebases desconhecidos.

A IA não precisa ser perfeita. Precisa ser estruturada, restrita e revisável. Quatro agentes especializados com limites claros produzem resultados dramaticamente melhores do que um agente de propósito geral com escopo ilimitado.

O trabalho real estava na documentação e no design do sistema, não em prompt engineering. Se o conhecimento do seu ecossistema vive apenas na cabeça das pessoas, comece a escrever. Esse é o pré-requisito — tudo o mais constrói em cima disso.

Construído com Claude Code. As definições de agente, skills, codebase maps e pipeline descritos nesse artigo são todos configurados usando os recursos nativos do Claude Code: agentes customizados, skills, rules e hooks.

Como estou reestruturando um ecossistema inteiro de aplicações com agentes de IA especializados, Spec-Driven Development e TDD automatizado.

Wescley Serrão Ribeiro Pinto — Tue, 07 Apr 2026 11:55:12 +0000

A algum tempo comecei a analisar o ecossistema que eu e minha equipe trabalhamos no dia a dia e os problemas que enfrentávamos por falta de uma arquitetura coesa e eficiente. Redesenhei o ecossistema cobrindo várias das necessidades e escala que os serviços precisavam, e era o mundo ideal que precisávamos, mas então como tirar do papel?

Como conciliar sprints e reestruturação? talvez mais devs? Mas e a rampagem desses devs novos? Talvez separar alguns devs existentes e começar um longo trabalho, talvez até um ano para isso. Esse tipo de trabalho de longo prazo muitas vezes não convence ou cabe em negócio que já está funcionando/faturando.

Como já estava trabalhando com o Claude Code (Commands, subagentes, skills, plugins e guidelines) e workflows no cotidiano de desenvolvimento, pensei como estruturar um setup para os agentes possam entender as features do legado, compreender a nova arquitetura e serviços e então desenvolver a reestruturação que precisamos em um tempo interessante e com qualidade.

Nos últimos meses, venho construindo um setup de orquestração com Claude Code que transformou a maneira como migramos e desenvolvemos features no ecossistema.

🎯 O Desafio e a Solução

O desafio: migrar um app (React Native) legado (130+ telas, 65+ endpoints, ~7000 LOC de lógica de negócio (Back-end) em JavaScript puro) para uma arquitetura moderna — e fazer isso com qualidade, rastreabilidade e testes obrigatórios em cada etapa.

A solução: utilização de SDD (Spec-Driven Development), TDD (MCP's: Playwright e Maestro), agentes especializados colaboram em um pipeline estruturado, cada um com responsabilidade única, skills de domínio e guardrails rígidos.

A ideia principal é ter um workflow de trabalho onde um agente especializado (readonly) munido com docs (legacy-knowledge), conhecendo assim o legado, a partir disso traga os insights para um outra agente especializado em escrever docs para SDD (Opus - raciocínio profundo) munidos de docs para a nova arquitetura e novos serviços, produzindo assim documento eficientes e assertivos. O trabalho a seguir fica mais “fácil”, uma equipe de agentes que vai primeiro escrever testes, desenvolvimento (subagentes por domínio) que devem passar no teste, revisores de código, por fim revisão humana e aprovação funcional por QA humano.

Vamos ao detalhes...

Diagram do Workflow

🏗️ Nova arquitetura em um Monorepo

Trabalhamos em um Monorepo para features inteiras de back e front utilizando Turborepo + pnpm workspaces:

@mobile — App cliente multiplataforma (Expo SDK 54 + Gluestack UI V3 + Zustand) — Web, Android, iOS
@api — BFF principal (NestJS + Prisma + Zod)
@backoffice — Painel administrativo (React + Vite + shadcn/ui + TanStack)
@backoffice-api — BFF do backoffice (Serverless + Hono.js + Zod OpenAPI)

Packages compartilhados:

@types — Entidades de domínio (interfaces TypeScript)
@contracts — Schemas Zod e DTOs (contratos de API)
@utils — Funções utilitárias

Regra de ouro: tipos vivem em @types, contratos em @contracts. Nunca duplicar entre apps.

🚀 O Pipeline em Detalhes

FASE 1 — O Discovery do Legado

Tudo começa com o comando /spec-write --legacy [descrição da feature].

A flag --legacy ativa o agente Legacy Discoverer — um especialista read-only em engenharia reversa que analisa dois repositórios legados:

Frontend legado: 130+ telas, Context API, 4 instâncias Axios diferentes, Design system próprio, tipos em src/@types/, helpers, enums, hooks.
Backend legado: 41 classes JavaScript agregadas via Object.assign (~7000 LOC) no Domain, 65+ endpoints em um único arquivo de rotas de 1383 linhas, Auth via JWT middleware, Queries Knex em 3 databases.

O Legacy Discoverer executa em 5 fases:

Absorve contexto — lê a skill legacy-knowledge, que contém: glossário de domínio, code hints, overview do projeto e mapa completo dos 65+ endpoints.
Identifica escopo — busca telas, contextos, tipos, enums, API calls no frontend E endpoints, handlers, services, repositories no backend via Glob/Grep.
Traça code flows completos — da tela até o banco de dados: Tela → Context/Hook → API Service → Endpoint backend → Handler do Domain → Repository → Response → UI.
Mapeia para o monorepo — cada item legado recebe um destino: Context API → Zustand store, Screen → apps/platform/, Domain handler → apps/api/, etc.
Gera o Legacy Discovery Report — documento estruturado com todo o diagnóstico e mapeamento para o spec-writer.

FASE 2 — Especificação com Spec Writer (Modelo Opus)

O Legacy Discovery Report é passado para o agente Spec Writer (Modelo Opus), que executa em 7 fases e produz documentos em 2 etapas com aprovação humana:

Etapa 1 — spec.md (Negocio):

Gera o documento de NEGÓCIO após absorver as skills project-brain e integration-contracts. Contém:

Objetivo, Personas, Regras de negócio numeradas e testáveis.
Cenários de aceitação BDD (Given/When/Then).
Mapeamento de migração do legado e decisões pendentes [DECISÃO NECESSÁRIA].

Quality Gate — Spec Reviewer: Valida a spec contra 9 checks (S1-S9): linguagem de negócio pura, regras testáveis, cenários BDD completos, etc. Se houver issues ALTA, o Spec Writer corrige antes da aprovação humana.

Etapa 2 — plan-{stack}.md (Técnico):

Gera planos autocontidos para cada stack (NestJS, Expo, Hono, React, Packages) com:

Decisões arquiteturais justificadas.
Design de componentes e fluxo de dados end-to-end.
Anti-patterns ("NÃO FAZER") e especificações de testes unitários (min 3/service, 2/entity, 2/componente).
Gera o tasks.md (checklist de implementação).

Quality Gate — Spec Reviewer (modo PLAN): Valida cada plan contra 13 checks (P1-P13) e 6 checks de consistência cross-documento (X1-X6).

FASE 3 — Implementação com TDD Automatizado

O comando /run-feature FEAT-XXX coordena agentes especializados:

Setup: Cria branch e worktree isolado (.worktrees/).
Contracts/Types primeiro: Regra: contratos ANTES de backend, backend ANTES de frontend.
Backend TDD (Red → Green → Review → Verify):
- Red: O Backend Test Writer escreve testes que DEVEM falhar.
- Green: O agente dev especializado (API Dev ou Serverless Dev) implementa até ficar verde.
- Review: O Backend Reviewer analisa aderência, TypeScript estrito e performance.
- Verify: O Test Runner garante servidor rodando e executa unit tests + funcionais via curl.
Frontend TDD: Mesma lógica com Playwright (web) e Maestro via MCP (mobile).

FASE 4 — Validação Humana e Commits

Nenhum commit acontece antes da validação humana.

Builds: Verifica compilação e type-check global.
Apresentação: Lista mudanças com diff, resultados de testes e status dos builds.
Aprovação: Aprovar (commitar), revisar (indicar correções) ou cancelar (zero commits).
Learnings: Aprendizagens extraídas para o futuro.

🤖 O Ecossistema de Agentes

No total, são 14 agentes especializados coordenados:

Agente	Modelo	Função	Read-only?
Legacy Discoverer	Sonnet	Engenharia reversa do app legado	Sim
Spec Writer	Opus	Decisões arquiteturais e specs	Sim
Spec Reviewer	Sonnet	Quality gate de specs e plans	Sim
Backend Test Writer	Sonnet	Red phase TDD backend	Não
Frontend Test Writer	Sonnet	Red phase TDD frontend	Não
API Dev	Sonnet	NestJS + Prisma + Zod	Não
Serverless Dev	Sonnet	Hono.js + Zod OpenAPI	Não
Platform Dev	Sonnet	Expo + Gluestack + Zustand	Não
Backoffice Dev	Sonnet	React + shadcn/ui + TanStack	Não
Backend Reviewer	Sonnet	Revisão de código backend	Sim
Frontend Reviewer	Sonnet	Revisão de código frontend	Sim
Test Runner	Sonnet	Execução de testes (unit + E2E)	Sim
Validation Gate	Sonnet	Builds, typechecks, contratos	Sim
QA Reviewer	Sonnet	Valida fixes de bugs	Sim

Skills e Workflows

6 Skills de domínio: project-brain, legacy-knowledge, integration-contracts, backend-conventions, frontend-conventions e learnings.
5 Commands/Workflows: /spec-write, /run-feature, /validate, /health-check, /jira.
7 Rules: Garantem consistência de style e patterns.

💡 O que muda na prática?

Rastreabilidade total: Cada decisão é documentada e justificada.
Testes obrigatórios: Red phase ANTES da implementação.
Conhecimento persistente: Skills acumulam o domínio e evitam repetir erros.
Humano no controle: Aprovação da spec, do plano e do código — zero commits automáticos.

Não é sobre substituir desenvolvedores por IA. É sobre criar um sistema onde agentes especializados lidam com o trabalho repetitivo e cognitivamente caro enquanto humanos focam no que importa: decisões de negócio, arquitetura e validação final.

O código continua sendo responsabilidade humana. Os agentes são ferramentas — ferramentas muito boas, com contexto, guardrails e accountability.