M2.2 Connections

Conteúdo detalhado

🧪 O teste do Connections

Existe um teste simples e brutal para saber se o seu AIOS tem Connections reais: faça uma pergunta que exige dado vivo. Não dado que você colou no chat — dado que o sistema precisa buscar sozinho. Se a resposta vier sem você copiar nada, seu Connections funciona.

🎯 O Teste em 1 Frase

"O que tenho na agenda amanhã e quais tarefas vencem?" — se essa resposta chega sem paste, você tem Connections.

• Dado colado = você ainda está fazendo o trabalho braçal de busca.
• Dado vivo = o AIOS alcança o sistema, busca, e responde. Você só lê.
• O teste vale para qualquer domínio — financeiro, tarefas, comunicação, reuniões.

✓ Connections reais

✓"O que vence hoje?" → busca automática
✓Resumo de emails → MCP ou script
✓Próxima reunião + pauta → Calendário API
✓Receita do mês → Financeiro API

✗ Falso Connections

✗Copiar reunião do Google Cal e colar no chat
✗Exportar CSV manualmente e subir no contexto
✗Digitar as tarefas que vencem no prompt
✗Fazer o AIOS perguntar "me mande os dados"

🗺️ Os 7 Domínios Tier-1 Universais

Todo trabalho de conhecimento passa por 7 domínios. São chamados de Tier-1 Universais porque aparecem independente do setor — agência, SaaS, consultoria, freelancer. Cobri-los é a base de um AIOS funcional.

📋 Mapa dos 7 Domínios — o que cobrir antes de qualquer outro

#	Domínio	O que inclui	Exemplos de ferramentas
1	💰 Receita/Financeiro	Faturamento, despesas, fluxo de caixa	Stripe, QuickBooks, Notion finance
2	🤝 Interações c/ cliente	Leads, deals, suporte, feedback	HubSpot, Pipedrive, Intercom, Linear
3	📅 Calendário	Agenda pessoal, reuniões, deadlines	Google Calendar, Calendly, Notion cal
4	💬 Comunicação	Email, chat, DMs, notificações	Gmail, Slack, Discord, Linear comments
5	✅ Projetos/Tarefas	To-dos, sprints, backlog, entregáveis	Linear, Notion, Asana, Trello
6	🎙️ Inteligência de reunião	Transcrições, action items, gravações	Fireflies, Otter, Notion meetings
7	📁 Conhecimento/Arquivos	Docs, wikis, SOPs, base de know-how	Notion, Drive, Confluence, Obsidian

💡 Dica Prática — Comece pelo domínio que dói mais

Não tente conectar os 7 de uma vez. Identifique qual domínio consome mais tempo de busca manual no seu dia. Esse é o primeiro a conectar. O /audit pontua a cobertura dos 7 domínios — 0 domínios = multiplicador 4x na penalização de score.

⚙️ Os 4 Mecanismos (agnóstico a ferramenta)

O kit AIS-OS é API-first e agnóstico: não importa qual ferramenta você usa, existem 4 maneiras de fazer o AIOS alcançar um sistema. Cada mecanismo tem tradeoffs de confiabilidade, setup e manutenção.

📄 connections.md — estrutura da tabela

#	Domínio	Tool	Mecanismo	Auth	Última checagem
1	Calendário	Google Calendar	mcp	OAuth	2026-06-01
2	Comunicação	Gmail	script	OAuth	2026-05-28
3	Projetos	Linear	key+ref	.env API_KEY	2026-05-15
4	Conhecimento	Notion	export	CSV dump	2026-05-01

Uma linha por sistema alcançável. Manter atualizado — o /audit lê este arquivo.

Os 4 mecanismos — do mais ao menos integrado

MCP

mcp — Servidor MCP

Maior integração · setup mais complexo · bidirecional

O Claude Code se conecta diretamente ao servidor MCP da ferramenta. Leitura e escrita em tempo real. Requer configuração no .claude/settings.json. É o mecanismo preferido quando disponível.

