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-conventionselearnings. - 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.
Top comments (0)