Perché il codice Claude è così stabile: Un'immersione profonda di uno sviluppatore nel suo progetto di archiviazione locale

Ultimamente il codice Claude è ovunque. Gli sviluppatori lo usano per produrre più velocemente funzionalità, automatizzare flussi di lavoro e prototipare agenti che funzionano davvero in progetti reali. Ciò che è ancora più sorprendente è il numero di non-codificatori che si sono lanciati in questa impresa, costruendo strumenti, collegando attività e ottenendo risultati utili quasi senza alcuna configurazione. È raro vedere uno strumento di codifica dell'intelligenza artificiale diffondersi così rapidamente tra così tanti livelli di competenza.

Ciò che spicca, però, è la sua stabilità. Claude Code ricorda ciò che è successo nelle varie sessioni, sopravvive agli arresti anomali senza perdere i progressi e si comporta più come uno strumento di sviluppo locale che come un'interfaccia di chat. L'affidabilità deriva dal modo in cui gestisce l'archiviazione locale.

Invece di trattare la sessione di codifica come una chat temporanea, Claude Code legge e scrive file reali, memorizza lo stato del progetto su disco e registra ogni fase del lavoro dell'agente. Le sessioni possono essere riprese, ispezionate o annullate senza dover fare congetture, e ogni progetto rimane isolato in modo pulito, evitando i problemi di contaminazione incrociata in cui incorrono molti strumenti per agenti.

In questo post daremo un'occhiata più da vicino all'architettura di archiviazione che sta alla base di questa stabilità e al motivo per cui gioca un ruolo così importante nel rendere Claude Code pratico per lo sviluppo quotidiano.

Le sfide che ogni assistente locale di codifica AI deve affrontare

Prima di spiegare come Claude Code affronta l'archiviazione, diamo un'occhiata ai problemi comuni in cui tendono a imbattersi gli strumenti di codifica AI locali. Questi si presentano naturalmente quando un assistente lavora direttamente sul filesystem e mantiene lo stato nel tempo.

1. I dati del progetto vengono mescolati tra gli spazi di lavoro.

La maggior parte degli sviluppatori passa da un repository all'altro nel corso della giornata. Se un assistente trasporta lo stato da un progetto all'altro, diventa più difficile capire il suo comportamento e più facile che faccia ipotesi errate. Ogni progetto ha bisogno di un proprio spazio pulito e isolato per lo stato e la cronologia.

2. Gli arresti anomali possono causare la perdita di dati.

Durante una sessione di codifica, un assistente produce un flusso costante di dati utili: modifiche ai file, chiamate agli strumenti, passaggi intermedi. Se questi dati non vengono salvati subito, un crash o un riavvio forzato possono cancellarli. Un sistema affidabile scrive lo stato importante su disco non appena viene creato, in modo che il lavoro non vada perso inaspettatamente.

3. Non è sempre chiaro cosa abbia fatto l'agente.

Una sessione tipica comporta molte piccole azioni. Senza una registrazione chiara e ordinata di tali azioni, è difficile ricostruire come l'assistente sia arrivato a un determinato risultato o individuare il passaggio in cui qualcosa è andato storto. Una cronologia completa rende il debugging e la revisione molto più gestibili.

4. Annullare gli errori richiede uno sforzo eccessivo.

A volte l'assistente apporta modifiche che non funzionano. Se non si dispone di un modo integrato per annullare le modifiche, si finisce per cercare manualmente le modifiche nel repo. Il sistema dovrebbe tenere traccia automaticamente delle modifiche apportate, in modo da poterle annullare in modo pulito e senza ulteriore lavoro.

5. Progetti diversi hanno bisogno di impostazioni diverse.

Gli ambienti locali variano. Alcuni progetti richiedono autorizzazioni, strumenti o regole di directory specifiche; altri hanno script o flussi di lavoro personalizzati. Un assistente deve rispettare queste differenze e consentire le impostazioni per progetto, pur mantenendo coerente il suo comportamento di base.

I principi di progettazione dello storage alla base di Claude Code

