La guida completa per scrivere System Prompt per Agenti — Lezioni dal reverse engineering di Claude Code

Ho decompilato il system prompt di Claude Code, studiato il codice sorgente di DeepAgents e costruito il mio AI agent da zero. La maggior parte delle guide sui prompt è pura fuffa.

In questo momento c'è un'illusione di massa in corso nel mondo dell'AI.

Ogni tutorial vi dice di scrivere i system prompt come se steste creando un incantesimo — basta trovare la formula magica giusta e il modello obbedirà. "Sei un ingegnere senior ESTREMAMENTE TALENTUOSO con 20 anni di esperienza..." Vi suona familiare?

Ho passato gli ultimi mesi a costruire VibeCom, un AI advisor per startup che esegue ricerche di mercato approfondite e genera analisi a livello di Venture Capital. Lungo il percorso, ho fatto reverse-engineering del system prompt di Claude Code, ho letto il codice sorgente del middleware di DeepAgents e ho bruciato più crediti API di quanti vorrei ammettere. La lezione più grande? La maggior parte delle cose che la gente pensa contino nei system prompt, in realtà non conta nulla. E le cose che contano davvero, non le menziona quasi nessuno.

Questo post è il playbook completo — non una panoramica di 5 minuti, ma tutto ciò che avrei voluto qualcuno mi dicesse prima di iniziare. Prendetevi un caffè.

1. Filosofia di Design: Fidati del Modello

"Un agente è un modello. Non un framework. Non una prompt chain." — shareAI-lab/learn-claude-code

Questa idea ha cambiato tutto per me. L'LLM sa già come ragionare, pianificare ed eseguire. Il vostro system prompt non gli sta insegnando a pensare — sta preparando l'ambiente in cui dovrà lavorare.

Pensatela come se steste assumendo un senior engineer. Non gli consegnate una checklist di 20 passaggi per ogni singola task. Gli dite: ecco chi siamo, ecco quali sono i limiti, ecco come appare un lavoro ben fatto. E poi vi fate da parte.

Il vostro system prompt ha esattamente quattro compiti:

Dirgli chi è — ruolo e identità
Dirgli dove sono i muri — vincoli di sicurezza
Dirgli cos'è la qualità — standard di output
Dargli gli strumenti — capacità e conoscenze (tool)

Questo è quanto. Tutto il resto è rumore.

Il Mindset dell'Harness (Impalcatura)

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

Il vostro system prompt è il manuale operativo per questa impalcatura. Non state progettando una pipeline rigida — state progettando un ambiente in cui il modello può fare del suo meglio in totale autonomia.

Non scrivete il vostro system prompt come un diagramma di flusso. Sarà il modello a decidere l'ordine di esecuzione.

2. Struttura del Prompt e Ordine delle Sezioni

Il Layout Consigliato (Reverse-Engineered da Claude Code v2.0.14)

┌─────────────────────────────────────────────┐
│ 1. Identity                                  │  ← Letto per primo, ancora il comportamento
│ 2. Security & Safety                         │  ← Marker IMPORTANTI, non negoziabili
│ 3. Tone & Style                              │  ← Controlla il formato di output
│ 4. Core Workflow                             │  ← Come svolgere il lavoro
│ 5. Tool Usage Policy                         │  ← Priorità di selezione dei tool
│ 6. Domain Knowledge                          │  ← Su richiesta, non pre-caricata
│ 7. Environment Info                          │  ← Contesto a runtime, iniettato dinamicamente
│ 8. Reminders                                 │  ← Ribadisce le regole critiche
├─────────────────────────────────────────────┤
│ [Tool Definitions — system-injected]         │  ← Non modificabili, di solito molto lunghi
├─────────────────────────────────────────────┤
│ [User Message]                               │
└─────────────────────────────────────────────┘

Perché Questo Ordine è Importante

Gli LLM hanno una curva di attenzione a forma di U — prestano la massima attenzione all'inizio e alla fine del prompt, e si distraggono nel mezzo. Questo è l'effetto "Lost in the Middle", ed è ampiamente documentato.

