Como usar o gstack em equipe: o que o team mode faz no repositório compartilhado?

Fala aí, beleza? Sabe aquele cenário clássico: três devs no mesmo repositório, um com o setup de IA configurado, outro com uma versão de seis meses atrás e o terceiro com nada

Aí cada um gera código de um jeito, com regra diferente, e a review vira terapia em grupo kkk

Segundo o próprio repositório oficial no GitHub, o gstack é o setup de Claude Code aberto por Garry Tan, presidente e CEO da Y Combinator, mantido em garrytan/gstack

A descrição oficial do repositório fala em 23 ferramentas opinativas que atuam como CEO, Designer, Eng Manager, Release Manager, Doc Engineer e QA

E o negócio pegou: são cerca de 129 mil estrelas no GitHub

Só que instalar na sua máquina resolve o SEU problema, não o do time

É exatamente aí que entra o team mode, e é isso que vamos montar aqui: o gstack rodando no repositório compartilhado, igual pra todo mundo

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

O que você precisa antes de rodar o gstack em equipe

A lista é curta, mas ela é obrigatória:

• Git
• Bun 1.0 ou superior
• Claude Code instalado e funcionando

E por que diabos o Bun aparece aqui, se o gstack é um pacote de skills?

Porque o setup compila um binário nativo durante a instalação, usado pela skill de navegação (/browse)

Sem Bun, esse passo não acontece

Tome cuidado com isso na hora de levar pro time: cada pessoa precisa cumprir os mesmos três pré-requisitos na máquina dela

Não adianta você commitar tudo bonitinho e o colega tentar rodar sem Bun, o passo dele simplesmente falha e ele vai te chamar no direct achando que a config tá quebrada 😅

Se o teu time já sofre pra manter o agente igual entre as máquinas, esse papo de padronizar o Claude Code entre vários devs é a base de tudo que vem abaixo

Como ativar o team mode do gstack passo a passo

Bora ver na prática

1. Rode o script de setup com a flag de time

./setup --team

Esse é o comando que liga o modo equipe, e ele vale por máquina: agora você está rodando ele na SUA

Ele registra um hook SessionStart que atualiza o gstack automaticamente no início da sessão, com throttle de uma checagem por hora

Em outras palavras: você abre o Claude Code e ele já se encarrega de estar na versão certa, sem você lembrar de nada

O hook é silencioso e tolerante a falha de rede, então não é aquele processo chato que trava a abertura da sessão

Erro comum deste passo: rodar o setup sem os pré-requisitos prontos, principalmente o Bun, e achar que o team mode não funciona

2. Faça o bootstrap do repositório com o gstack-team-init

gstack-team-init

Esse comando roda dentro do repositório do projeto

É ele que prepara o repo pra que os colegas de time recebam o gstack automaticamente

Erro comum deste passo: rodar o gstack-team-init fora do repositório, num diretório qualquer do sistema, e depois não achar a configuração no projeto

3. Escolha entre required e optional

São os dois modos do bootstrap

No optional, o gstack é apenas recomendado no CLAUDE.md

No required, ele é imposto via hooks

Comparo os dois na seção seguinte, mas a decisão acontece aqui

4. No modo required, confira o hook de checagem

O gstack-team-init em modo required cria o script .claude/hooks/check-gstack.sh e registra ele como hook PreToolUse em .claude/settings.json

A função dele é bloquear o uso das ferramentas de IA quando o gstack não está instalado

Vale abrir o .claude/settings.json e confirmar que o registro está lá antes de commitar

Erro comum deste passo: commitar a configuração e esquecer o .claude/hooks/check-gstack.sh fora do commit, o que deixa o hook registrado apontando pra um script que não existe na máquina do colega

5. Commite a configuração e peça pro time rodar o setup

git add .claude/ .gitignore CLAUDE.md

Aí é só commitar esses arquivos e subir pro repositório

Depois disso, cada dev do time repete na máquina dele o mesmo passo 1 que você já fez aqui: rodar o ./setup --team

Essa é a parte que o pessoal esquece: a configuração vai pro repo, mas a instalação continua sendo de cada um

Erro comum deste passo: avisar no grupo "tá commitado, é só dar pull" e ninguém rodar o setup, aí o modo required começa a bloquear as ferramentas e a culpa cai no gstack haha

Required ou optional: qual modo escolher para o seu time

Os dois modos existem porque time é gente, e gente tem contexto diferente

