Módulo 4.2 — Estrutura de pastas

🏛️ clients/<nome>/ — multi-cliente como diretório-cidadão

Cada cliente da iAmasters vira uma pasta de primeira classe dentro de clients/. Não é "uma branch", não é "um workspace separado", não é "um arquivo de config". É um cidadão do filesystem, com mesma forma para todos — garantida por clients/_templates/.

iamasters-os/ └── clients/ ├── _templates/ ← contrato. cópia base de todo cliente novo. │ ├── brand-context/ │ │ ├── voice.md │ │ ├── positioning.md │ │ ├── icp.md │ │ └── assets/ │ ├── projects/ │ │ └── briefs/ │ ├── .claude/ │ │ ├── skills/ │ │ └── commands/ │ └── README.md │ ├── acme-corp/ ← cliente real. herda forma de _templates/ │ ├── brand-context/ │ ├── projects/briefs/lancamento-q3/ │ └── .claude/skills/welcome.md │ ├── nubank-pj/ │ ├── brand-context/ │ ├── projects/briefs/onboarding-2026/ │ └── .claude/ │ └── bemobi/ └── ...

📥 Por que diretório (e não branch/DB)

Git diff legível: mudança em cliente = diff em 1 pasta.
Onboard agente novo: aponta pra clients/acme-corp/ e pronto.
Backup/arquivamento: tar czf acme.tgz clients/acme-corp/.
Sair do cliente: git rm -r clients/foo/. Limpo.

🎯 Regra do `_templates/`

Toda pasta nova de cliente nasce via cp -r _templates/ clients/<novo>/.
Mudança em _templates/ = ADR registrada.
Drift entre clientes vira lint check no CI.
Template é contrato — não sugestão.

💡 Tip — template como contrato

Quando _templates/ é tratado como contrato (com lint que falha se um cliente está fora de forma), o drift entre clientes desaparece. Sem isso, em 6 meses cada cliente vira um floco de neve único e o OS quebra.

🎨 brand-context/ — voz, posicionamento, ICP, assets

Cada cliente carrega sua identidade de marca em arquivos planos que o agente lê antes de qualquer entrega criativa. Quatro arquivos canônicos cobrem 90% dos casos.

clients/acme-corp/ └── brand-context/ ├── voice.md ← tom, palavras proibidas, exemplos do/don't ├── positioning.md ← posicionamento, concorrentes, narrativa-mãe ├── icp.md ← perfil ideal, jobs-to-be-done, objeções └── assets/ ├── logo.svg ├── palette.json ├── fonts/ └── references/ ← screenshots, prints de campanhas anteriores

Arquivo	Responsabilidade	Tamanho ideal
voice.md	Tom + 5 exemplos do/don't + glossário	< 400 tokens
positioning.md	Frase-mãe, concorrentes, diferenciação	< 300 tokens
icp.md	Persona, dores, gatilhos, objeções	< 500 tokens
assets/	Binários (logo, palette, fonts, refs)	< 20 MB

voice.md

Para todo output verbal.

positioning.md

Para estratégia.

icp.md

Para copy + ads.

assets/

Para visual + handoff.

🧠 context/ sectorizado — 8 arquivos, não 1 monolito

Aqui mora o contexto do operador (não do cliente). Quem é você, como trabalha, com quem, o que está priorizando, decisões já tomadas, aprendizados acumulados. Em vez de um CLAUDE.md gigante, são 8 arquivos < 500 tokens cada.

iamasters-os/ └── context/ ├── me.md ← identidade: quem é o operador ├── work.md ← rotina, ferramentas, ritmos ├── team.md ← quem trabalha com você (papéis) ├── current-priorities.md ← top 3-5 do trimestre, vivo ├── goals.md ← OKRs / metas anuais ├── decisions-log.md ← ADR-lite: o que foi decidido e por quê ├── learnings.md ← o que mudou de ideia (vivo) └── soul.md ← princípios, voz pessoal, gostos estéticos

✓ Fazer — context/ sectorizado

✓8 arquivos, cada um < 500 tokens, um assunto cada.
✓Agente carrega só o que precisa via SessionStart hook.
✓Edit cirúrgico — mudar prioridade não toca o resto.
✓Git diff revela qual dimensão mudou.
✓Soul.md fica estável; current-priorities.md muda toda semana.

✗ Evitar — CLAUDE.md monolítico

✗1 arquivo de 5k+ tokens com tudo misturado.
✗Agente carrega tudo, sempre — desperdiça contexto.
✗Editar prioridade arrisca quebrar tom/identidade.
✗Diff vira ruído — impossível revisar.
✗Em 3 meses ninguém quer mais tocar no arquivo.

📊 Dados — sectorizado vence em todo eixo

8 arquivos < 500 tokens = ~4k tokens total, carregamento seletivo via hook reduz para ~1.5k por sessão.
1 arquivo > 5k tokens = sempre carregado integral, ~5k por sessão, 3.3× mais.
Tempo médio de edição: sectorizado 90s, monolito 8min (procurar a seção certa + medo de quebrar vizinhos).
Conflitos de merge: sectorizado < 5%, monolito > 40% quando 2 pessoas tocam na mesma semana.

📋 projects/briefs/<nome>/brief.md com frontmatter

Todo projeto vira uma pasta de brief dentro do cliente. O brief.md carrega frontmatter YAML que o agente parseia para filtrar "o que está vivo agora" (status: active) vs. arquivo histórico.

clients/acme-corp/projects/briefs/ ├── lancamento-q3/ │ ├── brief.md ← status: active │ ├── research/ │ ├── drafts/ │ └── final/ ├── rebrand-2025/ │ └── brief.md ← status: done └── campanha-natal/ └── brief.md ← status: paused

