Um segundo cérebro no Claude Code: como criar a estrutura numa hora

Documentação de referência da Ailoot: ailoot.ai/docs/.

Porque é que o Claude Code precisa de um segundo cérebro e o que é essencial?#

Abre o Claude Code na terça-feira. Explica: este é o projeto, este é o público, não faças isto. Trabalham juntos. Na quinta-feira, é uma conversa nova e tem de explicar tudo outra vez.

Se tem um CLAUDE.md, resolveu a primeira fonte de frustração. As regras básicas e a descrição do projeto ficam num único ficheiro, que é carregado em todas as sessões. Expliquei como funciona este ficheiro no meu guia sobre CLAUDE.md — pode lê-lo primeiro para estabelecer as bases.

Mas o CLAUDE.md é um manual de instruções para um novo funcionário. Como se vestir, que tom usar com os clientes, que comandos utilizar para publicar. Isso não chega para tomar boas decisões sobre o projeto. As decisões exigem conhecimento: o que é o produto, quem é o público, como funciona a economia, o que tentou e o que não resultou.

Na experiência do autor descrita aqui, esse conhecimento costumava estar em quatro sítios: na sua cabeça, em conversas no Telegram, em documentos Google e na cabeça dos funcionários. Um mês depois de uma decisão, ninguém se lembrava do motivo por que tinha sido tomada. Uma pessoa nova passava uma hora a fazer perguntas à equipa para se pôr a par. O Claude não fazia sequer parte desse contexto.

Antes do segundo cérebro, segundo a experiência descrita pelo autor, cada sessão implicava voltar a explicar quem era o cliente, como estava estruturada a oferta e que fornecedor processava os pagamentos. Com business/, abro uma conversa e digo: «atualiza a oferta para o novo plano de preços» — o Claude vai por iniciativa própria a business/company/legal.md, lê os requisitos, depois vai a business/products/pricing.md, encontra o novo plano de preços e sugere uma alteração de uma só vez. Acabou a explicação inicial; o contexto é carregado automaticamente.

A Anthropic chama a este problema context rot no seu blogue de engenharia:

Por outras palavras, quanto mais coisas amontoar na janela, pior será o desempenho do agente ao trabalhar com detalhes específicos. A solução é manter uma estrutura de ficheiros externos que o Claude possa consultar por iniciativa própria em resposta a um pedido específico. É isso que é um segundo cérebro.

O que é um segundo cérebro e como se aplica ao Claude?#

Em geral, um segundo cérebro serve para a produtividade: as pessoas criam um vault no Obsidian e acrescentam excertos de livros, notas de chamadas e ideias para projetos.

Quando o autor aplicou esta ideia ao trabalho com o Claude Code, deixou de ser uma questão de produtividade e passou a ser uma questão de arquitetura de agentes.

No método clássico, o segundo cérebro é seu e acede-lhe manualmente. Ao trabalhar com o Claude Code, o segundo cérebro torna-se bidirecional: tanto o utilizador como o agente lhe acedem. Isso altera os requisitos do formato.

Como o agente lhe acede por iniciativa própria, os ficheiros têm de estar num formato que compreenda sem uma integração separada. Markdown é ideal: texto, uma hierarquia de títulos e ligações entre ficheiros. Notion e Google Docs não são adequados. Pode ligá-los através de MCP, mas isso acrescenta outra camada, mais um token por pedido e mais um ponto de falha.

Como os ficheiros estão no sistema de ficheiros, junto ao projeto, ficam automaticamente ao alcance do Claude Code. Não é necessária qualquer configuração. Inicie o agente na pasta do projeto e ele consegue ver todos os ficheiros que lá se encontram. É gratuito e funciona imediatamente.

Que hierarquia de memória tem o Claude Code de origem?#

Antes de acrescentarmos algo por nossa conta, vejamos o que o Claude consegue recordar sem ajuda. A Anthropic descreve dois mecanismos na sua documentação oficial: CLAUDE.md (regras que escreve) e memória automática (lições que o Claude escreve por si). Ambos são carregados no início de cada sessão.

