Di sinilah adopsi agen gagal secara diam-diam: pada alur dari kebutuhan menjadi kode. Agen tidak menulis kode yang buruk. Masalahnya, enam minggu kemudian tidak ada yang bisa menunjukkan perubahan ini berasal dari kebutuhan mana, siapa yang menyetujui lingkupnya, atau bukti apa yang dilihat peninjau sebelum menerimanya. Kodenya datang dengan cepat. Catatannya tidak.
Tutorial ini membangun catatan itu dengan sengaja: satu rantai dari kebutuhan tertulis sampai pull request yang sudah di-merge, di mana setiap mata rantainya bisa Anda buka. Spec Kit dari GitHub menutup celah yang sama lewat file-file di dalam repositori. Panduan ini menutupnya dengan sistem kerja, memakai Sharkly karena Sharkly menyimpan seluruh rantai pada satu Task, meski polanya bisa diterapkan ke tracker apa pun yang mampu menyimpan tautan yang sama. Jika Anda ingin tahu siklus operasionalnya lebih dulu, mulailah dari panduan kami tentang manajemen proyek agen AI.
TL;DR
Alur kerja dari kebutuhan ke kode yang dapat dilacak adalah alur di mana setiap artefak menunjuk ke artefak yang menyebabkannya: requirement, Task, sub-task, run, pull request, penerimaan. Di Sharkly, kebutuhan menjadi sebuah Task, seorang Agen mengusulkan perinciannya dalam mode Plan dan seseorang mengonfirmasinya, setiap sub-task berjalan di worktree terisolasi lengkap dengan log eksekusi, pull request menautkan kembali melalui Task ID, dan seseorang menerima hasilnya berdasarkan kriteria penerimaan yang ditulis di awal. Agen meneliti, mengeksekusi, menguji, dan melaporkan. Manusia menentukan arah, memberi wewenang, dan menerima hasilnya.
Apa yang harus dimaksud dengan dapat dilacak
Keterlacakan bukan laporan yang Anda buat di akhir. Keterlacakan adalah sifat dari rantai itu sendiri: setiap mata rantai ada karena mata rantai sebelumnya, dan Anda bisa menelusurinya ke dua arah. Enam mata rantai sudah cukup untuk mencakup sebuah fitur.
| Mata rantai | Letaknya | Apa yang menautkannya ke mata rantai sebelumnya |
|---|---|---|
| Requirement | Deskripsi Task, tipe Requirement atau User Story | Orang yang menulisnya |
| Perincian | Sub-task di bawah Task induk | Proposal mode Plan yang sudah dikonfirmasi |
| Eksekusi | Run Task dan log eksekusi | Penugasan plus status yang siap |
| Bukti | Komentar Agen berisi pemeriksaan dan hasil | Run yang menghasilkannya |
| Perubahan | Pull request | Task ID di branch, judul, atau isi |
| Penerimaan | Perubahan status oleh orang yang disebut namanya | Peninjauan terhadap kriteria penerimaan |
Jika ada mata rantai yang hilang, rantai itu cuma hiasan. Celah yang paling umum ada di mata rantai terakhir: pull request yang sudah di-merge dianggap sebagai penerimaan padahal tidak ada yang membandingkan perubahannya dengan kebutuhannya.
Langkah 1: Tulis kebutuhan sebagai sebuah Task
Task adalah unit dasar pekerjaan yang dilacak di Sharkly, dan Space yang disiapkan untuk pengembangan perangkat lunak dimulai dengan tipe task Requirement, Bug, Task, dan User Story. Gunakan Requirement atau User Story untuk induknya. Tipe inilah yang menentukan field kustom dan status Workflow mana yang berlaku, sehingga sebuah Requirement bisa punya status peninjauan sendiri tanpa mengotori workflow Bug.
Deskripsinya yang memikul beban terbesar. Tulis untuk orang yang belum pernah melihat percakapannya: mengapa pekerjaan ini penting, apa yang termasuk dan tidak termasuk dalam lingkup, file terkait atau perilaku yang diamati, keputusan yang sudah diambil, dan bagaimana penyelesaiannya akan ditinjau. Baris terakhir itulah kriteria penerimaan, jangkar untuk mata rantai keenam. Jika Anda belum bisa menulisnya, berarti kebutuhannya belum siap, dan Backlog ada justru untuk itu: Task yang ditugaskan ke Agen tidak akan mulai selama masih berada di sana.
Lampirkan repositori di tingkat Space agar setiap sub-task mewarisinya. Agen tanpa binding repositori akan memakai repositori Git milik Space sebagai fallback, dan itulah yang Anda inginkan untuk fitur dengan banyak Task.
Langkah 2: Biarkan Agen menyusun perinciannya, lalu konfirmasi
Buka chat Agen pada Task tersebut dan ubah sesinya ke mode Plan. Dalam mode Plan, Agen dapat mengusulkan tindakan untuk Anda tinjau, dan Sharkly baru membuat Task serta sub-task yang direncanakan setelah Anda mengonfirmasi proposalnya. Anda bisa mengonfirmasi tanpa memulai, atau mengonfirmasi sekaligus memulai pekerjaannya.
Inilah mata rantai yang paling sering dilewati tim, padahal justru ini yang membuat perinciannya dapat dilacak, bukan sekadar improvisasi. Proposalnya terlihat sebelum menjadi pekerjaan: hapus sub-task yang memperlebar lingkup, tambahkan langkah migrasi yang terlewat oleh Agen. Sub-task tetap berada di Space yang sama dengan induknya, dan Sharkly menolak induk untuk diri sendiri maupun siklus, sehingga hierarkinya tetap berbentuk pohon.
Gunakan satu Agen saja untuk kebutuhan yang bisa ditangani satu peran. Gunakan Crew ketika leadernya perlu menafsirkan tujuan, melibatkan anggota Agen lain seperti penulis tes, dan membawa hasil mereka kembali ke satu Task. Untuk perubahan tiga file, Crew hanya menambah bagian yang bergerak tanpa menambah keterlacakan. Panduan kami tentang Sharkly Crews membahas model leader-first.
Salin apa pun yang diputuskan di chat ke deskripsi Task. Chat pada sebuah Task bukan komentar dan tidak muncul di Activity, jadi keputusan yang hanya ada di sana tidak terlihat oleh rantai.
Langkah 3: Eksekusi secara terisolasi, dengan jejak
Tugaskan setiap sub-task ke Agen melalui kontrol Assignee, lalu pindahkan dari Backlog. Sharkly memeriksa kategori status dan kesiapan eksekusi, memasukkan run ke antrean, dan mengirimkannya ke Computer yang dipilih, di mana layanan lokal menyiapkan direktori task yang terisolasi dan menjalankan Runtime.
Dua detail menjaga mata rantai ini tetap jujur. Run menyertakan judul dan deskripsi Task, komentar terbaru, serta Workflow tipe Task beserta status yang diizinkan, sehingga Agen bekerja berdasarkan kebutuhannya, bukan parafrase. Dan setiap run yang berbasis repositori mendapat worktree sendiri dalam mode Temporary, sehingga sub-task yang berjalan paralel tidak saling menimpa. Artikel kami tentang menjalankan agen secara paralel tanpa merge conflict menjelaskan mengapa isolasi itulah yang membuat fan-out aman.
Progres, trace event, dan hasilnya kembali ke Task. Log eksekusi mencatat mengapa run dimasukkan ke antrean, kapan mulai dan berakhir, pemanggilan tool dan event Runtime, sumber pemicunya, serta detail kegagalannya. Log itulah mata rantai keempat.
Langkah 4: Tautkan pull request lewat ID
Hubungkan organisasi GitHub sekali saja, lalu letakkan Task ID di judul pull request, deskripsinya, atau nama branch sumbernya. SH-312 saja maupun Fixes SH-312 sama-sama membuat tautan. Linkback akan mengomentari URL Task pada pull request, aktif secara default untuk repositori privat.
Sekarang soal batasannya, karena ini penting untuk keterlacakan: kata seperti fixes dan closes tidak membawa makna tambahan, dan melakukan merge pull request tidak mengubah status Task. Sharkly menautkan perubahan ke Task; Sharkly tidak memutuskan bahwa Task sudah selesai. Status tetap keputusan manusia, dan itulah inti dari mata rantai keenam. Panduan kami tentang menugaskan tiket Jira ke agen AI dan mendapatkan PR kembali menunjukkan tautan yang sama dari sisi tracker.
Langkah 5: Tinjau terhadap kebutuhannya, lalu terima
Agen dapat membiarkan sebuah Task menunggu peninjauan manusia, dan sinyal itu masuk ke Inbox penanggung jawabnya di bawah Primary. Baca tiga hal secara berurutan: kriteria penerimaan dari langkah pertama, komentar Agen yang mencantumkan pemeriksaan yang dijalankan dan hal yang masih belum pasti, lalu log eksekusi. Baru setelah itu diff-nya.
Jika ada Task pengujian terpisah yang memverifikasi perubahan tersebut, catat relasinya secara eksplisit. Owner dan Admin Organisasi dapat membuat tipe tautan kustom, dan contoh dari dokumentasinya sendiri, validates / is validated by, adalah sisi keterlacakan untuk mata rantai ini. Relasi tidak mengubah status dengan sendirinya, jadi penerimaan tetap harus berupa perubahan status yang dilakukan oleh seseorang.
Satu aturan kategori melindungi Anda di sini: memindahkan Task ke Completed menandainya sebagai terminal tetapi tidak membatalkan run yang sedang aktif. Jika Agen masih bekerja, batalkan dulu, baru putuskan.
Di mana rantainya putus
Alur kerja di atas punya tiga titik putus yang sudah diketahui, dan semuanya layak disebutkan secara terang-terangan.
Kesimpulan yang ditinggal di chat. Sesi Agent Chat mandiri hanya milik orang yang membuatnya. Jika desainnya disepakati di sana, Task tidak mengetahuinya.
Run yang dimulai di luar Task. Aksi Run Agent pada workflow otomasi tidak membuat Task; run-nya tercatat pada Agen. Tidak masalah untuk pemeriksaan malam hari, tetapi salah untuk pekerjaan fitur.
File, bukan catatan. spec.md, plan.md, dan tasks.md milik Spec Kit adalah rantai yang kuat untuk satu developer yang bekerja di satu repositori. Gunakan itu ketika timnya hanya Anda. Gunakan sistem kerja bersama ketika orang kedua perlu meninjau, menerima, atau menanyakan apa yang terjadi tanpa membuka checkout Anda. Sharkly bukan pengganti Claude Code, Codex, atau tool eksekusi lain; Sharkly adalah lapisan yang menjaga rantai itu tetap terlihat di sekelilingnya. Dokumentasinya membahas setiap konsep lebih dalam di docs.sharkly.ai.
FAQ
Apakah requirements to code berarti Agen yang menulis kebutuhannya? Tidak. Manusia yang menulis kebutuhan beserta kriteria penerimaannya. Agen bisa meneliti basis kode dan mengusulkan perinciannya dalam mode Plan, tetapi proposal itu baru menjadi Task setelah seseorang mengonfirmasinya.
Bisakah kebutuhan tetap saya simpan di Jira dan jejaknya tetap didapat? Bisa. Impor dan sinkronisasi Jira mempertahankan tracker yang dibaca organisasi Anda, sementara Sharkly menyimpan catatan eksekusinya. Artikel kami alternatif Jira untuk tim manusia-agen membahas kasus ketika tracker-nya sendiri yang akan diganti.
Bagaimana jika pull request sudah di-merge sebelum ditinjau? Status Task tidak berubah, sehingga rantainya menunjukkan Task yang belum diterima dengan perubahan yang sudah di-merge. Itulah sinyal yang benar: masih ada keputusan yang harus diambil seseorang.
Seberapa kecil sebaiknya fitur pertama yang dapat dilacak? Satu kebutuhan, dua atau tiga sub-task, satu Agen. Panduan manajemen proyek Claude Code kami menjalankan siklusnya dari awal sampai akhir pada satu Task.
