Recebi sua solicitação e estou começando a trabalhar na explicação detalhada e didática sobre como instalar e usar a ferramenta 'antigravity-workspace-template'.

Tutorial Completo: Instalando e Usando o Antigravity Workspace Template no Windows 11

Público-alvo: Iniciante completo em programação Sistema operacional: Windows 11 Integração: Google Antigravity Projeto de exemplo: rv-adv Tempo estimado: 45-60 minutos

---

📋 Índice do Tutorial

1. O que é o Antigravity Workspace Template?
2. O que você precisa antes de começar
3. Instalando o Python e Git
4. Instalando o Antigravity Workspace Template
5. Configurando o ambiente
6. Inicializando o workspace para o projeto rv-adv
7. Usando os comandos principais
8. Integrando com o Google Antigravity
9. Resolvendo problemas comuns

---

1. O que é o Antigravity Workspace Template?

Imagine que você está entrando em uma empresa grande pela primeira vez. Você tem muitas perguntas: "Onde fica o café?", "Quem é responsável por quê?", "Como as coisas funcionam aqui?". Seria muito mais fácil se tivesse um "guia de boas-vindas" que explicasse tudo, certo?

O Antigravity Workspace Template é exatamente isso: um "guia de boas-vindas" inteligente para projetos de programação. Ele ajuda agentes de IA (como o Google Antigravity) a entenderem seu projeto rapidamente.

🎯 O que este template faz por você?

🧠 O que é um "motor multi-agente"?

O template usa vários "agentes" especializados que trabalham juntos:

📊 Fluxo de trabalho simplificado

Você faz uma pergunta
        ↓
Router Agent decide qual módulo sabe a resposta
        ↓
ModuleAgent responde com base no conhecimento do módulo
        ↓
Você recebe uma resposta precisa e contextualizada

---

2. O que você precisa antes de começar

2.1 Lista de materiais necessários

2.2 O que é Git e por que preciso dele?

Git é um sistema que permite acompanhar alterações em arquivos de código. É como um "histórico de versões" que permite voltar atrás se algo der errado.

Você precisa do Git porque o Antigravity Workspace Template está hospedado no GitHub, e você vai "clonar" (baixar) o projeto para o seu computador.

2.3 Preparando sua pasta de projetos

Antes de começar, organize seu trabalho:

1. Crie uma pasta chamada "projetos" no Desktop ou Documentos
2. Tenha certeza que a pasta do rv-adv está acessível
3. Anote o caminho da pasta rv-adv (ex: C:\Users\Junior\Documents\rv-adv)

---

3. Instalando o Python e Git

3.1 Verificando instalações anteriores

1. Abra o Prompt de Comando:

   • Pressione Win + R
   • Digite cmd e pressione Enter

2. Verifique o Python:

   python --version
   

3. Verifique o Git:

   git --version
   

4. Se ambos apareceram, você já tem tudo! Pule para a próxima seção.

3.2 Instalando o Python (se necessário)

1. Acesse: https://www.python.org/downloads/
2. Clique em "Download Python 3.12.x"
3. Execute o instalador e MARQUE "Add python.exe to PATH"
4. Clique em "Install Now"
5. Aguarde e clique em "Close"

3.3 Instalando o Git (se necessário)

1. Acesse: https://git-scm.com/download/win

2. O download começará automaticamente

3. Execute o instalador e siga os passos:

   Tela 1: Clique "Next"

   Tela 2: Escolha o local (pode deixar padrão), clique "Next"

   Tela 3: Marque as opções:

   • ✅ "Git from the command line and also from 3rd-party software"
   • ✅ "Use Windows' default console window"
   • ✅ "Checkout Windows-style, commit Unix-style line endings"

   Tela 4: Aguarde a instalação

   Tela 5: Clique "Finish"

3.4 Verificando instalações

1. Abra novo Terminal (feche e abra o cmd novamente)

2. Teste Python:

   python --version
   

   Deverá aparecer: Python 3.12.x

3. Teste Git:

   git --version
   

   Deverá aparecer: git version 2.x.x

4. Se ambos funcionaram, você está pronto! ✅

---

4. Instalando o Antigravity Workspace Template

4.1 Métodos de instalação disponíveis

Existem duas formas de instalar o template:

4.2 Instalação Completa (Recomendada)

Passo 1: Abrir o Terminal como Administrador

1. Pressione Win + X
2. Selecione "Terminal (Admin)" ou "Prompt de Comando (Admin)"
3. Confirme se aparecer pergunta sobre permissões

Passo 2: Instalar as dependências do sistema

pip install litellm pydantic openai-agent-sdk

