Mencatat Keuangan ke Spreadsheet dengan Workflow Hermes

Artikel ini adalah lanjutan dari Membuat Workspace Khusus agar Hermes Bekerja Lebih Terarah. Di artikel sebelumnya, saya menjelaskan kenapa Hermes saya pisahkan dari execution plane yang deterministik. Di sini saya menerapkan pola yang sama untuk satu pekerjaan yang lebih konkret: mencatat transaksi keuangan ke spreadsheet Financial Planner.

Masalahnya bukan hanya menulis satu baris

Pencatatan transaksi terlihat sederhana. Saya bisa saja membuka spreadsheet, mencari baris kosong, lalu mengisi nominal dan deskripsi.

Masalahnya muncul ketika pencatatan dilakukan berulang kali:

nama kategori harus konsisten;
account asal dan tujuan tidak boleh tertukar;
transaksi transfer tidak boleh dianggap sebagai income atau expense;
piutang baru dan pelunasannya perlu hubungan yang jelas;
angka dan tanggal harus memiliki format yang sama;
perubahan ke spreadsheet eksternal perlu bisa diaudit;
agent tidak boleh menganggap pesan yang ambigu sebagai izin untuk menulis.

Karena itu, saya tidak menjadikan Hermes sebagai spreadsheet editor yang bebas. Hermes memahami pesan dan membantu menyiapkan transaksi. Workspace dan CLI menerapkan aturan, meminta approval, menjalankan write, lalu membaca kembali hasilnya.

Hubungan dengan artikel Hermes workspace

Pola arsitekturnya sama dengan artikel sebelumnya:

Merender diagram...

Hermes berada di sisi percakapan dan routing. CLI menjadi kontrak yang bisa dipanggil secara manual maupun dari scheduler. Spreadsheet tetap menjadi tempat pencatatan, tetapi tidak menerima perubahan langsung dari prompt tanpa lifecycle.

Bentuk input yang saya gunakan

Saya tidak membutuhkan format command yang panjang untuk setiap transaksi. Pesan natural language biasanya sudah cukup, selama field pentingnya jelas.

Contoh:

Bayar makan siang 35.000 dari account utama

Atau:

Terima pembayaran freelance 2.500.000 ke account utama

Pesan tersebut belum langsung menjadi baris spreadsheet. Agent harus menormalkan maksudnya terlebih dahulu dan memastikan informasi yang wajib tidak hilang.

Untuk transaksi yang ambigu, saya lebih memilih bertanya daripada mengarang. Contohnya, jika ada dua account yang namanya mirip, atau kategori tidak dapat dipetakan dengan yakin, proses berhenti di tahap draft.

Metadata selalu dibaca sebelum transaksi

Kategori dan account bukan daftar yang boleh ditebak dari memory percakapan. Sebelum membuat plan, workflow membaca metadata Financial Planner yang sedang aktif.

Secara konsep, metadata tersebut berisi:

daftar account yang valid;
daftar kategori;
aturan cashflow;
pilihan field lain yang diwajibkan oleh spreadsheet;
konfigurasi setup yang sedang digunakan.

Command yang digunakan:

.venv/bin/kw finance metadata --json

Output JSON menjadi sumber validasi. Jika spreadsheet memakai nama kategori yang berbeda dari istilah sehari-hari, adapter melakukan mapping sesuai metadata, bukan membuat kategori baru secara diam-diam.

Ini juga menjaga workflow dari masalah yang sering terjadi pada spreadsheet personal: kategori yang sama muncul dengan beberapa ejaan, account tujuan masuk ke kolom yang salah, atau transaksi lama memakai nilai yang sudah tidak berlaku.

Memetakan maksud ke cashflow rule

Satu pesan transaksi harus cocok dengan satu cashflow rule. Saya tidak membiarkan satu pesan diproses sebagai beberapa jenis transaksi sekaligus tanpa kejelasan.

Secara konseptual, rule dapat mewakili beberapa jenis berikut:

Maksud	Contoh	Hal yang harus jelas
Expense	Membayar makan	nominal, kategori, account asal
Income	Menerima pembayaran	nominal, kategori, account tujuan
Transfer	Memindahkan uang antar-account	account asal dan account tujuan
Piutang baru	Meminjamkan uang	nominal, kategori, account asal, pihak terkait
Pelunasan piutang	Seseorang membayar utang	transaksi piutang asal dan account tujuan

Nama rule dan pilihan field sebenarnya tetap berasal dari metadata live. Tabel ini hanya menjelaskan cara berpikirnya, bukan menggantikan konfigurasi spreadsheet.

Perbedaan account asal dan account tujuan sangat penting. Pada expense, uang keluar dari From Account. Pada income, uang masuk ke To Account. Pada transfer, kedua sisi harus terisi dan transaksi tidak boleh dihitung sebagai pendapatan baru.

Dari pesan menjadi frozen payload

Setelah metadata dan rule cocok, workflow membuat plan. Plan menyimpan payload yang akan dipakai jika saya menyetujui transaksi.

Contoh bentuk konseptualnya:

{
  "cashflow_type": "expense",
  "date": "2026-08-04",
  "description": "Makan siang",
  "amount": 35000,
  "category": "<category-from-live-metadata>",
  "from_account": "<account-from-live-metadata>",
  "to_account": null
}

Nilai account dan kategori pada contoh sengaja tidak ditulis sebagai data nyata. Dalam eksekusi sebenarnya, nilai tersebut harus berasal dari metadata setup yang aktif.

