Spikes, PoCs & Nova Arquitetura

Q: Spike teve sucesso - podemos fazer merge na sexta-feira?

Apenas com ADR, flag desativada por padrão, evidência normal no template de PR, e sem hacks apenas de spike deixados em app.config.ts. Caso contrário, agende um sprint de PoC.

Q: Quem aprova o merge do spike brownfield no repositório host?

Líder da plataforma nativa + líder mobile + proprietário da CI. A aprovação apenas de RN é insuficiente - o binário do host é enviado para as lojas.

Q: Spike da Nova Arquitetura falhou - devemos bloquear o SDK 57?

Não - documente o plano de substituição do módulo. O SDK 57 / RN 0.86 ainda será lançado; o módulo falho receberá uma linha de EOL no registro e um cronograma de troca.

Um guia para avaliar Expo UI, integração brownfield e flags experimentais com segurança - branches com tempo limitado, critérios de sucesso claros e resultados de ADR para que a exploração não se torne dívida de produção permanente.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Bootstrap de Spike (nunca em main)
git checkout main && git pull --ff-only
git worktree add ../MyApp-spike-ui spike/expo-ui-tabs
cd ../MyApp-spike-ui
EXPO_PACKAGER_PORT=8082 npx expo start

# docs/spikes/TEMPLATE.md - copiar por spike
## Spike: <nome>
- **Responsável:** @engenheiro(a)
- **Tempo limite:** 3 dias (parada rígida)
- **Hipótese:** <o que aprendemos>
- **Critérios de sucesso:** <mensurável>
- **Fora do escopo:** merge em produção, aprovação de performance, auditoria de a11y
- **Resultado:** ADOTAR | ADIAR | REJEITAR + link para ADR

Ciclo de vida do Spike
  charter (30 min) → branch → tempo limite → demo → ADR → deletar branch
                              ↓
                    nunca fazer merge sem ADR + flags + matriz de QA

Quando usar isso:

Avaliando Expo UI (interoperabilidade SwiftUI/Jetpack Compose) para uma nova classe de tela.
Viabilidade de integração Brownfield antes que a equipe nativa confirme alterações de CI.
Validação da Nova Arquitetura após adicionar um módulo nativo apenas com bridge.
APIs Experimentais app.config.ts ou Expo Router marcadas como instáveis na documentação.
Liderança pede PoC "neste sprint" sem critérios de sucesso - charter primeiro.

Quando evitar:

Correção de bug de produção - use branch fix/*, não spike/*.
Padrão já adotado (rotas de arquivo do Expo Router) - envie em branch de funcionalidade com QA normal.
Reavaliar ADR decidido sem novas restrições - leia docs/adr/ primeiro.

Exemplo de Trabalho A - Spike de Expo UI

Avaliar se os componentes Expo UI podem substituir um chrome de abas nativo personalizado para layouts de tablet.

Passo 1 - Charter (antes do código)

## Spike: expo-ui-tablet-tabs
- **Tempo limite:** 3 dias
- **Hipótese:** Primitivos de aba do Expo UI reduzem PRs nativos para visualização dividida do iPad
- **Sucesso:** Troca de aba < 100ms no iPad 10ª geração; tipos TypeScript compilam SDK 57
- **Falha:** Crash na API 26 do Android ou requer edição manual de ios/ fora do CNG
- **Documento de resultado:** docs/adr/0012-expo-ui-tabs.md

Passo 2 - Branch isolado + flag

// src/shared/config/featureFlags.ts
export const flags = {
  expoUiTabs: __DEV__ && process.env.EXPO_PUBLIC_SPIKE_EXPO_UI === "1",
};

EXPO_PUBLIC_SPIKE_EXPO_UI=1 EXPO_PACKAGER_PORT=8082 npx expo start

Nunca habilite flags de spike no perfil EAS de production
Emparelhe com Regras de Navegação e Roteamento - um proprietário de navegador

Passo 3 - Matriz de validação

Verificação	Comando / ação
Doutor	`npx expo-doctor`
Tipos	`npx tsc --noEmit`
Performance similar a release	`eas build --profile preview` + Flashlight
Layout de tablet	iPad físico ou tamanhos de captura de tela ASC
Paridade Android	Dispositivo API 26 - não apenas emulador

Passo 4 - ADR de resultado

# ADR 0012: Expo UI para abas de tablet - ADIAR
- **Motivo:** Lacunas de paridade Android; equipe carece de revisor SwiftUI
- **Revisitar:** SDK 58 ou quando Expo UI atingir o status estável no changelog
- **Branch deletado:** spike/expo-ui-tabs

ADIAR é válido - link para lembrete de calendário em Rastreamento de Depreciação e EOL
ADOTAR requer plano de rollout de flag de funcionalidade - Flags de Funcionalidade para Rollout Seguro

Exemplo de Trabalho B - PoC de Integração Brownfield

Provar que o artefato expo-brownfield carrega no host nativo existente sem Node na CI do host.

Passo 1 - Layout de spike de dois repositórios

rn-checkout/          # Repositório do módulo Expo (branch de spike)
  expo-brownfield build → AAR + XCFramework
host-ios-android/     # Host nativo (branch spike/brownfield-checkout)
  consome artefato v0.0.1-spike.1

# Repositório RN
npx create-expo-app@latest CheckoutRn --template blank-typescript@sdk-57
npx expo install expo-brownfield
# construir artefatos conforme documentação do expo-brownfield

Siga Noções Básicas de Brownfield - decisão isolado vs integrado primeiro
PoC não faz merge no main do host até que a CI publique artefatos automaticamente - Brownfield CI/CD

Passo 2 - Critérios de sucesso

- [ ] Host inicia tela de checkout RN a partir de botão nativo
- [ ] Inicialização a frio da superfície RN < 2s no Android de nível médio
- [ ] Navegação de volta retorna ao nativo sem vazamento (Instruments / LeakCanary)
- [ ] Token de autenticação passado via contrato de bridge v1 - documentar em ADR
- [ ] Nenhuma cópia manual do bundle JS nos assets do host

Passo 3 - Versão do contrato da bridge

// Documentar em ADR - host e RN devem incrementar juntos
export const BRIDGE_CONTRACT_VERSION = "1.0.0-spike";

Relacionado: Autenticação Compartilhada e Bridges

Exemplo de Trabalho C - Validação da Nova Arquitetura

Módulo de câmera de terceiros afirma suporte a NA - validar antes do lançamento na loja.

Passo 1 - Habilitar NA apenas no spike

git checkout -b spike/new-arch-camera
npx expo prebuild --clean

// app.config.ts - spike documenta explicitamente NA (SDK 57 greenfield pode ter true por padrão)
export default {
  expo: {
    plugins: ["expo-camera", "expo-build-properties"],
  },
};

Passo 2 - Matriz de build (obrigatório)

npx expo-doctor
eas build --profile preview --platform ios
eas build --profile preview --platform android

Teste	Critérios de aprovação
Abrir câmera	Sem redbox no build NA
Tirar foto	URI do arquivo retornado
Background / Resume	Sem crash
Pontuação do Flashlight	Sem regressão vs linha de base da Arquitetura Antiga

Expo Go é inválido para prova de NA - cliente de desenvolvimento personalizado ou preview EAS
Se falhar: linha de registro em Rastreamento de Depreciação e EOL; avaliar módulo alternativo

Passo 3 - Critérios de merge se ADOTAR

- [ ] ADR: Nova Arquitetura habilitada em todo o projeto
- [ ] Todos os módulos nativos compatíveis com NA ou substituídos
- [ ] Matriz de build de produção eas verde
- [ ] 72h sem crash no canal de preview

Flags e Configurações Experimentais

Superfície	Padrão de spike seguro	Regra de produção
Toggles de spike `EXPO_PUBLIC_*`	Apenas `.env.local`	Nunca no ambiente de produção EAS
`experiments` na configuração do app	branch de spike	Remover ou ADR antes do merge
API instável do Expo Router	`spike/*`	Fixar na versão documentada da API
Experimental do React 19	Corresponder ao template SDK 57	Sem substituição manual de canário

// ❌ Nunca fazer merge para main sem ADR
export default {
  expo: {
    experiments: {
      // typedRoutes, reactCompiler, etc. - apenas spike até estabilizar
    },
  },
};

Leia a seção Experimental do changelog do Expo a cada atualização de SDK
Lista de Verificação de Regras do Projeto Expo - fonte da verdade da configuração em app.config.ts

Regras de Governança de Spikes

Regra	Racional
Máximo de 5 spikes ativos por squad	Diluição de foco
Tempo limite rígido (padrão 3–5 dias)	Spikes se expandem para preencher o sprint
Demo no dia N - mesmo que falhe	Força a articulação do aprendizado
Sem código de spike no branch de release	Veneno de cherry-pick
ADR para ADOTAR, ADIAR, REJEITAR	Memória institucional
Deletar branch após resultado	Evita merge acidental meses depois

# Após REJEITAR - deletar worktree
git worktree remove ../MyApp-spike-ui
git branch -D spike/expo-ui-tabs

PoC vs Spike vs Piloto de Produção

Tipo	Duração	Enviado para usuários?	Documento
Spike	3–5 dias	Não	ADR curto
PoC	1–2 sprints	Apenas TestFlight interno / trilha interna	ADR + plano de teste
Piloto	1 release	Marcado 1–5% em produção	QA completo + runbook de rollback

Caminho de promoção: Spike → ADR → PoC → Piloto → GA - pular etapas requer aprovação do EM + plataforma.

FAQs

Spike teve sucesso - podemos fazer merge na sexta-feira?

Apenas com ADR, flag desativada por padrão, evidência normal no template de PR, e sem hacks apenas de spike deixados em app.config.ts. Caso contrário, agende um sprint de PoC.

Quem aprova o merge do spike brownfield no repositório host?

Líder da plataforma nativa + líder mobile + proprietário da CI. A aprovação apenas de RN é insuficiente - o binário do host é enviado para as lojas.

Spike da Nova Arquitetura falhou - devemos bloquear o SDK 57?

Não - documente o plano de substituição do módulo. O SDK 57 / RN 0.86 ainda será lançado; o módulo falho receberá uma linha de EOL no registro e um cronograma de troca.

Relacionados

Noções Básicas de Brownfield - integrar vs reescrever
ADR de Adoção Incremental - padrão strangler
Política de Upgrade de SDK - spikes de upgrade
Registros de Decisão de Arquitetura - formato ADR
Rebase Interativo & Worktrees - trabalho paralelo de spike
Melhores Práticas de Governança - resumo da política de spike

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0, e Expo SDK 57 (expo ~57.0.4).

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Bootstrap de Spike (nunca em main)
git checkout main && git pull --ff-only
git worktree add ../MyApp-spike-ui spike/expo-ui-tabs
cd ../MyApp-spike-ui
EXPO_PACKAGER_PORT=8082 npx expo start

# docs/spikes/TEMPLATE.md - copiar por spike
## Spike: <nome>
- **Responsável:** @engenheiro(a)
- **Tempo limite:** 3 dias (parada rígida)
- **Hipótese:** <o que aprendemos>
- **Critérios de sucesso:** <mensurável>
- **Fora do escopo:** merge em produção, aprovação de performance, auditoria de a11y
- **Resultado:** ADOTAR | ADIAR | REJEITAR + link para ADR

Ciclo de vida do Spike
  charter (30 min) → branch → tempo limite → demo → ADR → deletar branch
                              ↓
                    nunca fazer merge sem ADR + flags + matriz de QA

Quando usar isso:

Avaliando Expo UI (interoperabilidade SwiftUI/Jetpack Compose) para uma nova classe de tela.
Viabilidade de integração Brownfield antes que a equipe nativa confirme alterações de CI.
Validação da Nova Arquitetura após adicionar um módulo nativo apenas com bridge.
APIs Experimentais app.config.ts ou Expo Router marcadas como instáveis na documentação.
Liderança pede PoC "neste sprint" sem critérios de sucesso - charter primeiro.

Quando evitar:

Correção de bug de produção - use branch fix/*, não spike/*.
Padrão já adotado (rotas de arquivo do Expo Router) - envie em branch de funcionalidade com QA normal.
Reavaliar ADR decidido sem novas restrições - leia docs/adr/ primeiro.

Exemplo de Trabalho A - Spike de Expo UI

Avaliar se os componentes Expo UI podem substituir um chrome de abas nativo personalizado para layouts de tablet.

Passo 1 - Charter (antes do código)

## Spike: expo-ui-tablet-tabs
- **Tempo limite:** 3 dias
- **Hipótese:** Primitivos de aba do Expo UI reduzem PRs nativos para visualização dividida do iPad
- **Sucesso:** Troca de aba < 100ms no iPad 10ª geração; tipos TypeScript compilam SDK 57
- **Falha:** Crash na API 26 do Android ou requer edição manual de ios/ fora do CNG
- **Documento de resultado:** docs/adr/0012-expo-ui-tabs.md

Passo 2 - Branch isolado + flag

// src/shared/config/featureFlags.ts
export const flags = {
  expoUiTabs: __DEV__ && process.env.EXPO_PUBLIC_SPIKE_EXPO_UI === "1",
};

EXPO_PUBLIC_SPIKE_EXPO_UI=1 EXPO_PACKAGER_PORT=8082 npx expo start

Nunca habilite flags de spike no perfil EAS de production
Emparelhe com Regras de Navegação e Roteamento - um proprietário de navegador

Passo 3 - Matriz de validação

Verificação	Comando / ação
Doutor	`npx expo-doctor`
Tipos	`npx tsc --noEmit`
Performance similar a release	`eas build --profile preview` + Flashlight
Layout de tablet	iPad físico ou tamanhos de captura de tela ASC
Paridade Android	Dispositivo API 26 - não apenas emulador

Passo 4 - ADR de resultado

# ADR 0012: Expo UI para abas de tablet - ADIAR
- **Motivo:** Lacunas de paridade Android; equipe carece de revisor SwiftUI
- **Revisitar:** SDK 58 ou quando Expo UI atingir o status estável no changelog
- **Branch deletado:** spike/expo-ui-tabs

ADIAR é válido - link para lembrete de calendário em Rastreamento de Depreciação e EOL
ADOTAR requer plano de rollout de flag de funcionalidade - Flags de Funcionalidade para Rollout Seguro

Exemplo de Trabalho B - PoC de Integração Brownfield

Provar que o artefato expo-brownfield carrega no host nativo existente sem Node na CI do host.

Passo 1 - Layout de spike de dois repositórios

rn-checkout/          # Repositório do módulo Expo (branch de spike)
  expo-brownfield build → AAR + XCFramework
host-ios-android/     # Host nativo (branch spike/brownfield-checkout)
  consome artefato v0.0.1-spike.1

# Repositório RN
npx create-expo-app@latest CheckoutRn --template blank-typescript@sdk-57
npx expo install expo-brownfield
# construir artefatos conforme documentação do expo-brownfield

Siga Noções Básicas de Brownfield - decisão isolado vs integrado primeiro
PoC não faz merge no main do host até que a CI publique artefatos automaticamente - Brownfield CI/CD

Passo 2 - Critérios de sucesso

- [ ] Host inicia tela de checkout RN a partir de botão nativo
- [ ] Inicialização a frio da superfície RN < 2s no Android de nível médio
- [ ] Navegação de volta retorna ao nativo sem vazamento (Instruments / LeakCanary)
- [ ] Token de autenticação passado via contrato de bridge v1 - documentar em ADR
- [ ] Nenhuma cópia manual do bundle JS nos assets do host

Passo 3 - Versão do contrato da bridge

// Documentar em ADR - host e RN devem incrementar juntos
export const BRIDGE_CONTRACT_VERSION = "1.0.0-spike";

Relacionado: Autenticação Compartilhada e Bridges

Exemplo de Trabalho C - Validação da Nova Arquitetura

Módulo de câmera de terceiros afirma suporte a NA - validar antes do lançamento na loja.

Passo 1 - Habilitar NA apenas no spike

git checkout -b spike/new-arch-camera
npx expo prebuild --clean

// app.config.ts - spike documenta explicitamente NA (SDK 57 greenfield pode ter true por padrão)
export default {
  expo: {
    plugins: ["expo-camera", "expo-build-properties"],
  },
};

Passo 2 - Matriz de build (obrigatório)

npx expo-doctor
eas build --profile preview --platform ios
eas build --profile preview --platform android

Teste	Critérios de aprovação
Abrir câmera	Sem redbox no build NA
Tirar foto	URI do arquivo retornado
Background / Resume	Sem crash
Pontuação do Flashlight	Sem regressão vs linha de base da Arquitetura Antiga

Expo Go é inválido para prova de NA - cliente de desenvolvimento personalizado ou preview EAS
Se falhar: linha de registro em Rastreamento de Depreciação e EOL; avaliar módulo alternativo

Passo 3 - Critérios de merge se ADOTAR

- [ ] ADR: Nova Arquitetura habilitada em todo o projeto
- [ ] Todos os módulos nativos compatíveis com NA ou substituídos
- [ ] Matriz de build de produção eas verde
- [ ] 72h sem crash no canal de preview

Flags e Configurações Experimentais

Superfície	Padrão de spike seguro	Regra de produção
Toggles de spike `EXPO_PUBLIC_*`	Apenas `.env.local`	Nunca no ambiente de produção EAS
`experiments` na configuração do app	branch de spike	Remover ou ADR antes do merge
API instável do Expo Router	`spike/*`	Fixar na versão documentada da API
Experimental do React 19	Corresponder ao template SDK 57	Sem substituição manual de canário

// ❌ Nunca fazer merge para main sem ADR
export default {
  expo: {
    experiments: {
      // typedRoutes, reactCompiler, etc. - apenas spike até estabilizar
    },
  },
};

Leia a seção Experimental do changelog do Expo a cada atualização de SDK
Lista de Verificação de Regras do Projeto Expo - fonte da verdade da configuração em app.config.ts

Regras de Governança de Spikes

Regra	Racional
Máximo de 5 spikes ativos por squad	Diluição de foco
Tempo limite rígido (padrão 3–5 dias)	Spikes se expandem para preencher o sprint
Demo no dia N - mesmo que falhe	Força a articulação do aprendizado
Sem código de spike no branch de release	Veneno de cherry-pick
ADR para ADOTAR, ADIAR, REJEITAR	Memória institucional
Deletar branch após resultado	Evita merge acidental meses depois

# Após REJEITAR - deletar worktree
git worktree remove ../MyApp-spike-ui
git branch -D spike/expo-ui-tabs

PoC vs Spike vs Piloto de Produção

Tipo	Duração	Enviado para usuários?	Documento
Spike	3–5 dias	Não	ADR curto
PoC	1–2 sprints	Apenas TestFlight interno / trilha interna	ADR + plano de teste
Piloto	1 release	Marcado 1–5% em produção	QA completo + runbook de rollback

Caminho de promoção: Spike → ADR → PoC → Piloto → GA - pular etapas requer aprovação do EM + plataforma.

FAQs

Spike teve sucesso - podemos fazer merge na sexta-feira?

Apenas com ADR, flag desativada por padrão, evidência normal no template de PR, e sem hacks apenas de spike deixados em app.config.ts. Caso contrário, agende um sprint de PoC.

Quem aprova o merge do spike brownfield no repositório host?

Líder da plataforma nativa + líder mobile + proprietário da CI. A aprovação apenas de RN é insuficiente - o binário do host é enviado para as lojas.

Spike da Nova Arquitetura falhou - devemos bloquear o SDK 57?

Não - documente o plano de substituição do módulo. O SDK 57 / RN 0.86 ainda será lançado; o módulo falho receberá uma linha de EOL no registro e um cronograma de troca.

Relacionados

Noções Básicas de Brownfield - integrar vs reescrever
ADR de Adoção Incremental - padrão strangler
Política de Upgrade de SDK - spikes de upgrade
Registros de Decisão de Arquitetura - formato ADR
Rebase Interativo & Worktrees - trabalho paralelo de spike
Melhores Práticas de Governança - resumo da política de spike

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0, e Expo SDK 57 (expo ~57.0.4).

Spikes, PoCs & Nova Arquitetura

Buscar na documentação

Spikes, PoCs & Nova Arquitetura