Por que o código do Claude parece tão estável: Um mergulho profundo de um desenvolvedor em seu design de armazenamento local

O código Claude tem estado em todo o lado ultimamente. Os programadores estão a utilizá-lo para lançar funcionalidades mais rapidamente, automatizar fluxos de trabalho e criar protótipos de agentes que funcionam em projectos reais. O que é ainda mais surpreendente é a quantidade de não-codificadores que também se juntaram a eles - construindo ferramentas, ligando tarefas e obtendo resultados úteis quase sem configuração. É raro ver uma ferramenta de codificação de IA espalhar-se tão rapidamente por tantos níveis de competências diferentes.

O que realmente se destaca, no entanto, é a sensação de estabilidade. O Claude Code lembra-se do que aconteceu em todas as sessões, sobrevive a crashes sem perder o progresso e comporta-se mais como uma ferramenta de desenvolvimento local do que como uma interface de chat. Essa fiabilidade resulta da forma como lida com o armazenamento local.

Em vez de tratar a sua sessão de codificação como um chat temporário, o Claude Code lê e escreve ficheiros reais, armazena o estado do projeto no disco e regista cada passo do trabalho do agente. As sessões podem ser retomadas, inspecionadas ou revertidas sem suposições, e cada projeto permanece isolado de forma limpa, evitando os problemas de contaminação cruzada que muitas ferramentas de agente enfrentam.

Neste post, vamos dar uma olhada mais de perto na arquitetura de armazenamento por trás dessa estabilidade e por que ela desempenha um papel tão importante em fazer o Claude Code parecer prático para o desenvolvimento diário.

Desafios que todo assistente local de codificação de IA enfrenta

Antes de explicar como o Claude Code aborda o armazenamento, vamos dar uma olhada nos problemas comuns que as ferramentas locais de codificação de IA tendem a enfrentar. Estes surgem naturalmente quando um assistente trabalha diretamente no seu sistema de ficheiros e mantém o estado ao longo do tempo.

1. Os dados do projeto são misturados entre os espaços de trabalho.

A maioria dos programadores alterna entre vários repositórios ao longo do dia. Se um assistente transporta o estado de um projeto para outro, torna-se mais difícil compreender o seu comportamento e mais fácil para ele fazer suposições incorrectas. Cada projeto precisa do seu próprio espaço limpo e isolado para o estado e o histórico.

2. Os crashes podem causar perda de dados.

Durante uma sessão de programação, um assistente produz um fluxo constante de dados úteis - edições de ficheiros, chamadas de ferramentas, passos intermédios. Se estes dados não forem guardados de imediato, uma falha ou reinício forçado pode eliminá-los. Um sistema fiável grava o estado importante no disco assim que é criado para que o trabalho não se perca inesperadamente.

3. Nem sempre é claro o que o agente realmente fez.

Uma sessão típica envolve muitas acções pequenas. Sem um registo claro e ordenado dessas acções, é difícil reconstituir a forma como o assistente chegou a um determinado resultado ou localizar o passo em que algo correu mal. Um histórico completo torna a depuração e a revisão muito mais fáceis de gerir.

4. Desfazer os erros exige demasiado esforço.

Por vezes, o assistente efectua alterações que não funcionam corretamente. Se não tiver uma forma integrada de reverter essas alterações, acaba por ter de procurar manualmente as edições no repositório. O sistema deve rastrear automaticamente o que foi alterado para que possa desfazê-lo de forma limpa sem trabalho extra.

5. Projectos diferentes precisam de configurações diferentes.

Os ambientes locais variam. Alguns projectos requerem permissões, ferramentas ou regras de diretório específicas; outros têm scripts ou fluxos de trabalho personalizados. Um assistente precisa respeitar essas diferenças e permitir configurações por projeto, mantendo seu comportamento central consistente.

Os princípios de design de armazenamento por trás do Claude Code

O design de armazenamento do Claude Code é construído em torno de quatro ideias diretas. Elas podem parecer simples, mas juntas abordam os problemas práticos que surgem quando um assistente de IA trabalha diretamente na sua máquina e em vários projetos.

1. Cada projeto tem o seu próprio armazenamento.