O CLAUDE.md é procurado em quatro locais ao mesmo tempo:

Os quatro ficheiros são carregados para o contexto. Quanto mais específico o nível, maior a sua prioridade. O ficheiro local é lido por último, pelo que as suas regras substituem todas as outras.

Também pode haver um ficheiro CLAUDE.md em qualquer pasta dentro do projeto. Quando o Claude lê um ficheiro de uma subpasta, carrega o CLAUDE.md dessa subpasta quando necessário. Isto é útil num monorepo: as regras do frontend ficam em frontend/CLAUDE.md, as do backend em backend/CLAUDE.md e só são carregadas quando o agente trabalha na parte relevante.

A memória automática surgiu no Claude Code 2.1.59. São ficheiros que o Claude escreve sobre si:

~/.claude/projects/<project-name>/memory/
├── MEMORY.md          # Índice, carregado em todas as sessões (200 linhas ou 25KB)
├── debugging.md       # Notas detalhadas (carregadas quando necessário)
├── api-conventions.md
└── ...

A Anthropic descreve-a assim na documentação oficial:

A memória automática é ativada com a flag autoMemoryEnabled em ~/.claude/settings.json. O Claude decide o que escrever. Pode ler o MEMORY.md e editá-lo manualmente — é markdown normal.

CLAUDE.md ou um segundo cérebro — onde deve traçar a linha?#

Nas minhas palestras, uso esta analogia: imagine que contratou um novo funcionário. O que lhe dá no primeiro dia?

Um manual de instruções: como se vestir, a que horas chegar, que tom usar com os clientes, através de que sistema publicar. É um documento curto. Não explica o que faz nem porquê. Limita-se a dizer como se deve comportar.

E, à parte, dá-lhe acesso à wiki da empresa. Explica o que é o produto, para quem se destina, quem é o público, qual é o preço e porquê, quem são os concorrentes e que erros cometeu. É um arquivo extenso. Ninguém o lê todo — consulta-o quando tem uma pergunta específica.

CLAUDE.md = manual de instruções. Segundo cérebro = wiki. Precisa dos dois.

A distinção é simples. Ponha no CLAUDE.md tudo o que é relevante para todas as tarefas:

• Quem é o agente neste projeto (ajudante, responsável, assistente)
• Em que idioma deve responder
• Stack de ferramentas
• Comandos de publicação
• Proibições (não usar travessões, não executar git push --force)
• Encaminhamento: onde procurar contexto empresarial e onde procurar princípios

Ponha no segundo cérebro tudo o que é necessário quando solicitado:

• O produto, o público, a economia e os objetivos
• Concorrentes e mercado
• Decisões anteriores e respetivos motivos
• Exemplos e avaliações de clientes
• Princípios e metodologia

A Anthropic faz a mesma distinção na sua documentação:

Skills são uma forma de guardar conhecimento episódico. Uma pasta business/ junto ao projeto é outra. Uso ambas e explicá-las-ei com mais detalhe abaixo.

O que compõe o cérebro de um projeto — 5 partes mais uma máquina do tempo#

Exemplo de arquitetura baseado na experiência descrita pelo autor:

O ponto metodológico fundamental é separar ai-clone/ e business/.

business/ responde à pergunta «o que fazemos?». Produto, público, preços, concorrentes. Diz respeito ao projeto. Se entregar o projeto a um parceiro amanhã, esta pasta vai com ele.

ai-clone/ responde à pergunta «como tomo decisões?». Os meus princípios, tom, ofício e palavras a evitar. Diz respeito a mim. Se começar um projeto novo amanhã, esta pasta vai comigo.

