Parei de tratar IA como chat: como configurei o Claude pra nunca explicar contexto duas vezes

Antes de mais nada

Hoje atuo como Senior Product Designer na Stone, construindo e redefinindo Renegociação de Crédito e uso o Claude em quase tudo: pesquisa, PRDs, geração de telas no figma, revisão de copy, análise de amplitude, deploy de protótipos. Esta página documenta como cheguei nessa estrutura para que outros designers possam copiar, adaptar e evoluir no próprio fluxo.

Durante a leitura, você vai se deparar com diversos termos (CLAUDE.md, MCP, hook, skill, agente, memory), mas cada um virá explicado em seguida. Se você nunca configurou um LLM além de pedir prompt no chat, a ideia é que você entenda.

Antes das camadas, o que é o harness?

No Claude Code, o harness é o CLI (ou app desktop) e ele faz, em cada turno:

• Lê o CLAUDE.md (global + projeto) e injeta no system prompt
• Carrega context/, memória relevante e a lista de skills disponíveis
• Expõe as tools pro modelo (Read, Edit, Bash, MCPs, sub-agentes)
• Pode delegar tarefas a sub-agentes, instâncias paralelas com contexto próprio que fazem o trabalho pesado (varrer arquivos, localizar código, revisar um diff) e devolvem só a conclusão, sem inchar o contexto principal
• Executa as chamadas de ferramenta e devolve o resultado pro modelo no próximo turno
• Dispara hooks no ciclo de vida (SessionStart, UserPromptSubmit, PostToolUse…)
• Compacta a conversa quando a janela de contexto enche, sem perder o fio da meada

Modelo mental: as 5 camadas

As 5 camadas se complementam:

1. CLAUDE.md: o briefing permanente (regras de comportamento)
2. Context: quem eu sou, o que faço, prioridades
3. Memory: fatos que o assistente coletou e quer lembrar
4. Skills: playbooks especializados (PRD, ideação, content review…)
5. MCPs e Hooks: conexão com ferramentas externas e automações

Duas peças orbitam as camadas: o vault Obsidian (conhecimento de domínio, indexado por _INDEX.md) que alimenta a sessão como fonte, e os sub-agentes que a sessão aciona pra trabalho pesado (varrer arquivos, revisar diff) sem inchar o contexto principal.

Tudo vive em arquivos Markdown no meu computador, versionável e portátil.

Camada 1: CLAUDE.md

Existem dois níveis:

• Global (~/.claude/CLAUDE.md): regras que valem para todos os projetos. No meu, ficam coisas tipo "pense antes de codar", "mude só o que precisa", "defina critério de sucesso antes de executar".
• Por projeto (./CLAUDE.md na raiz do repo): regras específicas daquele workspace. No meu workspace de design (ai-studio/) ficam coisas tipo "sempre use_figma, nunca generate_figma_design", "zero placeholders", "acentos obrigatórios em pt-BR".

Camada 2: Context

No meu setup tenho 4 arquivos:

O CLAUDE.md tem uma instrução explícita: "carregar context/ no boot antes de propor qualquer abordagem". Ou seja, o assistente nunca começa do zero, ele já sabe que estou no Q2, que minha prioridade é o Portal de Reneg, e que devo provocar premissas com 3 perguntas específicas (já pensamos isso de outra forma? dá pra experimentar em prod? temos dados colhendo?).

Camada 3: Memory

A memória é dividida em 4 tipos:

• user: fatos sobre quem eu sou (perfil, role, ferramentas)
• feedback: correções e validações de approach ("não mocke banco em teste", "o PR único foi a chamada certa")
• project: estado de iniciativas ativas ("freeze de merge começa em 05/03", "4 decisões pendentes na persona sintética")
• reference: onde encontrar coisas em sistemas externos ("bugs de pipeline ficam no projeto Linear INGEST")

O valor real aparece da terceira sessão em diante. O assistente já sabe que:

• eu sou direto e gosto de coach provocativo;
• placeholder em tela é gatilho de irritação;
• deploy em Vercel só rola com npm run build local antes;

Nada disso eu repito mais. Quando contradiz a realidade, eu falo "isso mudou" e a memória é atualizada.

Camada 4: Skills

Skills minhas (customizadas para o trabalho de design na Stone):