Identity + Safety in cima: Il modello stabilisce prima il ruolo e i confini (effetto primacy)
Core Workflow nel centro-alto: La sezione più importante — come l'agente svolge il suo lavoro
Le Tool Definitions vengono iniettate dal sistema dopo il vostro prompt: Le definizioni dei tool di Claude Code consumano ~11.438 token. Questo significa che il vostro contenuto personalizzato finisce in realtà più vicino all'inizio di quanto vi aspettereste — il che aiuta l'aderenza alle istruzioni
Reminders in fondo: Sfruttano il recency bias per rafforzare le regole critiche

3. Scrivere Ogni Sezione

3.1 Identity — Chi è Questo Agente?

Obiettivo: Ancorare il ruolo del modello in 1-3 frasi.

You are Claude Code, Anthropic's official CLI for Claude.
You are an interactive agent that helps users with software engineering tasks.

Linee guida:

Siate concisi — massimo 1-3 frasi
Nominate esplicitamente il ruolo (aiuta il modello a distinguere i contesti)
Dichiarate la responsabilità principale ("helps with X"), non un vago "sei un assistente utile"
Menzionate l'SDK/piattaforma se applicabile ("built on Anthropic's Claude Agent SDK")

Anti-pattern:

"You are a helpful, harmless, and honest AI assistant" — troppo generico, nessun ancoraggio di ruolo
Un intero paragrafo di backstory e lore — spreca token, il modello non ha bisogno di sviluppo del personaggio

3.2 Security & Safety — I Limiti Invalicabili

Obiettivo: Impostare vincoli comportamentali infrangibili.

IMPORTANT: Assist with defensive security tasks only.
Refuse to create, modify, or improve code that may be used maliciously.
IMPORTANT: You must NEVER generate or guess URLs for the user.

Linee guida:

Usate il prefisso IMPORTANT: — l'addestramento gerarchico delle istruzioni di Claude gli dà un peso extra
Usate un linguaggio assoluto: NEVER, MUST NOT, Refuse to
Dichiarate sia ciò che è permesso SIA ciò che è proibito (i vincoli bidirezionali sono più chiari)
Posizionatelo in cima, non sepolto nel mezzo
Ripetete le regole di sicurezza critiche alla fine — Claude Code fa esattamente questo

Perché ripetere? Effetto primacy (inizio) + Effetto recency (fine) = doppio rinforzo. La dichiarazione di sicurezza di Claude Code appare sia all'inizio che alla fine del prompt. Non perché gli ingegneri fossero smemorati — ma perché comprendono la curva di attenzione a forma di U.

3.3 Tone & Style — Controllare l'Output

Obiettivo: Controllare il formato e la voce dell'output.

## Tone and style

- Your responses should be short and concise.
- Only use emojis if the user explicitly requests it.
- Use Github-flavored markdown for formatting.
- NEVER create files unless absolutely necessary.

Linee guida:

Elencate comportamenti specifici, non un vago "sii professionale"
Ogni regola dovrebbe essere testabile come vero/falso ("short and concise" vs. "try to be brief")
Includete i requisiti del formato di output (markdown? JSON? plain text?)
Includete cosa NON fare — molti problemi di stile riguardano il proibire un comportamento

La perla di Claude Code — L'Oggettività Professionale:

Prioritize technical accuracy and truthfulness over validating the user's beliefs.
Focus on facts and problem-solving, providing direct, objective technical info
without any unnecessary superlatives, praise, or emotional validation.

Questo paragrafo è cruciale: blocca la tendenza all'adulazione del modello. Se il vostro agente deve dare giudizi oggettivi (code review, valutazione di idee, decisioni di architettura), avete assolutamente bisogno di una clausola simile.

3.4 Core Workflow — La Sezione Più Importante

Obiettivo: Insegnare al modello come lavorare — metodologia, non procedure rigide.

Questa è la sezione più difficile da scrivere bene, e quella con il maggiore impatto quando ci riuscite.

Il principio fondamentale: fornite principi, non procedure.

Dite all'LLM come appare un buon output e perché è buono — lasciate che sia lui a capire come arrivarci. Evitate di prescrivere conteggi esatti di campi, sequenze di passaggi o formati, a meno che l'output non debba essere consumato da macchine a valle.

L'approccio di Claude Code:

## Doing tasks

The user will primarily request software engineering tasks.
For these tasks the following steps are recommended:

- Use the TodoWrite tool to plan the task if required

Notate la parola "recommended" — non "devi seguire esattamente questi passaggi". Quella singola scelta di parole dà al modello spazio per adattarsi.

