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.

DEV Community: Wescley Serrão Ribeiro Pinto