Payload ini kemudian dibekukan bersama action ID dan hash. Setelah approval diberikan, workflow tidak membangun ulang transaksi dari context percakapan. Ia mengeksekusi payload yang sama.

Lifecycle plan, approval, execute, verify

Inilah bagian yang paling saya pertahankan dari desain workspace:

metadata
  → normalize intent
  → match one cashflow rule
  → plan frozen payload
  → show fields for review
  → explicit approval
  → execute spreadsheet write
  → read-back verification

1. Metadata

Workflow mengambil pilihan account, kategori, dan rule terbaru.

2. Normalize intent

Pesan natural language diubah menjadi field terstruktur: jenis cashflow, tanggal, deskripsi, nominal, dan account yang relevan.

3. Plan

CLI membuat durable action. Payload, hash, dan action ID disimpan sebelum ada write eksternal.

4. Review

Saya melihat ringkasan transaksi yang akan dicatat. Ringkasan ini menggunakan bullet agar mudah diperiksa dari Telegram atau mobile:

Jenis: Expense
Tanggal: 2026-08-04
Deskripsi: Makan siang
Nominal: Rp35.000
Kategori: <hasil metadata>
Dari Account: <hasil metadata>

5. Approval

Kata seperti ok atau approve hanya dianggap approval jika konteksnya jelas. Jika ada beberapa draft atau field yang belum pasti, workflow tidak menebak transaksi mana yang dimaksud.

6. Execute

Action yang sudah disetujui dieksekusi menggunakan payload beku. Tidak ada perubahan field secara diam-diam di antara approval dan execute.

7. Verify

Adapter membaca kembali hasil pencatatan atau memeriksa bukti yang disediakan spreadsheet. Status selesai hanya boleh dilaporkan ketika action dan verification sama-sama berhasil.

Kenapa tidak langsung memakai Google Sheets API?

Secara teknis, agent bisa saja memanggil Google Sheets API langsung. Namun pola itu membuat beberapa tanggung jawab tercampur:

prompt ikut menentukan struktur spreadsheet;
validasi kategori tidak selalu konsisten;
approval hanya menjadi kalimat di percakapan;
retry dan verification mudah terlewat;
perubahan sulit direproduksi dari log.

Dengan CLI, Hermes hanya membutuhkan kontrak sederhana. Contohnya, skill mengarahkan percakapan ke command finance, sedangkan implementasi di workspace menangani metadata, payload, spreadsheet adapter, dan verification.

Hermes skill
      → kw finance metadata
      → kw finance plan
      → explicit approval
      → kw action execute
      → verified transaction result

Skill tetap tipis. Ia menjelaskan kapan workflow dipakai dan aturan apa yang harus dijaga, tetapi tidak menyimpan business logic transaksi di dalam prompt.

Kasus khusus: pelunasan piutang

Pelunasan piutang tidak saya catat sebagai income biasa. Workflow perlu mencari transaksi piutang yang cocok terlebih dahulu.

Contoh pesan:

Andi bayar utang 500.000 ke account utama

Jika ada satu transaksi pada kategori piutang baru yang cocok, workflow dapat memetakan:

jenis menjadi pelunasan piutang;
kategori mengikuti transaksi piutang asal;
account tujuan menjadi account penerima;
hubungan dengan transaksi asal dipertahankan.

Jika tidak ada kecocokan tunggal, workflow harus meminta klarifikasi. Mencatatnya sebagai income umum hanya karena uang masuk akan merusak histori dan analisis cashflow.

Apa yang saya lihat dari desain ini

Spreadsheet tetap sederhana bagi manusia, tetapi proses di sekitarnya memiliki boundary yang jelas:

Hermes memahami maksud pesan;
metadata menjaga pilihan tetap valid;
rule membedakan income, expense, transfer, dan piutang;
plan membuat perubahan bisa direview;
approval mencegah write tanpa izin;
adapter mengurus detail spreadsheet;
verification memastikan catatan benar-benar tersimpan.

Ini bukan upaya membuat pencatatan lebih rumit. Tujuannya adalah memindahkan kerumitan dari percakapan yang tidak konsisten ke workflow yang dapat diuji.

Batasan dan keamanan

Workflow keuangan tidak boleh menganggap spreadsheet sebagai tempat aman untuk semua hal. Saya tetap menjaga beberapa batas:

spreadsheet ID dan credential tidak masuk repository;
token OAuth berada di secret storage lokal;
data transaksi tidak dikirim ke channel publik;
hasil konfirmasi tidak menampilkan total saldo kecuali memang diminta;
command read-only dan external write dibedakan;
approval tidak boleh dilewati hanya karena scheduler atau agent menganggap transaksi terlihat jelas.

Untuk operasi yang berasal dari email, import job hanya membuat draft atau status pending_review. Deteksi email tidak otomatis menjadi transaksi tercatat.

Penutup

Pencatatan keuangan adalah contoh kecil dari prinsip yang saya jelaskan di artikel Hermes workspace: agent boleh fleksibel dalam memahami tujuan, tetapi eksekusi eksternal perlu kontrak, state, approval, dan bukti.

Dengan pola ini, saya bisa menulis pesan transaksi secara natural tanpa menjadikan spreadsheet sebagai area eksperimen. Hermes membantu saya berbicara dengan sistem. CLI dan adapter memastikan pencatatan mengikuti aturan Financial Planner.

Cari sesuatu