Una buona definizione di workflow:

1. Understand first — read existing code before modifying it
2. Plan first — break complex tasks into steps before executing
3. Minimal changes — only change what's necessary, don't "refactor while you're in there"
4. Verify — confirm your changes work (run tests, lint, etc.)

Ogni regola ha un "perché" implicito — il modello può comprendere l'intento e generalizzare a nuovi scenari.

Anti-pattern:

Una procedura rigida di 20 passaggi — il modello eseguirà meccanicamente e si bloccherà su input inaspettati
"Prima fai A, poi fai B, poi fai C" — questa è una prompt chain, non il prompt di un agente
Guidare eccessivamente cose in cui l'LLM è già bravo — spreca token

L'ho imparato a mie spese con VibeCom. Le prime versioni avevano un workflow di ricerca in 10 passaggi. Il modello eseguiva diligentemente tutti e 10 i passaggi anche quando il passaggio 3 aveva già risposto alla domanda dell'utente. Quando sono passato ai principi ("fai ricerca finché non hai prove sufficienti, poi sintetizza"), la qualità è salita e i costi dei token sono scesi.

L'eccezione: Quando l'output viene consumato da macchine a valle (comunicazione inter-agente, formati di risposta API), dovete definire formati rigorosi. I principi servono per il comportamento; gli schemi servono per le interfacce.

3.5 Tool Usage Policy — Risolvere l'Ambiguità

Obiettivo: Quando più tool possono fare la stessa cosa, dire al modello quale preferire.

## Tool usage policy

- Use specialized tools instead of bash commands:
  - Read for reading files instead of cat/head/tail
  - Edit for editing instead of sed/awk
  - Grep for searching instead of grep/rg
- You can call multiple tools in a single response. If independent, call in parallel.
- Use the Task tool for file search to reduce context usage.

Linee guida:

Usate "instead of" per esprimere priorità (A invece di B)
Spiegate perché preferire certi tool ("provides a better user experience", "reduces context usage")
Definite la strategia di parallelismo (indipendenti → parallelo, dipendenti → sequenziale)
Elencate i vincoli di sicurezza per l'uso dei tool (validazione dei path, controlli dei permessi)

La relazione cruciale tra tool e prompt:

Le definizioni dei tool sono tipicamente iniettate dal sistema e non potete modificarle direttamente. Le definizioni dei tool di Claude Code pesano ~11.438 token. Questo significa:

Non ripetete informazioni già presenti nelle definizioni dei tool
Usate il system prompt per una guida strategica: quando usare ogni tool, perché preferirne uno a un altro, ordine di priorità
La qualità della definizione dei tool ha un impatto diretto sull'efficacia dell'agente — se state costruendo il vostro agente, investite tempo nello scrivere descrizioni eccellenti per i tool

3.6 Domain Knowledge — Caricare su Richiesta, Non in Anticipo

Obiettivo: Fornire conoscenze specializzate che potrebbero mancare nei dati di addestramento del modello.

Il principio chiave: divulgazione progressiva (progressive disclosure), non discariche di conoscenza.

❌ Incollare tutti i 200 endpoint API nel system prompt → esplosione di token
✅ Dare al modello un tool per cercare le cose → "Carica la conoscenza quando ne hai bisogno"

Questa strategia è condivisa dal sistema Skills di Claude Code e dal middleware Progressive Disclosure di DeepAgents. Entrambi caricano la conoscenza su richiesta tramite chiamate ai tool piuttosto che pre-caricare tutto.

Approcci di implementazione:

Inserire puntatori nel system prompt: "Use the get_api_docs tool to retrieve documentation when needed"
Usare CLAUDE.md / AGENTS.md per il contesto del progetto — caricati a runtime, non hardcoded
Usare Skills / SKILL.md per la scoperta delle capacità — il modello vede un menu di skill disponibili, e recupera le specifiche complete su richiesta

3.7 Environment Info — Contesto a Runtime

Obiettivo: Dare al modello consapevolezza del suo ambiente di esecuzione.

<env>
Working directory: /Users/fengliu/Desktop/tfm/vibecom
Is directory a git repo: true
Platform: darwin
Today's date: 2026-03-21
</env>
You are powered by the model named Claude Opus 4.6.

Linee guida:

Generatelo dinamicamente, mai hardcoded
Includete: working directory, piattaforma, data, nome del modello, stato di git
Usate un formato strutturato (tag XML o blocchi di codice) per facilitare il parsing
La data è importante — il modello ha bisogno di conoscere l'"adesso" per giudicare la freschezza delle informazioni

3.8 Reminders — Il Rinforzo Finale

Obiettivo: Ribadire le regole più critiche alla fine del prompt.

Claude Code ripete i suoi vincoli di sicurezza e il requisito TodoWrite in fondo:

IMPORTANT: Assist with defensive security tasks only. [repeated]
IMPORTANT: Always use the TodoWrite tool to plan and track tasks. [repeated]

Linee guida:

Ripetete solo 2-3 delle regole più critiche — non duplicate tutto
Sfruttate il recency bias — il modello ricorda più fortemente i contenuti recenti
I migliori candidati: vincoli di sicurezza, regole violate più di frequente, promemoria del core workflow

4. Budget dei Token e Gestione del Contesto

Riferimento per l'Allocazione del Budget

Sezione	Token Consigliati	Note
Identity + Safety	200-500	Concisi ma non negoziabili
Tone & Style	300-800	Le regole devono essere specifiche, non divagate
Core Workflow	500-2.000	La sezione più importante, vale l'investimento
Tool Usage Policy	300-1.000	Dipende dal numero di tool
Domain Knowledge	0-1.000	Preferibile il caricamento su richiesta
Environment Info	100-300	Generato dinamicamente
Reminders	100-300	Ripetete solo l'essenziale
Il vostro totale	1.500-6.000
Tool Definitions (system)	5.000-15.000	Non sotto il vostro controllo

Curva di Degradazione del Contesto

I test della community (Reddit u/CodeMonke_) hanno mappato il degrado reale dell'aderenza alle istruzioni:

< 80K token: L'aderenza al prompt rimane stabile
80K - 120K token: Il rispetto delle istruzioni inizia a degradare
> 120K token: Degrado significativo — il modello "dimentica" le prime istruzioni
> 180K token: Degrado grave

La vostra context window di 200K ≠ 200K di contesto effettivo. Pianificate di conseguenza.

Strategie di mitigazione:

Mantenete il vostro system prompt snello (< 6.000 token per la vostra parte)
Usate la summarization per comprimere la cronologia della conversazione (DeepAgents si attiva a ~80K caratteri)
Posizionate le regole critiche a entrambe le estremità del prompt (attenzione a forma di U)
Iniettate tag <system-reminder> a metà conversazione (ne parleremo di più nella sezione 8)

5. Principi di Scrittura

5.1 Fornite Principi, Non Procedure

❌ "Step 1: Read the file. Step 2: Find the bug. Step 3: Fix it. Step 4: Run tests."
✅ "Always understand existing code before modifying it. Verify your changes work."

I principi generalizzano. Le procedure possono essere seguite solo meccanicamente. Quando il modello incontra una situazione che non avevate previsto, i principi guidano la decisione giusta. Le procedure no.

Eccezione: Quando l'output è consumato da macchine (comunicazione inter-agente, formati API), definite schemi rigorosi.

5.2 Usate un Linguaggio Assoluto per i Vincoli Rigidi

Forza	Linguaggio	Usare Per
Proibizione assoluta	`NEVER`, `MUST NOT`	Sicurezza, operazioni irreversibili
Requisito forte	`ALWAYS`, `MUST`	Regole del core workflow
Raccomandazione	`recommended`, `prefer`	Best practice con eccezioni
Suggerimento	`consider`, `you may`	Ottimizzazioni opzionali

Esempi da Claude Code:

NEVER update the git config — proibizione assoluta
ALWAYS prefer editing an existing file — forte, ma esistono eccezioni
The following steps are recommended — workflow suggerito

5.3 Usate Esempi Invece di Spiegazioni

## Code References

When referencing specific functions or pieces of code include
the pattern `file_path:line_number`.

<example>
user: Where are errors from the client handled?
assistant: Clients are marked as failed in the `connectToServer`
function in src/services/process.ts:712.
</example>

Un esempio insegna più di 100 parole di spiegazione:

I modelli imparano i pattern dagli esempi in modo più affidabile rispetto alle descrizioni astratte
Avvolgeteli con i tag <example> per separarli dalle regole
Fornite esempi sia positivi ("fai questo") che negativi ("non fare questo")
Usate esempi reali e specifici — non placeholder come "foo/bar"

5.4 Vincoli Bidirezionali

✅ "Use dedicated tools: Read for reading files, Edit for editing files."
✅ "Do NOT use bash for file operations (cat, head, tail, sed, awk)."

Dire solo "fai questo" → il modello non sa quando NON farlo. Dire solo "non fare questo" → il modello non conosce l'alternativa. Bidirezionale → chiaro e inequivocabile.

5.5 Spiegate il Perché, Non Solo il Cosa

❌ "Don't use git commit --amend."
✅ "Avoid git commit --amend. ONLY use --amend when either
   (1) user explicitly requested amend OR
   (2) adding edits from pre-commit hook.
   Reason: amending may overwrite others' commits."

Spiegare il perché permette al modello di esprimere giudizi corretti nei casi limite. Il protocollo di sicurezza git di Claude Code è una masterclass — ogni regola implica la sua logica.

5.6 Struttura Prima della Prosa

Header Markdown (##, ###) — i modelli riconoscono la gerarchia
Elenchi puntati invece di paragrafi — ogni regola è testabile in modo indipendente
Tag XML per contenuti speciali: <example>, <env>, <system-reminder>
Tabelle per confronti e mappature
Non buttate mai testo non strutturato — i prompt strutturati superano costantemente la prosa in linguaggio naturale nei test di aderenza

6. Anti-Pattern Che Sprecano i Vostri Token

Prompt Chain Travestite da Agenti

"First call tool A to get data.
Then call tool B with the result.
Then format the output as JSON.
Then save to file."

Questo non è il prompt di un agente — è uno script di pipeline. Il modello eseguirà meccanicamente e perderà la sua capacità di pianificazione autonoma.

La soluzione: Dite al modello l'obiettivo e i vincoli. Lasciate che sia lui a decidere i passaggi.

Ingegneria dell'Adulazione (Flattery Engineering)

"You are an EXTREMELY TALENTED and INCREDIBLY EXPERIENCED
senior software engineer with 20 years of experience..."

Complimenti e superlativi non migliorano la qualità dell'output. Il modello non ha un ego da gonfiare. Risparmiate quei 15 token per una regola vera.

Knowledge Dump (Scaricare troppe informazioni)

"Here is the complete API documentation for our 200 endpoints..."

Questo divora la vostra context window e accelera il degrado del contesto. Sostituitelo con il caricamento su richiesta:

"Use the get_api_docs tool to retrieve API documentation when needed."

Ripetere le Descrizioni dei Tool

Se la definizione del tool dice già "Read tool reads a file from the filesystem", non ripetetelo nel vostro system prompt. Aggiungete solo indicazioni strategiche che la definizione del tool non copre — quando usarlo, perché preferirlo, ordine di priorità.

Mancanza di Gestione dei Fallimenti

Senza una guida esplicita, i modelli riproveranno le chiamate ai tool fallite in un loop infinito. Includete sempre:

"If a tool call is denied, do not re-attempt the exact same call.
Think about why it was denied and adjust your approach."

Ignorare il Decadimento della Context Window

200K di context window ≠ 200K di contesto effettivo. I test reali mostrano che il degrado inizia a 80K. Avete bisogno di una strategia di summarization.

7. Punti di Iniezione e Priorità

I Tre Metodi di Personalizzazione di Claude Code

Metodo	Sostituisce	Posizionamento	Ideale Per
Output Styles	Sezioni "Tone and style" + "Doing tasks"	Subito prima delle definizioni dei tool	Cambiare lo stile di interazione
--append-system-prompt	Nulla (additivo)	Dopo l'output style, prima dei tool	Aggiungere comportamenti specifici
--system-prompt	Intero system prompt	Mantiene i tool + una riga di identity	Personalizzazione totale (opzione nucleare)

Se ne usate più di uno: Output Style → Append Prompt → Tool Definitions

Gerarchia delle Istruzioni

Claude è specificamente addestrato con una gerarchia di istruzioni:

1. User's explicit instructions (CLAUDE.md, direct requests)  ← Priorità massima
2. Custom system prompt additions                               ← Alta
3. Default system prompt                                        ← Media
4. Tool definitions                                             ← Livello di riferimento

Questo significa:

Le regole in CLAUDE.md sovrascrivono il comportamento del system prompt di default
Le richieste dirette dell'utente sovrascrivono tutto
Il vostro prompt personalizzato sovrascrive il prompt di default

Meccanismi di Iniezione Dinamica

<system-reminder> — iniettato in qualsiasi messaggio a metà conversazione per ricordare al modello le regole critiche
CLAUDE.md / AGENTS.md — caricati a runtime da file, appesi al system prompt
Skills / SKILL.md — caricati su richiesta via chiamate ai tool, zero impatto sul system prompt

8. Iniezione a Metà Conversazione — L'Arma Segreta

Il system prompt appare solo una volta, all'inizio dell'array dei messaggi. Ma gli LLM accettano l'intero array dei messaggi (alternando messaggi utente / assistente / tool) come input, e potete iniettare prompt anche nei messaggi utente e nei risultati dei tool. Claude Code usa pesantemente questa tecnica in produzione.

Perché è Necessario

Combattere il degrado del contesto. Man mano che le conversazioni si allungano, l'aderenza del modello alle istruzioni del system prompt si degrada (evidente oltre gli 80K token). Iniettare promemoria a metà conversazione = rinfrescare le regole tramite recency bias.

Il modello mentale:

System prompt = la costituzione (stabilita una volta, autorità a lungo termine)
Promemoria nei messaggi utente = circolari/memo (inviate periodicamente, mantengono l'applicazione delle regole)

Tre Punti di Iniezione nell'Array dei Messaggi

Messages Array:
┌─────────────────────────────────────┐
│ System Prompt                       │ ← Appare una volta, effetto primacy
│   (identity, safety, workflow...)   │
├─────────────────────────────────────┤
│ User Message 1                      │
│ Assistant Message 1                 │
│ User Message 2 + <system-reminder>  │ ← Iniezione a metà conversazione
│ Assistant Message 2                 │
│ Tool Result + <system-reminder>     │ ← Si può iniettare anche nei risultati dei tool
│ ...                                 │
│ User Message N + <system-reminder>  │ ← Ultimo messaggio, recency più forte
└─────────────────────────────────────┘

Posizione	Vantaggio	Svantaggio
System prompt	Effetto primacy, letto per primo	Appare una volta, "dimenticato" in chat lunghe
User message injection	Recency bias, refresh periodico	Ogni iniezione costa token
Tool result injection	Punto di iniezione più naturale	Funziona solo quando vengono chiamati i tool

Come lo Usa Effettivamente Claude Code

Prerequisito — dichiarare i tag nel system prompt:

Tool results and user messages may include <system-reminder> tags.
<system-reminder> tags contain useful information and reminders.
They are automatically added by the system, and bear no direct
relation to the specific tool results or user messages in which they appear.

Questo passaggio è critico: dice al modello che questi tag sono iniettati dal sistema, non parole dell'utente.

Uso 1: Promemoria Comportamentali (refresh periodico delle regole)

<system-reminder>
The task tools haven't been used recently. If you're working on tasks
that would benefit from tracking progress, consider using TaskCreate...
</system-reminder>

Claude Code lo usa per ricordare al modello di pianificare con TodoWrite — perché i modelli tendono a "dimenticare" di pianificare e iniziano semplicemente a scrivere codice.

Uso 2: Cambio di Modalità (Plan Mode)

<system-reminder>
Plan mode is active. The user indicated that they do not want you to
execute yet -- you MUST NOT make any edits, run any non-readonly tools,
or otherwise make any changes to the system.
</system-reminder>

La Plan mode non è implementata nel system prompt. È un tag iniettato nel messaggio utente successivo. Questo vi permette di attivare/disattivare modalità dinamicamente senza modificare il system prompt. Geniale.

Uso 3: Notifiche di Modifica dei File

<system-reminder>
Note: /path/to/file.ts was modified, either by the user or by a linter.
This change was intentional, so make sure to take it into account.
</system-reminder>

Quando un processo esterno (linter, formatter, modifica manuale) modifica un file, il sistema notifica il modello tramite un reminder — prevenendo decisioni basate su contenuti del file obsoleti.

Uso 4: Contesto Dinamico (date, regole del progetto)

<system-reminder>
Today's date is 2026-03-21.
Current branch: dev
claudeMd: [CLAUDE.md content injected here]
</system-reminder>

Il contesto a runtime (data, stato git, regole del progetto) viene iniettato tramite i messaggi utente, non hardcoded nel system prompt.

Linee Guida per Scrivere i Reminders

Avvolgeteli in tag XML (<system-reminder>) — il modello può distinguere l'iniezione di sistema dalle parole dell'utente
Pre-dichiarate i tag nel system prompt — altrimenti il modello potrebbe cercare di rispondere al promemoria
Non iniettateli in ogni messaggio — ogni iniezione costa token, iniettate solo quando necessario
Manteneteli brevi — un reminder non è un secondo system prompt, solo 1-2 regole critiche
Non contraddite il system prompt — i reminder integrano e rafforzano, non sovrascrivono
Usateli per toggle dinamici — plan mode, readonly mode, feature flags

Quando Usare System Prompt vs. User Message Reminder

Scenario	System Prompt	User Message Reminder
Definizione del ruolo	✅	❌
Vincoli di sicurezza	✅ Prima dichiarazione	✅ Ripetizione periodica
Metodologia di workflow	✅	❌
Cambio modalità (plan mode)	❌	✅
Notifiche modifica file	❌	✅
Data / info ambiente	✅ Valore iniziale	✅ Valore aggiornato
Correzione comportamentale	❌	✅
Promemoria uso tool	✅ Definizione regola	✅ Spinte all'esecuzione

9. Prompt Cache — Risparmia il 90% sui Token Ripetuti

Il prompt caching di Anthropic vi permette di mettere in cache il prefisso statico del vostro array di messaggi. Quando le richieste successive condividono lo stesso prefisso, colpiscono la cache — risparmiando denaro e riducendo la latenza.

Per gli agenti, questo conta moltissimo: state reinviando il system prompt + le definizioni dei tool ad ogni singola chiamata LLM all'interno di una conversazione.

I Numeri Chiave

Metrica	Valore
Costo cache hit	10% del prezzo normale (90% di risparmio)
Costo cache write	125% del prezzo normale (25% di sovrapprezzo alla prima scrittura)
Cache TTL	5 minuti (scade se non ci sono richieste)
Lunghezza minima cache	1.024 token (Claude 3.5+)
Granularità cache	Prefix matching — dall'inizio fino a un breakpoint segnato
Breakpoint massimi	4

Come Questo Cambia il Design del Prompt

Principio base: prima i contenuti statici, poi quelli dinamici.

✅ Layout cache-friendly:
  System prompt (statico)      ← Cache breakpoint 1
  Tool definitions (statico)   ← Cache breakpoint 2
  CLAUDE.md / regole progetto  ← Cache breakpoint 3 (cambia occasionalmente)
  Cronologia conversazione     ← Breakpoint 4 per rolling window

❌ Layout che distrugge la cache:
  System prompt
  TIMESTAMP DINAMICO           ← Cambia a ogni richiesta, tutto ciò che segue = cache miss
  Tool definitions
  Cronologia conversazione

La trappola di cui nessuno vi parla: Se mettete un timestamp dinamico nel mezzo del vostro system prompt, tutto ciò che viene dopo diventa un cache miss. Ogni. Singola. Richiesta. Un timestamp nel posto sbagliato e pagherete il prezzo pieno su migliaia di token.

Utilizzo dell'API

const response = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  system: [
    {
      type: "text",
      text: "You are a startup advisor...",
      cache_control: { type: "ephemeral" }  // ← segna un cache breakpoint
    }
  ],
  messages: [...]
});

