# Um segundo cérebro no Claude Code: como criar a estrutura numa hora
> Como criar um segundo cérebro para o Claude Code: uma hierarquia de memória, uma estrutura de pastas com cinco partes e git para que o agente se lembre de tudo sobre o seu projeto entre sessões.
Source: https://ailoot.ai/blog/pt-pt/claude-code-second-brain/
Canonical: https://ailoot.ai/blog/pt-pt/claude-code-second-brain/
Language: pt-PT
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-233
Revision: sha256-a99ee99e935dc3815539686e9a6e940f15cbff396a3d8d715b1db7e008dad317
Ponto-chave
Um segundo cérebro para o Claude Code não é um único ficheiro; é uma estrutura de cinco pastas mais git. CLAUDE.md define as regras e o encaminhamento, `business/` guarda conhecimentos sobre o projeto, `ai-clone/` guarda informações sobre si enquanto pessoa que toma decisões, `plans/` contém planos técnicos e `retrospectives/` reúne as lições de sessões anteriores. O agente começa pelo CLAUDE.md e segue as ligações até à pasta certa para o pedido específico. Este artigo aborda a hierarquia de memória da documentação oficial do Claude Code, uma estrutura de cinco partes e como a criar passo a passo numa hora.
Documentação de referência da Ailoot: [ailoot.ai/docs/](https://ailoot.ai/docs/).
## Porque é que o Claude Code precisa de um segundo cérebro e o que é essencial?
Ponto-chave
Um único ficheiro CLAUDE.md cobre as regras básicas, mas não dá conta da memória empresarial. Passado um mês, esqueceu-se do motivo por que aumentou o preço. Passados três meses, esqueceu-se do motivo por que rejeitou os pagamentos em prestações. O conhecimento vive simultaneamente em quatro sítios: na sua cabeça, em conversas no Telegram, em documentos Google e na cabeça dos funcionários. Um segundo cérebro reúne tudo numa pasta de ficheiros markdown junto ao projeto, e o Claude pode consultá-la por iniciativa própria.
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](https://ailoot.ai/blog/pt-pt/claude-md-template/) — 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.
Nota
Não é um problema de memória do Claude. É um problema de arquitetura. A janela de contexto de um agente é a sua memória de trabalho. Só carrega aquilo para que o orienta explicitamente. Tudo o resto fica fora da janela e é carregado quando necessário. Um segundo cérebro guarda esse «tudo o resto» de forma estruturada para que o Claude se possa orientar.
A Anthropic chama a este problema context rot no seu blogue de engenharia:
Quanto mais tokens houver na janela de contexto, pior será a capacidade do modelo para recuperar com precisão informações desse contexto.
— Anthropic, anthropic.com/engineering/effective-context-engineering-for-ai-agents
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?
Ponto-chave
A ideia é simples: a mente serve para ter pensamentos, não para os armazenar. Um arquivo digital externo pode organizar notas para que, no Claude Code, o agente lhes aceda diretamente através do sistema de ficheiros.
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.
Dica
Pode manter o seu segundo cérebro no Obsidian — também o abro lá para ser mais fácil visualizar o grafo de ligações. Mas os próprios ficheiros estão numa pasta normal, junto ao código. O Obsidian é apenas uma interface agradável para ficheiros markdown. O Claude consegue vê-los sem o Obsidian. Pode usar qualquer editor; o importante é que os ficheiros estejam no disco e não num serviço na nuvem com um formato próprio.
## Que hierarquia de memória tem o Claude Code de origem?
Ponto-chave
O Claude Code consegue ler, de origem, ficheiros CLAUDE.md em quatro níveis (enterprise, utilizador, projeto e local) e, desde a versão 2.1.59, mantém a sua própria memória automática em `~/.claude/projects//memory/`. Isto é suficiente para a memória básica, mas não para o contexto empresarial — esse deve ficar numa pasta separada, junto ao projeto.
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](https://code.claude.com/docs/en/memory): 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:
| Nível | Localização | Finalidade |
|----|----|----|
| **Enterprise** | `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS), `/etc/claude-code/CLAUDE.md` (Linux), `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows) | Regras que um administrador implementa para toda a equipa através de MDM. Os utilizadores individuais não precisam disto. |
| **Utilizador** | `~/.claude/CLAUDE.md` | Regras pessoais que se aplicam a todos os projetos. «Responde no meu idioma preferido», «não uses travessões». |
| **Projeto** | `./CLAUDE.md` na raiz do projeto | Regras para um projeto específico: stack, estrutura de pastas, regras empresariais. Com este ficheiro no git. |
| **Local** | `./CLAUDE.local.md` | As suas notas pessoais para este projeto, que não são guardadas no git. Incluído em `.gitignore`. |
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//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:
O Claude não guarda algo em todas as sessões. Decide o que vale a pena recordar com base na possibilidade de a informação ser útil numa conversa futura.
— Anthropic, code.claude.com/docs/en/memory
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.
Aviso
A memória automática é útil, mas não substitui um segundo cérebro. O Claude escreve nela conclusões práticas sobre ferramentas e padrões de código. «Este script falha sem a flag X», «esta tabela da base de dados tem este nome». Não escreve nela estratégias empresariais. Se quiser que o agente se lembre de quem é o seu público e do motivo por que escolheu determinado preço, tem de guardar essa informação numa pasta de contexto separada.
## CLAUDE.md ou um segundo cérebro — onde deve traçar a linha?
Ponto-chave
O CLAUDE.md é um manual de instruções para um novo funcionário: como se comportar, que comandos usar e o que não fazer. Um segundo cérebro é uma wiki da empresa: o que faz, para quem, como funciona a economia e o que já experimentou. Um ficheiro com regras de comportamento e uma estrutura de conhecimento externo. O CLAUDE.md é o índice; o segundo cérebro é o arquivo. Sem o índice, o agente não sabe que o arquivo existe. Sem o arquivo, conhece apenas as regras, não o contexto empresarial.
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:
O CLAUDE.md é carregado em todas as sessões, por isso inclua apenas aquilo que se aplica de forma abrangente. Para conhecimentos de domínio ou fluxos de trabalho necessários apenas ocasionalmente, use Skills. O Claude carrega-os quando necessário sem sobrecarregar todas as conversas.
— Anthropic, code.claude.com/docs/en/best-practices
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
Ponto-chave
O cérebro de um projeto é composto por cinco pastas com git por cima. CLAUDE.md define as regras e o encaminhamento. `ai-clone/` guarda a sua projeção digital: os seus princípios, tom e feedback após erros. `business/` guarda conhecimentos sobre o projeto. `plans/` contém planos técnicos por fase. `retrospectives/` contém reflexões após as sessões. O git transforma tudo isto numa máquina do tempo: passado um ano, pode abrir qualquer ficheiro e ver o que continha quando uma decisão foi tomada.
Exemplo de arquitetura baseado na experiência descrita pelo autor:
| Pasta | Conteúdo | Finalidade |
|----|----|----|
| **`CLAUDE.md`** | Regras do projeto, stack, estrutura de ficheiros, encaminhamento entre pastas, idioma de comunicação | O manual de instruções do agente. Carregado em todas as sessões. Menos de 200 linhas, idealmente 80-120. |
| **`ai-clone/`** | Quem sou, os meus princípios, o meu tom, o meu estilo de decisão, feedback após erros | Uma projeção digital de mim enquanto pessoa que toma decisões. Sabe o que vou rejeitar imediatamente, o estilo em que proponho coisas e as regras que aprendi com os erros. |
| **`business/`** | Produto, público, objetivos, economia, marketing, decisões anteriores, exemplos | Ficheiros markdown ligados entre si, com ligações wiki. Cada ficheiro liga-se aos outros através de ligações `[[...]]`. O agente consulta-os para obter respostas a perguntas específicas. |
| **`plans/`** | Um plano por funcionalidade. Ficheiro `YYYY-MM-DD-feature.md` com fases e caixas de verificação | O Plan Mode existe numa conversa e perde-se depois de `/clear`. A pasta `plans/` fica no repositório — qualquer agente pode retomar o plano a qualquer momento. |
| **`retrospectives/`** | Reflexões após cada sessão: o que foi feito, o que recordar, o que poderia ser melhor | Autoaprendizagem do sistema. Os erros transformam-se em regras em `ai-clone/feedback/`. |
| **`+ git`** | Histórico de versões de todos os ficheiros | Uma máquina do tempo. Abra qualquer ficheiro e execute `git log` para ver quando e porquê foi alterado. |
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?
Ponto-chave
Ponha em `business/` factos do projeto que mudam uma vez por semana ou menos: posicionamento, público, produtos e preços, objetivos trimestrais e decisões importantes. Não inclua correspondência de conversas, materiais brutos por tratar, informações duplicadas no código, capturas de ecrã nem números dinâmicos. Substitua os números pelo marcador LIVE e por uma ligação a uma consulta SQL — explico isto numa secção separada mais abaixo.
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`:
```markdown
### 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.
Aviso
Se o repositório for público, a pasta `business/` também é pública. Trato o segundo cérebro como se o repositório pudesse tornar-se público amanhã, mesmo que seja privado neste momento. Nada de nomes de clientes sem consentimento, valores de receitas mensais ou palavras-passe. Este hábito poupa muito stress.
## Porque ter uma pasta ai-clone separada e porque não a misturar com business?
Ponto-chave
`ai-clone/` guarda a sua projeção digital: princípios, tom, palavras a evitar e feedback após erros. Cada erro do agente transforma-se numa regra em `ai-clone/feedback/`, segundo a fórmula «regra → porquê → como aplicar». A pasta acompanha-o de projeto em projeto. `business/` fica com o projeto. Mantenha-as separadas: num projeto novo, `business/` será nova, mas os seus princípios e estilo mantêm-se.
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:
```markdown
---
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.
Nota
Uma medida da maturidade desta abordagem é quantas vezes por semana diz ao agente «não, não é assim» sobre a mesma coisa. Num sistema maduro, a resposta é zero. Cada erro transforma-se numa regra em `feedback/` e o agente não o repete da próxima vez.
## O que são Live Metrics e porque não devemos fixar números nos ficheiros?
Ponto-chave
Os números nos ficheiros do segundo cérebro ficam desatualizados em poucos dias. «1,000 clientes» hoje passa a 1,050 amanhã e a 2,000 dentro de um mês. Se fixar o número no ficheiro, passado um mês o agente fará sugestões com base nos dados de ontem. A solução é usar um marcador LIVE no ficheiro e um documento separado, `live-metrics.md`, com consultas SQL prontas a executar. Quando vê LIVE, o agente vai à base de dados, obtém o número atual e raciocina com base em dados atualizados.
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:
```markdown
## 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:
````markdown
## 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.
Aviso
Na abordagem descrita pelo autor, só os agentes de confiança têm acesso à base de dados de produção. Só lhes é dado acesso através de um wrapper que regista as consultas e não expõe palavras-passe. Colocar um comando `psql` direto, com uma palavra-passe em texto simples, em `live-metrics.md` é uma má ideia. Crie um wrapper que obtenha a palavra-passe de uma variável de ambiente e não a exponha na saída. É uma camada técnica à parte, mas sem ela o LIVE torna-se uma falha de segurança.
## Como navega a IA pelo segundo cérebro para responder a um pedido?
Ponto-chave
O percurso do pedido é sempre o mesmo: Claude lê CLAUDE.md, vê os mapas (`business/INDEX.md`, `ai-clone/INDEX.md`), abre o INDEX relevante, segue-o até um ficheiro específico e, se necessário, obtém um número através de LIVE. São 5-6 operações de leitura em vez de colocar a pasta inteira no contexto. A janela fica livre para raciocinar e não se desperdiçam tokens com ficheiros irrelevantes.
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:
Os agentes criados com uma abordagem «just in time» mantêm identificadores leves (caminhos de ficheiros, consultas guardadas, ligações, etc.) e usam essas ligações para carregar dados dinamicamente para o contexto em tempo de execução, através de ferramentas.
— Anthropic, anthropic.com/engineering/effective-context-engineering-for-ai-agents
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?
Ponto-chave
Os principais erros dos principiantes ao criar um segundo cérebro: 1) um CLAUDE.md demasiado extenso, com mais de 500 linhas, em vez de um encaminhador curto; 2) uma pasta para tudo que se transforma num depósito; 3) duplicar coisas que o Claude já sabe pela linguagem ou pelo código; 4) fixar números que ficam desatualizados sem LIVE; 5) deixar o contexto inacessível ao agente ou sem encaminhamento, esteja no mesmo repositório ou num armazenamento privado separado.
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:
Mantenha-o curto. Para cada linha, pergunte: «Se a remover, o Claude começará a cometer erros?» Se não, elimine-a. Os ficheiros CLAUDE.md inchados fazem com que o Claude ignore as suas instruções reais!
— Anthropic, code.claude.com/docs/en/best-practices
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.
Dica
Um branch separado (`context` ou `business-context`) organiza trabalho, mas não é um limite de acesso: os ficheiros continuam a ser objetos Git do mesmo repositório e podem ser publicados com branches ou histórico. Para contexto empresarial privado, use um repositório privado separado ou armazenamento externo com controlo explícito e encaminhamento permitido ao agente. Um submódulo pode apontar para um repositório privado separado, mas a privacidade vem das permissões desse repositório, não do submódulo. Outra opção é uma pasta local deliberadamente ignorada, com cópia própria; ignorar um caminho não remove ficheiros já controlados pelo Git nem histórico publicado. Mantenha junto do código só contexto partilhável.
## Como criar um segundo cérebro numa hora — receita passo a passo
Ponto-chave
Pode configurar um segundo cérebro básico numa hora: crie as pastas de raiz `business/` e `ai-clone/`, faça um mapa `INDEX.md` em cada uma, acrescente uma descrição curta do produto em `business/products/`, uma descrição do cliente em `audience/` e uma descrição de quem é em `ai-clone/role.md`. Acrescente o encaminhamento para estas pastas em `CLAUDE.md`. Depois, expanda-o enquanto trabalha: após cada erro do agente, acrescente uma regra em `ai-clone/feedback/`; após cada decisão, acrescente uma nota em `business/`.
1. ### Crie duas pastas de raiz
Na raiz do projeto, junto a `src/`:
```bash
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:
```markdown
## 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ê».
Prompt: pronto a usar para atualizar o segundo cérebro ao fim do dia
```
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
Ponto-chave
Um segundo cérebro e o CLAUDE.md são a base. Acrescente-lhe Skills (conhecimento procedimental carregado quando necessário, com base na descrição da tarefa), Subagents (instâncias isoladas do Claude com janelas de contexto próprias para tarefas exigentes) e context engineering (gestão do que entra na janela). Estes são os três pisos superiores. Não funcionam sem a base — o agente não tem nada para ler.
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:
Os subagentes especializados podem resolver tarefas específicas em janelas de contexto limpas. [...] Cada subagente pode explorar amplamente, consumindo dezenas de milhares de tokens ou mais, mas devolve apenas um resumo condensado e destilado do seu trabalho (muitas vezes 1,000-2,000 tokens).
— Anthropic, anthropic.com/engineering/effective-context-engineering-for-ai-agents
**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](https://ailoot.ai/blog/pt-pt/claude-md-template/).
### Fontes
- [Documentação Claude Code Memory](https://code.claude.com/docs/en/memory) - hierarquia oficial de memória do Claude Code, da Anthropic
- [Boas práticas do Claude Code](https://code.claude.com/docs/en/best-practices) - orientações oficiais para trabalhar com o CLAUDE.md
- [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) - Anthropic Engineering, explicação de context rot, orçamento de atenção e contexto just-in-time
- [Skills explained](https://claude.com/blog/skills-explained) - blogue da Anthropic: distinção entre Skills, Memory, Subagents e MCP
Continue a explorar a Ailoot em [ailoot.ai](https://ailoot.ai/).
## Perguntas frequentes
### Pôr o contexto empresarial noutro branch Git mantém-no privado?
Não. O branch pertence ao mesmo repositório e os ficheiros podem ser partilhados com os objetos e o histórico. Use armazenamento privado controlado separadamente ou uma pasta local deliberadamente ignorada com cópia; ignorar o caminho não apaga o histórico já controlado.
### Como encontra o agente contexto privado fora do repositório de código?
Forneça uma referência explícita e apenas as permissões necessárias à tarefa. Mantenha um índice curto que encaminhe para o documento pertinente e confirme que o agente lê o ficheiro autorizado; um local privado sem encaminhamento não fornece contexto automaticamente.
## Ailoot · A empresa e a sua carteira de projetos
A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI.
A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões.
A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.