Come funziona

Questa pagina spiega il meccanismo dietro il report: cosa viene catturato localmente, cosa diventa una git note e come quei dati arrivano a PR Report e Dashboard. Non serve ricordare ogni dettaglio per usare Agent Note, ma questo è il modello da controllare quando qualcosa sembra inatteso.

Flusso dei dati

1. PromptChiedi al tuo coding agent

Gli hook catturano il prompt e il turn id.

→

2. EditL’AI aggiorna i file

Hook o transcript registrano i file cambiati e gli indizi usati per l’attribuzione.

→

3. CommitLa note viene scritta

Quando esistono dati di sessione registrabili, git commit inserisce il trailer e scrive la git note.

→

4. ShareCondividi insieme al codice

git push invia refs/notes/agentnote al remote.

Quando i git hook generati sono installati, nella maggior parte dei repository basta continuare a usare git commit e git push. Cursor recupera anche le coppie prompt / response dai transcript locali e può continuare a tracciare i commit quando i git hook non sono disponibili.

Storage

Livello 1: temporaneo locale

Dati di sessione in .git/agentnote/sessions/. File JSONL per prompt, cambiamenti e blob hash. Ruotati dopo ogni commit. Mai pushati.

Livello 2: Git Notes

Record permanente in refs/notes/agentnote. Un JSON per commit. Pushabile, fetchabile e condivisibile con il team.

File di sessione

File	Scopo
prompts.jsonl	Un prompt per riga con numero di turn
changes.jsonl	File toccati dall’IA con post-edit blob hash
pre_blobs.jsonl	Stato del file prima di ogni edit dell’IA
heartbeat	Timestamp di attività della sessione
turn	Contatore monotono incrementato a ogni prompt

Note Schema

{
  "v": 1,
  "agent": "claude",
  "session_id": "a1b2c3d4-...",
  "timestamp": "2026-04-02T10:30:00Z",
  "model": "claude-sonnet-4-20250514",
  "interactions": [
    {
      "prompt": "Implementa middleware di autenticazione JWT",
      "contexts": [
        { "kind": "reference", "source": "previous_response", "text": "La response precedente spiega perché questo middleware deve cambiare." }
      ],
      "selection": {
        "schema": 1,
        "source": "primary",
        "signals": ["primary_edit_turn"]
      },
      "response": "Creerò il middleware...",
      "files_touched": ["src/auth.ts"],
      "tools": ["Edit"]
    }
  ],
  "files": [
    { "path": "src/auth.ts", "by_ai": true },
    { "path": "CHANGELOG.md", "by_ai": false }
  ],
  "attribution": {
    "ai_ratio": 73,
    "method": "line",
    "lines": { "ai_added": 146, "total_added": 200, "deleted": 12 }
  }
}

Modalità di attribution

Claude Code

Di solito è line-level. Agent Note confronta lo stato del file prima e dopo ogni edit IA e sottrae dal diff finale gli edit umani arrivati dopo.

Codex CLI

Parte come file-level. Sale a line-level solo quando i conteggi patch del transcript coincidono con il diff finale del commit.

Cursor

Parte come file-level. Sale a line-level solo quando i conteggi degli edit coincidono e il file finale corrisponde ancora all’ultimo edit IA.

Gemini CLI

Registra prompt / response e attribution a livello file tramite hook e parsing del transcript. Il line-level non è ancora disponibile.

Come viene raccolto 📝 Context

📝 Context è una nota solo visiva per prompt brevi come “continue” o “fai il prossimo”. Aiuta a capire il prompt senza cambiare l’attribution.

• Il reference context arriva dalla response immediatamente precedente quando cita un percorso file modificato, un nome file o un identificatore di codice presente nel diff finale.
• Lo scope context arriva dalla response corrente quando le prime righe spiegano chiaramente il lavoro in corso.
• Agent Note non usa parole di approvazione come yes, continue o お願いします come regole di selezione. Se non c’è un indizio concreto legato a file o codice, salta Context.
• Context non cambia mai files_touched, prompt ownership, AI Ratio, attribution method o se viene salvata una git note.

Agent Note vs Entire

Agent Note ed Entire risolvono problemi collegati, ma diversi.

• Agent Note collega i git commit alla conversazione con l’AI che li ha prodotti. Entire è un checkpoint product più ampio con workflow di rewind / resume.
• Agent Note salva il record permanente in refs/notes/agentnote; i file temporanei della sessione restano in .git/agentnote/. Entire mette al centro checkpoint metadata e una hosted web application.
• La Dashboard di Agent Note è static GitHub Pages opzionale basata su git notes. Puoi usare Agent Note senza hosted service.
• Agent Note non prova a ripristinare un vecchio workspace state. Si concentra sulla reviewability: perché un commit è cambiato, quali prompt sono coinvolti e quanta parte del diff è AI-authored.

Consiglio

Le liste di prompt arrivano dalla finestra di conversazione tra un commit e il successivo, non da tutto il backlog della sessione. Agent Note conserva i prompt utili di pianificazione, chiarimento e review per il commit corrente, rimuovendo la cronologia di prompt citata e gli edit turn che non sono rimasti in questo commit.

Nota

Gli artefatti generati più comuni vengono esclusi dal denominatore di AI Ratio per quanto possibile usando segnali specifici, come path di framework/cache, nomi o suffissi generati e header dei file committati. I nomi di directory generici come build/, dist/, gen/, generated/ e target/ non bastano da soli. Se il tuo repository committa bundle o output generati che devono restare visibili ma non influenzare l’AI Ratio, elencali nella .agentnoteignore nella root del repository.

Ciclo di vita della sessione

Evento	Cosa succede
SessionStart	Crea la directory della sessione e scrive l’heartbeat
UserPromptSubmit	Appende il prompt, incrementa il contatore di turn e ruota i log
PreToolUse Edit/Write	Cattura in modo sincrono il pre-edit blob hash
PostToolUse Edit/Write	Cattura il post-edit blob hash e il percorso del file
Stop	Registra l’evento stop (l’heartbeat resta attivo — Stop = fine della response, non fine della sessione)

Nota

I plain Git hooks richiedono una sessione recente con file evidence prima di inserire trailer. Quando l’Agent transcript corrente è affidabile, Agent Note può comunque conservare commit-level attribution anche senza file touches esatti per prompt.

Consiglio

Agent Note tiene traccia dell’agente che ha prodotto la sessione. I metadati della sessione salvano l’adapter attivo, così show, status e la registrazione del commit possono risolvere in seguito il formato corretto del transcript.

Git Notes

Le git notes sono invisibili nelle liste dei branch, nell’interfaccia GitHub e in CI — ma possono essere pushate e fetchate.

# Condividi con il team
git push origin refs/notes/agentnote

# Recupera dal remote
git fetch origin refs/notes/agentnote:refs/notes/agentnote

# Mostra una note
git notes --ref=agentnote show <commit>

Consiglio

agent-note init configura l’auto-fetch e l’hook pre-push gestisce l’auto-push. Non servono comandi manuali.