Strategia Multi-Breakpoint

Breakpoint 1: System prompt           ← Non cambia quasi mai
Breakpoint 2: Tool definitions         ← Non cambiano quasi mai
Breakpoint 3: Regole progetto / CLAUDE.md ← Cambiano occasionalmente
Breakpoint 4: Primi N messaggi di history ← Rolling window cache

Anche quando la cronologia della conversazione cambia, i primi 3 breakpoint colpiscono ancora la cache. Una conversazione di 10 turni fa risparmiare circa il 40-60% sui costi dei token di input.

Raccomandazioni di Design

Nessun valore dinamico ad alta frequenza nel system prompt — la data va bene (cambia ogni giorno), i timestamp precisi no
Mettete il contesto dinamico (stato git, ecc.) nelle iniezioni dei messaggi utente — non nel system prompt, o distruggerete la cache
Mantenete stabili le definizioni dei tool — non aggiungete/rimuovete tool dinamicamente a runtime
Usate una rolling window per la cronologia della conversazione — mettete in cache i primi N messaggi, solo il messaggio più recente sarà un cache miss

10. La Checklist

Dopo aver scritto il vostro system prompt, verificatelo con questa checklist:

Struttura

L'Identity è in cima?
I vincoli di sicurezza sono contrassegnati con IMPORTANT e ripetuti alla fine?
Chiara separazione delle sezioni con gli header?
Esempi avvolti nei tag <example>?