O Claude Code vincula todos os dados da sessão ao diretório do projeto a que pertencem. Isto significa que as conversas, edições e registos permanecem no projeto de onde vieram e não se infiltram noutros. Manter o armazenamento separado torna o comportamento do assistente mais fácil de compreender e simplifica a inspeção ou eliminação de dados para um repositório específico.

2. Os dados são salvos no disco imediatamente.

Em vez de manter os dados de interação na memória, o Claude Code grava-os no disco assim que são criados. Cada evento - mensagem, chamada de ferramenta ou atualização de estado - é anexado como uma nova entrada. Se o programa travar ou for fechado inesperadamente, quase tudo ainda estará lá. Esta abordagem mantém as sessões duráveis sem adicionar muita complexidade.

3. Cada ação tem um lugar claro na história.

O Claude Code liga cada mensagem e ação da ferramenta à anterior, formando uma sequência completa. Este histórico ordenado permite rever o desenrolar de uma sessão e seguir os passos que levaram a um resultado específico. Para os desenvolvedores, ter esse tipo de rastreamento facilita muito a depuração e a compreensão do comportamento do agente.

4. As edições de código são fáceis de reverter.

Antes de o assistente atualizar um ficheiro, o Claude Code guarda um instantâneo do seu estado anterior. Se a alteração se revelar incorrecta, pode restaurar a versão anterior sem ter de vasculhar o repositório ou adivinhar o que mudou. Esta simples rede de segurança torna as edições feitas por IA muito menos arriscadas.

Layout do armazenamento local do Claude Code

Claude Code armazena todos os seus dados locais em um único lugar: seu diretório pessoal. Isto mantém o sistema previsível e facilita a inspeção, depuração ou limpeza quando necessário. O layout de armazenamento é construído em torno de dois componentes principais: um pequeno arquivo de configuração global e um diretório de dados maior, onde fica todo o estado do projeto.

Dois componentes principais:

• ~/.claude.jsonArmazena a configuração global e os atalhos, incluindo mapeamentos de projeto, configurações do servidor MCP e prompts usados recentemente.

• ~/.claude/O diretório de dados principal, onde o Claude Code armazena conversas, sessões de projeto, permissões, plug-ins, habilidades, histórico e dados de tempo de execução relacionados.

De seguida, vamos analisar mais detalhadamente estes dois componentes principais.

(1) Configuração global: ~/.claude.json

Este ficheiro funciona como um índice e não como um armazenamento de dados. Regista os projectos em que trabalhou, as ferramentas que estão associadas a cada projeto e os prompts que utilizou recentemente. Os dados de conversação em si não são armazenados aqui.

{
  "projects": {
    "/Users/xxx/my-project": {
      "mcpServers": {
        "jarvis-tasks": {
          "type": "stdio",
          "command": "python",
          "args": ["/path/to/run_mcp.py"]
        }
      }
    }
  },
  "recentPrompts": [
    "Fix the bug in auth module",
    "Add unit tests"
  ]
}

(2) Diretório de dados principal: ~/.claude/

O diretório ~/.claude/ é onde reside a maior parte do estado local do Claude Code. A sua estrutura reflecte algumas ideias centrais de design: isolamento de projectos, persistência imediata e recuperação segura de erros.

~/.claude/
├── settings.json                    # Global settings (permissions, plugins, cleanup intervals)
├── settings.local.json              # Local settings (machine-specific, not committed to Git)
├── history.jsonl                    # Command history
│
├── projects/                        # 📁 Session data (organized by project, core directory)
│   └── -Users-xxx-project/          # Path-encoded project directory
│       ├── {session-id}.jsonl       # Primary session data (JSONL format)
│       └── agent-{agentId}.jsonl    # Sub-agent session data
│
├── session-env/                     # Session environment variables
│   └── {session-id}/                # Isolated by session ID
│
├── skills/                          # 📁 User-level skills (globally available)
│   └── mac-mail/
│       └── SKILL.md
│
├── plugins/                         # 📁 Plugin management
│   ├── config.json                  # Global plugin configuration
│   ├── installed_plugins.json       # List of installed plugins
│   ├── known_marketplaces.json      # Marketplace source configuration
│   ├── cache/                       # Plugin cache
│   └── marketplaces/
│       └── anthropic-agent-skills/
│           ├── .claude-plugin/
│           │   └── marketplace.json
│           └── skills/
│               ├── pdf/
│               ├── docx/
│               └── frontend-design/
│
├── todos/                           # Task list storage
│   └── {session-id}-*.json          # Session-linked task files
│
├── file-history/                    # File edit history (stored by content hash)
│   └── {content-hash}/              # Hash-named backup directory
│
├── shell-snapshots/                 # Shell state snapshots
├── plans/                           # Plan Mode storage
├── local/                           # Local tools / node_modules
│   └── claude                       # Claude CLI executable
│   └── node_modules/                # Local dependencies
│
├── statsig/                         # Feature flag cache
├── telemetry/                       # Telemetry data
└── debug/                           # Debug logs