Mais um punhado de skills de terceiros (figma-use, frontend-design, deploy-to-vercel, web-design-guidelines, deep-research) que vieram via marketplace.

Camada 5: MCPs e Hooks

MCPs que tenho ligados:

• figma-remote-mcp: ler e escrever no Figma (foi como esta página inclusive teve telas planejadas em outros fluxos)
• Amplitude: consultar eventos, funis, dashboards
• Vercel: análise de sessões e funis do meu protótipo de Portal de Reneg

Meu hook mais útil hoje é o de SessionStart que injeta no início de toda sessão a lista de "tópicos abertos", discussões que ficaram pendentes em sessões anteriores. Exemplo real do que apareceu no boot desta sessão:

📌 Tópicos abertos:
  - topic_harness_estudo.md: Bruno quer aprofundar entendimento
    sobre harness do Claude Code
  - topic_heatmap_portal_reneg.md: Tópico aberto: escolher
    abordagem de heatmap pro protótipo portal-reneg

Sem esse hook, eu esqueceria que esses tópicos existem. Com ele, eles voltam à mesa toda sessão.

Outro hook que rodo é um par SessionStart + UserPromptSubmit que liga um modo de comunicação comprimido ("caveman mode"): o assistente responde em telegrama, cortando artigo e floreio pra gastar menos token sem perder a substância técnica. É exemplo de como hook molda a forma da resposta, não só o que entra de contexto.

Onde fica o conhecimento de domínio

Fora das 5 camadas que ensinam o Claude como trabalhar, eu mantenho um vault Obsidian (repo-obsidian/second-brain/) onde fica o conhecimento bruto: fluxogramas, refs do design system Jade e Ginga, PRDs antigos, transcrições de pesquisa, glossário de Crédito, FAQs.

A estrutura segue o método PARA (Projects, Areas, Resources, Archives), adaptado:

• 00 - Index: MOCs (mapas de conteúdo) por tema
• 01 - Diário: log do dia a dia
• 02 - Áreas: responsabilidades contínuas
• 03 - Projetos: iniciativas com fim definido (inclui as skills como sub-pastas)
• 04 - Recursos: guias operacionais e conhecimento de domínio
• 05 - Rituais: OKRs, planning, tasks de Jira
• 06 - Entregas: outputs prontos
• 07 - Carreira: painel de evolução (entregas, metas, 1:1)
• 99 - Arquivo: congelado

Camada de busca, índice gerado: conforme o vault cresceu, varrer pasta por pasta ficou caro (gasta token e às vezes abre o arquivo errado). Resolvi com um índice: um script (gerar-index.sh) varre todas as notas e monta um _INDEX.md com uma linha por arquivo (caminho: primeiro heading). A regra virou "leia o _INDEX.md primeiro, depois abra só o path exato". É RAG manual e barato: índice antes de leitura.

O Claude lê esse vault como fonte sempre que precisa de um dado de domínio: "qual é o token de cor de erro no Jade?", "qual a estrutura padrão de FAQ Stone?", "o que ficou definido no critique de 14 de maio?"

Por que Markdown e arquivos locais

Razões:

1. Versionável com git: toda mudança fica rastreada. Quando uma regra do CLAUDE.md piora as respostas, eu reverto.
2. Portátil: se amanhã eu trocar de assistente (Claude → outro), os arquivos continuam legíveis. Conhecimento não fica refém de uma ferramenta.
3. Legível por humano e por máquina: Markdown é simples o suficiente pra eu editar no Obsidian e estruturado o suficiente pra IA parsear.
4. Composição: um arquivo pode referenciar outro com [[link]]. Memórias linkam pra memórias. Skills referenciam pastas do vault. O sistema vira grafo, não pasta plana.
5. Sem lock-in de plataforma: se a Anthropic mudar drasticamente o Claude Code amanhã, eu não perco nada. Markdown sobrevive a qualquer migração.

Como designer, faz total sentido. A gente já trabalha com design tokens (variáveis exportáveis), design system docs (Markdown no Storybook/Zeroheight), handoff em texto estruturado. Tratar o assistente de IA com o mesmo cuidado é continuidade, não novidade.

Passo a passo: como replicar

1. Instale o Claude Code

npm install -g @anthropic-ai/claude-code

Ou baixe o app desktop: claude.com/claude-code.