O optional combina com time pequeno e alinhado, aquele grupo de três ou quatro pessoas que conversa o dia inteiro

A recomendação no CLAUDE.md já resolve, porque o próprio agente lê ali qual é o padrão da casa

O required faz mais sentido em time grande, com gente entrando e saindo

Quem chega no onboarding não sabe que o padrão existe, e o hook conta pra ele no primeiro uso, em vez de descobrirem três PRs depois

E repositório com contribuidor externo? Aí a conversa muda de figura

Bloquear ferramenta pra quem só quer mandar uma correção pontual pode ser fricção demais

Pensa em quem paga o custo do bloqueio antes de escolher, porque required é imposição mesmo, não é sugestão simpática

Como migrar do gstack vendorizado para o team mode

Se você conhece aquela prática de copiar a lib inteira pra dentro do projeto (vendoring), é isso

O gstack já teve esse caminho, mas vendorizar o gstack dentro do repositório do projeto está deprecado

O motivo é bem direto: as cópias vendorizadas não são mantidas atualizadas, e o projeto vai ficando pra trás enquanto o upstream anda

A recomendação atual é instalação global mais ./setup --team

A migração é curtinha:

1. Commite a configuração de team mode

git add .claude/ .gitignore CLAUDE.md
git commit -m "chore: migrate gstack from vendored to team mode"

2. Cada dev roda o setup em modo equipe

./setup --team

E o upgrade de quem já tinha coisa instalada?

A skill gstack-upgrade detecta o tipo de instalação (global ou vendorizada no projeto) e roda o upgrade de acordo

Ela é transacional: se der ruim no meio, tem restauração via .bak

Erro comum desta migração: deixar a cópia vendorizada velha convivendo com a instalação global

Aí você tem duas fontes de verdade brigando, e a que o time enxerga pode não ser a que você atualizou

Se a ideia de manter o padrão fora do projeto te agrada, o mesmo raciocínio vale pra manter suas skills num repositório central

Como controlar o auto update do gstack no time

Auto update automático assusta bastante gente, e com razão: ninguém quer a ferramenta mudando debaixo do pé no meio de uma entrega

A boa notícia é que dá pra controlar

O auto upgrade é configurável pela variável de ambiente GSTACK_AUTO_UPGRADE ou pelo gstack-config, na opção auto_upgrade

E tem adiamento escalonado: você pode dar snooze de 24h, depois 48h e depois 1 semana

Ou seja, dá pra segurar a onda numa semana de release sem desligar tudo pra sempre

Sobre o hook SessionStart que o ./setup --team registra, dois detalhes importam pro time:

• ele é silencioso, não fica poluindo o começo da sessão
• ele é tolerante a falha de rede, então quem está offline não fica preso esperando uma checagem que nunca volta

Somando isso ao throttle de uma checagem por hora, o custo pro dia a dia é baixo

Erro comum aqui: virar o rei do snooze

Adia 24h, adia 48h, adia mais uma semana, e quando você vê cada máquina do time está num estado diferente de novo

Que é exatamente o problema que o team mode veio matar, né? 😅

Veja o gstack funcionando na prática

Pra começar do zero com o gstack antes de padronizar o time, esse vídeo do canal mostra o pacote em ação e as skills rodando dentro do Claude Code

Conclusão

A sacada do team mode é o que ele NÃO deixa no seu projeto

Em team mode não ficam arquivos do gstack vendorizados no repositório: a instalação global é a fonte única de verdade

Sem version drift, sem upgrade manual, sem aquele diretório gigante de ferramenta entrando no diff do PR

Recapitulando o combo: ./setup --team liga o modo equipe em cada máquina e registra o hook SessionStart de atualização, o gstack-team-init prepara o repositório, e a escolha entre optional e required define se o padrão é recomendado no CLAUDE.md ou imposto via hook PreToolUse

Meu veredito: se o teu time já vive o problema das versões diferentes, vale ligar, porque o custo do setup é pequeno perto da confusão que ele evita

Seu próximo passo é bem concreto:

1. rode ./setup --team na sua máquina
2. rode gstack-team-init dentro do repositório do time
3. decida entre optional e required ANTES de commitar

Depois é só avisar a galera pra rodar o setup na máquina de cada um, e o time inteiro passa a trabalhar com o mesmo padrão

Começa pelo optional se o teu time for pequeno, dá pra apertar o parafuso depois…

Até o próximo post! 🙂