Este layout é intencionalmente simples: tudo o que o Claude Code gera vive em um diretório, organizado por projeto e sessão. Não há nenhum estado oculto espalhado pelo seu sistema, e é fácil inspecionar ou limpar quando necessário.

Como o Claude Code gerencia a configuração

O sistema de configuração do Claude Code é projetado em torno de uma idéia simples: manter o comportamento padrão consistente entre as máquinas, mas ainda permitir que ambientes e projetos individuais personalizem o que precisam. Para que isso funcione, o Claude Code usa um modelo de configuração de três camadas. Quando a mesma configuração aparece em mais de um lugar, a camada mais específica sempre vence.

Os três níveis de configuração

O Claude Code carrega a configuração na seguinte ordem, da prioridade mais baixa para a mais alta:

┌─────────────────────────────────────────┐
│    Project-level configuration          │  Highest priority
│    project/.claude/settings.json        │  Project-specific, overrides other configs
├─────────────────────────────────────────┤
│    Local configuration                  │  Machine-specific, not version-controlled
│    ~/.claude/settings.local.json        │  Overrides global configuration
├─────────────────────────────────────────┤
│    Global configuration                 │  Lowest priority
│    ~/.claude/settings.json              │  Base default configuration
└─────────────────────────────────────────┘

Pode pensar nisto como começar com predefinições globais, depois aplicar ajustes específicos da máquina e, finalmente, aplicar regras específicas do projeto.

A seguir, examinaremos cada nível de configuração em detalhes.

(1) Configuração global: ~/.claude/settings.json

A configuração global define o comportamento padrão do Claude Code em todos os projetos. É aqui que você define as permissões de linha de base, habilita plug-ins e configura o comportamento de limpeza.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Read(**)", "Bash(npm:*)"],
    "deny": ["Bash(rm -rf:*)"],
    "ask": ["Edit", "Write"]
  },
  "enabledPlugins": {
    "document-skills@anthropic-agent-skills": true
  },
  "cleanupPeriodDays": 30
}

(2) Configuração local: ~/.claude/settings.local.json

A configuração local é específica para uma única máquina. Não se destina a ser partilhada ou verificada no controlo de versões. Isto torna-a um bom local para chaves de API, ferramentas locais ou permissões específicas do ambiente.

{
  "permissions": {
    "allow": ["Bash(git:*)", "Bash(docker:*)"]
  },
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxx"
  }
}

(3) Configuração ao nível do projeto: project/.claude/settings.json

A configuração ao nível do projeto aplica-se apenas a um único projeto e tem a prioridade mais elevada. É aqui que se definem as regras que devem ser sempre aplicadas quando se trabalha nesse repositório.

{
  "permissions": {
    "allow": ["Bash(pytest:*)"]
  }
}

Com as camadas de configuração definidas, a próxima pergunta é como o Claude Code realmente resolve a configuração e as permissões em tempo de execução.

O Claude Code aplica a configuração em três camadas: começa com padrões globais, depois aplica substituições específicas da máquina e, por fim, aplica regras específicas do projeto. Quando a mesma configuração aparece em vários lugares, a configuração mais específica tem prioridade.

As permissões seguem uma ordem de avaliação fixa:

1. negar - bloqueia sempre

2. pedir - requer confirmação

3. permitir - é executado automaticamente

4. predefinição - aplica-se apenas quando nenhuma regra corresponde

Isto mantém o sistema seguro por defeito, ao mesmo tempo que dá aos projectos e às máquinas individuais a flexibilidade de que necessitam.

Armazenamento de sessão: Como o Claude Code persiste os principais dados de interação

