Cómo funciona

Esta página explica la mecánica detrás del reporte: qué se captura localmente, qué se guarda como git note y cómo esos datos llegan al PR Report y al Dashboard. No necesitas recordar todo para usar Agent Note, pero este es el modelo al que conviene volver cuando algo sorprende.

Flujo de datos

1. PromptPide algo a tu coding agent

Los hooks capturan el prompt y el turn id.

→

2. EditLa IA cambia archivos

Los hooks o transcripts registran los archivos cambiados y las pistas usadas para la atribución.

→

3. CommitSe registra la note

Cuando hay datos de sesión registrables, git commit inyecta el trailer y escribe la git note.

→

4. ShareSe comparte con el código

git push envía refs/notes/agentnote al remote.

Con los git hooks generados instalados, en la mayoría de los repos basta con seguir usando git commit y git push. Cursor también recupera pares prompt / response desde transcripts locales y puede seguir registrando commits cuando los git hooks no están disponibles.

Almacenamiento

Capa 1: temporal local

Datos de sesión en .git/agentnote/sessions/. Archivos JSONL para prompts, cambios y blob hashes. Se rotan después de cada commit. Nunca se envían.

Capa 2: Git Notes

Registro permanente en refs/notes/agentnote. Un JSON por commit. Se puede hacer push, fetch y compartir con el equipo.

Archivos de sesión

Archivo	Propósito
prompts.jsonl	Un prompt por línea con número de turn
changes.jsonl	Archivos tocados por la IA con blob hashes después de la edición
pre_blobs.jsonl	Estado del archivo antes de cada edición de la IA
heartbeat	Marca temporal de actividad de la sesión
turn	Contador monotónico que aumenta con cada 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 JWT auth",
      "contexts": [
        { "kind": "reference", "source": "previous_response", "text": "La respuesta anterior explica por qué este middleware debe cambiar." }
      ],
      "selection": {
        "schema": 1,
        "source": "primary",
        "signals": ["primary_edit_turn"]
      },
      "response": "Crearé el 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 }
  }
}

Modos de atribución

Claude Code

Line-level por defecto. Agent Note guarda el estado del archivo antes y después de cada edición de IA y resta del diff final las ediciones humanas posteriores.

Codex CLI

Empieza como file-level. Solo sube a line-level cuando los conteos de patch del transcript coinciden con el diff final del commit.

Cursor

Empieza como file-level. Solo sube a line-level cuando los conteos de edición coinciden y el archivo final todavía coincide con la última edición de IA.

Gemini CLI

Registra prompt / response y atribución a nivel archivo mediante hooks y parseo de transcripts. El modo line-level todavía no está disponible.

Cómo se recopila 📝 Context

📝 Context es una nota solo visual para prompts cortos como “continue” o “haz el siguiente”. Ayuda a entender el prompt sin cambiar la attribution.

• El reference context viene de la response inmediatamente anterior cuando menciona una ruta de archivo cambiada, un nombre de archivo o un identificador de código del diff final.
• El scope context viene de la response actual cuando sus primeras líneas explican claramente el trabajo en curso.
• Agent Note no usa palabras de aprobación como yes, continue o お願いします como reglas de selección. Si no hay una pista concreta de archivo o código, omite Context.
• Context nunca cambia files_touched, prompt ownership, AI Ratio, attribution method ni si se guarda una git note.

Agent Note vs Entire

Agent Note y Entire resuelven problemas relacionados, pero distintos.

• Agent Note vincula git commits con la conversación de IA que los produjo. Entire es un checkpoint product más amplio con workflows de rewind / resume.
• Agent Note guarda el registro permanente en refs/notes/agentnote; los archivos temporales de sesión quedan en .git/agentnote/. Entire se centra en checkpoint metadata y una hosted web application.
• El Dashboard de Agent Note es static GitHub Pages opcional respaldado por git notes. Puedes usar Agent Note sin hosted service.
• Agent Note no intenta restaurar un workspace state antiguo. Se centra en reviewability: por qué cambió un commit, qué prompts participaron y qué parte del diff fue AI-authored.

Consejo

Las listas de prompts vienen de la ventana de conversación entre commits, no de todo el historial de la sesión. Agent Note conserva los prompts útiles de planificación, aclaración y revisión del commit actual, y recorta historiales de prompts citados y turnos de edición que no sobrevivieron en este commit.

Nota

Los generated artifacts comunes se excluyen del denominador de AI Ratio como best effort usando señales específicas, como rutas de framework/cache, nombres o sufijos generados y headers del archivo commiteado. Los nombres genéricos de directorio como build/, dist/, gen/, generated/ y target/ no bastan por sí solos. Si tu repository commitea bundles o generated outputs que deben seguir visibles pero no afectar el AI Ratio, inclúyelos en la .agentnoteignore en la raíz del repository.

Ciclo de vida de la sesión

Evento	Qué ocurre
SessionStart	Crea el directorio de sesión y escribe el heartbeat
UserPromptSubmit	Añade el prompt, incrementa el contador de turn y rota logs
PreToolUse Edit/Write	Captura el pre-edit blob hash de forma síncrona
PostToolUse Edit/Write	Captura el post-edit blob hash y la ruta del archivo
Stop	Registra el evento stop (el heartbeat sigue activo — Stop = fin de la respuesta, no fin de la sesión)

Nota

Los plain Git hooks exigen una sesión reciente con file evidence antes de inyectar trailers. Cuando el Agent transcript actual es confiable, Agent Note puede conservar commit-level attribution aunque no haya file touches exactos por prompt.

Consejo

Agent Note conoce el agente activo. Los metadatos de sesión guardan el adapter activo, así show, status y el registro del commit pueden resolver después el formato correcto del transcript.

Git Notes

Git notes no aparecen en listados de ramas, en la UI de GitHub ni en CI, pero sí se pueden hacer push y fetch.

# Compartir con el equipo
git push origin refs/notes/agentnote

# Traer desde remote
git fetch origin refs/notes/agentnote:refs/notes/agentnote

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

Consejo

agent-note init configura el auto-fetch y el hook pre-push se encarga del auto-push. No hacen falta comandos manuales.