Budget dei Token

La vostra parte è < 6.000 token?
Non state ripetendo informazioni già presenti nelle definizioni dei tool?
La Domain knowledge è caricata su richiesta, non pre-caricata?
Nessuna lore prolissa o backstory del personaggio?

Qualità delle Regole

Ogni regola è testabile come vero/falso?
I vincoli rigidi usano un linguaggio assoluto (NEVER/MUST)?
I suggerimenti leggeri usano un linguaggio di raccomandazione (recommended/prefer)?
Le regole critiche spiegano il perché, non solo il cosa?
Vincoli bidirezionali (fai questo + non fare quello)?

Comportamento dell'Agente

Avete fornito principi, non rigide procedure passo-passo?
Avete gestito lo scenario "chiamata al tool negata"?
Avete gestito la strategia "ostacolo incontrato" (non riprovare con la forza bruta)?
Strategia di gestione del contesto implementata (soglia di summarization)?

Cosa NON Fare

Nessuna adulazione o aggettivi superlativi?
Nessuna dichiarazione ridondante tipo "sei un'AI utile"?
Non è scritto come una prompt chain?
Nessun over-engineering (feature che nessuno ha chiesto)?

Se Dovessi Ricominciare Oggi

Ecco esattamente cosa farei:

Iniziate con identity + safety nelle prime 3 righe. Due frasi per dire chi è l'agente. Vincoli rigidi con NEVER/MUST. Ripetete le regole di sicurezza alla fine.
Scrivete il vostro core workflow come principi, non passaggi. Massimo 4-5 punti elenco. Usate "recommended" e "prefer" per le regole flessibili, "NEVER" e "MUST" per quelle rigide.
Mettete a budget 1.500-6.000 token per la vostra parte. Le definizioni dei tool ne aggiungeranno altri 5.000-15.000. Se siete oltre i 6K, probabilmente state scaricando conoscenza che dovrebbe essere caricata su richiesta.
Strutturate tutto. Header Markdown, elenchi puntati, tag XML per gli esempi. Un prompt strutturato batte sempre la prosa in linguaggio naturale.
Integrate i reminder a metà conversazione fin dal primo giorno. Dichiarate <system-reminder> nel vostro system prompt. Iniettate reminder per regole critiche, cambi di modalità e aggiornamenti di contesto.
Progettate per la cache. Prima i contenuti statici, poi quelli dinamici. Non mettete mai valori mutevoli nel corpo del vostro system prompt.

L'ironia di tutto questo lavoro? I migliori system prompt sono brevi. Le istruzioni personalizzate di Claude Code (escluse le definizioni dei tool) sono sorprendentemente concise. Ogni riga si guadagna il suo posto.

Una volta pensavo che il prompt engineering riguardasse il trovare trucchi intelligenti. Ora penso che riguardi la disciplina — dire meno, dirlo in modo preciso, e fidarsi del modello per capire il resto. Il modello è più intelligente del vostro prompt. Progettate l'ambiente, non il comportamento.

Riferimenti

Fonte	Insight Chiave
Claude Code v2.0.14 System Prompt	Riferimento completo alla struttura del prompt di un agente in produzione
Reddit: Understanding Claude Code's 3 System Prompt Methods	Deep dive su Output Styles / --append / --system-prompt, dati reali sul context rot
shareAI-lab/learn-claude-code	Filosofia "Il modello è l'agente", metodologia di harness engineering
Anthropic Prompt Engineering Docs	Best practice ufficiali per i prompt
DeepAgents Framework	Middleware di summarization, divulgazione progressiva delle skill