No Claude Code, as sessões são a unidade central de dados. Uma sessão captura toda a interação entre o usuário e a IA, incluindo a própria conversa, chamadas de ferramentas, alterações de arquivos e contexto relacionado. O modo como as sessões são armazenadas tem um impacto direto na confiabilidade, na capacidade de depuração e na segurança geral do sistema.

Manter os dados da sessão separados para cada projeto

Depois que as sessões são definidas, a próxima pergunta é como o Claude Code as armazena de forma a manter os dados organizados e isolados.

O Claude Code isola os dados da sessão por projeto. As sessões de cada projeto são armazenadas em um diretório derivado do caminho do arquivo do projeto.

O caminho de armazenamento segue este padrão:

~/.claude/projects/ + path-encoded project directory

Para criar um nome de diretório válido, caracteres especiais como /, espaços e ~ são substituídos por -.

Por exemplo:

/Users/bill/My Project → -Users-bill-My-Project

Esta abordagem garante que os dados da sessão de diferentes projectos nunca se misturam e podem ser geridos ou removidos por projeto.

Por que as sessões são armazenadas no formato JSONL

O Claude Code armazena dados de sessão usando JSONL (JSON Lines) em vez de JSON padrão.

Em um arquivo JSON tradicional, todas as mensagens são agrupadas em uma estrutura grande, o que significa que o arquivo inteiro precisa ser lido e reescrito sempre que for alterado. Em contraste, o JSONL armazena cada mensagem como a sua própria linha no ficheiro. Uma linha equivale a uma mensagem, sem qualquer invólucro exterior.

Aspeto	JSON padrão	JSONL (Linhas JSON)
Como os dados são armazenados	Uma estrutura grande	Uma mensagem por linha
Quando os dados são guardados	Normalmente no final	Imediatamente, por mensagem
Impacto do crash	Todo o ficheiro pode quebrar	Apenas a última linha é afetada
Escrever novos dados	Reescrever todo o ficheiro	Acrescentar uma linha
Utilização da memória	Carregar tudo	Ler linha a linha

O JSONL funciona melhor em vários aspectos importantes:

• Gravação imediata: Cada mensagem é escrita no disco assim que é gerada, em vez de esperar que a sessão termine.

• Resistente a falhas: Se o programa falhar, apenas a última mensagem inacabada pode ser perdida. Tudo o que foi escrito antes disso permanece intacto.

• Anexos rápidos: As novas mensagens são adicionadas ao final do ficheiro sem ler ou reescrever os dados existentes.

• Baixa utilização de memória: Os ficheiros de sessão podem ser lidos uma linha de cada vez, pelo que o ficheiro inteiro não precisa de ser carregado na memória.

Um ficheiro de sessão JSONL simplificado tem o seguinte aspeto:

{"type":"user","message":{"role":"user","content":"Hello"},"timestamp":"2026-01-05T10:00:00Z"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}]}}
{"type":"user","message":{"role":"user","content":"Help me fix this bug"}}

Tipos de mensagens de sessão

Um ficheiro de sessão regista tudo o que acontece durante uma interação com o Claude Code. Para fazer isso claramente, ele usa diferentes tipos de mensagens para diferentes tipos de eventos.

• As mensagens do utilizador representam novas entradas no sistema. Isto inclui não só o que o utilizador escreve, mas também os resultados devolvidos pelas ferramentas, como a saída de um comando shell. Do ponto de vista da IA, ambas são entradas às quais ela precisa responder.

• As mensagens do assistente captam o que o Claude faz em resposta. Estas mensagens incluem o raciocínio da IA, o texto que gera e quaisquer ferramentas que decida utilizar. Também registam detalhes de utilização, como contagens de tokens, para fornecer uma imagem completa da interação.

• Os instantâneos do histórico de ficheiros são pontos de controlo de segurança criados antes de o Claude modificar quaisquer ficheiros. Ao salvar o estado original do arquivo primeiro, o código do Claude torna possível desfazer as alterações se algo der errado.

• Os resumos fornecem uma visão geral concisa da sessão e estão ligados ao resultado final. Eles facilitam a compreensão do que foi uma sessão sem repetir cada passo.

Em conjunto, estes tipos de mensagens registam não só a conversa, mas também a sequência completa de acções e efeitos que ocorrem durante uma sessão.

Para tornar isto mais concreto, vejamos exemplos específicos de mensagens do utilizador e de mensagens do assistente.