Il progetto di archiviazione di Claude Code si basa su quattro idee semplici. Possono sembrare semplici, ma insieme affrontano i problemi pratici che si presentano quando un assistente AI lavora direttamente sulla vostra macchina e su più progetti.

1. Ogni progetto ha il suo spazio di archiviazione.

Claude Code lega tutti i dati della sessione alla directory del progetto a cui appartengono. Ciò significa che le conversazioni, le modifiche e i registri rimangono nel progetto da cui provengono e non si disperdono negli altri. Mantenere l'archiviazione separata rende il comportamento dell'assistente più facile da capire e semplifica l'ispezione o l'eliminazione dei dati per un repo specifico.

2. I dati vengono salvati subito su disco.

Invece di tenere in memoria i dati delle interazioni, Claude Code li scrive su disco non appena vengono creati. Ogni evento (messaggio, chiamata allo strumento o aggiornamento dello stato) viene aggiunto come una nuova voce. Se il programma si blocca o viene chiuso inaspettatamente, quasi tutto è ancora lì. Questo approccio mantiene le sessioni durevoli senza aggiungere molta complessità.

3. Ogni azione ha un posto chiaro nella storia.

Claude Code collega ogni messaggio e azione dello strumento a quello precedente, formando una sequenza completa. Questa cronologia ordinata permette di rivedere come si è svolta una sessione e di tracciare i passaggi che hanno portato a un risultato specifico. Per gli sviluppatori, questo tipo di traccia rende molto più semplice il debug e la comprensione del comportamento dell'agente.

4. Le modifiche al codice possono essere facilmente annullate.

Prima che l'assistente aggiorni un file, Claude Code salva un'istantanea del suo stato precedente. Se la modifica si rivela sbagliata, è possibile ripristinare la versione precedente senza dover scavare nel repo o indovinare cosa è cambiato. Questa semplice rete di sicurezza rende le modifiche guidate dall'intelligenza artificiale molto meno rischiose.

Layout di archiviazione locale di Claude Code

Claude Code memorizza tutti i dati locali in un unico luogo: la vostra home directory. Questo rende il sistema prevedibile e più facile da ispezionare, debuggare o ripulire quando necessario. Il layout di archiviazione si basa su due componenti principali: un piccolo file di configurazione globale e una directory di dati più grande, dove risiede tutto lo stato del progetto.

Due componenti principali:

• ~/.claude.jsonMemorizza la configurazione globale e i collegamenti, compresi i mapping dei progetti, le impostazioni del server MCP e i prompt usati di recente.

• ~/.claude/La directory principale dei dati, dove Claude Code memorizza le conversazioni, le sessioni del progetto, i permessi, i plugin, le competenze, la cronologia e i relativi dati di runtime.

Diamo quindi un'occhiata più da vicino a questi due componenti principali.

(1) Configurazione globale: ~/.claude.json

Questo file funge da indice piuttosto che da archivio di dati. Registra i progetti su cui si è lavorato, gli strumenti collegati a ciascun progetto e i prompt utilizzati di recente. I dati di conversazione non sono memorizzati qui.

