Esta organização existe para documentar, versionar e gerenciar as automações internas da Asimov Academy — incluindo fluxos n8n, agentes de IA e integrações operacionais.

Não é apenas um lugar para guardar código ou workflows. É o lugar onde cada automação ganha contexto, histórico, regras de negócio e instruções claras de uso, para que ninguém dependa de conhecimento informal, prints ou conversas soltas para entender como as coisas funcionam.

• Por que essa organização existe
• O que você vai encontrar aqui
• Como usamos os repositórios
• n8n-agent
• Como pessoas não técnicas participam
• Como abrir uma issue
• Como organizar melhorias
• Boas práticas de documentação
• Segurança
• Primeiros passos

Boa parte das nossas automações nasce em ferramentas visuais, como o n8n. Elas são ótimas para criar fluxos, integrar APIs e colocar processos para rodar — mas não são o melhor lugar para documentar tudo o que uma automação precisa ter.

Por isso, usamos o GitHub como camada de documentação, organização e gestão das automações. Cada automação importante tem seu próprio repositório, com README, issues, documentação técnica e histórico de evolução.

A ideia é que qualquer pessoa autorizada consiga entender o básico de uma automação sem depender apenas de conversas soltas, prints ou conhecimento informal.

Cada repositório representa uma automação, um conjunto de automações ou uma ferramenta interna. Dentro dele, esperamos encontrar:

• Visão geral — o que a automação faz
• Área responsável — qual time usa ou mantém
• Como usar — instruções para quem opera a automação
• Como configurar — variáveis, credenciais e dependências
• Regras de negócio — decisões e condições que a automação respeita
• Fluxos envolvidos — workflows, agentes, scripts ou integrações relacionados
• Problemas conhecidos — limitações e pontos de atenção
• Histórico de melhorias — o que já foi feito e o que falta fazer

💡 O README de cada repositório deve ser direto, simples e útil. A documentação não precisa ser perfeita desde o primeiro dia — mas precisa existir e evoluir junto com a automação.

Para facilitar o trabalho com automações do n8n, usamos uma ferramenta open-source chamada n8n-agent.

Essa CLI foi criada para permitir que agentes de IA locais trabalhem melhor com workflows do n8n, sincronizando informações entre a nuvem e o ambiente local.

Na prática, o n8n-agent conecta três pontas:

    ┌────────────────────┐        ┌────────────────────────┐        ┌────────────────────────┐
    │   Workflow no n8n  │  <──>  │  Documentação (GitHub) │  <──>  │  Trabalho local + IA   │
    └────────────────────┘        └────────────────────────┘        └────────────────────────┘

Isso permite que agentes de IA ajudem de verdade na manutenção das automações, sem depender de copiar e colar JSONs enormes manualmente.

Nem todo mundo que usa uma automação precisa saber programar ou editar workflows. Os repositórios também servem como espaço organizado para que outras áreas participem da melhoria das ferramentas.

Pessoas de áreas como Customer Success, Vendas, Produto e outras podem usar issues padronizadas para:

• 🐞 Reportar problemas
• ✨ Pedir melhorias
• 📋 Explicar casos de uso
• ⚠️ Informar comportamentos inesperados
• 💬 Sugerir ajustes em mensagens, regras ou processos
• 👀 Acompanhar o andamento das solicitações

Sempre que possível, problemas e melhorias devem virar issues no repositório da automação correspondente, evitando que pedidos importantes se percam em mensagens soltas.

Ao encontrar um problema ou sugerir uma melhoria, procure o repositório da automação relacionada e abra uma issue usando o modelo disponível, respondendo sempre que possível:

• O que aconteceu?
• O que deveria ter acontecido?
• Em qual automação isso ocorreu?
• Quando o problema aconteceu?
• Existe algum print, link, mensagem ou exemplo?
• Isso impede o uso da automação ou é apenas uma melhoria?

Quanto mais contexto a issue tiver, mais fácil será entender, priorizar e resolver.

As melhorias das automações são acompanhadas dentro dos próprios repositórios. Isso ajuda o time a entender:

• O que já foi feito
• O que está em andamento
• O que ainda precisa ser analisado
• Quais problemas são recorrentes
• Quais automações precisam de mais atenção

O GitHub funciona como o histórico operacional da automação — não é só um lugar para guardar arquivos, é onde a evolução fica registrada.

Ao criar ou atualizar um repositório, mantenha estas informações claras:

Evite documentações longas demais. O ideal é que qualquer pessoa consiga abrir o README e entender rapidamente:

o que é isso, para que serve e como usar.

Sempre que uma automação precisar de variáveis de ambiente, use um arquivo de exemplo:

.env.example

Esse arquivo deve mostrar quais variáveis são necessárias, mas nunca deve conter valores reais.

1. Entenda quais repositórios você tem acesso
2. Leia o README do repositório da automação que você vai usar
3. Veja se existem issues abertas relacionadas à sua área
4. Use os modelos de issue para reportar problemas ou sugerir melhorias
5. Em caso de dúvida, mencione o time responsável dentro da própria issue