Gerando spikes

Gerar um spike é o núcleo do SpikeMe. Você fornece o manifesto do projeto, um tema (uma decisão técnica real), quantas opções comparar, a língua do documento e a profundidade. O SpikeMe coleta fatos vivos sobre os pacotes candidatos e escreve um documento de decisão completo que você lê, baixa e compartilha.

Escolhendo um tema

Um spike responde a exatamente uma decisão técnica, então um bom tema é concreto e comparativo, não um assunto amplo. Pense em "lib de gerenciamento de estado", "asyncpg vs psycopg" ou "qual ferramenta de teste end-to-end". Quanto mais estreito o tema, mais afiada a recomendação.

Você não precisa inventar temas do zero. Quando o SpikeMe analisa seu manifesto, ele categoriza suas dependências e detecta lacunas (categorias para as quais sua stack não tem pacote) e transforma essas lacunas em temas sugeridos. Escolha um deles ou digite o seu.

Junto com o tema, você define:

• Opções a comparar: quantos candidatos o SpikeMe deve analisar lado a lado (por exemplo, duas ou três libs).
• Língua: a língua em que o documento é escrito.
• Profundidade: quick ou full, descritas abaixo.

Profundidade: quick vs full

A profundidade controla qual modelo escreve o documento e quão detalhado ele é. É a principal alavanca de custo e tempo.

quick

O quick usa um modelo mais barato e rápido e produz um documento conciso (por volta de 600-900 palavras). Mantém os trechos de código ao mínimo e foca na comparação e na recomendação. Use para triar uma decisão rápido ou quando a escolha é de baixo risco.

full

O full usa o modelo mais forte e produz um documento detalhado (por volta de 1500-2200 palavras), com trechos de código realistas para cada opção e um plano de prova de conceito detalhado. Use para decisões com as quais você vai de fato se comprometer e defender depois.

Opções e língua

O número de opções define quantos candidatos entram na tabela de comparação e ganham subseção própria. Duas ou três é o ponto ideal: o suficiente para ver um trade-off real, poucas o bastante para o documento continuar decisivo.

O ajuste de língua controla o texto (títulos, análise, recomendação). Os trechos de código e os nomes dos pacotes permanecem como estão.

O motor de evidência

É isto que separa um documento do SpikeMe de uma resposta de chat qualquer. Antes de escrever, o SpikeMe coleta fatos vivos sobre os pacotes candidatos e injeta um bloco facts datado no prompt, para o documento citar números reais e nomear a fonte e a data em vez de chutar a partir de dados de treino velhos.

As fontes dependem do ecossistema:

• npm: o npm registry (versão, licença), o npm downloads (downloads/semana) e o bundlephobia (tamanho de bundle em gzip).
• Python: o PyPI (versão, licença) e o pypistats (downloads/semana).
• Go: o deps.dev (versão, licença). O Go não tem contagem pública de downloads semanais, então esses números ficam de fora — o esperado.

O bloco injetado tem mais ou menos esta cara:

<facts date="2026-07-14">
zustand: v5.0.2, MIT, 4.8M downloads/semana, 1.1 kB gzip (npm registry, npm downloads, bundlephobia)
jotai:   v2.10.3, MIT, 1.6M downloads/semana, 3.4 kB gzip (npm registry, npm downloads, bundlephobia)
</facts>

A coleta é best-effort: se um fato não puder ser reunido a tempo, a geração segue sem ele e nunca trava. Esse determinismo e essa atualidade são o diferencial do produto: o mesmo tema gera um documento ancorado nos números reais de hoje, não na lembrança de um modelo.

O que vem no documento

Todo spike gerado segue a mesma estrutura, para as decisões ficarem fáceis de comparar no seu time:

• Um título e um parágrafo de contexto citando o projeto e a stack dele.
• ## Objective and decision criteria: bullets mensuráveis pelos quais você vai julgar as opções.
• ## Options analyzed: uma subseção por opção, com prós e contras e um trecho de código curto e real.
• ## Comparison: uma tabela pontuando as opções por critério.
• ## Recommendation: a escolha, por que ela vence e quando reconsiderar.
• ## Proof-of-concept plan: passos numerados e com tempo definido, mais o comando de instalação exato para o gerenciador de pacotes do seu projeto.
• ## Risks and mitigation: o que pode dar errado e como conter.
• ## Spike acceptance criteria: um checklist para saber quando o spike terminou.

Exportando e compartilhando

Assim que o documento chega em streaming, você pode:

• Ler ao vivo, conforme ele é escrito.
• Baixar como arquivo .md.
• Exportar como ADR no formato MADR, para cair direto nos seus registros de decisão de arquitetura.
• Guardar em My spikes: todo documento fica salvo na sua conta.
• Compartilhar um link público em /s/<slug>, com imagem de preview gerada.
• Exportar um Team kit: um kit de onboarding compartilhável que empacota a decisão para o resto do time.

Onde gerar

Você gera um spike a partir de três lugares, todos apoiados no mesmo motor:

• Wizard web em spikeme.io/app: envie um manifesto, escolha tema e profundidade, leia e compartilhe o resultado.
• CLI com spikeme gen: gere pelo terminal, onde seu código já mora. Veja CLI.
• Servidor MCP: exponha a geração para o seu agente de código (Claude Code, Cursor), que passa a entregar o artefato direto. Veja MCP.