script

script — Python/Bash batendo API

Alta flexibilidade · API-first · você controla

Scripts Python ou Bash que chamam a API REST da ferramenta. Armazenados em scripts/. Bom quando não existe MCP. Você versionea, testa e adapta.

key

key+ref — Chave .env + references/{tool}-api.md

Leve · rápido de setar · boa base para skills futuras

API key no .env + guia de referência em references/{tool}-api.md. O AIOS lê o guia e monta as chamadas. Padrão do researched-once-saved-forever.

exp.

export — Dump CSV/JSON

Mais manual · sem integração contínua · ponto de partida

Exportar manualmente e jogar no contexto. Válido para Dia 1 quando a API é complexa. Mas atenção: dado fica estale rapidamente. Use como ponto de partida, não destino final.

📋 connections.md — o registro central

O connections.md é o manifesto de integrações do seu AIOS. Uma linha por sistema alcançável. O /audit lê este arquivo diretamente para pontuar a cobertura dos 7 domínios e verificar o freshness das conexões.

📌 Campos obrigatórios por linha

# Número — sequência simples. Não tem significado além de ordenação.
Domínio Um dos 7 Tier-1 (ou sub-domínio customizado seu).
Tool Nome exato da ferramenta (Gmail, Notion, Linear…).
Mecanismo mcp / script / export / key+ref — como a conexão funciona.
Auth OAuth / API Key / .env / sem auth. Não colocar chaves aqui — só o tipo.
Última checagem Data da última vez que a conexão foi testada/validada. O /audit penaliza freshness ruim.

✓ connections.md correto

✓Uma linha por ferramenta, simples
✓Mecanismo preenchido (mcp/script/export/key+ref)
✓Data de checagem atual (menos de 30 dias)
✓7 domínios representados

✗ Erros comuns

✗Colocar chaves de API no arquivo (vai para git)
✗Deixar "Última checagem" em branco
✗Não registrar conexões do tipo export (valem ponto)
✗Só read-only (ver Tópico 6)

💾 Researched-once-saved-forever

Cada vez que você pesquisa como uma API funciona — endpoints, autenticação, queries — você está investindo tempo de pesquisa. Salvar esse investimento em references/{tool}-api.md é o padrão "researched-once-saved-forever": você pesquisa uma vez, e todo uso futuro — seja seu, de uma skill, de um agente — é instantâneo.

📊 Por que isso importa tanto

Skills futuras não re-pesquisam — A skill lê o references/{tool}-api.md e já sabe os endpoints.
O /audit premia isso — A presença de guias de API em references/ é pontuada diretamente no score de Connections.
Compounding real — 10 guias de API salvos = AIOS 10x mais rápido para qualquer nova skill que envolva esses sistemas.
Sem re-pesquisa manual — Você documentou a API do Linear uma vez. Toda skill que usa Linear herda esse conhecimento.

📄 references/linear-api.md — estrutura sugerida

# Linear API — Guia de Referência
## Base URL
https://api.linear.app/graphql

## Auth
Header: Authorization: {API_KEY}
Var: LINEAR_API_KEY no .env

## Queries mais usadas
- Listar issues: query { issues { nodes { id title state } } }
- Issues do usuário: query { viewer { assignedIssues { ... } } }

## Mutations
- Criar issue: mutation { issueCreate(input: {...}) }
- Fechar issue: mutation { issueUpdate(id: "...", input: {stateId: "..."}) }

## Última atualização: 2026-06-01

💡 Dica — Documente enquanto conecta

Ao fazer qualquer nova conexão (MCP, script ou key+ref), abra o arquivo references/{tool}-api.md e registre os endpoints que você testou, a autenticação que funcionou e os parâmetros mais comuns. Leva 5 minutos e economiza horas no futuro.

⚖️ Read AND Write Balance

