🧬 Herança CLAUDE.md raiz + cliente
Quando fazes cd clients/acme && claude, o Claude lê dois CLAUDE.md em cascata: o da raiz (instruções gerais) e o do cliente (overrides específicos). Saber a ordem evita conflitos.
CLAUDE.md raiz (do repo)
Regras gerais que se aplicam a TODOS os clientes + ao operador
Idioma, convenções de pastas, install gate, paths, skills registry. Não tem regras específicas de cliente — só sistema.
clients/<X>/CLAUDE.md (do cliente)
Overrides específicos — só ativos quando estás cd no cliente
Nome do cliente, template base, regras particulares ("nunca usar 'vocês' formal"), skills prioritárias, notas operativas, referências ao brand-context do cliente.
brand-context/ + context/ do cliente
Carregados automaticamente pelas skills marketing-*
Voice profile, ICP, positioning, soul, user — todos do cliente. Skills da raiz (.claude/skills/) continuam disponíveis e operam sobre o brand-context do cliente.
💡 Skills custom por cliente
Se um cliente requer skill que NÃO se aplica a outros, cria em clients/<X>/.claude/skills/<categoria>/<nome>/.
Essa skill só está disponível quando estás cd nesse cliente. Não polui os outros nem a raiz.
⚠️ Sinapsis é global
O operator-state.json de Sinapsis é UM, em ~/.claude/skills/, partilhado entre todos os clientes. Aplica-se a ti como operador, não ao cliente. É o esperado — tu és o mesmo profissional para todos.
🔄 Workflow típico (cd, claude, /start-here, /wrap-up)
Um ritual simples que respeita a separação. Sempre cd antes de claude. Sempre /wrap-up antes de mudar de cliente.
Segunda-feira típica · 3 clientes
# Cliente A (freelance-ia) cd clients/acme-corp && claude > /start-here > "Cria post LinkedIn sobre case study X" → marketing-copywriting gera com voice de Acme > /wrap-up exit # Cliente B (agencia-marketing) cd ../widget-shop && claude > /start-here > "Repurpose último vídeo do CEO em 5 peças" → marketing-content-repurposing > /wrap-up exit # Cliente C (consultoria-b2b) cd ../north-star-consult && claude > /start-here > "Redige proposta comercial para novo lead" → marketing-copywriting com registo A formal > /wrap-up exit
✓ Best practices
- ✓Sempre
cdantes declaude - ✓
/wrap-upao mudar de contexto - ✓Brand voice por cliente, não partilhar
- ✓2 terminais para sessões simultâneas
- ✓Backup separado para clientes críticos
✗ Anti-patterns
- ✗Trabalhar cliente desde a raiz do repo
- ✗Mudar de cliente sem wrap-up
- ✗1 sessão a saltar entre clientes
- ✗Copiar voice profile entre clientes
- ✗Esquecer de qual cliente estás (usa
pwd)
🔒 Segurança: separação de info entre clientes
Por design, o OS não partilha info entre clientes automaticamente. O sistema remove a maioria das oportunidades de erro; a disciplina diária é tua.
| Mecanismo | O que protege | Limitação |
|---|---|---|
.gitignore extensivo | Não exporta clientes para git público | Repo privado se quiseres sync |
Skills isoladas por cd | Skills marketing-* só veem o cliente atual | Falha se ignoras a regra do cd |
| update.sh skip user-data | Updates nunca tocam em clients/<X>/ | Templates de _templates/ podem mudar |
| Brand-context separado | Voice/ICP de A não influencia copy de B | Operator-state é global |
| Decisions-log por cliente | Decisões de A não aparecem em B | Decisões pessoais ficam na raiz |
💡 Reutilizar info entre clientes
Se queres usar aprendizagens do cliente A para o cliente B:
- Faz manual e consciente (não acidental)
- Gera "case study anonimizado" como output do cliente A
- Referencia esse case study no cliente B
⚠️ Troubleshooting comum
- "O Claude não aplica voice do cliente" → verifica
pwd(estás no cliente?),voice-profile.mdpreenchido (sem{{...}}),CLAUDE.mddo cliente referencia o path correto. - "Skills da raiz não aparecem" → reinicia Claude Code (Ctrl+C × 2 + claude).
- "Misturo info acidentalmente" → sinal de não respeitar
cd. Sai do Claude entre clientes, NÃO abrir 2 sessões na mesma terminal.
▶️ /start-here ritual diário
Cada sessão começa com /start-here (ou automaticamente no primeiro turno). Em 30s o sistema lê tudo o que precisas saber para arrancar e propõe a tarefa do dia. Funciona por cliente ou na raiz, conforme o cwd.
💡 O que /start-here lê
- •
~/.claude/skills/_operator-state.json— perfil do operador, deteta needsOnboarding - •
context/me.md— identidade (deriva para wizard se vazio) - •
synapsis/daily-summaries/<ONTEM>.md— "For tomorrow" da sessão anterior - •
context/learnings.md— última lição adicionada - •
projects/briefs/*/brief.mdcomstatus: active - •
context/decisions-log.md— últimas 5 decisões
3 modos de cumprimento
# Modo 1 · Continuidade (há daily summary de ontem) "Olá Nei. Ontem fechaste com: blog post Stripe billing (status: pending review). Para hoje propunhas: passá-lo pelo output-verifier e publicar. Continuas com isso, ou mudamos?" # Modo 2 · Projeto ativo sem summary recente "Olá Nei. Tens o projeto **landing-iamasters** aberto na fase copy. Continuas com ele ou vamos a outra coisa?" # Modo 3 · Sem atividade recente "Olá Nei. Em que te ajudo hoje?"
💡 Em multi-cliente
O /start-here lê o contexto do cwd atual. Se estás em clients/acme/, lê só a daily summary, projetos e decisions de Acme. Continuidade preservada por cliente.
⏹️ /wrap-up (commit, daily summary, learnings)
/wrap-up é o ritual de fecho. Sem wrap-up, amanhã não há memória de hoje. 9 passos automáticos, ~1 minuto.
Recap mental + sync skills
Resume o que se completou, o que ficou a meio, o que se aprendeu. Sincroniza skills-catalog.json.
Update CLAUDE.md skills registry
Regenera tabela entre <!-- skills-registry-start --> e end. Sem isto, o registry desincroniza-se do filesystem.
Append learnings (se aplicável)
Se uma skill falhou, append em context/learnings.md com data + razão + fix. Próxima vez essa skill carrega o aprendido.
Gerar daily summary
Cria/atualiza synapsis/daily-summaries/<TODAY>.md com Sessions, Done, Pending, Learnings, Decisions + "For tomorrow" + "Quick resume".
Commit Git (com aprovação)
Mostra git status, propõe mensagem conventional (feat(skills): add X, chore(wrap-up): EOD <data>). Espera "sim" explícito. Nunca push automático.
⚠️ NÃO se invoca automaticamente
Fechar Claude Code com Ctrl+C não dispara wrap-up. Tens de pedi-lo explicitamente. Se esqueces, perdes o daily summary daquela sessão.
💡 Em multi-cliente
Daily summary é gerado por cliente (o cwd determina onde grava). Ao mudar de cliente, faz /wrap-up primeiro para não misturar.
⬆️ update.sh + multi-cliente
bash scripts/update.sh sincroniza o repo com o upstream do iAmasters OS. Nunca toca em user-data — clients/, brand-context/, context/, projects/, .env. Skills custom por cliente também protegidas.
| O que update.sh ATUALIZA | O que update.sh NÃO toca |
|---|---|
| ✅ Skills do repo (.claude/skills/) | ❌ clients/<nome>/ (todos os teus clientes) |
| ✅ Slash commands (.claude/commands/) | ❌ brand-context/ (a tua marca) |
| ✅ Templates de clientes (_templates/) | ❌ context/ (me, work, decisions-log, learnings) |
| ✅ Scripts (install, add-client, etc.) | ❌ projects/ (os teus outputs) |
| ✅ vendor/sinapsis/ (espelho upstream) | ❌ .env (API keys) |
| ✅ CLAUDE.md raiz + docs/ | ❌ clients/<X>/.claude/skills/ (custom) |
📊 Fluxo seguro
git status— commit ou stash tudo o que tens pendente primeirobash scripts/update.sh— faz backup automático antes- Se houver conflitos em ficheiros que editaste, interativo: mantém o teu / aceita upstream / merge
/doctorapós update — confirma que tudo continua válido- Se o state schema mudou (raro),
/install --resumereaplica as fases necessárias
⚠️ Conflict resolution
Se editaste algum ficheiro do sistema, o update deteta conflito e pergunta:
- •[1] Manter o meu — perde fixes do upstream, guarda customização
- •[2] Aceitar upstream — perde a tua edição (backup em
.backup/) - •[3] Merge manual — abre 3-way merge para resolveres
💡 Frequência
Update mensal está bem para a maioria. Se segues o release notes ativamente, semanal. Se nada do que sai te interessa, fica como estás — o OS funciona sem updates.
✅ Resumo do Módulo
Próxima Trilha:
Trilha 6 — Estender: install-skill (skills externas de GitHub), install-mcp (MCP servers), criar a tua skill própria e contribuir ao catálogo.