{
  "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) Directory principale dei dati: ~/.claude/

La directory ~/.claude/ è il luogo in cui risiede la maggior parte dello stato locale di Claude Code. La sua struttura riflette alcune idee fondamentali del progetto: isolamento dei progetti, persistenza immediata e recupero sicuro dagli errori.

~/.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

Questo layout è intenzionalmente semplice: tutto ciò che Claude Code genera vive in un'unica directory, organizzata per progetto e sessione. Non ci sono stati nascosti sparsi per il sistema, ed è facile ispezionarli o ripulirli quando necessario.

Come Claude Code gestisce la configurazione

Il sistema di configurazione di Claude Code è progettato intorno a un'idea semplice: mantenere il comportamento predefinito coerente tra le macchine, ma lasciare che i singoli ambienti e progetti personalizzino ciò di cui hanno bisogno. Per far funzionare questo sistema, Claude Code utilizza un modello di configurazione a tre livelli. Quando la stessa impostazione compare in più punti, vince sempre il livello più specifico.

I tre livelli di configurazione

Claude Code carica la configurazione nel seguente ordine, dalla priorità più bassa a quella più 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
└─────────────────────────────────────────┘

Si può pensare di iniziare con i valori predefiniti globali, poi applicare le regolazioni specifiche della macchina e infine applicare le regole specifiche del progetto.

Di seguito, analizzeremo in dettaglio ciascun livello di configurazione.

(1) Configurazione globale: ~/.claude/settings.json

La configurazione globale definisce il comportamento predefinito per Claude Code in tutti i progetti. Qui si impostano i permessi di base, si abilitano i plugin e si configura il comportamento di pulizia.

{
  "$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) Configurazione locale: ~/.claude/settings.local.json

La configurazione locale è specifica per una singola macchina. Non è destinata a essere condivisa o controllata nel controllo di versione. È quindi un buon posto per le chiavi API, gli strumenti locali o i permessi specifici dell'ambiente.

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

(3) Configurazione a livello di progetto: project/.claude/settings.json

La configurazione a livello di progetto si applica solo a un singolo progetto e ha la massima priorità. Qui si definiscono le regole che devono essere sempre applicate quando si lavora in quel repository.

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

Definiti i livelli di configurazione, la domanda successiva è come Claude Code risolva effettivamente la configurazione e i permessi in fase di esecuzione.

Claude Code applica la configurazione in tre livelli: inizia con i valori predefiniti globali, poi applica le sovrascritture specifiche della macchina e infine applica le regole specifiche del progetto. Quando la stessa impostazione compare in più punti, la configurazione più specifica ha la priorità.

I permessi seguono un ordine di valutazione fisso:

1. deny - blocca sempre

2. ask - richiede una conferma

3. consenti - viene eseguito automaticamente

4. default - si applica solo quando nessuna regola corrisponde

In questo modo il sistema rimane sicuro per impostazione predefinita, pur garantendo ai progetti e alle singole macchine la flessibilità necessaria.

Memorizzazione della sessione: Come Claude Code conserva i dati fondamentali dell'interazione

In Claude Code, le sessioni sono l'unità centrale dei dati. Una sessione cattura l'intera interazione tra l'utente e l'IA, compresa la conversazione stessa, le chiamate agli strumenti, le modifiche ai file e il relativo contesto. Il modo in cui vengono archiviate le sessioni ha un impatto diretto sull'affidabilità, la debuggabilità e la sicurezza generale del sistema.

Mantenere i dati delle sessioni separati per ogni progetto

Una volta definite le sessioni, la domanda successiva è come Claude Code le memorizzi in modo da mantenere i dati organizzati e isolati.

Claude Code isola i dati delle sessioni per progetto. Le sessioni di ogni progetto sono memorizzate in una directory derivata dal percorso dei file del progetto.

Il percorso di archiviazione segue questo schema:

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

Per creare un nome di directory valido, i caratteri speciali come /, gli spazi e ~ vengono sostituiti con -.

Ad esempio:

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

Questo approccio garantisce che i dati delle sessioni di progetti diversi non si mescolino mai e che possano essere gestiti o rimossi a seconda del progetto.

Perché le sessioni sono memorizzate in formato JSONL

Claude Code memorizza i dati di sessione utilizzando JSONL (JSON Lines) invece di JSON standard.

In un file JSON tradizionale, tutti i messaggi sono raggruppati in un'unica grande struttura, il che significa che l'intero file deve essere letto e riscritto ogni volta che viene modificato. Al contrario, JSONL memorizza ogni messaggio come una propria riga del file. Una riga equivale a un messaggio, senza alcun involucro esterno.

Aspetto	JSON standard	JSONL (Linee JSON)
Come vengono memorizzati i dati	Una grande struttura	Un messaggio per riga
Quando vengono salvati i dati	Di solito alla fine	Immediatamente, per messaggio
Impatto del crash	L'intero file può rompersi	Solo l'ultima riga è interessata
Scrittura di nuovi dati	Riscrivere l'intero file	Aggiunta di una riga
Utilizzo della memoria	Carica tutto	Leggere riga per riga

JSONL funziona meglio in diversi modi:

• Salvataggio immediato: Ogni messaggio viene scritto su disco non appena viene generato, invece di aspettare che la sessione finisca.

• Resistente agli arresti anomali: se il programma si blocca, solo l'ultimo messaggio non terminato può andare perso. Tutto ciò che è stato scritto prima rimane intatto.

• Aggiunta rapida di messaggi: I nuovi messaggi vengono aggiunti alla fine del file senza leggere o riscrivere i dati esistenti.

• Basso utilizzo della memoria: I file di sessione possono essere letti una riga alla volta, quindi non è necessario caricare in memoria l'intero file.

Un file di sessione JSONL semplificato ha il seguente aspetto:

{"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"}}

Tipi di messaggi di sessione

Un file di sessione registra tutto ciò che accade durante un'interazione con Claude Code. Per farlo in modo chiaro, utilizza diversi tipi di messaggi per diversi tipi di eventi.

• I messaggi dell'utente rappresentano i nuovi input che arrivano al sistema. Questo include non solo ciò che l'utente digita, ma anche i risultati restituiti dagli strumenti, come l'output di un comando di shell. Dal punto di vista dell'intelligenza artificiale, entrambi sono input a cui deve rispondere.

• Imessaggi dell'assistente catturano ciò che Claude fa in risposta. Questi messaggi includono il ragionamento dell'intelligenza artificiale, il testo che genera e gli strumenti che decide di utilizzare. Registrano anche i dettagli di utilizzo, come il conteggio dei token, per fornire un quadro completo dell'interazione.

• Leistantanee della storia dei file sono checkpoint di sicurezza creati prima che Claude modifichi qualsiasi file. Salvando prima lo stato originale dei file, Claude Code permette di annullare le modifiche se qualcosa va storto.

• I sommari forniscono una panoramica concisa della sessione e sono collegati al risultato finale. In questo modo è più facile capire il senso di una sessione senza dover ripetere ogni fase.

Insieme, questi tipi di messaggi registrano non solo la conversazione, ma l'intera sequenza di azioni ed effetti che si verificano durante una sessione.

Per rendere questo concetto più concreto, esaminiamo esempi specifici di messaggi dell'utente e di messaggi dell'assistente.

(1) Esempio di messaggi dell'utente:

{
  "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) Esempio di messaggi dell'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
    }
  }
}