Aguarde até aparecer "Successfully installed…"

Passo 3: Instalar o CLI do Template

pip install "git+https://github.com/study8677/antigravity-workspace-template.git#subdirectory=cli"

Passo 4: Instalar o Engine do Template

pip install "git+https://github.com/study8677/antigravity-workspace-template.git#subdirectory=engine"

4.3 Instalação Simples (Alternativa)

Se a instalação completa der problemas, use esta versão mais simples:

pip install git+https://github.com/study8677/antigravity-workspace-template.git#subdirectory=cli

Depois use:

ag init minha-pasta-projeto
cd minha-pasta-projeto

4.4 Verificar instalação

ag --version

Deverá aparecer a versão do CLI.

---

5. Configurando o ambiente

5.1 O arquivo .env - O que é e para que serve?

O arquivo .env é como uma "ficha de configuração" que guarda informações importantes:

• Endereço da API de IA que você quer usar
• Sua chave de acesso (API Key)
• Qual modelo de IA preferir
• Tempo limite para respostas

5.2 Configurar acesso à API de IA

Você precisa de uma chave de API de algum provedor de IA. Os provedores mais comuns são:

5.3 Criar o arquivo .env na pasta do projeto

Passo 1: Navegue até a pasta do projeto

cd C:\caminho\para\rv-adv

(Substitua pelo caminho real da pasta rv-adv)

Passo 2: Criar o arquivo .env

copy con .env

Passo 3: Digite o seguinte conteúdo

(Substitua your-key pela sua chave real)

OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=your-key-here
OPENAI_MODEL=gpt-4o-mini
AG_ASK_TIMEOUT_SECONDS=120
AG_REFRESH_AGENT_TIMEOUT_SECONDS=180
AG_MODULE_AGENT_TIMEOUT_SECONDS=90

Passo 4: Salvar o arquivo

1. Pressione Ctrl + Z (para finalizar a entrada)
2. Pressione Enter

Passo 5: Verificar se o arquivo foi criado

type .env

Você deverá ver o conteúdo que acabou de digitar.

---

6. Inicializando o workspace para o projeto rv-adv

6.1 O que é "ag init"?

O comando ag init é como "inicializar" o projeto. Ele cria todos os arquivos de configuração necessários para que o agente de IA entenda seu projeto.

6.2 Executar a inicialização

1. Garanta que está na pasta do rv-adv

2. Digite o comando:

   ag init .
   

3. O que vai acontecer:

   • O sistema vai criar vários arquivos de configuração
   • Pode levar de 1 a 5 minutos
   • Você verá mensagens de progresso

6.3 Arquivos que serão criados

O ag init vai criar os seguintes arquivos na sua pasta:

6.4 Estrutura da pasta .antigravity

.antigravity/
├── memory/              # Memória de interações passadas
├── rules.md            # Regras específicas do projeto
└── workflows/          # Workflows automáticos

---

7. Usando os comandos principais

7.1 Comando ag-refresh - Gerar conhecimento do projeto

Este comando faz o "agente" analisar todo o seu código e criar documentação inteligente.

ag-refresh --workspace .

O que acontece:

1. Escaneia todos os arquivos do projeto
2. Analisa a estrutura de pastas
3. Gera gráficos de conhecimento
4. Cria documentação dos módulos
5. Analisa histórico do Git

Tempo estimado: 5-30 minutos dependendo do tamanho do projeto

Resultado:

• structure.md - Mapa da estrutura do projeto
• conventions.md - Convenções de código adotadas
• knowledge_graph.json - Grafo de conexões
• module_registry.md - Registro de todos os módulos

7.2 Comando ag-ask - Fazer perguntas sobre o projeto

Depois de gerar o conhecimento, você pode fazer perguntas em linguagem natural.

ag-ask "Como funciona a autenticação no projeto?"

Exemplos de perguntas:

7.3 Comando ag-mcp - Servidor MCP para Claude Code

Este comando ativa um "servidor" que permite ao Claude Code acessar seu projeto.

ag-mcp --workspace .

Ferramentas disponíveis:

• ask_project - Fazer perguntas ao projeto
• refresh_project - Atualizar o conhecimento

7.4 Comando ag report - Registrar descobertas

Quando você descobre algo importante, registre para referência futura:

ag report "O módulo de autenticação precisa de refatoração"

7.5 Comando ag log-decision - Registrar decisões

Registre decisões arquiteturais importantes:

ag log-decision "Usamos PostgreSQL" "A equipe tem experiência com esse banco"

---

8. Integrando com o Google Antigravity

8.1 O que significa "integrar"?