Quer não só configurar uma segunda pasta, mas também criar um sistema que torne o Claude consistente? Isso, por si só, não chega. Sem ai-clone/, o agente responde por todos, não por si. Sem context engineering, percorre a pasta toda e desperdiça tokens. É útil ligar os três elementos: segundo cérebro + clone de IA + context engineering. São os três pilares sem os quais a IA alucina.

O que deve estar em business/ e o que não deve?#

Estrutura de topo da pasta business/ no projeto descrito pelo autor:

business/
├── INDEX.md              ← mapa da pasta, ler primeiro
├── company/              ← missão, entidade legal, valores, políticas jurídicas
├── products/             ← produtos, programas, preços
├── audience/             ← perfil do cliente, segmentos, objeções
├── goals/                ← objetivos anuais, trimestrais e mensais, métricas
├── economics/            ← economia unitária, receitas, despesas, previsão
├── marketing/             ← canais, funil, materiais, concorrentes
├── execution/            ← planeamento semanal, backlog
└── assets/               ← sistema de design, avaliações, banco de textos

Este é um exemplo do projeto descrito pelo autor, não um dogma. Crio pastas conforme necessário. Comecei com três (products/, audience/, goals/); as outras foram acrescentadas passados 2-3 meses, quando já não era claro onde guardar coisas novas.

O ficheiro principal da pasta é INDEX.md. É um mapa. Contém uma tabela «pergunta → ficheiro» que o Claude usa para perceber onde deve ir. Sem ela, o agente gasta tokens a ler todos os ficheiros pela ordem em que aparecem.

Excerto de exemplo de INDEX.md:

### Onde encontrar as coisas

| O que precisa | Onde procurar |
|---|---|
| Quem é o nosso cliente e quais são os seus problemas | `business/audience/avatar.md` |
| Produtos, planos e preços | `business/products/` |
| Objetivos e métricas | `business/goals/` |
| Economia (receitas, despesas, economia unitária) | `business/economics/` |
| Canais e materiais de promoção | `business/marketing/` |

Depois, basta uma linha no CLAUDE.md: «Para questões empresariais, lê business/INDEX.md e segue o mapa.» O agente não carrega a pasta inteira para o contexto. Carrega o mapa, escolhe o ficheiro certo e lê apenas esse.

Lista do que não deve pôr em business/:

• Correspondência bruta de conversas sem tratamento. Se houver uma ideia relevante, extraia-a e registe-a. Caso contrário, deixe-a de fora.
• Informação duplicada no código. Não é preciso escrever «os pagamentos são processados através de CloudPayments»; o agente consegue ver isso no código.
• Capturas de ecrã e imagens. Aumentam o tamanho da pasta e não são interpretadas por um modelo de texto sem uma etapa adicional.
• Números dinâmicos. «Hoje há 423 pagamentos para o produto» estará desatualizado dentro de uma semana. Use o marcador LIVE e uma ligação a uma consulta à base de dados.
• Informação sensível ou duvidosa. Se o repositório fosse publicado amanhã no YouTube perante 100 mil desconhecidos, mantenha apenas o que estaria disposto a mostrar. Os funcionários, agentes e, por vezes, prestadores de serviços externos leem a pasta.

Porque ter uma pasta ai-clone separada e porque não a misturar com business?#

A ideia é simples: o negócio sabe o que fazemos. O clone sabe como tomo decisões.

Estrutura de ai-clone/ no projeto descrito pelo autor:

ai-clone/
├── INDEX.md           ← mapa da pasta
├── role.md            ← quem sou, o meu percurso, o que é importante
├── identity/          ← valores, visão, missão
├── thinking/          ← modelos mentais de palestras
├── voice/             ← tom, vocabulário, estilo
├── principles/        ← convicções sobre produto, código, negócio
├── feedback/          ← regras aprendidas com erros ← pasta principal
├── style/             ← palavras a evitar, formato do Telegram
└── reference/         ← ferramentas, ambiente

A pasta mais útil é feedback/. Contém regras específicas que aprendi com os erros dos agentes. Cada regra fica num ficheiro separado com este formato:

---
name: short-name
description: uma linha - o que está no ficheiro e quando se aplica
type: feedback
---

Uma regra curta numa frase.

**Porquê:** por que razão existe esta regra. Contexto, incidente, observação.

**Como aplicar:** situações específicas em que a regra se aplica.

Sem «Porquê», a regra está morta — o agente não a transfere para uma situação semelhante. Sem «Como aplicar», não é claro quando usar a regra.

Um exemplo da minha pasta: a regra «hífen, não travessão». Surgiu porque o travessão — é um marcador visual típico de texto gerado. Aplica-se a qualquer texto destinado ao público. O ficheiro está em ai-clone/feedback/no-em-dashes.md.

Faço-o de maneira um pouco diferente: escrevo as regras em ai-clone/feedback/, não em CLAUDE.md. O CLAUDE.md é um ficheiro do projeto, mas as regras sobre tom e estilo são pessoais. Acompanham-me para o projeto seguinte. O CLAUDE.md fica com o projeto.

O que são Live Metrics e porque não devemos fixar números nos ficheiros?#

Uma das principais armadilhas ao começar um segundo cérebro é enchê-lo de números desatualizados. Escreve «temos 320 clientes» e, duas semanas depois, já são 410. Escreve «a receita mensal é 4.7 million» e, um mês depois, o número perdeu o contexto: é uma meta, um valor real ou uma previsão?

No exemplo do autor, funciona assim. No ficheiro business/products/practicum.md, há um marcador em vez de um número:

## Coortes

> **LIVE** - execute as consultas em `live-metrics.md`, secção «Vendas»,
> para ver os pagamentos atuais por coorte.

| Coorte | Datas | Pagantes |
|-------|------|------------|
| 1 | March 10-12, 2026 | LIVE |
| 2 | March 24-26, 2026 | LIVE |

Um ficheiro separado, live-metrics.md, contém consultas SQL prontas a executar e descrições do que devolvem:

## Vendas (pagamentos por coorte)

```sql
SELECT c.name, COUNT(p.id) AS paid, SUM(p.amount) AS revenue
FROM purchases p
JOIN cohorts c ON c.id = p.cohort_id
WHERE p.status = 'paid'
GROUP BY c.name
ORDER BY c.starts_at DESC;
```

Quando pergunto ao agente «quantos pagamentos temos para a segunda coorte?», ele:

1. Lê business/products/practicum.md
2. Vê o marcador LIVE junto ao número
3. Abre live-metrics.md
4. Encontra a secção «Vendas»
5. Executa a consulta na base de dados de produção
6. Responde com dados atualizados

Isto resolve dois problemas de uma só vez. Os números não ficam desatualizados. E as decisões são tomadas com base na situação atual, não na do ano passado.

Como navega a IA pelo segundo cérebro para responder a um pedido?#

Um pedido específico, por exemplo: «redige um e-mail para os participantes sobre a nova coorte».

1. Claude começa com uma janela vazia. Carrega CLAUDE.md (regras, stack, encaminhamento).
2. A partir do encaminhamento em CLAUDE.md, vê: «ai-clone/INDEX.md — ler sempre no início de uma sessão.» Abre o ficheiro e fica a saber quem sou, qual é o meu tom e que palavras a evitar uso.
3. Vê no encaminhamento: «modelos de e-mail — src/lib/email/layout.ts». Abre o ficheiro e compreende o formato.
4. Vê: «contexto do produto — business/products/practicum.md». Abre o ficheiro e lê sobre o produto.
5. Vê no ficheiro o marcador LIVE e uma referência a live-metrics.md. Abre o ficheiro e encontra o SQL pronto a executar. Se precisar de um número atual, executa a consulta. Caso contrário, assinala «obter este número no momento do envio».
6. Vê as regras de tom em ai-clone/style/telegram-format.md, a proibição de travessões em ai-clone/feedback/no-em-dashes.md e as taxas de conversão do funil em business/marketing/funnel.md.