Come sono collegati i messaggi di sessione

Claude Code non memorizza i messaggi di sessione come voci isolate. Al contrario, li collega tra loro per formare una chiara catena di eventi. Ogni messaggio include un identificatore unico (uuid) e un riferimento al messaggio che lo ha preceduto (parentUuid). In questo modo è possibile vedere non solo cosa è successo, ma anche perché è successo.

Una sessione inizia con un messaggio dell'utente, che dà inizio alla catena. Ogni risposta di Claude rimanda al messaggio che l'ha causata. Le chiamate agli strumenti e i loro risultati vengono aggiunti allo stesso modo, con ogni passo collegato a quello precedente. Quando la sessione termina, al messaggio finale viene allegato un riepilogo.

Poiché ogni passo è collegato, Claude Code può riprodurre l'intera sequenza di azioni e capire come è stato prodotto un risultato, facilitando il debugging e l'analisi.

Facilità di annullamento delle modifiche al codice con le istantanee dei file

Le modifiche generate dall'intelligenza artificiale non sono sempre corrette e a volte vanno nella direzione completamente sbagliata. Per rendere queste modifiche sicure da sperimentare, Claude Code utilizza un semplice sistema di snapshot che consente di annullare le modifiche senza dover scavare nei diff o ripulire manualmente i file.

L'idea è semplice: prima di modificare un file, Claude Code salva una copia del contenuto originale. Se la modifica si rivela un errore, il sistema può ripristinare istantaneamente la versione precedente.

Che cos'è un'istantanea della storia del file?

Un'istantanea della cronologia dei file è un checkpoint creato prima che i file vengano modificati. Registra il contenuto originale di ogni file che Claude sta per modificare. Queste istantanee servono come fonte di dati per le operazioni di annullamento e rollback.

Quando un utente invia un messaggio che può modificare i file, Claude Code crea un'istantanea vuota per quel messaggio. Prima di modificare, il sistema esegue il backup del contenuto originale di ciascun file di destinazione nell'istantanea, quindi applica le modifiche direttamente sul disco. Se l'utente attiva l'annullamento, Claude Code ripristina il contenuto salvato e sovrascrive i file modificati.