Um AIOS que só lê é um visualizador sofisticado, não um Operating System. Para ser um OS de verdade, pelo menos uma conexão precisa escrever — mandar e-mail, criar issue, postar mensagem, atualizar registro. A capacidade de agir no mundo é o que separa consulta de automação.

🔄 A distinção que importa

📖 READ (consulta)

• "Qual reunião tenho hoje?"
• "Quantos issues abertos no Linear?"
• "Qual a receita do mês passado?"
• "Resuma meus emails não lidos"

Útil, mas você ainda precisa agir manualmente.

✍️ WRITE (ação)

• Manda o e-mail de follow-up
• Cria o issue no Linear
• Agenda a reunião
• Posta o update no Slack

O AIOS age. Você só aprova (ou nem isso).

⚠️ Atenção — o /audit penaliza all-read-only

Se todas suas conexões forem read-only, o /audit aplica um multiplicador 2x na lacuna de Connections. Isso sozinho pode tirar 8-12 pontos do seu score. A exigência é pequena: 1 conexão com capacidade de escrita já zera essa penalidade.

💡 Por onde começar a escrever

A conexão de escrita mais simples para a maioria das pessoas: Gmail com permissão de rascunho. O AIOS cria o rascunho — você revisa e envia. Cobre o write-balance sem risco de envio acidental.

Conforme ganha confiança: Fase Bike Method = começa criando rascunhos, evolui para envio com aprovação, depois envio automático para categorias específicas.

🪜 The Integration Ladder

Nem toda conexão é igualmente confiável. A Integration Ladder define uma hierarquia de confiabilidade: suba o degrau mais alto disponível para cada ferramenta. Degraus mais baixos são usados quando os superiores não existem — nunca por preferência.

🪜 Hierarquia de Confiabilidade — API no topo

API direta PREFERIDA

Interface oficial, versionada, documentada. Responde previsível. Tem limites de rate claros. Não quebra com mudança de UI.

CLI (linha de comando) boa alternativa

Ferramentas como gh (GitHub), gcloud (GCP). Menos granular que API mas muito mais estável que browser.

Browser Automation use com cautela

Playwright, Puppeteer, Computer Use. Frágil — qualquer mudança de layout quebra. Mais custo de manutenção. Use só quando API e CLI não existem.

Scraping último recurso

HTML parsing de páginas públicas. Altamente instável — quebra com qualquer deploy. Termos de serviço frequentemente proibem. Nunca como solução de longo prazo.

✓ Aplicar a Ladder

✓Verifica se existe API antes de Browser Automation
✓Documenta no connections.md o mecanismo usado
✓Planeja migrar para degrau superior quando disponível

✗ Ignorar a Ladder

✗Usar scraping quando existe API (fragil + desnecessário)
✗Browser automation para ferramenta com CLI oficial
✗Construir integração em degrau baixo e nunca revisar

🔌 Resumo do Módulo 2.2

✓

O teste do Connections — dado vivo sem paste. Se você copia, ainda não tem Connections.

✓

7 Domínios Tier-1 — Receita, Cliente, Calendário, Comunicação, Projetos, Reuniões, Conhecimento. Cobri-los é a base.

✓

4 mecanismos — mcp / script / key+ref / export. Kit é API-first, agnóstico de ferramenta.

✓

connections.md — manifesto de integrações. Lido pelo /audit para pontuar cobertura e freshness.

✓

Researched-once-saved-forever — referencias/{tool}-api.md. Uma pesquisa, uso infinito por skills e agentes.

✓

Read AND Write — mínimo 1 conexão que escreve. All-read-only = visualizador, não OS.

✓

Integration Ladder — API > CLI > Browser Automation > Scraping. Sempre suba ao degrau mais confiável disponível.

Próximo Módulo:

2.3 — Capabilities: Sabe fazer o trabalho 🧩

Uma frase dispara um artefato. Skills vs Agents, Autonomy Spectrum e como o /level-up constrói capabilities semana a semana.

← Voltar para Trilha Próximo Módulo →