Escreve o e-mail no meu tom, com números atualizados e sem travessões ou marcas de IA.

A Anthropic chama a esta abordagem just-in-time context no seu blogue de engenharia:

Por outras palavras, o Claude transporta apontadores para os dados, não os próprios dados. É muito mais eficiente em tokens e muito mais preciso, porque só as informações relevantes entram no contexto. A janela mantém-se livre para raciocinar.

5 práticas a evitar ao criar um segundo cérebro — o que deve evitar?#

Prática a evitar 1. Um CLAUDE.md demasiado extenso. 500 linhas de instruções «em vez de pôr tudo num só lugar». A Anthropic é clara:

O objetivo é 80-120 linhas. Ponha tudo o resto em ficheiros separados e indique onde os encontrar.

Prática a evitar 2. Uma pasta para tudo. Atira tudo para o segundo cérebro: correspondência bruta de conversas, capturas de ecrã inúteis, relatórios que ninguém vai ler. Passado um mês, a pasta cresceu, o agente desperdiça tokens a ler lixo e não consegue lembrar-se onde está cada coisa. A regra: cada ficheiro do segundo cérebro deve responder a uma pergunta específica. Se ninguém o abrir há seis meses, apague-o ou mova-o para o arquivo.

Prática a evitar 3. Duplicação. «Os pagamentos passam por CloudPayments, em src/lib/payment/cloudpayments.ts; o fornecedor está configurado em .env». O agente consegue ver tudo isso no código. Não o duplique em business/. As cópias ficam desatualizadas: o código muda, business/ não é atualizado e o agente trabalha com informações antigas.

Prática a evitar 4. Números fixos. «Temos 1,247 clientes, com uma taxa de conversão de 6.3%» — imagine que estes são números de uma startup fintech abstrata. Todos estes números ficarão desatualizados dentro de uma semana. Use o marcador LIVE e live-metrics.md. A secção sobre este tema está acima.

Prática a evitar 5. Contexto sem um percurso acessível. Se o segundo cérebro estiver noutro local e o agente não tiver permissão nem referência, iniciar na pasta do código não basta. Para notas comuns não sensíveis, business/ e profile/ dentro do repositório são uma organização prática. Para contexto privado, use um local controlado separadamente e configure explicitamente o acesso permitido e o encaminhamento. A conveniência das pastas não prevalece sobre a confidencialidade.

Como criar um segundo cérebro numa hora — receita passo a passo#

1. Crie duas pastas de raiz

   Na raiz do projeto, junto a src/:

   mkdir -p business/{products,audience,goals,economics,marketing}
   mkdir -p ai-clone/{identity,voice,principles,feedback,style}
   

2. Crie um INDEX.md como mapa da pasta

   business/INDEX.md é uma tabela «pergunta → ficheiro». Comece com pelo menos 5 linhas e acrescente outras à medida que avança. Faça o mesmo em ai-clone/INDEX.md.

3. Acrescente descrições curtas do produto e do cliente

   business/products/main.md — o que é o produto, para quem se destina, quanto custa e o que o distingue. 30-50 linhas. business/audience/avatar.md — quem é o cliente, quais são os seus problemas e o que compra. 30-50 linhas. Não descreva um cliente ideal; descreva um cliente real. Se não souber algo, marque-o «a esclarecer» e avance.

4. Descreva-se em ai-clone/role.md

   Quem é, o que faz e o que é importante para si. 20-30 linhas. É suficiente para começar. Acrescente o tom, os princípios e as palavras a evitar quando reparar que o agente escreve num estilo que não é o seu.

5. Acrescente o encaminhamento a CLAUDE.md

   Abra CLAUDE.md e acrescente uma secção:

   ## Mapa do projeto
   
   - Contexto empresarial → `business/INDEX.md`
   - Contexto sobre mim → `ai-clone/INDEX.md`
   - Planos técnicos → `plans/YYYY-MM-DD-*.md`
   - Reflexões sobre sessões anteriores → `retrospectives/`
   
   Leia sempre `ai-clone/INDEX.md` e `business/INDEX.md` no início de uma sessão.
   