In pratica, il ciclo di vita di una modifica annullabile è il seguente:

1. L'utente invia un messaggioClaudeCode crea un nuovo record file-history-snapshot vuoto.

2. Claude si prepara a modificare i fileIlsistema identifica i file che verranno modificati ed esegue il backup del loro contenuto originale in trackedFileBackups.

3. Claude esegue la modificaLeoperazioni dimodificae scrittura vengono eseguite e il contenuto modificato viene scritto su disco.

4. L'utente attiva l'annullamentoL'utente preme Esc + Esc, segnalando che le modifiche devono essere annullate.

5. Il contenuto originale viene ripristinatoClaudeCode legge il contenuto salvato da trackedFileBackups e sovrascrive i file correnti, completando l'annullamento.

Perché l'annullamento funziona: Le istantanee salvano la vecchia versione

L'annullamento in Claude Code funziona perché il sistema salva il contenuto originale del file prima di qualsiasi modifica.

Invece di cercare di annullare le modifiche a posteriori, Claude Code adotta un approccio più semplice: copia il file così com'era prima della modifica e lo memorizza in trackedFileBackups. Quando l'utente attiva l'annullamento, il sistema ripristina questa versione salvata e sovrascrive il file modificato.

Il diagramma seguente mostra questo flusso passo per 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
└──────────────────────────┘

L'aspetto interno di un'istantanea della cronologia dei file

L'istantanea stessa è memorizzata come un record strutturato. Acquisisce i metadati relativi al messaggio dell'utente, l'ora dell'istantanea e, cosa più importante, una mappa dei file rispetto al loro contenuto originale.

L'esempio seguente mostra un singolo record di file-history-snapshot creato prima che Claude modifichi i file. Ogni voce di trackedFileBackups memorizza il contenuto precedente alla modifica di un file, che viene poi utilizzato per ripristinare il file durante un annullamento.

{
  "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
}

Dove vengono memorizzate le istantanee e per quanto tempo vengono conservate

• Dove vengono memorizzati i metadati delle istantanee: I record delle istantanee sono legati a una sessione specifica e salvati come file JSONL all'indirizzo~/.claude/projects/-path-to-project/{session-id}.jsonl.

• Dove viene eseguito il backup dei contenuti originali dei file: Il contenuto pre-modifica di ogni file è memorizzato separatamente per hash di contenuto in~/.claude/file-history/{content-hash}/.

• Per quanto tempo vengono conservate le istantanee per impostazione predefinita: I dati delle istantanee vengono conservati per 30 giorni, coerentemente con l'impostazione globale cleanupPeriodDays.

• Come modificare il periodo di conservazione: Il numero di giorni di conservazione può essere regolato tramite il campo cleanupPeriodDays in ~/.claude/settings.json.

Comandi correlati

Comando / Azione	Descrizione
Esc + Esc	Annulla l'ultimo ciclo di modifiche del file (più comunemente usato)
/ritorno	Torna a un punto di controllo (snapshot) precedentemente specificato.
/diff	Visualizza le differenze tra il file corrente e l'istantanea di backup.

Altre directory importanti

(1) plugins/ - Gestione dei plugin

La directory plugins/ contiene i componenti aggiuntivi che conferiscono a Claude Code ulteriori capacità.

In questa directory sono memorizzati i plugin installati, la loro provenienza e le abilità extra che essi forniscono. Conserva anche le copie locali dei plugin scaricati, in modo che non debbano essere recuperati di nuovo.

~/.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/ - Dove vengono memorizzate e applicate le abilità

In Claude Code, un'abilità è una piccola capacità riutilizzabile che aiuta Claude a svolgere un compito specifico, come lavorare con i PDF, modificare documenti o seguire un flusso di lavoro di codifica.

Non tutte le abilità sono disponibili ovunque. Alcune si applicano a livello globale, mentre altre sono limitate a un singolo progetto o fornite da un plugin. Claude Code memorizza le competenze in posizioni diverse per controllare dove ciascuna competenza può essere utilizzata.

