🤖 O problema do Claude Code vanilla
O Claude Code é poderoso, mas é amnésico. Cada sessão começa de zero: ele não sabe quem és, que stack usas, que cliente é este, qual a tua voz, que decisões tomaste no mês passado. Tu sabes — mas tens de re-explicar tudo, todos os dias.
💡 Conceito principal
O custo invisível do Claude Code vanilla é o tempo de re-onboarding. Se passas 10-15 min por sessão a explicar contexto, e fazes 4 sessões por dia, perdes 1h diária só a repetir-te.
- •Outputs ficam genéricos (não sabe a tua voz)
- •Decisões anteriores são esquecidas (contradiz-te a ti próprio)
- •Skills úteis não se ativam (não sabe que existem)
✓ Com iAmasters OS
- ✓Memória persistente entre sessões (Sinapsis)
- ✓Skills ativam-se sozinhas pelo description
- ✓Brand voice carregada automaticamente
- ✓Decisions-log mantém coerência
✗ Sem OS (vanilla)
- ✗Re-explicas stack/contexto cada sessão
- ✗Pides skills uma a uma manualmente
- ✗Outputs em "tom IA genérico"
- ✗Decisões esquecidas → contradições
🏗️ As 3 camadas do OS
O iAmasters OS empilha três camadas independentes. Cada uma resolve um problema, e juntas formam o sistema completo. Conhecer a separação ajuda-te a debugar quando algo falha.
🧠 Sinapsis (engine de memória)
Vendorizado intacto de vendor/sinapsis/ · instalado em ~/.claude/
Operator state global, instincts auto-aprendidos, skills on-demand, dashboard, dream cycle. Original do Luis Pitik. Aplica-se a TODOS os teus repos Claude Code, não só ao iAmasters OS.
📦 Camada OS (estrutura do repo)
brand-context/ · context/ · projects/ · clients/
Brand context (voice + 3 registos + ICP + positioning), agent context setorizado (me, work, team, current-priorities, goals), projetos estruturados, e multi-cliente com 4 templates verticais.
🎯 Skills curadas + commands + scripts
.claude/skills/ · .claude/commands/ · scripts/
23 skills validadas (marketing, automation, strategy, tools, visualization, _meta) + 10 slash commands + scripts de gestão (install, add-client, update, validate-skill).
💡 Dica prática
Quando algo falha, pergunta-te: "Isto vem do Sinapsis, da Camada OS ou de uma Skill?". A resposta diz-te onde procurar. Sinapsis em ~/.claude/. Resto no repo.
📁 Estrutura do repo
Saber a árvore canónica permite-te encontrar tudo em segundos e — mais importante — saber o que NÃO tocar e o que entra no git público vs privado.
iamasters-os/
├── CLAUDE.md # Constituição (lida em cada sessão)
├── README.md
├── .claude/
│ ├── settings.json # Hooks + permissões
│ ├── commands/ # 10 slash commands
│ └── skills/ # 23 skills curadas
│ ├── _meta/ # Sistema e rituais
│ ├── marketing/ # 6 skills (voice, copy, ICP...)
│ ├── automation/ # 2 skills (n8n)
│ ├── strategy/ # 1 skill (web-research)
│ ├── tools/ # 3 skills (humanizer, verifier...)
│ └── visualization/ # 1 skill (visual-explainer)
│
├── brand-context/ # 🔒 Privado (.gitignore)
│ ├── voice/ # Profile + 3 registos
│ ├── positioning/
│ └── icp/
│
├── context/ # 🔒 Privado (parcial)
│ ├── soul.md # Personalidade agente (público)
│ ├── me.md # Identidade (privado)
│ ├── work.md # Negócio (privado)
│ ├── decisions-log.md # Diário (privado)
│ └── learnings.md # Feedback skills
│
├── clients/ # 🔒 Privado (multi-cliente)
│ └── _templates/ # 4 verticais (público)
│
├── scripts/ # Installer, add-client, etc.
└── vendor/
└── sinapsis/ # 🚫 NÃO TOCAR — engine vendorizado
⚠️ Atenção
NUNCA edites vendor/sinapsis/ diretamente. É um espelho do upstream do Luis Pitik. Modificações são perdidas em cada update.sh. Se precisas mudar Sinapsis, abre issue lá.
⚡ Como skills se ativam sozinhas
Não chamas skills. Elas encontram-te. O segredo está no description: do frontmatter de cada SKILL.md.
Anatomia de uma SKILL.md
--- name: marketing-copywriting description: Gera copy para LinkedIn, blog, email, ads com brand voice carregada + register auto-detetado. Invoca tool-output-verifier antes de entregar. --- # marketing-copywriting ## Quando se invoca - Quando pedes "escreve post LinkedIn sobre..." - Quando pedes "email frio para..." - Quando outra skill (content-repurposing) precisa de copy ## Process ...
📊 O que o Claude faz
- Ao iniciar sessão, lê todas as
description:de todas as SKILL.md - Cada vez que escreves, faz matching semântico contra essas descriptions
- Se uma encaixa, ativa-a → lê o Process e segue os passos
- Se nenhuma encaixa, responde com o conhecimento geral
Resultado: tu pedes em linguagem natural, ele escolhe a ferramenta certa.
💡 Dica prática
Description ideal: 50-500 caracteres, com verbo de intenção (cria, gera, analisa, valida) e quando ativar ("quando pedes X, quando aparece Y"). Sem isso, a skill nunca ativa.
📦 Vendoring intacto do Sinapsis
Sinapsis vive em vendor/sinapsis/ como espelho intacto do upstream do Luis Pitik. Vendoring lock-free: o iAmasters OS adiciona uma camada por cima, não modifica o que o Luis publica.
✓ Vantagens
- ✓Updates do upstream chegam sem conflitos
- ✓O Luis continua a manter o engine, tu focas-te na camada
- ✓Bugs upstream resolvem-se onde fazem sentido (lá)
✗ Tentações a evitar
- ✗Editar diretamente um ficheiro Sinapsis
- ✗"Vou só comentar esta linha rápido"
- ✗Modificar hooks/scripts sem documentar
💡 Se precisas mudar Sinapsis
Abre issue em github.com/Luispitik/sinapsis ou faz fork. Mudanças locais perdem-se no próximo update.sh.
🌱 Filosofia "sistema vivo"
O OS não é um produto fechado. É um substrato. As 23 skills core são só o ponto de partida. O catálogo cresce com a comunidade — e tu fazes parte dela.
🔌 Skills via /install-skill
Qualquer URL GitHub que cumpra a estrutura mínima (SKILL.md com frontmatter válido) pode ser instalada. O comando valida localmente antes de globalizar. Anti-inflação built-in.
🔧 MCPs via /install-mcp
Lista curada (Firecrawl, n8n-mcp, GitHub MCP, etc.) ou URL custom. Configura permissões + env vars automaticamente em .mcp.json do projeto.
📚 Catálogo curado da comunidade
Ver docs/skills-recommended.md. Skills de membros da iAmasters Academy que passaram revisão. Quando criares a tua, contribui com PR.
💡 Cultura de fork
Não consumas passivamente. Quando uma skill core não te serve, copia para .claude/skills/_custom/, edita, e (se for útil) abre PR. Quem partilha, multiplica.
✅ Resumo do Módulo
Próximo Módulo:
1.2 — Para quem é + custo real: 4 avatares, custo Anthropic Pro/Max, prerequisitos técnicos.