Fonctionnement

Cette page explique le mécanisme derrière le rapport : ce qui est capturé localement, ce qui devient une git note, et comment ces données arrivent dans PR Report et Dashboard. Vous n’avez pas besoin de tout retenir pour utiliser Agent Note, mais c’est le bon modèle à vérifier quand un résultat surprend.

Flux de données

1. PromptDemandez à votre coding agent

Les hooks capturent le prompt et le turn id.

→

2. EditL’IA modifie les fichiers

Les hooks ou transcripts enregistrent les fichiers touchés et les signaux d’attribution.

→

3. CommitLa note est enregistrée

Si la session contient des données enregistrables, git commit injecte le trailer et écrit la git note.

→

4. SharePartagez avec le code

git push envoie refs/notes/agentnote vers le remote.

Une fois les git hooks générés installés, la plupart des dépôts peuvent continuer à utiliser simplement git commit et git push. Cursor récupère aussi les paires prompt / response depuis les transcripts locaux et peut continuer à suivre les commits quand les git hooks ne sont pas disponibles.

Stockage

Couche 1 : temporaire locale

Données de session dans .git/agentnote/sessions/. Fichiers JSONL pour les prompts, changements et blob hashes. Rotés après chaque commit. Jamais poussés.

Couche 2 : Git Notes

Enregistrement permanent dans refs/notes/agentnote. Un JSON par commit. Poussable, récupérable et partageable avec l’équipe.

Fichiers de session

Fichier	Rôle
prompts.jsonl	Un prompt par ligne avec numéro de turn
changes.jsonl	Fichiers touchés par l’IA avec blob hashes post-édition
pre_blobs.jsonl	État du fichier avant chaque édition IA
heartbeat	Horodatage d’activité de la session
turn	Compteur monotone incrémenté à chaque prompt

Note Schema

{
  "v": 1,
  "agent": "claude",
  "session_id": "a1b2c3d4-...",
  "timestamp": "2026-04-02T10:30:00Z",
  "model": "claude-sonnet-4-20250514",
  "interactions": [
    {
      "prompt": "Implémenter un middleware d'auth JWT",
      "contexts": [
        { "kind": "reference", "source": "previous_response", "text": "La réponse précédente explique pourquoi ce middleware doit changer." }
      ],
      "selection": {
        "schema": 1,
        "source": "primary",
        "signals": ["primary_edit_turn"]
      },
      "response": "Je vais créer le 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 }
  }
}

Modes d’attribution

Claude Code

Line-level par défaut. Agent Note enregistre l’état du fichier avant et après chaque edit IA, puis retire du diff final les edits humains arrivés ensuite.

Codex CLI

Démarre en file-level. Passe en line-level uniquement si les comptes de patch du transcript correspondent au diff final du commit.

Cursor

Démarre en file-level. Passe en line-level seulement lorsque les comptes d’édition correspondent et que le fichier final correspond encore au dernier edit IA.

Gemini CLI

Enregistre prompt / response et attribution au niveau fichier via les hooks et le parsing du transcript. Le mode line-level n’est pas encore disponible.

Comment 📝 Context est collecté

📝 Context est une note affichée seulement pour aider à lire les prompts courts comme “continue” ou “fais le suivant”. Elle n’affecte pas l’attribution.

• Le reference context vient de la response immédiatement précédente lorsqu’elle mentionne un chemin de fichier modifié, un nom de fichier ou un identifiant de code présent dans le diff final.
• Le scope context vient de la response courante lorsque ses premières lignes décrivent clairement le travail en cours.
• Agent Note n’utilise pas des mots d’approbation comme yes, continue ou お願いします comme règles de sélection. Sans indice concret lié aux fichiers ou au code, Context est ignoré.
• Context ne change jamais files_touched, prompt ownership, AI Ratio, attribution method ni le fait qu’une git note soit enregistrée.

Agent Note vs Entire

Agent Note et Entire résolvent des problèmes proches, mais différents.

• Agent Note relie les git commits à la conversation avec l’IA qui les a produits. Entire est un checkpoint product plus large avec des workflows rewind / resume.
• Agent Note stocke l’enregistrement permanent dans refs/notes/agentnote; les fichiers temporaires de session restent sous .git/agentnote/. Entire se concentre sur la checkpoint metadata et une hosted web application.
• Le Dashboard d’Agent Note est un static GitHub Pages optionnel, alimenté par les git notes. Vous pouvez utiliser Agent Note sans hosted service.
• Agent Note ne cherche pas à restaurer un ancien workspace state. Il optimise la reviewability: pourquoi un commit a changé, quels prompts sont intervenus et quelle part du diff est AI-authored.

Astuce

Les listes de prompts viennent de la fenêtre de conversation entre deux commits, pas de tout l’historique de la session. Agent Note garde les prompts utiles de planification, de clarification et de revue pour le commit courant, et retire l’historique de prompts cité ainsi que les tours d’édition qui ne survivent pas dans ce commit.

Note

Les generated artifacts courants sont exclus du dénominateur de AI Ratio en best effort à partir de signaux précis, comme les chemins de framework/cache, les noms ou suffixes générés et les en-têtes des fichiers commités. Les noms de dossiers génériques comme build/, dist/, gen/, generated/ et target/ ne suffisent pas à eux seuls. Si votre repository commit des bundles ou generated outputs qui doivent rester visibles sans influencer l’AI Ratio, listez-les dans le .agentnoteignore à la racine du repository.

Cycle de vie de la session

Événement	Ce qui se passe
SessionStart	Crée le répertoire de session et écrit le heartbeat
UserPromptSubmit	Ajoute le prompt, incrémente le compteur de turn et fait tourner les logs
PreToolUse Edit/Write	Capture le pre-edit blob hash de façon synchrone
PostToolUse Edit/Write	Capture le post-edit blob hash et le chemin du fichier
Stop	Journalise l’événement stop (le heartbeat reste actif — Stop = fin de réponse, pas fin de session)

Note

Les plain Git hooks exigent une session récente avec file evidence avant d’injecter des trailers. Quand l’Agent transcript courant est fiable, Agent Note peut garder une commit-level attribution même sans file touches exacts par prompt.

Astuce

Agent Note garde la trace de l’agent qui a produit la session. Les métadonnées de session stockent l’adapter actif afin que show, status et l’enregistrement du commit puissent retrouver plus tard le bon format de transcript.

Git Notes

Les git notes sont invisibles dans les listes de branches, l’interface GitHub et CI — mais elles peuvent être poussées et récupérées.

# Partager avec l’équipe
git push origin refs/notes/agentnote

# Récupérer depuis le remote
git fetch origin refs/notes/agentnote:refs/notes/agentnote

# Afficher une note
git notes --ref=agentnote show <commit>

Astuce

agent-note init configure l’auto-fetch, et le hook pre-push gère l’auto-push. Aucune commande manuelle n’est nécessaire.