La gerarchia che segue mostra come le competenze siano stratificate in base all'ambito, da quelle disponibili a livello globale a quelle specifiche di un progetto e a quelle fornite da un plugin.

Livello	Posizione di memorizzazione	Descrizione
Utente	~/.claude/skills/	Disponibile a livello globale, accessibile da tutti i progetti
Progetto	progetto/.claude/skills/	Disponibile solo per il progetto corrente, personalizzazione specifica del progetto
Plugin	~/.claude/plugins/marketplaces/*/skills/	Installato con i plugin, dipende dallo stato di abilitazione dei plugin.

(3) todos/ - Archiviazione degli elenchi di attività

La cartella todos/ memorizza gli elenchi di attività che Claude crea per tenere traccia del lavoro durante una conversazione, come i passi da completare, gli elementi in corso e le attività completate.

Gli elenchi di attività sono salvati come file JSON sotto~/.claude/todos/{session-id}-*.json.Ogni nome di file include l'ID di sessione, che lega l'elenco di attività a una specifica conversazione.

I contenuti di questi file provengono dallo strumento TodoWrite e includono informazioni di base sulle attività, come la descrizione dell'attività, lo stato attuale, la priorità e i metadati correlati.

(4) local/ - Runtime locale e strumenti

La directory local/ contiene i file fondamentali di cui Claude Code ha bisogno per funzionare sulla vostra macchina.

Comprende l'eseguibile da riga di comando claude e la directory node_modules/ che contiene le sue dipendenze di runtime. Mantenendo questi componenti a livello locale, Claude Code può funzionare in modo indipendente, senza dipendere da servizi esterni o installazioni a livello di sistema.

（5）Dirette di supporto aggiuntive

• shell-snapshots/: Memorizza istantanee dello stato della sessione di shell (come la directory corrente e le variabili d'ambiente), consentendo il rollback delle operazioni di shell.

• plans/: Memorizza i piani di esecuzione generati dalla modalità Piano (ad esempio, le suddivisioni passo-passo di attività di programmazione in più fasi).

• statsig/: Memorizza le configurazioni dei flag delle funzioni (come l'abilitazione di nuove funzioni) per ridurre le richieste ripetute.

• telemetria/: Memorizza dati di telemetria anonimi (come la frequenza di utilizzo delle funzioni) per l'ottimizzazione del prodotto.

• debug/: Memorizza i log di debug (compresi gli stack di errore e le tracce di esecuzione) per facilitare la risoluzione dei problemi.

Conclusione

Dopo aver analizzato il modo in cui Claude Code memorizza e gestisce tutto a livello locale, il quadro diventa piuttosto chiaro: lo strumento è stabile perché le fondamenta sono solide. Non c'è nulla di sofisticato, ma solo un'ingegnerizzazione accurata. Ogni progetto ha il suo spazio, ogni azione viene annotata e le modifiche ai file vengono salvate prima di qualsiasi cambiamento. È il tipo di design che fa tranquillamente il suo lavoro e vi lascia concentrare sul vostro.

Ciò che mi piace di più è che non c'è nulla di mistico. Claude Code funziona bene perché le basi sono fatte bene. Se avete mai provato a costruire un agente che tocca file reali, sapete quanto sia facile che le cose vadano a rotoli: lo stato si mescola, i crash cancellano i progressi e l'annullamento diventa una congettura. Claude Code evita tutto questo grazie a un modello di archiviazione semplice, coerente e difficile da rompere.

Per i team che costruiscono agenti di intelligenza artificiale locali o on-premise, soprattutto in ambienti sicuri, questo approccio dimostra come una solida archiviazione e persistenza renda gli strumenti di intelligenza artificiale affidabili e pratici per lo sviluppo quotidiano.

Se state progettando agenti di intelligenza artificiale locali o on-premise e volete discutere in modo più approfondito dell'architettura di archiviazione, del design delle sessioni o del rollback sicuro, non esitate a unirvi al nostro canale Slack. Potete anche prenotare un incontro individuale di 20 minuti tramite Milvus Office Hours per una guida personalizzata.