Integrar significa fazer o Google Antigravity "entender" seu projeto. Depois de integrado, o Antigravity vai:

• Ler automaticamente os arquivos de configuração
• Conhecer a estrutura do projeto
• Responder perguntas com contexto preciso
• Sugerir código baseado nas convenções do projeto

8.2 Configuração automática (via ag init)

Se você já executou ag init, a integração já está parcialmente feita!

O ag init criou:

• .antigravity/rules.md - Regras para o Antigravity
• .antigravity/memory/ - Memória do projeto

8.3 Configuração manual (se necessário)

Se a integração automática não funcionar:

Passo 1: Localize a pasta de configuração do Antigravity

Geralmente está em:

C:\Users\SeuNome\.antigravity\

Passo 2: Copie os arquivos do projeto

1. Copie a pasta .antigravity do rv-adv
2. Cole na pasta de configuração do Antigravity

Ou:

1. Edite o arquivo de configuração do Antigravity
2. Adicione referência aos arquivos do projeto

8.4 Testando a integração

1. Abra o Google Antigravity
2. Navegue até o projeto rv-adv
3. Digite uma pergunta:

   Explique a estrutura do projeto rv-adv
   

4. Verifique se a resposta faz referência aos arquivos e módulos corretos

---

9. Resolvendo problemas comuns

Problema 1: "'ag' não é reconhecido como comando"

Causa: O Python não está no PATH ou a instalação falhou.

Solução:

1. Reinicie o Terminal
2. Se continuar, reinstale:

   pip uninstall antigravity-workspace-template
   pip install "git+https://github.com/study8677/antigravity-workspace-template.git#subdirectory=cli"
   

Problema 2: "Module not found: litellm" ou "openai"

Causa: Dependências não instaladas.

Solução:

pip install litellm pydantic openai-agent-sdk

Problema 3: "git: command not found"

Causa: Git não instalado ou não está no PATH.

Solução:

1. Reinicie o computador (isso atualiza o PATH)
2. Se continuar, reinstale o Git marcando "Add to PATH"

Problema 4: "ag-refresh demora muito"

Causa: Projeto muito grande ou API lenta.

Solução:

1. Use –quick para escanear apenas arquivos alterados:

   ag-refresh --quick
   

2. Aumente o timeout no arquivo .env:

   AG_REFRESH_AGENT_TIMEOUT_SECONDS=300
   

Problema 5: "ag-ask retorna respostas genéricas"

Causa: Refresh não foi executado ainda.

Solução:

1. Execute refresh primeiro:

   ag-refresh --workspace .
   

2. Aguarde até completar
3. Tente a pergunta novamente

Problema 6: "API key inválida"

Causa: Chave incorreta ou expirada.

Solução:

1. Verifique a chave no arquivo .env
2. Teste a chave diretamente no site do provedor
3. Gere uma nova chave se necessário

Problema 7: "Python não reconhecido após instalação"

Solução:

1. Pesquise "Python" no Menu Iniciar
2. Clique em "Open MSYS2 MinGW" ou similar
3. Ou use VS Code Terminal que geralmente reconhece Python

---

📊 Resumo dos Comandos Principais

---

🎯 Fluxo de trabalho recomendado para rv-adv

Dia 1 - Setup:

cd C:\caminho\para\rv-adv
ag init .

Dia 1-2 - Gerar conhecimento:

ag-refresh --workspace .

(Aguarde 10-30 minutos)

Uso diário:

ag-ask "Como funciona o módulo de autenticação?"
ag report "Encontrei um bug no arquivo X"

---

🚀 Próximos passos depois deste tutorial

1. Explore o conteúdo gerado:

   • Abra structure.md para ver a estrutura
   • Abra module_registry.md para ver os módulos

2. Configure integrações extras:

   • Para GitNexus (análise de código avançada)
   • Para outras ferramentas (Cursor, VS Code, etc.)

3. Personalize as configurações:

   • Edite AGENTS.md para regras específicas
   • Ajuste timeouts no .env

4. Mantenha atualizado:

   • Execute ag-refresh periodicamente
   • Use ag-refresh --quick para atualizações rápidas

---

📚 Glossário de termos técnicos

---

❓ Precisa de ajuda?

• GitHub do projeto: https://github.com/study8677/antigravity-workspace-template
• Documentação: Procure na pasta docs/ do projeto

---

Parabéns por completar este tutorial! 🎉

Agora você sabe como instalar, configurar e usar o Antigravity Workspace Template no Windows 11. Continue explorando as funcionalidades epersonalizando conforme as necessidades do seu projeto rv-adv!