(1) Exemplo de mensagens do utilizador:

{
  "type": "user",
  "uuid": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
  "parentUuid": null,
  "sessionId": "e5d52290-e2c1-41d6-8e97-371401502fdf",
  "timestamp": "2026-01-05T10:00:00.000Z",
  "message": {
    "role": "user",
    "content": "Analyze the architecture of this project"
  },
  "cwd": "/Users/xxx/project",
  "gitBranch": "main",
  "version": "2.0.76"
}

(2) Exemplo de mensagens do assistente:

{
  "type": "assistant",
  "uuid": "e684816e-f476-424d-92e3-1fe404f13212",
  "parentUuid": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
  "message": {
    "role": "assistant",
    "model": "claude-opus-4-5-20251101",
    "content": [
      {
        "type": "thinking",
        "thinking": "The user wants to understand the project architecture, so I need to check the directory structure first..."
      },
      {
        "type": "text",
        "text": "Let me take a look at the project structure first."
      },
      {
        "type": "tool_use",
        "id": "toolu_01ABC",
        "name": "Bash",
        "input": {"command": "ls -la"}
      }
    ],
    "usage": {
      "input_tokens": 1500,
      "output_tokens": 200,
      "cache_read_input_tokens": 50000
    }
  }
}

Como as mensagens de sessão são ligadas

O Claude Code não armazena mensagens de sessão como entradas isoladas. Em vez disso, associa-as para formar uma cadeia clara de eventos. Cada mensagem inclui um identificador único (uuid) e uma referência à mensagem que veio antes dela (parentUuid). Isto torna possível ver não só o que aconteceu, mas porque é que aconteceu.

Uma sessão começa com uma mensagem do utilizador, que inicia a cadeia. Cada resposta do Claude aponta para a mensagem que a originou. As chamadas de ferramentas e os seus resultados são adicionados da mesma forma, com cada passo ligado ao anterior. Quando a sessão termina, um resumo é anexado à mensagem final.

Como cada etapa está conectada, o Claude Code pode reproduzir a sequência completa de ações e entender como um resultado foi produzido, facilitando muito a depuração e a análise.

Tornar as alterações de código fáceis de desfazer com instantâneos de ficheiros

As edições geradas por IA nem sempre são corretas e, às vezes, vão na direção completamente errada. Para tornar estas alterações seguras para experimentar, o Claude Code utiliza um sistema simples de instantâneos que lhe permite desfazer edições sem ter de procurar em diffs ou limpar manualmente os ficheiros.

A ideia é simples: antes de o Claude Code modificar um ficheiro, guarda uma cópia do conteúdo original. Se a edição se revelar um erro, o sistema pode restaurar a versão anterior instantaneamente.

O que é um instantâneo do histórico de ficheiros?

Um instantâneo do histórico de ficheiros é um ponto de controlo criado antes de os ficheiros serem modificados. Regista o conteúdo original de cada ficheiro que o Claude está prestes a editar. Esses instantâneos servem como fonte de dados para operações de desfazer e reverter.

Quando um utilizador envia uma mensagem que pode alterar ficheiros, o Claude Code cria um instantâneo vazio para essa mensagem. Antes de editar, o sistema faz uma cópia de segurança do conteúdo original de cada ficheiro de destino para o instantâneo e, em seguida, aplica as edições diretamente no disco. Se o utilizador desativar a ação, o Claude Code restaura o conteúdo guardado e substitui os ficheiros modificados.

Na prática, o ciclo de vida de uma edição que pode ser desfeita é o seguinte:

1. O utilizador envia uma mensagemO ClaudeCode cria um registo novo e vazio em file-history-snapshot.

2. Osistema identifica quais os ficheiros que vão ser editados e faz uma cópia de segurança do seu conteúdo original em trackedFileBackups.

3. O Claude executa a ediçãoAsoperações deediçãoe escrita são efectuadas e o conteúdo modificado é escrito no disco.

4. O utilizador desencadeiaa anulaçãoOutilizador carrega em Esc + Esc, indicando que as alterações devem ser revertidas.

5. Oconteúdo original é restauradoOcódigo doCláudiolê o conteúdo guardado em trackedFileBackups e substitui os ficheiros actuais, concluindo a anulação.

