Imersão IA - ParisGroup AI
Repositório central da Imersão de IA. Contém o instalador do ambiente e um plugin de skills de IA curadas para turbinar seu desenvolvimento com Claude Code e Codex.
1. Instalação do Ambiente
Para configurar seu Mac com todas as ferramentas necessárias, cole o comando abaixo no Terminal:
curl -fsSL https://raw.githubusercontent.com/parisgroup-ai/imersao-ia-setup/main/instalar_imersao.sh | bashO que será instalado:
- Xcode Command Line Tools — Git e compilador nativo
- Homebrew — gerenciador de pacotes
- Node.js — runtime JavaScript (necessário para Claude Code, Codex, ToStudy CLI e a statusline)
- GitHub CLI (
gh) — autenticação e operações no GitHub pelo terminal - Ghostty — terminal moderno e otimizado
- Docker Desktop — containerização e orquestração
- Obsidian — notas e base de conhecimento
- Claude Desktop — app desktop do Claude
- Nerd Font (MesloLG) — fonte com ícones, usada pela statusline
- Claude Code — CLI do Claude (npm)
- Codex CLI — CLI do OpenAI Codex (npm)
- ToStudy CLI — CLI dos cursos da imersão,
@tostudy-ai/cli(npm) - Skills da Imersão — instaladas automaticamente como plugin do Claude Code (passo 9 do instalador)
- jq — processador de JSON de linha de comando (usado para ligar a statusline no
settings.json) - Statusline da ParisGroup — statusline do Claude Code (contexto, modelo, git, custo), baixada do repo público e já ligada no
~/.claude/settings.json
O script verifica cada item e pula os que já estão instalados. Ao final, feche e reabra o terminal (ou o Claude Code) para carregar tudo. Pode levar alguns minutos — siga as instruções na tela e forneça sua senha quando pedida.
> O instalador configura o npm para instalar pacotes globais no seu usuário (~/.npm-global), evitando sudo npm install -g — que costuma quebrar atualizações futuras.
> A statusline já vem ligada no seu ~/.claude/settings.json (só é adicionada se você ainda não tiver uma). Para customizar segmentos, cores ou desligar, veja o repositório da statusline.
Instalou e travou em algo? Veja docs/PRIMEIROS-PASSOS.md (o que fazer depois do setup) e docs/TROUBLESHOOTING.md (erros comuns). Para re-checar o ambiente a qualquer momento:
curl -fsSL https://raw.githubusercontent.com/parisgroup-ai/imersao-ia-setup/main/scripts/check.sh | bash2. Claude Code Setup (oficial) antes de plugins
> Ordem correta: (1) Claude Code instalado e logado → (2) Claude Code Setup (plugin oficial Anthropic, se disponível no seu ambiente) → (3) só então plugins curados da imersão. > Evite instalar dezenas de plugins aleatórios (“plugin soup”): o setup fica lento e você extrai pouco valor.
Dentro do Claude Code (marketplace oficial Anthropic):
/plugin- Aba Discover / marketplace
claude-plugins-official - Procure o plugin de setup / configuração do projeto (Claude Code Setup) e instale se aparecer na sua versão
- Docs: https://code.claude.com/docs/en/discover-plugins
Depois disso, instale apenas o plugin da imersão (abaixo). Lista curta recomendada na imersão:
| Plugin | Quando | |--------|--------| | imersao@imersao-ia (este repo) | Sempre — pipeline da imersão | | GitHub (github@claude-plugins-official) | Se for usar Issues/PRs do terminal | | Não instale “packs” genéricos de dezenas de skills | Só com indicação do instrutor |
3. Skills de IA (plugin da imersão)
As skills são distribuídas como um plugin do Claude Code via marketplace. Não é preciso copiar pastas à mão: o Claude Code descobre cada skill automaticamente, e você atualiza ou desinstala com um comando.
O instalador já faz isso por você. Se quiser instalar manualmente (ou em outra máquina), dentro do Claude Code rode:
/plugin marketplace add https://github.com/parisgroup-ai/imersao-ia-setup
/plugin install imersao@imersao-iaOu pelo terminal, com o CLI:
claude plugin marketplace add https://github.com/parisgroup-ai/imersao-ia-setup
claude plugin install imersao@imersao-iaReinicie o Claude Code para carregar as skills.
Codex
Plugins são um recurso do Claude Code. Para usar as mesmas skills no Codex, rode o script de sincronização (copia as skills para ~/.codex/skills/):
curl -fsSL https://raw.githubusercontent.com/parisgroup-ai/imersao-ia-setup/main/scripts/sync-codex-skills.sh | bash4. Processo da Imersão (do PRD ao app)
O plugin traz um pipeline guiado que leva da ideia a um app no ar, em 4 fases sobre um motor autônomo (/imersao:pg-imersao-goal, com 2 gates humanos).
👉 Comece por /imersao:pg-imersao-start — a bússola mostra os 4 passos e diz qual é o próximo (sem executar por você; quem roda cada fase é o aluno, de propósito):
| Comando | Fase | O que faz | |---|---|---| | /imersao:pg-imersao-start | 👈 | Comece aqui — bússola dos 4 passos | | /imersao:pg-imersao-prd | 1 | Ideia → docs/plano-do-produto.md (conversa guiada) | | /imersao:pg-imersao-prototipo | 2 | Plano → protótipo no Design OS público → export React + Tailwind | | /imersao:pg-imersao-implementar | 3 | Export + plano → app Next.js + Tailwind + shadcn/ui + Drizzle + Postgres (Docker) | | /imersao:pg-imersao-publicar | 4 | App → no ar: push pro GitHub + deploy no Railway |
> Contas: Claude Max $200/mês (obrigatório), GitHub (grátis) e Railway (Hobby $5/mês, exige cartão — dá pra testar o deploy no Trial grátis sem cartão) — crie antes de começar.
Passo a passo completo (aluno + instrutor): docs/PROCESSO-IMERSAO.md.
5. Gerenciar skills
| Ação | Comando (dentro do Claude Code) | Comando (CLI) | |------|----------------------------------|----------------| | Listar instaladas | /plugin | claude plugin list | | Ver detalhes | — | claude plugin details imersao | | Atualizar | /plugin → update | claude plugin update imersao | | Desinstalar | /plugin | claude plugin uninstall imersao |
/plugin sempre mostra a lista completa e atualizada das skills do plugin — não há tabela neste README para ficar desatualizada.
6. Skills disponíveis
Dezenas de skills curadas, organizadas por área. Use /plugin (ou veja plugins/imersao/skills/) para a lista completa e sempre atualizada. Um panorama:
- Contexto & Documentação —
agents-maintenance,context-maintenance,memory-bank,obsidian-docs,readme-maintenance,prompt-maintenance - Arquitetura & Design —
api-design,clean-architecture,database-design,redis-design,logger-design,github-design,security-practices - Qualidade de Código —
code-quality,code-consolidation,reviewer - Testes & Cobertura —
testing-strategy,coverage-run,coverage-report,coverage-check - E2E (web) & Mobile —
e2e-run,e2e-architect,e2e-chrome-devtools,maestro-run,maestro-capture,mobile-native-bestpractices,pwa-audit,qa-mobile,design-critic - DevOps, Release & Logs —
docker-devops,ci-fix,project-release,project-stats,tag-audit,log-audit,railway-debug - i18n, SaaS & Lançamento —
i18n-audit,i18n-maintenance,launch-audit,saas-bootstrap,saas-migration-audit - Produtividade & Time —
tasknotes,sprint-report,weekly-metrics,session-close,team-plan,team-execute,team-reviewer
6. Formato das Skills
Cada skill é uma pasta plugins/imersao/skills/<nome>/ com um SKILL.md. O frontmatter YAML precisa de name e description — é só isso que o Claude Code usa para descobrir e acionar a skill:
---
name: minha-skill
description: "O que a skill faz e QUANDO usá-la (gatilhos em PT-BR e EN ajudam na descoberta)"
---
# Minha Skill
Conteúdo em Markdown: instruções passo a passo, exemplos de código,
padrões, boas práticas e checklist de validação.Campos como version, author e tags são opcionais e decorativos — o runtime não depende deles. A versão oficial do plugin fica em plugins/imersao/.claude-plugin/plugin.json. Veja schema/skill-schema.yml para o contrato completo.
6. Contribuindo
Para adicionar ou melhorar uma skill:
1. Faça um fork ou crie um branch em parisgroup-ai/imersao-ia-setup. 2. Crie/edite plugins/imersao/skills/<nome>/SKILL.md com frontmatter name + description válido. 3. Rode a validação local: bash scripts/validate-skills.sh. 4. Abra um Pull Request. O CI valida os manifestos e o frontmatter automaticamente.
Depois do merge, quem já instalou o plugin recebe a novidade com claude plugin update imersao (ou /plugin → update). Sem cópia manual, sem tabela para manter.
---
Dúvidas? Explore os exemplos em plugins/imersao/skills/. Cada skill tem documentação completa.
Nos vemos na imersão! 🚀
