Home | Blog | Guide

Pesquisa entre ferramentas: o código é o lugar errado

A maioria das decisões dos desenvolvedores existe fora do código. Veja como construir pesquisa entre Slack, Linear, GitHub e Notion.

By Ellis Keane · 2026-03-17

O código é o lugar menos útil para pesquisar por que uma decisão foi tomada.

Sei que isso parece ao contrário. Passamos anos aprendendo flags do ripgrep, configurando a pesquisa da IDE, memorizando padrões de expressões regulares – e nada disso ajuda quando a pergunta não é "onde está essa função?" mas "por que escolhemos essa abordagem em vez das três alternativas que discutimos?". A resposta a essa segunda pergunta quase nunca está no código. Está em um thread do Slack de quatro meses atrás, em um comentário do Linear enterrado sob atualizações de status, em um documento Notion que alguém começou e nunca terminou, e em uma revisão de PR onde o verdadeiro debate aconteceu em uma resposta a uma resposta a uma resposta.

Esse é o problema de pesquisa entre ferramentas para desenvolvedores – o contexto da decisão está dividido entre ferramentas sem um caminho de consulta unificado. Temos pesquisa que funciona bem dentro de cada ferramenta – a pesquisa do Slack é razoável, a pesquisa de código do GitHub é excelente, o Linear tem filtros para tudo – mas nada que pesquise em todas elas. As decisões que moldaram a sua arquitetura vivem em cinco lugares diferentes, e espera-se que você se lembre de onde procurar.

Certo, então – aqui está como construir pesquisa entre ferramentas com o que você já tem. Sem novas ferramentas necessárias (bem, quase – vou mencionar uma no final, mas isso funciona sem ela).

A Anatomia de uma Decisão Dispersa

Deixe-me percorrer algo específico. No ano passado, estávamos decidindo se usaríamos BullMQ ou Temporal para nossa fila de trabalhos. Veja onde essa decisão realmente vivia:

Slack (#engineering): Três threads separados ao longo de dois dias. O primeiro foi um link que alguém compartilhou para uma postagem de blog do Temporal. O segundo foi um debate sobre se precisávamos de execução durável. O terceiro (uma semana depois, canal diferente) foi alguém perguntando "espera, decidimos sobre a fila?".
Linear: Um issue intitulado "Avaliar opções de fila de trabalhos" com seis comentários, incluindo uma tabela comparativa que um dos nossos engenheiros passou uma tarde escrevendo.
GitHub: Uma descrição de PR para a implementação do BullMQ que dizia "conforme discutido" sem links para onde foi discutido.
Notion: Um registro de decisão de arquitetura pela metade que cobria os prós do Temporal mas nunca foi atualizado com a escolha final.
Google Docs: Notas de reunião de uma chamada onde realmente tomamos a decisão, enterradas em pontos entre dois itens de agenda não relacionados.

Cinco ferramentas. Uma decisão. E se você tivesse pesquisado em qualquer ferramenta individual, teria encontrado um fragmento – nunca a imagem completa. O PR diz o que escolhemos. Os threads do Slack dizem o que consideramos. O issue do Linear diz os trade-offs. O documento Notion diz metade do raciocínio. As notas da reunião dizem o momento em que foi finalizado.

Isso não é incomum. Esse é, de alguma forma, o estado da arte de como as equipes de engenharia rastreiam decisões em 2026. Temos IA que gera código e mecanismos de pesquisa que indexam toda a internet, mas descobrir por que sua equipe escolheu BullMQ em vez de Temporal requer verificar cinco aplicativos e torcer para que a memória de alguém aguente.

O que torna a pesquisa entre ferramentas difícil para desenvolvedores

Não é um problema de API – cada ferramenta que usamos tem uma API de pesquisa perfeitamente boa. O problema é mais estranho do que isso:

Formatos de dados diferentes. O Slack retorna mensagens com timestamps e IDs de canal. O Linear retorna issues com estados e rótulos. O GitHub retorna commits, PRs e correspondências de código em formatos de resposta completamente diferentes. Mesclar esses em uma linha do tempo coerente requer normalização que ninguém se preocupa em construir (porque, honestamente, é o tipo de trabalho que não aparece nas demonstrações de sprint).

Fragmentação de contexto. Uma mensagem do Slack dizendo "vamos com a opção B" não tem sentido sem o thread que definiu as opções A, B e C. Mas a pesquisa do Slack retorna mensagens individuais, não arcos de conversa. Você encontra a conclusão sem o raciocínio.

Deriva temporal. O processo de decisão muitas vezes abrange dias ou semanas, com lacunas onde nada aconteceu porque todos estavam focados em outro trabalho. Uma pesquisa por palavra-chave pode trazer o início e o fim de uma conversa enquanto perde o meio crucial, simplesmente porque palavras diferentes foram usadas em diferentes estágios.

A pesquisa entre ferramentas para desenvolvedores não é um problema de API – cada ferramenta tem um endpoint de pesquisa perfeitamente bom. É um problema de contexto: as decisões estão dispersas por ferramentas em formatos incompatíveis, fragmentadas por arcos de conversa e separadas por deriva temporal. A pesquisa por palavra-chave encontra fragmentos; apenas o contexto conectado encontra a imagem completa.

Construindo pesquisa entre ferramentas com o que você tem

Aqui está a parte prática. Para três ou quatro ferramentas com pesquisa somente leitura, espere meio dia para ter um MVP funcionando – a maior parte disso gasta na configuração de autenticação e normalização de respostas, e não na lógica de pesquisa em si.

Configurar acesso à API

Você precisará de tokens para cada ferramenta:

Slack: Um token de usuário com escopo search:read (os métodos de pesquisa do Slack requerem tokens de usuário, não tokens de bot – crie via página de apps do Slack API)
Linear: Uma chave de API pessoal em Configurações, depois API
GitHub: Um PAT granular com acesso de leitura aos seus repositórios
Notion: Um token de integração interna em Configurações, depois Conexões

O script de consulta com distribuição

O padrão básico é constrangedoramente simples – dispare a mesma consulta de pesquisa para cada API e colete os resultados:

```typescript interface SearchResult { source: 'slack' | 'linear' | 'github' | 'notion'; title: string; snippet: string; url: string; timestamp: Date; }

async function crossToolSearch(query: string): Promise<SearchResult[]> { const results = await Promise.all([ searchSlack(query), searchLinear(query), searchGitHub(query), searchNotion(query), ]);

return results .flat() .sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime()); } ```

Cada função search* envolve a respectiva API. Para o Slack, é search.messages. Para o Linear, é uma consulta GraphQL nos campos de pesquisa. Para o GitHub, é o endpoint de pesquisa REST. Para o Notion, é o endpoint de pesquisa com um parâmetro query.

Normalizar e deduplicar

A parte complicada não é a pesquisa – é tornar os resultados úteis. Você vai querer:

Normalizar timestamps entre ferramentas (Slack usa épocas Unix, Linear usa strings ISO, GitHub usa ISO com deslocamentos de fuso horário)
Agrupar resultados relacionados – se o mesmo thread do Slack aparecer três vezes porque três mensagens corresponderam, recolha-os em um único resultado com a URL do thread
Classificar por relevância – a maioria das APIs retorna suas próprias pontuações de relevância, mas não são comparáveis entre ferramentas. Uma heurística simples: correspondências exatas de palavra-chave em títulos ficam acima de correspondências no corpo, e resultados mais recentes ficam acima de mais antigos com relevância igual

Encapsular em um CLI

Uso Commander.js para isso (principalmente por hábito, mas qualquer coisa funciona):

```bash $ cross-search "bullmq vs temporal"

Found 14 results across 4 tools:

[Slack] #engineering – 2025-11-14 "I've been comparing BullMQ and Temporal for the job queue..." https://myteam.slack.com/archives/C0X.../p17318...

[Linear] ENG-342 – 2025-11-15 "Evaluate job queue options – BullMQ vs Temporal" https://linear.app/myteam/issue/ENG-342

[GitHub] PR #289 – 2025-11-22 "feat: implement BullMQ job queue (as discussed)" https://github.com/myorg/myrepo/pull/289

[Notion] Architecture Decisions – 2025-11-13 "Job Queue Evaluation: Temporal vs BullMQ" https://notion.so/myteam/abc123... ```

Quatorze resultados, classificados por tempo, em quatro ferramentas. Você pode ver o arco completo da decisão em um só lugar: o documento Notion foi iniciado primeiro, depois aconteceu a discussão no Slack, depois o issue do Linear foi criado para rastreamento, e finalmente o PR chegou uma semana depois.

Tornando isso realmente bom

A versão básica acima funciona, mas tem algumas arestas frustrantes. Veja como melhorá-la:

Expansão de threads do Slack. Quando você encontrar uma mensagem correspondente, busque o thread inteiro com conversations.replies. A mensagem correspondente pode ser "sim, vamos com BullMQ" – inútil sem as 40 mensagens de debate anteriores. Exiba um trecho do thread, não apenas a mensagem correspondente.

Comentários de revisão de PR. A API de pesquisa do GitHub não exibe comentários de revisão quando você pesquisa por PRs – você precisará de uma chamada separada ao endpoint de revisões de pull request para buscá-los. É lá que a discussão técnica real acontece.

Backlinks. Quando encontrar um issue do Linear, verifique se alguma mensagem do Slack contém a URL desse issue. A pesquisa do Slack suporta filtros has:link combinados com palavras-chave. Isso revela a discussão informal que aconteceu em torno do rastreamento formal.

Cache. Se a sua equipe gera muito conteúdo (e qual não gera?), você atingirá os limites de taxa rapidamente. Faça cache dos resultados localmente com um TTL de 30 minutos – a maioria das decisões históricas não muda tão rápido.

Quando a pesquisa de texto falha

Aqui vou ser honesto sobre as limitações. A pesquisa por palavra-chave entre ferramentas leva você surpreendentemente longe, e então bate em uma parede.

A parede é esta: as decisões evoluem. O thread do Slack sobre "filas de trabalhos" pode nunca mencionar "BullMQ" pelo nome – em vez disso, alguém compartilhou um link, outra pessoa disse "gosto da opção baseada em Redis", e uma terceira pessoa disse "concordo, vamos com isso". A sua pesquisa por "BullMQ" perde todo o thread porque a palavra nunca foi usada. As pessoas no thread sabiam o que "a opção baseada em Redis" significava. A sua pesquisa não sabe.

Este é fundamentalmente um problema de grafo, não um problema de texto. O que você realmente quer é: "mostre-me tudo conectado à decisão que levou ao PR #289." Isso significa entender que o PR faz referência a um issue do Linear, que foi criado após uma discussão no Slack, que começou porque alguém leu um documento Notion. As conexões são implícitas – os humanos as fizeram copiando URLs e dizendo "conforme discutido" – e uma pesquisa por palavra-chave não consegue reconstruí-las.

Você pode resolver isso parcialmente seguindo links. Analise URLs de mensagens do Slack, descrições de PR e comentários do Linear. Construa uma lista de adjacência simples: este thread do Slack leva a este issue do Linear, que é referenciado neste PR. Então, quando alguém pesquisar, você pode expandir os resultados para incluir itens vinculados mesmo que não correspondam à palavra-chave.

Essa abordagem de lista de adjacência é essencialmente um grafo de conhecimento rudimentar – e é onde o valor real da pesquisa entre ferramentas para desenvolvedores reside. Não em encontrar mensagens individuais, mas em seguir o fio de uma decisão por cada ferramenta que tocou. É menos "pesquisa" e mais gestão do conhecimento para desenvolvedores – entender como as informações fluem entre suas ferramentas para que você possa reconstruir o contexto quando precisar.

O problema de manutenção (e um atalho)

A abordagem de script funciona brilhantemente por uns três meses, e então alguém muda o workspace do Slack, ou o Linear atualiza seu esquema GraphQL, ou você adiciona uma nova ferramenta e ninguém se lembra de atualizar o script de pesquisa. Já construí exatamente isso duas vezes e abandonei duas vezes (o que provavelmente diz mais sobre meu compromisso com a manutenção do que sobre a abordagem em si).

Se você quer pesquisa entre ferramentas para desenvolvedores que se mantém atualizada sem precisar de cuidados, é para isso que ferramentas como o Sugarbug são construídas – ele mantém o grafo de conhecimento automaticamente e mantém as conexões vivas à medida que suas ferramentas mudam. Mas a versão DIY acima é genuinamente útil se você estiver disposto a mantê-la.

Pare de pesquisar em cinco ferramentas separadamente. O Sugarbug constrói o grafo de conhecimento para que você possa encontrar qualquer decisão, discussão ou commit em um só lugar.

Q: Como pesquisar em várias ferramentas de desenvolvimento ao mesmo tempo? A: Você pode criar uma pesquisa leve entre ferramentas combinando a API de cada ferramenta – search.messages do Slack, issueSearch do Linear e o endpoint de pesquisa de código do GitHub – em um único script que distribui consultas e mescla resultados por timestamp. Os exemplos de código acima vão te ajudar a começar em uma tarde. O principal desafio não é a pesquisa em si, mas normalizar os diferentes formatos de resposta em uma linha do tempo coerente.

Q: O Sugarbug oferece pesquisa entre ferramentas para desenvolvedores? A: Sim. O Sugarbug coleta sinais do Linear, GitHub, Slack, Figma, Notion e outras ferramentas em um grafo de conhecimento, para que você possa pesquisar uma decisão ou discussão e encontrar cada thread, issue e commit relacionado em um só lugar. Ele lida automaticamente com normalização, deduplicação e rastreamento de links – as partes que tornam a abordagem DIY frágil com o tempo.

Q: Por que não consigo encontrar decisões de arquitetura no código? A: Porque a maioria das decisões acontece em threads do Slack, comentários do Linear, documentos do Notion e revisões de PR – não no código em si. O código registra o resultado de uma decisão (a função existe, a biblioteca foi escolhida), mas o raciocínio, os trade-offs e as alternativas discutidas estão dispersos pelas ferramentas de comunicação. Um git blame diz quem mudou uma linha e quando, mas não por que escolheram essa abordagem em vez das alternativas.

Q: O Sugarbug pode substituir documentos ADR para rastreamento de decisões? A: O Sugarbug não substitui os ADRs, mas captura as decisões que nunca chegam a um ADR. A maioria das equipes escreve ADRs para talvez 10% de suas escolhas arquitetônicas – o restante se dissolve em threads do Slack e comentários de PR. O Sugarbug os exibe conectando conversas às mudanças de código que produziram, para que você obtenha rastreamento de decisões para os outros 90% sem mudar o fluxo de trabalho de ninguém.