Как это работает

Эта страница объясняет механику отчета: что собирается локально, что превращается в git note и как эти данные попадают в PR Report и Dashboard. Чтобы пользоваться Agent Note, не нужно помнить все детали, но это полезная модель, когда результат выглядит неожиданно.

Поток данных

1. PromptПопросите coding agent

Hooks захватывают prompt и turn id.

2. EditAI меняет файлы

Hooks или transcripts записывают изменённые файлы и сигналы, которые используются для attribution.

3. CommitЗапишите note

Когда в сессии есть данные для записи, git commit вставляет trailer и записывает git note.

4. ShareПоделитесь вместе с кодом

git push отправляет refs/notes/agentnote в remote.

Если сгенерированные git hooks установлены, в большинстве репозиториев достаточно продолжать пользоваться обычными git commit и git push. Cursor также восстанавливает пары prompt / response из локальных transcripts и может продолжать отслеживать коммиты, когда git hooks недоступны.

Хранилище

Слой 1: локальные временные данные

Данные сессии в .git/agentnote/sessions/. JSONL-файлы для prompts, changes и blob hashes. Ротируются после каждого commit и никогда не pushатся.

Слой 2: Git Notes

Постоянная запись в refs/notes/agentnote. Один JSON на commit. Можно push, fetch и делиться с командой.

Файлы сессии

Файл	Назначение
`prompts.jsonl`	Один prompt на строку с номером turn
`changes.jsonl`	Файлы, которых коснулась AI, с post-edit blob hashes
`pre_blobs.jsonl`	Состояние файла до каждого AI edit
`heartbeat`	Timestamp активности сессии
`turn`	Монотонный счетчик, увеличивающийся с каждым prompt

Note Schema

{
  "v": 1,
  "agent": "claude",
  "session_id": "a1b2c3d4-...",
  "timestamp": "2026-04-02T10:30:00Z",
  "model": "claude-sonnet-4-20250514",
  "interactions": [
    {
      "prompt": "Реализуй JWT auth middleware",
      "contexts": [
        { "kind": "reference", "source": "previous_response", "text": "Предыдущий response объясняет, почему этот middleware нужно изменить." }
      ],
      "selection": {
        "schema": 1,
        "source": "primary",
        "signals": ["primary_edit_turn"]
      },
      "response": "Я создам 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 }
  }
}

Режимы атрибуции

Claude Code

Обычно это line-level. Agent Note сравнивает состояние файла до и после каждого AI edit и затем вычитает из final diff человеческие edits, которые появились позже.

Codex CLI

Начинает как file-level. Переходит на line-level только когда patch counts в transcript совпадают с final commit diff.

Cursor

Начинает как file-level. Переходит на line-level только когда совпадают counts правок и финальный файл всё ещё соответствует последнему AI edit.

Gemini CLI

Сохраняет prompt / response и file-level attribution через hooks и парсинг transcript. Перехода на line-level пока нет.

Как собирается `📝 Context`

📝 Context — это подсказка только для отображения коротких prompt вроде “continue” или “сделай следующий шаг”. Она помогает понять prompt, не меняя attribution.

Agent Note Dashboard showing Context before a short prompt

reference context берётся из непосредственно предыдущего response, если он упоминает путь изменённого файла, имя файла или code identifier из финального diff.
scope context берётся из текущего response, если его первые строки ясно описывают текущую работу.
Agent Note не использует короткие подтверждения вроде yes, continue или お願いします как правила выбора. Если нет конкретной подсказки по файлу или коду, Context не добавляется.
Context никогда не меняет files_touched, prompt ownership, AI Ratio, attribution method или факт сохранения git note.

Agent Note vs Entire

Agent Note и Entire решают похожие, но разные задачи.

Agent Note связывает git commits с диалогом с AI, который их создал. Entire — более широкий checkpoint product с workflow rewind / resume.
Agent Note хранит постоянную запись в refs/notes/agentnote; временные файлы сессии остаются в .git/agentnote/. Entire строится вокруг checkpoint metadata и hosted web application.
Dashboard Agent Note — это optional static GitHub Pages на основе git notes. Agent Note можно использовать без hosted service.
Agent Note не пытается восстановить старый workspace state. Он фокусируется на reviewability: почему commit изменился, какие prompts участвовали и какая часть diff была AI-authored.

Жизненный цикл сессии

Событие	Что происходит
SessionStart	Создаёт директорию сессии и записывает heartbeat
UserPromptSubmit	Добавляет prompt, увеличивает turn counter и ротирует logs
PreToolUse Edit/Write	Синхронно захватывает pre-edit blob hash
PostToolUse Edit/Write	Захватывает post-edit blob hash и путь к файлу
Stop	Логирует событие stop (heartbeat остаётся активным — Stop = конец response, а не конец сессии)

Git Notes

Git notes невидимы в списках веток, в UI GitHub и в CI, но их можно push и fetch.

# Поделиться с командой
git push origin refs/notes/agentnote

# Забрать из remote
git fetch origin refs/notes/agentnote:refs/notes/agentnote

# Посмотреть note
git notes --ref=agentnote show <commit>