Como funciona

Esta página explica a mecânica por trás do report: o que é capturado localmente, o que vira git note e como esses dados chegam ao PR Report e ao Dashboard. Você não precisa memorizar tudo para usar o Agent Note, mas este é o modelo para consultar quando algo parecer inesperado.

Fluxo de dados

1. PromptPeça algo ao seu coding agent

Os hooks capturam o prompt e o turn id.

→

2. EditA IA altera arquivos

Hooks ou transcripts registram arquivos tocados e sinais de attribution.

→

3. CommitA note é gravada

Quando houver dados de sessão registráveis, git commit injeta o trailer e escreve a git note.

→

4. ShareCompartilhe junto com o código

git push envia refs/notes/agentnote para o remote.

Quando os git hooks gerados estão instalados, na maioria dos repositórios basta continuar usando git commit e git push. O Cursor também recupera pares de prompt / response a partir de transcripts locais e consegue continuar registrando commits quando os git hooks não estão disponíveis.

Armazenamento

Camada 1: temporário local

Dados de sessão em .git/agentnote/sessions/. Arquivos JSONL para prompts, mudanças e blob hashes. Rotacionados após cada commit. Nunca são enviados.

Camada 2: Git Notes

Registro permanente em refs/notes/agentnote. Um JSON por commit. Pode ser enviado, buscado e compartilhado com o time.

Arquivos da sessão

Arquivo	Finalidade
prompts.jsonl	Um prompt por linha com número de turn
changes.jsonl	Arquivos tocados pela IA com post-edit blob hashes
pre_blobs.jsonl	Estado do arquivo antes de cada edição da IA
heartbeat	Timestamp de atividade da sessão
turn	Contador monotônico incrementado a cada prompt

Note Schema

{
  "v": 1,
  "agent": "claude",
  "session_id": "a1b2c3d4-...",
  "timestamp": "2026-04-02T10:30:00Z",
  "model": "claude-sonnet-4-20250514",
  "interactions": [
    {
      "prompt": "Implementar middleware de autenticação JWT",
      "contexts": [
        { "kind": "reference", "source": "previous_response", "text": "A response anterior explica por que esse middleware precisa mudar." }
      ],
      "selection": {
        "schema": 1,
        "source": "primary",
        "signals": ["primary_edit_turn"]
      },
      "response": "Vou criar o 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 atribuição

Claude Code

O padrão é line-level. O Agent Note salva o estado do arquivo antes e depois de cada edição da IA e remove do diff final as edições humanas que vieram depois.

Codex CLI

Começa como file-level. Só sobe para line-level quando as contagens de patch do transcript batem com o diff final do commit.

Cursor

Começa como file-level. Só sobe para line-level quando as contagens de edição batem e o arquivo final ainda corresponde à última edição da IA.

Gemini CLI

Registra prompt / response e atribuição em nível de arquivo via hooks e parsing de transcript. O modo line-level ainda não está disponível.

Como o 📝 Context é coletado

📝 Context é uma nota apenas visual para prompts curtos como “continue” ou “faça o próximo”. Ela ajuda a entender o prompt sem mudar a attribution.

• O reference context vem da response imediatamente anterior quando ela menciona um caminho de arquivo alterado, nome de arquivo ou code identifier do diff final.
• O scope context vem da response atual quando as primeiras linhas explicam claramente o trabalho em andamento.
• O Agent Note não usa palavras curtas de aprovação como yes, continue ou お願いします como regra de seleção. Se não houver uma pista concreta de arquivo ou código, ele omite Context.
• Context nunca muda files_touched, prompt ownership, AI Ratio, attribution method ou se uma git note será gravada.

Agent Note vs Entire

Agent Note e Entire resolvem problemas relacionados, mas diferentes.

• Agent Note conecta git commits à conversa com a IA que os produziu. Entire é um checkpoint product mais amplo com workflows de rewind / resume.
• Agent Note guarda o registro permanente em refs/notes/agentnote; arquivos temporários da sessão ficam em .git/agentnote/. Entire é centrado em checkpoint metadata e uma hosted web application.
• O Dashboard do Agent Note é static GitHub Pages opcional, apoiado por git notes. Você pode continuar usando Agent Note sem hosted service.
• Agent Note não tenta restaurar um workspace state antigo. Ele foca em reviewability: por que um commit mudou, quais prompts participaram e quanto do diff foi AI-authored.

Dica

As listas de prompts vêm da janela de conversa entre commits, não de todo o backlog da sessão. O Agent Note mantém prompts úteis de planejamento, esclarecimento e revisão do commit atual, e remove históricos de prompts citados e turnos de edição que não sobreviveram neste commit.

Nota

Generated artifacts comuns são excluídos do denominador de AI Ratio em best effort usando sinais específicos, como caminhos de framework/cache, nomes ou sufixos gerados e headers dos arquivos commitados. Nomes genéricos de diretório como build/, dist/, gen/, generated/ e target/ não bastam por si só. Se o seu repository commita bundles ou generated outputs que devem continuar visíveis, mas não influenciar o AI Ratio, liste-os na .agentnoteignore na raiz do repository.

Ciclo de vida da sessão

Evento	O que acontece
SessionStart	Cria o diretório da sessão e grava o heartbeat
UserPromptSubmit	Acrescenta o prompt, incrementa o contador de turn e rotaciona os logs
PreToolUse Edit/Write	Captura o pre-edit blob hash de forma síncrona
PostToolUse Edit/Write	Captura o post-edit blob hash e o caminho do arquivo
Stop	Registra o evento stop (o heartbeat continua ativo — Stop = fim da response, não fim da sessão)

Nota

Plain Git hooks exigem uma sessão recente com file evidence antes de injetar trailers. Quando o Agent transcript atual é confiável, Agent Note ainda pode manter commit-level attribution mesmo sem file touches exatos por prompt.

Dica

O Agent Note entende qual agent está ativo. Os metadados da sessão armazenam o adapter ativo, então show, status e o registro do commit conseguem resolver o formato correto do transcript depois.

Git Notes

Git notes são invisíveis em listas de branches, na UI do GitHub e no CI, mas podem ser pushadas e fetchadas.

# Compartilhar com o time
git push origin refs/notes/agentnote

# Buscar do remote
git fetch origin refs/notes/agentnote:refs/notes/agentnote

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

Dica

agent-note init configura o auto-fetch, e o hook pre-push cuida do auto-push. Nenhum comando manual é necessário.