6. Inicie o Claude Code e verifique

   Abra o agente. Pergunte-lhe: «fala-me do meu produto e do meu público». Se responder com base no contexto da pasta, está a funcionar. Se inventar coisas, verifique se as pastas estão junto ao projeto, se os ficheiros têm os nomes corretos e se o encaminhamento em CLAUDE.md está formulado com precisão.

Depois disso, o segundo cérebro cresce com base em dois princípios.

Primeiro: sempre que o agente cometer um erro, acrescente uma regra. Ao fim de 3-4 semanas, ai-clone/feedback/ terá 15-20 ficheiros de regras e o agente deixará de cometer a maioria dos erros comuns.

Segundo: sempre que tomar uma decisão empresarial, registe-a em business/. Se aumentar o preço, acrescente uma nota com a data e o motivo a business/products/pricing.md. Se alterar o posicionamento, acrescente uma nota a business/company/about.md. Daqui a seis meses, terá um arquivo que se recorda do «porquê».

Fizemos uma quantidade considerável de trabalho juntos esta semana.

Analisa todas as alterações ao código desta semana e todos os commits que fizemos.
Que informações valiosas daqui devem ficar em business/? Escreve-as nos ficheiros apropriados,
com ligações wiki a ficheiros próximos, para que o contexto não se perca.

Se houver decisões no código que eu não tenha explicado, pergunta-me porquê
e regista o motivo no ficheiro apropriado com a data.

Não dupliques o que já é evidente no código. Inclui apenas o que o agente
não saberia na próxima sessão sem business/.

E a seguir — Skills, Subagents e context engineering#

Depois de criar o segundo cérebro, há mais três ferramentas que a Anthropic descreve como três níveis diferentes de otimização do contexto.

Skills são conhecimento procedimental. Se tem um fluxo de trabalho que repete (escrever um guia de aprendizagem, preparar uma publicação para o Telegram, auditar um site), pode codificá-lo num ficheiro SKILL.md com uma descrição da tarefa. No início de uma sessão, o Claude analisa os nomes e as descrições das skills e carrega apenas as que se adequam à tarefa atual. Isto poupa tokens e mantém o foco.

Subagents são instâncias isoladas do Claude com as suas próprias janelas de contexto. Inicie um subagente para uma tarefa exigente (ler 30 ficheiros e preparar um resumo); ele trabalha na sua própria janela e devolve apenas o resultado. A sua janela principal mantém-se livre. A Anthropic escreve:

Context engineering é gerir o que entra na janela. A Anthropic chamou-lhe uma competência fundamental para trabalhar com agentes em 2025, um nível acima de prompt engineering. Prompt engineering é escolher a formulação. Context engineering é escolher ficheiros, encaminhamentos, skills e subagentes.

Um segundo cérebro é o primeiro bloco de construção do context engineering. Sem ele, as Skills leem um espaço vazio, os Subagents não têm para onde ir e a janela do agente enche-se de informação aleatória. Com ele, as três ferramentas começam a funcionar.

Próximo passo. Crie duas pastas junto ao projeto: business/ e ai-clone/. Acrescente um INDEX.md a cada uma, com 5 linhas a servir de mapa. Acrescente quatro linhas de encaminhamento ao CLAUDE.md. Dentro de uma hora, terá uma estrutura funcional de segundo cérebro. Depois, desenvolva-a seguindo a regra «depois de cada erro do agente, acrescente uma linha a ai-clone/feedback/». Explico o modelo completo de CLAUDE.md que usará para encaminhar para o segundo cérebro no guia Como configurar corretamente o CLAUDE.md.

Continue a explorar a Ailoot em ailoot.ai.