Cara kerjanya

Halaman ini menjelaskan mekanisme di balik report: apa yang dikumpulkan secara local, apa yang menjadi git note, dan bagaimana data itu sampai ke PR Report dan Dashboard. Anda tidak perlu mengingat semua detail untuk memakai Agent Note, tetapi halaman ini berguna saat hasilnya terasa tidak sesuai harapan.

Alur data

1. PromptBerikan tugas ke coding agent

Hooks menangkap prompt dan turn id.

→

2. EditAI mengubah file

Hooks atau transcript mencatat file yang berubah dan petunjuk yang dipakai untuk attribution.

→

3. CommitNote direkam

Jika ada data sesi yang dapat direkam, git commit menyisipkan trailer dan menulis git note.

→

4. ShareBagikan bersama kode

git push mengirim refs/notes/agentnote ke remote.

Jika git hook yang dihasilkan sudah terpasang, kebanyakan repository cukup terus memakai git commit dan git push seperti biasa. Cursor juga memulihkan pasangan prompt / response dari transcript lokal dan tetap bisa melacak commit saat git hook tidak tersedia.

Penyimpanan

Lapisan 1: data sementara lokal

Data sesi di .git/agentnote/sessions/. File JSONL untuk prompt, perubahan, dan blob hash. Dirotasi setelah setiap commit. Tidak pernah dipush.

Lapisan 2: Git Notes

Catatan permanen di refs/notes/agentnote. Satu JSON per commit. Bisa dipush, difetch, dan dibagikan ke tim.

File sesi

File	Tujuan
prompts.jsonl	Satu prompt per baris dengan nomor turn
changes.jsonl	File yang disentuh AI dengan post-edit blob hash
pre_blobs.jsonl	Keadaan file sebelum setiap edit AI
heartbeat	Stempel waktu aktivitas sesi
turn	Penghitung monoton yang bertambah di setiap prompt

Note Schema

{
  "v": 1,
  "agent": "claude",
  "session_id": "a1b2c3d4-...",
  "timestamp": "2026-04-02T10:30:00Z",
  "model": "claude-sonnet-4-20250514",
  "interactions": [
    {
      "prompt": "Implementasikan middleware auth JWT",
      "contexts": [
        { "kind": "reference", "source": "previous_response", "text": "Response sebelumnya menjelaskan mengapa middleware ini perlu berubah." }
      ],
      "selection": {
        "schema": 1,
        "source": "primary",
        "signals": ["primary_edit_turn"]
      },
      "response": "Saya akan membuat middleware-nya...",
      "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 }
  }
}

Mode atribusi

Claude Code

Biasanya line-level. Agent Note membandingkan kondisi file sebelum dan sesudah setiap edit AI, lalu mengurangi edit manusia yang masuk belakangan dari final diff.

Codex CLI

Mulai sebagai file-level. Naik ke line-level hanya jika jumlah patch di transcript cocok dengan final commit diff.

Cursor

Mulai sebagai file-level. Naik ke line-level hanya ketika jumlah edit cocok dan file akhir masih sama dengan edit AI terakhir.

Gemini CLI

Mencatat prompt / response dan attribution level file lewat hook dan parsing transcript. Mode line-level belum tersedia.

Cara mengumpulkan 📝 Context

📝 Context adalah catatan khusus tampilan untuk prompt pendek seperti “continue” atau “kerjakan yang berikutnya”. Context membantu pembaca memahami prompt tanpa mengubah attribution.

• reference context diambil dari response tepat sebelumnya ketika response itu menyebut path file yang berubah, nama file, atau code identifier dari diff final.
• scope context diambil dari response saat ini ketika awal response menjelaskan pekerjaan yang sedang dilakukan.
• Agent Note tidak memakai kata persetujuan singkat seperti yes, continue, atau お願いします sebagai aturan seleksi. Jika tidak ada petunjuk konkret tentang file atau code, Context dilewati.
• Context tidak pernah mengubah files_touched, prompt ownership, AI Ratio, attribution method, atau apakah git note disimpan.

Agent Note vs Entire

Agent Note dan Entire menyelesaikan masalah yang berdekatan, tetapi berbeda.

• Agent Note menghubungkan git commit dengan percakapan AI yang membuatnya. Entire adalah checkpoint product yang lebih luas dengan workflow rewind / resume.
• Agent Note menyimpan record permanen di refs/notes/agentnote; file sementara sesi tetap berada di .git/agentnote/. Entire berpusat pada checkpoint metadata dan hosted web application.
• Dashboard Agent Note adalah static GitHub Pages opsional yang didukung git notes. Agent Note tetap bisa dipakai tanpa hosted service.
• Agent Note tidak mencoba memulihkan workspace state lama. Fokusnya adalah reviewability: mengapa commit berubah, prompt mana yang terlibat, dan seberapa besar diff yang AI-authored.

Tips

Daftar prompt berasal dari jendela percakapan antar-commit, bukan dari seluruh backlog sesi. Agent Note mempertahankan prompt planning, clarification, dan review yang berguna untuk commit saat ini, sambil memangkas riwayat prompt yang dikutip dan edit turn yang tidak bertahan di commit ini.

Catatan

Generated artifact umum dikeluarkan dari denominator AI Ratio secara best-effort memakai sinyal spesifik seperti path framework/cache, nama atau suffix generated, dan header file yang di-commit. Nama direktori generik seperti build/, dist/, gen/, generated/, dan target/ saja tidak cukup. Jika repository Anda meng-commit bundle atau generated output yang harus tetap terlihat tetapi tidak memengaruhi AI Ratio, tulis polanya di .agentnoteignore di repository root.

Siklus hidup sesi

Event	Yang terjadi
SessionStart	Membuat direktori sesi dan menulis heartbeat
UserPromptSubmit	Menambahkan prompt, menaikkan counter turn, dan merotasi log
PreToolUse Edit/Write	Menangkap pre-edit blob hash secara sinkron
PostToolUse Edit/Write	Menangkap post-edit blob hash dan path file
Stop	Mencatat event stop (heartbeat tetap aktif — Stop = akhir response, bukan akhir sesi)

Catatan

Plain Git hooks membutuhkan session yang masih fresh dan file evidence sebelum menyisipkan trailer. Jika Agent transcript saat ini tepercaya, Agent Note tetap dapat menyimpan commit-level attribution meski file touches per prompt tidak tersedia.

Tips

Agent Note memahami agent yang sedang aktif. Metadata sesi menyimpan adapter aktif, sehingga show, status, dan perekaman commit nanti bisa menyelesaikan format transcript yang benar.

Git Notes

Git notes tidak terlihat di daftar branch, UI GitHub, atau CI — tetapi bisa dipush dan difetch.

# Bagikan ke tim
git push origin refs/notes/agentnote

# Ambil dari remote
git fetch origin refs/notes/agentnote:refs/notes/agentnote

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

Tips

agent-note init menyiapkan auto-fetch, dan hook pre-push menangani auto-push. Tidak perlu perintah manual.