Gerenciamento de Memória
Como escrever na memória automática do Claude Code e no CLAUDE.md para que a biblioteca permaneça pesquisável à medida que o projeto cresce.
Referência Rápida
| Usuário diz... | Faça isso |
|---|---|
| "registra isso" (vago, múltiplos candidatos)/"revisão"/"depois do desenvolvimento, veja o que vale registrar" | → Modo 1: Avaliação de Candidatos (filtragem de múltiplos candidatos) |
| "registra aquele X bug de hoje" (item específico único)/após consertar um bug grave/fim de incidente de segurança/decisão única com conclusão não óbvia | → Modo 2: Nova memória (vai direto) |
| "atualiza esta memória / corrige a conclusão de X" | → Modo 3: Atualizar memória existente (prioritário sobre criar nova) |
| O trecho a adicionar tem mais de 100 linhas ou o arquivo já tem > 4 tópicos H2 | → Regra 6: Dividir em vez de atualizar |
| "mudar schema / adicionar novo tipo / alterar estrutura de memória" | → Modo 4: Mudança estrutural (leia a lista de armadilhas) |
| "novo projeto, memória do zero" / "como começar" | → Modo 5: Bootstrap sem memória |
| "o sistema de memória parece bagunçado / auditoria" | → Se existir scripts/audit-memory.sh na raiz do projeto, execute-o; caso contrário, consulte templates/audit-memory.template.sh para criar o seu próprio |
Regras Importantes
Regra 1: Fatos na memória, métodos na habilidade
O arquivo de memória armazena "caiu no buraco X", "dados da indústria Y", "estado do projeto Z"; esta habilidade armazena "como decidir o que registrar / como escrever / como organizar". Não coloque especificações de schema nos arquivos de memória (erro de categoria).
Regra 2: Primeiro julgue "vale a pena registrar?", depois decida "onde registrar"
Nem toda descoberta merece ser registrada. Árvore de decisão:
| Sinal | Deve registrar? |
|---|---|
| Mesmo buraco, 2ª vez | ✅ Obrigatório |
| Julgamento não óbvio descoberto em revisão | ✅ Registre o "Porquê" da decisão |
| Comparação com a indústria / números medidos (linha de base reutilizável) | ✅ Registre |
| Debug único já corrigido sem valor de aprendizado | ❌ Não registre (mensagem de commit é suficiente) |
| Estado temporário que mudará | ⚠️ Veja a persistência; só registre se for duradouro |
| Baixa frequência, mas fatal (não lido em 6 meses, mas ainda é a única verdade) | ✅ Mantenha — 30 dias sem toque ≠ obsoleto; o critério para excluir é "tópico desapareceu/foi substituído", não "há quanto tempo não é lido" |
Julgue "onde registrar" — Roteamento de quatro níveis por localidade de gatilho:
Primeiro faça uma pergunta ortogonal: "Quando esta informação for necessária no futuro, a pessoa estará olhando para uma localização específica do código, ou estará tomando uma decisão entre arquivos / depurando um tipo específico de erro?"
| Condição de gatilho | Destino | Mecanismo |
|---|---|---|
| Olhando para uma linha/bloco específico, o PORQUÊ cabe em uma frase | Comentário inline no código (logo acima da linha) | 100% de chance de ser visto ao modificar o arquivo, custo de indexação zero |
| Contrato de múltiplos pontos envolvendo um conjunto específico de arquivos / checklist | .claude/rules/<x>.md + frontmatter paths: | Contexto injetado automaticamente ao acessar caminhos correspondentes |
| Gatilho é um cenário/erro/tipo de problema, ou envolve vários arquivos, ou não pertence a um único arquivo do repositório (SDK/buraco de plataforma) | memory (este sistema) | Acionado pela description |
| Regra que deve ser seguida em toda sessão (comandos, pilha tecnológica, preferências de colaboração) | CLAUDE.md | Permanente |
Feedback vinculado a um arquivo: por padrão, DIVIDIR: O cerne local do arquivo vai para comentários inline; a memória só mantém o princípio reutilizável entre arquivos + um ponteiro para o arquivo.
Três barreiras contra migração excessiva (por padrão, fique na memória, evite migrar):
- Se após remover o arquivo específico ainda restar uma lição genérica → mantenha na memória (ex.: "não use campos opcionais para decisões críticas" — o arquivo específico é só um exemplo, o princípio é transferível)
- Comportamento de plataforma/SDK que se repete em vários arquivos → mantenha na memória, mesmo que tenha implicações de código
- Lápide (X foi aposentado → veja Y) / SOP de investigação / raciocínio econômico do negócio → mantenha na memória (gatilho está no nível de arquitetura/cenário)
Evidência (auditoria completa de uma base de produção com 175 arquivos): apenas ~15% das entradas estão vinculadas a um único arquivo, e na maioria desses casos o cerne do arquivo já estava em comentários de código — "migrar" geralmente significa remover cópias redundantes da memória, não uma verdadeira realocação.
Como escrever .claude/rules/*.md (coloque em .claude/rules/ do projeto, no git → compartilhado entre máquinas/worktrees):
---
description: Uma frase sobre o que esta regra trata
paths:
- src/components/SomeDialog.tsx
- src/lib/providers/*.ts # suporta glob
---
Corpo do contrato / checklist de vários pontos (gotchas de múltiplos pontos) que é injetado automaticamente ao acessar os caminhos acima.
⚠️ Limitações conhecidas da injeção nativa de regras (verificado em 2026-07, anthropics/claude-code issues): Regras com paths: só são injetadas durante Leitura de arquivos correspondentes, não durante Escrita / criação de novos arquivos (#23478); paths: nas regras do usuário ~/.claude/rules/ são ignoradas, apenas as do projeto funcionam (#21858). Contratos que "devem ser aplicados mesmo ao criar novos arquivos" devem ficar no CLAUDE.md, não apenas nas regras.
Regra 3: Priorize atualizar existente, não criar novo
Se já existe um arquivo relacionado ao tópico → atualize esse arquivo (adicione seção ou seção de changelog). Crie novo apenas se o tópico for completamente ortogonal. Criar novos leva à fragmentação do tópico → dificuldade em encontrar → perda de memória.
Regra 4: Memória não é carregada automaticamente, a description determina o acerto
Arquivos de tópico (memory/*.md) não são carregados no início da sessão. O Claude usa a description no índice MEMORY.md para decidir se deve lê-los. A description deve ser uma mistura de palavras-chave de cenário + conclusão central, caso contrário, o Claude decidirá qual ler por impulso.
Verificação do mecanismo nativo (2026-07, docs oficiais/en/memory): Não há recuperação semântica automática por vetores — a descoberta depende inteiramente da "linha de índice MEMORY.md + nome do arquivo"; o Claude lê sob demanda usando Read; ao ler, o harness injeta um aviso de atualidade "Esta memória tem N dias de idade". A qualidade do gancho da linha de índice = 100% da taxa de acerto — este é o comportamento nativo, não uma convenção desta habilidade.
Regra 5: A habilidade deve obedecer às regras que ensina
Se esta habilidade instrui o usuário a escrever uma seção ## Why, ela também deve explicar o Porquê de cada uma de suas regras (todas estão inline neste arquivo).
Aviso de Escopo: A Regra 5 se aplica a "método/forma de escrever/formato da Referência Rápida, etc.", não se aplica recursivamente às regras de schema. Schema (nomeação/ frontmatter/ seção Why) é para arquivos de memória, não se aplica à habilidade em si. A habilidade não é um arquivo de memória.
Regra 6: Quando dividir em vez de atualizar (evitar sobrecarga de arquivo único / grupo único)
A Regra 3 prioriza atualizar, mas há limites. Sinais de que deve dividir (nível de arquivo único):
| Sinal | Ação |
|---|---|
| Arquivo existente > 100 linhas, e o novo conteúdo é ortogonal ao tópico original | Divida em novo arquivo, não insira |
| Arquivo existente já tem ≥ 4 seções de nível H2, e o novo conteúdo pertence a um 5º tópico independente | Divida em novo arquivo |
| Após adicionar, o comprimento total ultrapassa 150 linhas | Avalie se deve dividir (depende da independência do tópico) |
| O novo conteúdo não corresponde ao título/description do arquivo existente | Divida em novo arquivo (o arquivo original deve focar no tópico declarado) |
Sobrecarga de grupo único (nível de índice):
| Sinal | Ação |
|---|---|
| Número de entradas em um grande grupo do MEMORY.md ≥ 15 | Considere criar uma memória hub (índice de seção) para substituir a lista plana; novas entradas são anexadas ao hub |
| A soma das descriptions de um grupo, quando lida, > 25 linhas | Mesmo que acima |
MEMORY.md > 23.000 caracteres (wc -m) ou > 190 linhas | 🔴 Limite nativo = primeiras 200 linhas ou 25K caracteres, o que vier primeiro (redação oficial "25KB", mas na prática é medido como comprimento de string em caracteres: um índice de 27.972 caracteres/37,9KB foi truncado exatamente no caractere 25.000, ~35% antes do que seria por bytes). A parte excedente não é carregada silenciosamente. ⚠️ Não use wc -c (bytes) para estimar: chinês UTF-8 tem 3 bytes por caractere, superestimando a margem em ~35%. Próximo ao limite, o harness injeta um aviso; se vir Only part of it was loaded, o índice já está sendo perdido |
| Linha de índice individual > ~160 caracteres | Description com muitos detalhes → mova para o arquivo de tópico ou para comentários de código, deixando apenas "palavras-chave de cenário + conclusão central" |
Por que a sobrecarga de grupo único também importa: O Claude escaneia as descriptions do MEMORY.md para acertar; com 20+ descriptions em um grupo, há risco de omissão em uma única varredura. Depois de criar um hub, o índice do grupo aponta para uma única linha para o hub, e o hub contém um mapa de tópicos.
Por que a sobrecarga do índice como um todo é a mais perigosa: Sobrecarga de arquivo único/grupo único é apenas "queda na taxa de acerto"; mas o truncamento do índice = a entrada inteira no final não é carregada = taxa de acerto zero, e silenciosamente, sem erro. Portanto, ⭐⭐⭐ as entradas coroa devem ser colocadas no topo do MEMORY.md (seguro contra truncamento).
Prioridades de redução quando o índice está acima do limite / muito grande (comprimir descriptions é a pior primeira medida, pois prejudica a taxa de acerto):
- Primeiro migre: Entradas locais de arquivo → comentários inline /
.claude/rules(índice fica menor e taxa de acerto aumenta, veja Regra 2 roteamento de quatro níveis) - Depois exclua: Lápides reais (tópico desapareceu/foi substituído e sem valor de prevenção de renascimento)
- Depois reordene: Mova ⭐⭐⭐ para o topo do MEMORY.md
- Depois classifique: Aloque orçamento de caracteres por importância — entradas coroa ≤160 caracteres, entradas comuns ≤110, entradas de cauda longa/baixa frequência agregadas em uma única linha com vários links (
subtópico → [a](f1.md) · [b](f2.md), uma linha comporta 5-10 arquivos). Além disso: use nomes curtos sem prefixo de tipo para rótulos de links ([foo-bar](feedback_foo_bar.md)), não repita o nome completo do arquivo, economize 12-45 caracteres por linha - Por último comprima a quantidade de informação de uma descrição individual
Casos históricos de buracos (referência, não parte das regras)
- Sobrecarga de arquivo único: Um arquivo de referência cresceu para 130+ linhas, com 7-8 subtópicos independentes (infraestrutura, lista de crons, manual de falhas, etc.), e a descrição no índice MEMORY.md não resumia bem, então o Claude não conseguia acertar o subtópico específico. Dividido em 5 memórias independentes, cada tópico foi acertado com precisão.
- Sobrecarga de grupo único: Um determinado grupo acumulou 20+ entradas; em uma nova sessão, o Claude omitiu algumas ao escanear o índice e, ao processar uma tarefa, reinventou a roda. Criar uma memória hub para agregar as entradas relacionadas → resolvido.
- Sobrecarga geral do índice: MEMORY.md cresceu para 43KB (≈31K caracteres, excedendo o limite de 25K caracteres), com 93 descriptions cada uma com 400-900 caracteres; ao iniciar, foi truncado silenciosamente, e entradas ⭐⭐⭐ no final foram perdidas → em uma investigação, um mecanismo que funcionava conforme o design foi erroneamente classificado como um bug. Lição: description não é quanto mais detalhada melhor; detalhes excessivos estouram o índice e prejudicam o acerto.
- Calibração errada entre bytes e caracteres: Ao gerenciar a sobrecarga, o limite de aviso foi definido em bytes (
wc -c) como 32KB, enquanto o harness executa em caracteres (chinês tem 3 bytes por caractere) → o limite em bytes fez parecer que ainda havia margem, e o índice foi truncado novamente. Lição: alinhe-se com o harness usando a mesma unidade; monitore comwc -m.
Modos de Fluxo de Trabalho
Modo 1: Avaliação de Candidatos (múltiplos candidatos, precisa filtrar)
Cenários de gatilho (múltiplos candidatos → precisa do Modo 1 para filtrar):
- Após concluir uma funcionalidade / após um longo debug / após uma revisão
- Após concluir uma ação antiexploração (possivelmente múltiplos pontos de julgamento + lições)
- Após concluir um incidente de segurança / localizar uma falha
- Usuário diz "registra isso" (vago, sem especificar qual buraco)
Conteúdo específico único vai direto para o Modo 2: Usuário diz "registra aquele bug wildcard de hoje" / "registra o manual de falhas de vazamento de conexão" → já está claro que é um item único → Modo 2, não Modo 1.
Passos:
- Revise os nós-chave desta sessão (correções do usuário, descobertas de revisão, bugs inesperados, consultas de comparação da indústria, conclusões não óbvias de decisões únicas)
- Aplique a árvore de decisão da Regra 2 a cada um, filtrando os que valem a pena registrar
- Para cada candidato, julgue:
- Já existe um arquivo de memória cobrindo isso? (grep no índice MEMORY.md) → Se sim, vá para o Modo 3 (atualizar); se não, vá para o Modo 2 (criar novo)
- O conteúdo a ser adicionado ultrapassa a linha de gatilho de divisão da Regra 6? → Divida em novo arquivo
- Deve ir para o CLAUDE.md em vez de memória? (veja tabela abaixo)
- Confirme a lista com o usuário: Liste os candidatos "sugerido criar novo / sugerido atualizar / sugerido dividir" e aguarde confirmação antes de escrever
Limite memória vs CLAUDE.md:
| Natureza do conteúdo | Onde colocar |
|---|---|
| Buracos específicos aprendidos (bug de SDK, limitação de plataforma, dados da indústria) | memória feedback_* |
| Referência aprofundada sobre tópico / método padrão / documentação de processo | memória reference_* |
| Fatos de estado (trabalho em andamento, configuração temporária, snapshot da arquitetura atual) | memória project_* |
| Regras que devem ser seguidas em toda sessão (comandos, pilha tecnológica, preferências de colaboração) | CLAUDE.md |
| Regras necessárias apenas ao operar em arquivos específicos | .claude/rules/*.md com frontmatter paths |
Modo 2: Nova memória (fluxo padrão)
Passo 0: Primeiro verifique a localidade do gatilho (Regra 2, roteamento de quatro níveis)
Antes de escrever, confirme se realmente deve ir para a memória: arquivo único → comentário inline; contrato de múltiplos arquivos → .claude/rules+paths; cenário/entre arquivos/buraco de plataforma → só então vai para a memória. Feedback vinculado a arquivo: por padrão DIVIDIR (cerne vai para comentário, memória só mantém princípio entre arquivos + ponteiro). Veja Regra 2.
Passo 1: Determine o tipo
| Tipo | Quando usar | Informação obrigatória |
|---|---|---|
| feedback | Buraco aprendido (bug de SDK / limitação de plataforma / preferência do usuário) | Razão (por que esta conclusão) + Quando reutilizar (cenário de gatilho) |
| reference | Referência aprofundada sobre tópico / método padrão / comparação da indústria / pipeline reutilizável | Seção de razão não obrigatória (descritiva) |
| project | Fatos de estado (snapshot de arquitetura, trabalho em andamento, análise econômica) | Seção de razão não obrigatória (estado) |
Forma de apresentação da informação obrigatória para feedback (qualquer uma serve):
- Seção separada:
## Whyou sinônimos em chinês## 根因/## 原因/## 教训/## 为什么(auditoria aceita) - Negrito inline:
**Why**:/**根因**:(também para conclusões curtas) - Inline na description ou no título ## (se a conclusão em si já implica a razão + quando reutilizar, como tabela ❌/✅)
Informação de quando reutilizar: Pode ser uma seção separada ## How to apply, ou a description contém palavras-chave de cenário (ex.: troca de tab / mutation já sugere o cenário de gatilho).
Passo 2: Nomeação do arquivo
<type>_<topic>[_<modifier>].md tudo minúsculo com underscore:
- ✅
feedback_supabase_from_deadlock.md - ✅
reference_supabase_egress_favorites_refactor.md - ❌
feedback-supabase-deadlock.md(usou hífen) - ❌
FeedbackSupabaseDeadlock.md(CamelCase) - ❌
_schema.md(começa com underscore, será tratado como arquivo oculto e Claude não o lerá ativamente)
Passo 3: Escreva o frontmatter
---
name: slug-em-kebab-case
description: Palavras-chave de cenário + conclusão central
type: feedback | reference | project # plano (recomendado)
# ou:
# metadata:
# type: feedback | reference | project # aninhado (compatível)
---
Posição do campo type: type: plano (recomendado) ou metadata.type: aninhado (ambos aceitos). O script de auditoria reconhece ambos. Para novos arquivos, prefira o formato plano, alinhado com a maioria existente.
Critério de estilo da description:
| ✅ Boa description | ❌ Má description |
|---|---|
Mutation supabase.from() no lado do navegador causa deadlock após troca de tab; deve usar fetch() para chamar a API REST | Problemas relacionados ao Supabase |
Falha de Transformações de Imagem CF com cache de 7 dias / cf-resized err= / Padrão de repetição FavoriteCard | Às vezes a imagem não aparece |
Políticas RLS devem ser encapsuladas com (SELECT auth.uid()), caso contrário, serão reavaliadas por linha | Otimização de desempenho RLS |
Critério: Ao ler a description, Claude consegue saber imediatamente "esta é a conclusão Y a ser consultada no cenário X"?
Passo 4: Escreva o corpo
Classe feedback (deve conter razão + quando reutilizar):
# Título (O quê — uma frase)
[Conclusão central + 1-2 parágrafos de contexto]
## Why (ou sinônimos: ## 根因 / ## 原因 / ## 教训 / ## 为什么)
[Por que esta conclusão — o buraco específico que caiu, descoberta de revisão, preferência do usuário]
**Por que é obrigatório**: Sem a seção de razão, na próxima vez que a mesma decisão for discutida, muitas vezes a mesma conclusão errada será alcançada.
## How to apply (pode ser omitido, se a description já contiver palavras-chave de cenário)
[Quando reutilizar esta — cenário de gatilho, checklist, passos para evitar o buraco]
Classes reference / project: Estrutura de seção não obrigatória; organize naturalmente por tópico.
Passo 5: Adicione ao índice MEMORY.md
- Escolha um grupo grande existente, não crie um novo grupo
- Adicione a description na posição correspondente dentro do grupo (alta importância use negrito ⭐⭐ / ⭐⭐⭐)
- Entre tópicos: adicione
(veja também [[outro-arquivo]])no final da description
Modo 3: Atualizar memória existente (prioritário sobre criar nova)
Passo 1: Confirme a afiliação do tópico existente com grep
grep -l "<palavra-chave>" memory/*.md
Passo 2: Decida como atualizar
| Situação | Como atualizar |
|---|---|
| Novo dado / novo caso complementa conclusão existente | Adicione seção no corpo ou seção de changelog |
| Conclusão existente é refutada | Adicione no topo do arquivo antigo ⚠️ Substituído por [[novo-arquivo-slug]]; no novo arquivo, escreva "substitui a parte X de [[antigo]]" |
| Apenas a description não está clara o suficiente | Altere a description no índice MEMORY.md, não altere o arquivo em si (a menos que também adicione conteúdo) |
Passo 3: Sincronize o MEMORY.md
Se a description foi alterada, a linha correspondente no MEMORY.md também deve ser alterada.
Modo 4: Mudança estrutural (alterar schema / adicionar novo tipo / alterar agrupamento)
Lista de buracos já conhecidos (leitura obrigatória):
- Não tente usar a sintaxe de glob
if: "Write(memory/*.md)"—if:é uma regra de permissão, não um glob de arquivo, já verificado como ineficaz - Não use
exit 2para bloquear hooks — já verificado que quebra o fluxo de lote de pré-implantação (Claude não tem mecanismo de repetição automática) - Não coloque a fonte oficial do schema em arquivos que começam com underscore, como
_schema.md— Claude não lê arquivos de tópico ativamente - Não configure hooks em
.claude/settings.jsondo projeto — este diretório geralmente está em.gitignore, não entra no git e não é compartilhado entre worktrees - Ao adicionar um novo campo obrigatório, sincronize 3 lugares: (a) seção desta habilidade "Modo 2 → Passo 3" (b) seção de resumo rápido no topo do MEMORY.md (c) lista de campos no script audit-memory.sh
- Antes de modificar um hook / adicionar restrição, execute
bash scripts/audit-memory.shpara ver a taxa de conformidade atual — só tome medidas rigorosas se <95%; se ≥95%, mantenha avisos leves - O monitoramento do tamanho do MEMORY.md deve ser em caracteres (
wc -m), não em bytes (wc -c) — o limite nativo de 200 linhas/25K caracteres é contado em caracteres; chinês tem 3 bytes por caractere, calibrar por bytes causará truncamento silencioso (veja casos históricos na Regra 6)
Fluxo para alteração de schema:
- Execute a auditoria para obter a linha de base atual
- Projete a alteração (modifique esta habilidade + hub do projeto)
- Verifique se as memórias existentes violam massivamente a nova regra (>10% → adie, primeiro migre conforme a nova regra)
- Atualize a seção de resumo do MEMORY.md
- Altere a lista de campos do script de auditoria
- Execute a auditoria novamente para ver a nova taxa de conformidade
Modo 5: Bootstrap sem memória (novo projeto)
Quando o usuário, em um projeto sem sistema de memória, disser "comece a construir a memória":
Passo 1: Confirme o caminho do diretório de memória automática
O Claude Code cria automaticamente ~/.claude/projects/<project-slug>/memory/, onde <project-slug> = caminho absoluto do projeto com / substituído por -. Ex.:
- Projeto
/Users/alice/Project/myapp→ slug-Users-alice-Project-myapp
Se o Claude Code já tiver criado memória automática para este projeto, o diretório existirá. Verifique: ls ~/.claude/projects/ | grep <nome do projeto>.
Passo 2: Crie o índice MEMORY.md
Modelo do topo (pode ser comprimido para ~25 linhas):
# Memória do projeto <Nome do Projeto>
## ⭐⭐⭐ Regras rápidas para escrever memória (regras rígidas)
- Nome do arquivo:`<type>_<topic>.md` tudo minúsculo com underscore; type ∈ {feedback, reference, project}
- Frontmatter obrigatório: name / description / type
- feedback deve conter seção ## Why (ou sinônimos em chinês ## 根因 / ## 教训 / ## 原因)
- Estilo da description: palavras-chave de cenário + conclusão central (uma linha ≤160 caracteres)
- Se já existe arquivo para o mesmo tópico → atualize, não crie novo (se ultrapassar o limite da Regra 6, divida)
- Limite rígido deste índice: primeiras 200 linhas ou 25K caracteres (o que vier primeiro); o que exceder não é carregado silenciosamente
- Método detalhado: habilidade memory-management
## ⭐ Lista de tópicos do projeto
(Nenhum ainda — posteriormente, adicione grupos por tópico)
Passo 3: Limiares de evolução de agrupamento (estrutura determinada pelo número de arquivos)
| Número de arquivos de memória | Estrutura recomendada |
|---|---|
| < 15 | Lista plana, sem agrupamento (uma única lista é suficiente; agrupar fragmenta) |
| 15-25 | Introduza 3-5 grupos grandes (agregue por tópico) |
| > 25 | Agrupamento maduro, congele grupos proibindo novos; novas entradas anexadas a grupos existentes (entre tópicos, use (veja também X)) |
Passo 4: Adicione um protocolo de Memória no topo do CLAUDE.md (3-5 linhas)
## Gerenciamento de Memória
Ao escrever / atualizar memória / ajustar schema → use a habilidade `memory-management`.
- Regras rápidas: seção ⭐⭐⭐ no topo do MEMORY.md
- Taxa de conformidade da auditoria:`bash scripts/audit-memory.sh` (opcional, veja skill templates/)
Passo 5: Reutilize os métodos gerais desta habilidade
Não copie o conteúdo da habilidade para o projeto. A habilidade fica no nível do usuário, todos os projetos compartilham um único conjunto de métodos. No projeto, coloque apenas o estado específico do projeto (lista de grupos / tarefas pendentes / buracos específicos do projeto).
Especificação do Schema (fonte oficial)
Nomeação de arquivos
<type>_<topic>[_<modifier>].md tudo minúsculo com underscore, type ∈ {feedback, reference, project}
Frontmatter obrigatório
---
name: slug-em-kebab-case
description: Palavras-chave de cenário + conclusão central
type: feedback | reference | project # plano (recomendado)
# ou:
# metadata:
# type: feedback | reference | project # aninhado (compatível)
---
O script de auditoria reconhece ambos. Para novos arquivos, prefira o formato plano.
Informação obrigatória para feedback
Seção de razão (qualquer uma):
## Whyou título sinônimo em chinês## 根因/## 教训/## 原因/## 为什么/## Root cause(pode ter:em inglês ou chinês)- Negrito inline
**Why**:/**Why**:/**根因**:etc.
Quando reutilizar (qualquer um):
- Seção separada
## How to apply - Description contém palavras-chave de cenário (implícito o cenário de gatilho)
Estilo da description
Mistura (palavras-chave de cenário + conclusão central) para que Claude, pela description, acerte "consulta Y no cenário X". Uma linha ≤ ~160 caracteres — detalhes vão para o arquivo de tópico ou comentários de código (limite rígido do índice = 200 linhas/25.000 caracteres, o que vier primeiro; o que exceder não é carregado silenciosamente)
Formato da linha de índice
- [rótulo curto](nome completo do arquivo.md) — gancho. Rótulo curto = nome com hífen sem prefixo de tipo (ex.: [supabase-from-deadlock](feedback_supabase_from_deadlock.md)); entradas de cauda longa/baixa frequência usam linha agregada (subtópico → [a](f1.md) · [b](f2.md))
Congelamento de grupos
Escolha entre grupos grandes existentes, proibido criar novos grupos. Afiliação ambígua use (veja também hub-X) para referência cruzada.
Erros Comuns
| Erro | Certo |
|---|---|
| Escrever description genérica "Problema Supabase" de memória | Escreva palavras-chave de cenário + conclusão "supabase.from() deadlock ao trocar tab, use fetch" |
| feedback só descreve "o quê" | feedback deve ter ## Why, protegendo contra re-questionamento futuro |
| Criar segundo arquivo para o mesmo tópico | Priorize atualizar o existente; criar novo fragmenta |
| Criar novo grupo "Problemas de Rede" para colocar 1 entrada | Use grupo existente; entre tópicos, use (veja também X) |
| Colocar especificação de schema em arquivo de memória | Schema está nesta habilidade; memória armazena fatos |
| Usar hook com exit 2 para bloqueio forçado | Use aviso leve (stderr + exit 0) ou auditoria posterior |
Auto-Verificação (após escrever)
- O tipo está correto (feedback/reference/project)?
- O nome do arquivo segue
<type>_<topic>.mdtudo minúsculo com underscore? - Frontmatter completo (name / description / type)?
- Classe feedback tem seção de razão (
## Whyou sinônimo em chinês / negrito inline)? - Description contém palavras-chave de cenário + conclusão central?
- Já foi adicionado ao grupo correto no índice MEMORY.md?
- Não foi criado um novo grupo? (se sim, desfaça e coloque em grupo existente)
- Entre tópicos, foi adicionado
(veja também X)? - Verificação da Regra 6: Novo arquivo < 100 linhas + < 5 seções H2? (se atualizar um arquivo existente o fez ultrapassar o limite, converta em divisão em novo arquivo)
- Verificação de localidade de gatilho (Regra 2): Esta entrada está vinculada a um arquivo específico? Se sim, o PORQUÊ local do arquivo já deve / deve estar em comentários de código, e a memória deve conter apenas o princípio entre arquivos?
- Verificação do nível do índice: Após adicionar/alterar a description, o MEMORY.md ainda tem < 23.000 caracteres (
wc -m, não bytes!) e < 190 linhas + cada linha ≤ ~160 caracteres? - Auditoria de força de gatilho: Liste 3 palavras-chave de cenário que podem ser perguntadas no futuro e simule: "Claude leria esta memória com base na description?" (se não conseguir imaginar um cenário, a description está inadequada)
Integração com Ferramentas
O script de auditoria é uma ferramenta opcional do projeto.
Se existir scripts/audit-memory.sh na raiz do projeto → execute:
bash scripts/audit-memory.sh # veja taxa de conformidade / liste violações / liste não tocados há 30 dias
Saída: total de arquivos / sem frontmatter / sem Why / links quebrados no MEMORY.md / não tocados há 30 dias / tamanho do MEMORY.md (caracteres + linhas, comparado ao limite nativo de 200 linhas/25K caracteres) / taxa de conformidade em %. Taxa de conformidade alvo ≥ 95%.
Se não houver script de auditoria → crie a partir do modelo:
# A habilidade no nível do usuário tem um modelo genérico
cp ~/.claude/skills/memory-management/templates/audit-memory.template.sh \
<seu-projeto>/scripts/audit-memory.sh
# Modifique MEMORY_DIR para apontar para o diretório de memória automática do seu projeto
chmod +x <seu-projeto>/scripts/audit-memory.sh
bash <seu-projeto>/scripts/audit-memory.sh
Caminho de memória automática padrão de referência: ~/.claude/projects/<project-slug>/memory/, veja Modo 5, Passo 1.