--- title: Lançamento Q3 — produto Aurora client: acme-corp status: active # active | paused | done owner: nei deadline: 2026-09-15 budget_tokens: 250000 related_skills: [six-hats, visual] --- ## Objetivo Lançar Aurora para ICP enterprise até 15/set. ## Critério de pronto - [ ] 3 ângulos de copy testados - [ ] Landing aprovada - [ ] Plano de mídia validado

status: active

Carregado no contexto do agente, aparece em /eod.

status: paused

Indexado, mas não compete por atenção. Some do dashboard.

status: done

Arquivado, vira referência histórica para learnings.md.

💡 Tip — frontmatter é interface

O frontmatter não é decoração — é interface entre humano e agente. Quando você muda status: active → done, o OS inteiro reage: o brief sai do contexto carregado, o orquestrador para de sugerir tarefas dele, o /eod para de listar.

🛠️ .claude/skills/ e .claude/commands/

Skills são capacidades especializadas versionadas em markdown. Commands são atalhos de slash que disparam fluxos. Cada um vive no seu lugar canônico para que o Claude Code descubra automaticamente.

iamasters-os/ └── .claude/ ├── skills/ │ ├── welcome/ │ │ └── SKILL.md ← onboard de qualquer pessoa no OS │ ├── six-hats/ │ │ └── SKILL.md ← análise de De Bono com anti-âncora │ └── visual/ │ └── SKILL.md ← geração de assets visuais (canvas-design) │ └── commands/ ├── eod.md ← /eod — end of day: relatório do dia └── dream.md ← /dream — sessão criativa exploratória

📚 skills/ — capacidades

welcome: primeiro contato. Lê context/me.md e contextualiza.
six-hats: análise multi-perspectiva com isolamento estrito de fases.
visual: dispara canvas-design + brand-context do cliente ativo.
Cada skill = 1 pasta, 1 SKILL.md com frontmatter (name, description, trigger).

⚡ commands/ — atalhos

/eod: varre briefs active, lista o que avançou, o que travou.
/dream: abre sessão sem julgamento, alimenta learnings.md depois.
Versionados no git — todo mundo do time pode invocar.
Discoverable: / no Claude Code lista todos.

welcome

skill de onboarding

six-hats

skill analítica

/eod

comando diário

/dream

comando criativo

⚙️ vendor/sinapsis/ — engine embedded com pin

O Sinapsis (engine de orquestração) é embedded — vive dentro do iAmasters OS em vendor/sinapsis/, com pin de versão explícito. Atualização é deliberada, via bun run vendor:update, nunca automática.

iamasters-os/ ├── vendor/ │ └── sinapsis/ │ ├── .version ← v2.4.1 (pin explícito, commitado) │ ├── src/ │ ├── package.json │ └── README.md │ ├── scripts/ │ └── vendor-update.ts ← controla bun run vendor:update │ └── package.json └── "scripts": { "vendor:update": "bun run scripts/vendor-update.ts" }

🚨 Alerta — vendor sem pin quebra prod

Se você consome Sinapsis via npm install sinapsis@latest ou submodule sem pin, um breaking change upstream entra silenciosamente na próxima instalação. Cliente em produção quebra sem você ter mudado uma linha.

Antídoto: .version committed + vendor:update manual que abre PR com diff legível. Você vê o que mudou antes de aceitar.

🎯 Por que embedded (e não dependência)

Sinapsis é core do OS — não periferia.
Debug profundo: stack trace aponta pra vendor/, lê o código.
Patches locais possíveis sem fork.
Zero surpresa em build/CI offline.

🔄 Fluxo de update

bun run vendor:update busca última versão upstream.
Compara .version atual vs. nova.
Aplica diff, roda testes, abre PR.
Humano revisa changelog + diff antes do merge.

Pin

.version commitado

Embedded

vendor/, não node_modules

Update

manual via bun script

Review

PR com diff legível

🌳 Árvore completa — o iAmasters OS num só print

iamasters-os/ ├── context/ │ ├── me.md │ ├── work.md │ ├── team.md │ ├── current-priorities.md │ ├── goals.md │ ├── decisions-log.md │ ├── learnings.md │ └── soul.md │ ├── clients/ │ ├── _templates/ │ ├── acme-corp/ │ │ ├── brand-context/ │ │ │ ├── voice.md │ │ │ ├── positioning.md │ │ │ ├── icp.md │ │ │ └── assets/ │ │ └── projects/briefs/lancamento-q3/brief.md │ └── nubank-pj/ │ ├── .claude/ │ ├── skills/{welcome,six-hats,visual}/ │ └── commands/{eod.md,dream.md} │ ├── vendor/ │ └── sinapsis/ │ ├── .version │ └── src/ │ ├── scripts/ │ └── vendor-update.ts │ ├── CLAUDE.md ← aponta para context/ + clients/ └── package.json

📝 Resumo do módulo

✓

clients/<nome>/ é cidadão de primeira classe — diretório, não branch nem DB. Forma garantida por _templates/.

✓

brand-context/ isola identidade da marca — voice, positioning, icp, assets. 4 arquivos canônicos.

✓

context/ em 8 arquivos sectorizados — <500 tokens cada, vence o CLAUDE.md monolítico em todo eixo.

✓

briefs com frontmatter — status: active/paused/done vira interface entre humano e OS.

✓

.claude/skills/ + commands/ — welcome, six-hats, visual, /eod, /dream. Versionados, discoverable.

✓

vendor/sinapsis/ com pin — engine embedded, .version commitado, update via bun run vendor:update.

Próximo módulo:

4.3 — Sinapsis engine: como o orquestrador embedded conecta skills, briefs e brand-context em runtime.

← Voltar para Trilha 4 Próximo Módulo →