Nudge: Collaborative Memory Layer untuk Claude Code dan Codex CLI

AI coding agent seperti Claude Code dan Codex CLI seringkali lupa convention proyek atau mengulang kesalahan yang sudah pernah diperbaiki. Nudge hadir sebagai collaborative memory layer yang menangkap aturan proyek, preferensi workflow, dan pelajaran debugging ke dalam format yang bisa dibaca dan dieksekusi oleh agent secara otomatis.

Mengapa Agent Membutuhkan Memori Eksternal

Agent AI bekerja lebih baik ketika mereka bisa fokus pada tugas aktual daripada menyimpan setiap preferensi proyek dalam working memory. Nudge memindahkan konvensi tersebut ke dalam rule yang kecil, teruji, dan durable. Rule menangkap convention deterministik sebelum operasi dieksekusi. Bash substitutions memperbaiki kesalahan command sederhana secara otomatis. Prompt reminders menambahkan konteks proyek ketika user meminta sesuatu yang spesifik. Learned incident notes mencegah agent di masa depan mengulangi debugging yang sudah pernah dilakukan.

Desain Nudge sangat langsung: setiap pesan mengatakan apa yang salah, bagaimana memperbaikinya, dan bahwa agent harus mencoba ulang. Pendekatan ini mengurangi noise prompt sekaligus meningkatkan konsistensi output.

Instalasi dan Setup

Nudge mendukung macOS, Linux, dan Windows x64. Proses instalasi menggunakan script one-liner yang mengunduh binary sesuai platform. Jalankan perintah berikut di terminal:

Untuk Windows PowerShell, gunakan:

irm https://raw.githubusercontent.com/attunehq/nudge/main/scripts/install.ps1 | iex

Setelah terinstal, setup hook untuk Claude Code:

nudge claude setup

Atau untuk Codex CLI:

nudge codex setup

Kedua command akan memodifikasi konfigurasi agent agar memanggil Nudge sebelum tool use dan prompt submission. Restart sesi agent yang sedang berjalan, lalu verifikasi dengan menjalankan /hooks di dalam Claude Code atau Codex CLI.

curl -sSfL https://raw.githubusercontent.com/attunehq/nudge/main/scripts/install.sh | bash

Untuk Windows PowerShell, gunakan:

irm https://raw.githubusercontent.com/attunehq/nudge/main/scripts/install.ps1 | iex

Setelah terinstal, setup hook untuk Claude Code:

nudge claude setup

Atau untuk Codex CLI:

nudge codex setup

Kedua command akan memodifikasi konfigurasi agent agar memanggil Nudge sebelum tool use dan prompt submission. Restart sesi agent yang sedang berjalan, lalu verifikasi dengan menjalankan /hooks di dalam Claude Code atau Codex CLI.

Menulis Aturan Proyek dengan .nudge.yaml

Buat file .nudge.yaml di root repositori. File ini berisi versi, daftar rules, dan konfigurasi trigger. Berikut contoh rule yang melarang penggunaan .unwrap() di Rust dan menyarankan .expect() dengan pesan deskriptif:

version: 1
rules:
  - name: no-unwrap
    message: 'Use .expect("descriptive error message") instead of .unwrap(), then retry.'
    on:
      - hook: PreToolUse
        tool: Write
        file: "**/*.rs"
        content:
          - kind: Regex
            pattern: "\\.unwrap\\(\\)"

Rule ini aktif pada hook PreToolUse untuk tool Write dan Edit, dengan scope file *.rs. Pola regex mendeteksi kemunculan .unwrap() dan memicu pesan koreksi sebelum file ditulis.

Workflow Learned Notes untuk Debugging

Ketika debugging session menghasilkan insight berharga, catat sebagai learned note agar agent di masa depan tidak perlu mendiscovery ulang. Claude Code setup menginstal slash command nudge:learn untuk workflow ini. Setelah sesi debugging yang sukses, cukup minta agent: use nudge:learn to record this fix.

Learned notes disimpan di repositori dan diindeks menggunakan BM25 search. Nudge akan mencocokkan query user dengan note yang paling relevan, lalu menyuntikkan konteks tersebut ke prompt agent sebelum ia mulai bekerja. Ini sangat berguna untuk proyek besar dengan codebase kompleks.

Integrasi CI dengan nudge check

Salah satu keunggulan Nudge adalah kemampuannya berjalan di luar sesi agent. Command nudge check bisa dipasang di pre-commit hook atau pipeline CI untuk memastikan setiap pull request mematuhi convention proyek. Tambahkan ke .pre-commit-config.yaml atau GitHub Actions:

nudge check --config .nudge.yaml --path src/

Integrasi ini menjadikan Nudge bukan sekadar tool untuk agent, tapi juga bagian dari quality gate standar. Tim bisa menambahkan rule baru kapan saja tanpa perlu mengubah setup agent individu.

Contoh Rule Lengkap untuk Berbagai Skenario

Repository Nudge menyertakan contoh rule siap pakai di direktori examples/rules. Mulai dari larangan penggunaan console.log di production, pemaksaan penggunaan typed imports, hingga validasi nama file snake_case. Setiap rule bisa dikopi dan dimodifikasi sesuai kebutuhan tim.

Untuk project menggunakan TypeScript, tambahkan rule yang memastikan setiap fungsi publik memiliki JSDoc atau tipe return eksplisit. Untuk Python, rule bisa memaksa penggunaan typing.Optional daripada None tanpa anotasi. Fleksibilitas ini membuat Nudge bekerja di berbagai stack teknologi.

Kesimpulan

Nudge mengubah cara kita berinteraksi dengan AI coding agent. Daripada mengulang instruksi yang sama setiap sesi, kita menulis rule sekali dan membiarkan agent menghafalnya secara permanen. Kombinasi rule enforcement, bash substitution, prompt reminder, dan learned notes menjadikan Nudge fondasi solid untuk collaborative coding dengan AI di tim developer skala apa pun.

Sumber: github.com/attunehq/nudge