Prompt, contesto e memoria: come strutturo il lavoro con gli agenti

La differenza tra un agente utile e uno frustrante non è il modello: è come gli struttturi il contesto. Ho un flusso ripetibile che uso su ogni task.

Tre livelli di contesto

Divido ciò che l’agente vede in tre livelli, dal più stabile al più volatile.

{
  "durevole":  "convenzioni, architettura, glossario di dominio",
  "di_task":   "issue corrente, file coinvolti, criteri di done",
  "volatile":  "ultimo errore di test, output dell'ultimo comando"
}

Il livello durevole vive in un file versionato. Il volatile lo inietto al momento e lo butto via subito dopo: tenerlo troppo a lungo è la causa numero uno di allucinazioni.

Lo script che assembla il prompt

Compongo il prompt da questi pezzi invece di scriverlo a mano ogni volta.

function buildPrompt(task: Task): string {
  return [
    readFile(".agent/durevole.md"),
    renderTask(task),
    task.lastError ? `Ultimo errore:\n${task.lastError}` : "",
  ]
    .filter(Boolean)
    .join("\n\n---\n\n");
}

La memoria è un file, non magia

Non mi fido della “memoria” implicita. Quello che l’agente deve ricordare tra sessioni lo scrivo esplicitamente su disco e lo rileggo. Se non è in un file, non esiste.