2. Crie o CLAUDE.md global

No terminal:

mkdir -p ~/.claude
open ~/.claude/CLAUDE.md

Comece com 3-5 regras de comportamento. Sugestão de partida para designer:

# CLAUDE.md (global)

## 1. Pense antes de codar
- Diga suas premissas explicitamente. Se incerto, pergunte.
- Se houver caminho mais simples, fale antes de implementar.

## 2. Simplicidade primeiro
- Mínimo de código pra resolver. Nada especulativo.
- Sem abstração pra código de uso único.

## 3. Mudanças cirúrgicas
- Toque só no que pede o pedido.
- Match o estilo existente, mesmo que você faça diferente.

## 4. Critério de sucesso definido
- Transforme "fazer X" em "X funciona quando [check verificável]".

Não precisa ser perfeito. Você vai evoluir.

3. Crie a pasta context/ no seu projeto principal

Na raiz do seu repositório de trabalho (pode ser uma pasta do Obsidian, do design system, ou um repo dedicado):

mkdir -p .claude/context
touch .claude/context/me.md
touch .claude/context/work.md
touch .claude/context/goals.md

E crie um CLAUDE.md na raiz desse projeto com uma única instrução de boot:

# CLAUDE.md

## Boot: ler no início de cada sessão

- `.claude/context/me.md`: quem eu sou
- `.claude/context/work.md`: o que faço
- `.claude/context/goals.md`: prioridades atuais

Preencha os 3 arquivos. Não tente ficar perfeito, comece com 10 bullets em cada e evolua.

4. Deixe a memória crescer organicamente

Não escreva memórias manualmente. O sistema de auto-memory funciona assim: você corrige o assistente, ele percebe o padrão, e salva. Quanto mais natural for sua interação ("não faz assim", "isso aqui sim", "esse caminho foi o certo"), mais útil a memória fica.

Depois de 2-3 semanas você vai abrir o MEMORY.md e ver 20+ entradas. Aí dá pra revisar e podar.

5. Adicione MCPs quando aparecer a dor

Não pluga tudo de uma vez. Quando você notar "poxa, queria que o Claude lesse meu Figma diretamente", aí pluga o figma-remote-mcp. Quando notar "queria que ele criasse páginas no Notion", pluga o Notion. Cada MCP tem instrução de instalação no site oficial.

MCPs úteis pra designer:

• figma-remote-mcp: ler/escrever Figma e FigJam
• notion: criar páginas, ler bases
• Amplitude: análise de produto

6. Crie sua primeira skill no terceiro "de novo, por favor"

Quando você se pegar explicando o mesmo passo a passo pela terceira vez ("olha, pra montar PRD a gente faz assim: seção tal, depois tal…"), pare e transforme em skill.

Estrutura mínima:

~/.claude/skills/minha-skill/
├── SKILL.md       ← instruções
└── template.md    ← arquivos de apoio

O SKILL.md precisa de frontmatter com name, description (com triggers!), e depois o passo a passo. O Claude Code descobre skills novas automaticamente.

7. Configure hooks só quando notar fricção

Se você sente "acho que esqueci de algo importante daquela conversa", aí vale um hook de SessionStart que recupera tópicos. Antes disso, é overengineering.

O que NÃO funciona (aviso de quem vem testando muito até agora)

• Misturar regras de comportamento com fatos do projeto: separa CLAUDE.md (comportamento) de context/ (identidade). Bagunçar isso te confunde e confunde o assistente.
• Escrever memórias manualmente. O sistema de auto-memory funciona assim: você corrige o assistente, ele percebe o padrão, e salva. Memória escrita à mão envelhece rápido e ninguém atualiza.
• Criar skill antecipadamente: "e se um dia eu precisar de X?" não justifica skill. Espera a terceira repetição.
• Empilhar 20 MCPs: cada MCP adiciona tools ao contexto e gasta token. Mantém só os que você realmente usa toda semana.
• Achar que o setup é um produto pronto: é um sistema vivo. Toda semana eu reviso e enxugo um pouco.

Para se aprofundar

• Documentação do Claude Code
• Model Context Protocol (MCP), site oficial
• Método PARA, Forte Labs (estrutura do vault Obsidian)
• Obsidian (editor Markdown com grafo de links)
• Harness Design - Um artigo sobre a aplicação em design