Por que o desfazer funciona: Os instantâneos salvam a versão antiga

O desfazer no Claude Code funciona porque o sistema salva o conteúdo original do arquivo antes que qualquer edição aconteça.

Em vez de tentar reverter as alterações após o fato, o Claude Code adota uma abordagem mais simples: ele copia o arquivo como ele existia antes da modificação e armazena essa cópia em trackedFileBackups. Quando o utilizador desencadeia a anulação, o sistema restaura esta versão guardada e substitui o ficheiro editado.

O diagrama abaixo mostra este fluxo passo a passo:

┌─────────────────────────┐
│    before edit,  app.py │
│    print("old")         │───────→  Backed up into snapshot trackedFileBackups
└─────────────────────────┘
↓
┌──────────────────────────┐
│   After Claude edits     │
│    print(“new”)          │───────→  Written to disk (overwrites the original file)
└──────────────────────────┘
↓
┌──────────────────────────┐
│    User triggers undo    │
│    Press   Esc + Esc     │───────→ Restore “old” content to disk from snapshot
└──────────────────────────┘

Qual o aspeto interno de um instantâneo do histórico do ficheiro

O instantâneo em si é armazenado como um registo estruturado. Captura metadados sobre a mensagem do utilizador, a hora do instantâneo e, o mais importante, um mapa de ficheiros para o seu conteúdo original.

O exemplo abaixo mostra um único registo file-history-snapshot criado antes de o Claude editar quaisquer ficheiros. Cada entrada em trackedFileBackups armazena o conteúdo pré-edição de um ficheiro, que é posteriormente utilizado para restaurar o ficheiro durante uma anulação.

{
  "type": "file-history-snapshot",
  "messageId": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
  "snapshot": {
    "messageId": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
    "trackedFileBackups": {
      "/path/to/file1.py": "Original file content\ndef hello():\n    print('old')",
      "/path/to/file2.js": "// Original content..."
    },
    "timestamp": "2026-01-05T10:00:00.000Z"
  },
  "isSnapshotUpdate": false
}

Onde os instantâneos são armazenados e por quanto tempo são mantidos

• Onde os metadados do instantâneo são armazenados: Os registos de instantâneos estão associados a uma sessão específica e são guardados como ficheiros JSONL em~/.claude/projects/-path-to-project/{session-id}.jsonl.

• Onde é feito o backup do conteúdo original do ficheiro: O conteúdo pré-edição de cada ficheiro é armazenado separadamente por hash de conteúdo em~/.claude/file-history/{content-hash}/.

• Durante quanto tempo os instantâneos são mantidos por predefinição: Os dados dos instantâneos são mantidos durante 30 dias, de acordo com a definição global cleanupPeriodDays.

• Como alterar o período de retenção: O número de dias de retenção pode ser ajustado através do campo cleanupPeriodDays em ~/.claude/settings.json.

Comandos relacionados

Comando / Ação	Descrição
Esc + Esc	Desfazer a ronda mais recente de edições de ficheiros (mais frequentemente utilizado)
/rewind	Reverter para um ponto de controlo previamente especificado (snapshot)
/diff	Ver as diferenças entre o ficheiro atual e a cópia de segurança do instantâneo

Outros diretórios importantes

(1) plugins/ - Gerenciamento de plugins

O diretório plugins/ armazena add-ons que dão ao Claude Code capacidades extra.

Este diretório guarda os plugins que estão instalados, de onde vieram, e as capacidades extra que esses plugins fornecem. Também guarda cópias locais dos plugins descarregados para que não precisem de ser obtidos novamente.

~/.claude/plugins/
├── config.json
│   Global plugin configuration (e.g., enable/disable rules)
├── installed_plugins.json
│   List of installed plugins (including version and status)
├── known_marketplaces.json
│   Plugin marketplace source configuration (e.g., Anthropic official marketplace)
├── cache/
│   Plugin download cache (avoids repeated downloads)
└── marketplaces/
    Marketplace source storage
    └── anthropic-agent-skills/
        Official plugin marketplace
        ├── .claude-plugin/
        │   └── marketplace.json
        │       Marketplace metadata
        └── skills/
            Skills provided by the marketplace
            ├── pdf/
            │   PDF-related skills
            ├── docx/
            │   Word document processing skills
            └── frontend-design/
                Frontend design skills

(2) skills/ - Onde as habilidades são armazenadas e aplicadas

No Claude Code, uma habilidade é uma capacidade pequena e reutilizável que ajuda o Claude a executar uma tarefa específica, como trabalhar com PDFs, editar documentos ou seguir um fluxo de trabalho de codificação.

Nem todas as habilidades estão disponíveis em todos os lugares. Algumas se aplicam globalmente, enquanto outras são limitadas a um único projeto ou fornecidas por um plug-in. O Claude Code armazena as competências em diferentes locais para controlar onde cada competência pode ser utilizada.

A hierarquia abaixo mostra como as habilidades são colocadas em camadas por escopo, desde as habilidades disponíveis globalmente até as específicas do projeto e as fornecidas por plugins.

Nível	Local de armazenamento	Descrição
Utilizador	~/.claude/skills/	Disponível globalmente, acessível a todos os projectos
Projeto	projeto/.claude/skills/	Disponível apenas para o projeto atual, personalização específica do projeto
Plugin	~/.claude/plugins/marketplaces/*/skills/	Instalado com plugins, dependente do estado de ativação do plugin

(3) todos/ - Armazenamento de listas de tarefas

O diretório todos/ armazena listas de tarefas que o Claude cria para acompanhar o trabalho durante uma conversa, como etapas a serem concluídas, itens em andamento e tarefas concluídas.

As listas de tarefas são guardadas como ficheiros JSON em~/.claude/todos/{session-id}-*.json. Cada nome de ficheiro inclui o ID da sessão, que liga a lista de tarefas a uma conversa específica.

O conteúdo destes ficheiros provém da ferramenta TodoWrite e inclui informações básicas sobre a tarefa, tais como a descrição da tarefa, o estado atual, a prioridade e os metadados relacionados.

(4) local/ - Tempo de execução local e ferramentas

O diretório local/ contém os principais arquivos que o Claude Code precisa para ser executado em sua máquina.

Isso inclui o executável de linha de comando claude e o diretório node_modules/ que contém suas dependências de tempo de execução. Ao manter estes componentes locais, o Claude Code pode ser executado de forma independente, sem depender de serviços externos ou instalações em todo o sistema.

（5）Diretórios adicionais de suporte

• shell-snapshots/: Armazena instantâneos do estado da sessão do shell (como o diretório atual e as variáveis de ambiente), permitindo a reversão da operação do shell.

• plans/: Armazena planos de execução gerados pelo Modo Plano (e.g., decomposições passo-a-passo de tarefas de programação de múltiplos passos).

• statsig/: Armazena configurações de sinalizadores de recursos (como se novos recursos estão habilitados) para reduzir solicitações repetidas.

• telemetry/: Armazena dados de telemetria anónimos (como a frequência de utilização de funcionalidades) para otimização do produto.

• debug/: Armazena logs de depuração (incluindo pilhas de erros e traços de execução) para ajudar na solução de problemas.

Conclusão

Depois de analisar como o Claude Code armazena e gerencia tudo localmente, a imagem fica bem clara: a ferramenta parece estável porque a base é sólida. Nada extravagante - apenas engenharia bem pensada. Cada projeto tem o seu próprio espaço, cada ação é anotada e as edições de ficheiros são guardadas antes de qualquer alteração. É o tipo de design que faz o seu trabalho calmamente e permite-lhe concentrar-se no seu.

O que mais gosto é que não há nada de místico a acontecer aqui. O Claude Code funciona bem porque o básico está bem feito. Se alguma vez tentou construir um agente que toca em ficheiros reais, sabe como é fácil as coisas correrem mal - o estado mistura-se, as falhas apagam o progresso e o desfazer torna-se um trabalho de adivinhação. O Claude Code evita tudo isso com um modelo de armazenamento que é simples, consistente e difícil de quebrar.

Para as equipas que criam agentes de IA locais ou no local, especialmente em ambientes seguros, esta abordagem mostra como o armazenamento e a persistência fortes tornam as ferramentas de IA fiáveis e práticas para o desenvolvimento diário.

Se estiver a conceber agentes de IA locais ou on-prem e quiser discutir a arquitetura de armazenamento, a conceção de sessões ou a reversão segura em mais pormenor, sinta-se à vontade para se juntar ao nosso canal Slack.