Ini adalah bagian ke-2 dari seri postingan teknis tunaFlow. Di bagian 1, kami berbicara tentang "memberikan proses kepada agen", dan bagian ini adalah tentang bagaimana kami benar-benar mengimplementasikan proses tersebut. Saat ini kami sedang melakukan pengujian akhir dan menguji berbagai cara untuk mengurangi sejumlah besar token yang dihasilkan oleh ContextPack 😁. Baik masalahnya besar maupun tidak berarti, tetapi karena keserakahan untuk tidak mengorbankan apa pun, waktu rilis ditunda. Terima kasih atas perhatian Anda terhadap proyek kecil ini. Kami akan membalas dengan open source yang tidak buruk, meskipun bukan hebat dan agung. 🙏

---

Jika Anda mengatakan kepada agen "Buatkan ini untuk saya"

Jika Anda mengatakan kepada Claude Code "Refaktor middleware autentikasi untuk saya", itu langsung mulai menulis kode. Tanpa desain. Tanpa ulasan. Kadang-kadang berhasil, tetapi semakin kompleks tugasnya, semakin banyak masalah yang muncul.

- Mulai implementasi tanpa memahami cakupan dampak

- Setelah dimodifikasi, "Oh, ini bukan arahnya", lalu ditarik kembali

- Meninjau kode miliknya sendiri sambil berpikir "Sepertinya ditulis dengan baik ✅"

Ini adalah masalah yang terjadi bahkan jika manusia melakukannya. Di tim, ulasan kode menangkap ini, tetapi ketika agen bekerja sendirian, mekanisme keselamatan ini tidak ada.

Pipeline workflow tunaFlow dirancang untuk menyelesaikan masalah ini. Ini adalah struktur yang menerapkan proses pengembangan manusia (desain → persetujuan → implementasi → ulasan) kepada agen.

> Inspirasi untuk workflow ini berasal dari blog Stavros Korokithakis. Saat dia melanjutkan proyek dengan Claude Code, aliran yang terbentuk secara alami — menetapkan Plan terlebih dahulu, mendapat persetujuan, kemudian mengimplementasikan, dan meninjau hasilnya — membuat kami berpikir "Bukankah ini yang harus didukung oleh alat?" menjadi titik awal.

---

Workflow 7 Tahap

Workflow tunaFlow memiliki 7 tahap.

1. Chat           — Pengguna menjelaskan persyaratan kepada Architect
2. Drafting       — Architect mengusulkan Plan
3. Approval       — Pengguna menyetujui/menolak/meminta revisi Plan
4. Dev            — Developer mengimplementasikan kode
5. Review         — Reviewer(s) melakukan ulasan
6. Rework         — Jika ulasan gagal, lakukan perbaikan → ulasan lagi
7. Done           — Selesai

Ada transisi otomatis antara setiap tahap, dan titik keterlibatan manusia jelas. Bukan diimplementasikan sekaligus tetapi dibuat tahap demi tahap, dan kami berbagi masalah dan keputusan yang kami temui dalam prosesnya.

---

Deteksi Berbasis Penanda: Mengekstrak Struktur dari Output Agen

Pertanyaan pertama adalah "Bagaimana kami mendeteksi bahwa agen telah mengusulkan Plan?"

Jika menggunakan SDK, kami dapat menerima output terstruktur seperti submit_plan_proposal({ title, subtasks }) melalui function calling. Namun tunaFlow menggunakan mode CLI subprocess, jadi output agen adalah teks format bebas.

Jadi kami menggunakan penanda komentar HTML.

## Transisi Middleware Autentikasi ke OAuth2
### subtasks
1. Ganti logika validasi JWT dengan OAuth2 PKCE
2. Ubah adaptor route guard
3. Perbarui tes
### description
Saat ini autentikasi berbasis JWT akan diubah menjadi OAuth2 PKCE...

Di Persona agen (role prompt) ada aturan "Saat mengusulkan Plan, letakkan di dalam penanda ini", dan frontend menjalankan parsing penanda ini.

// planProposalParser.ts
const MARKER_OPEN = "";
const MARKER_CLOSE = "";
export function hasPlanProposal(content: string): boolean {
    return content.includes(MARKER_OPEN);
}

Ketika penanda terdeteksi, alih-alih teks biasa, ia dirender dengan komponen UI PlanProposalCard. Pengguna dapat langsung menyetujui/menolak/meminta revisi dari kartu.

Mengapa komentar HTML

 tidak dirender di markdown

Bahkan jika agen memasukkan penanda, penanda tersebut tidak terlihat di renderer markdown biasa, hanya tunaFlow yang mendeteksinya. Sekalipun penanda secara tidak sengaja ditampilkan, tidak akan terpapar kepada pengguna.

Keterbatasan Penanda

Karena berbasis penanda, deteksi gagal jika agen tidak mengikuti format. Ini terjadi dalam penggunaan nyata.

- Agen tidak menutup penanda hilang)

- Tidak ada bagian subtasks di dalam penanda

- Penanda ditempatkan di dalam blok kode sehingga parsing gagal

Ada dua respons. Pertama, kami menulis aturan format secara terperinci di prompt Persona. Kedua, kami membuat parser yang toleran — jika penanda penutup tidak ada, anggap hingga akhir pesan sebagai isi; jika tidak ada subtasks, tampilkan kartu hanya dengan description.

---

Approval Gate: Titik di Mana Manusia Membuat Keputusan

Setelah Architect mengusulkan Plan, pengguna ditampilkan 3 pilihan.

┌───────────────────────────────────┐
│ Plan: Transisi Middleware OAuth2    │
│                                   │
│ Subtasks:                         │
│  1. Ganti JWT → OAuth2 PKCE        │
│  2. Ubah route guard               │
│  3. Perbarui tes                   │
│                                   │
│  [Setujui]  [Minta Revisi]  [Tunda] │
└───────────────────────────────────┘

- Setujui: Implementation Branch dibuat secara otomatis, dan instruksi implementasi dikirimkan ke agen Developer

- Minta Revisi: Ketika pengguna memasukkan umpan balik, permintaan reusul dikirimkan ke Architect

- Tunda: Putuskan nanti

Awalnya hanya ada 2 pilihan persetujuan/penolakan, tetapi dalam penggunaan nyata, kasus "arahnya tepat tetapi ubah subtask sedikit" sering terjadi, jadi kami menambahkan permintaan revisi.

Mengapa 3-way

Dengan 2-way (persetujuan/penolakan), setelah penolakan Anda harus menjelaskan lagi kepada Architect "mengapa ditolak". Dengan 3-way, Anda dapat langsung menulis umpan balik untuk permintaan revisi, menyelesaikannya dalam satu kali jalan.

// Dalam ApprovalGate
case "revise":
    // Masukkan umpan balik → Minta reusul Plan ke Architect
    await requestPlanRevision(plan, feedback, architectEngine);
    break;

---

Implementation Branch: Implementasi dalam Ruang Terisolasi

Ketika Plan disetujui, Branch dibuat secara otomatis. Branch berarti "percabangan percakapan" di tunaFlow (dibahas secara terperinci di bagian 3).

Klik Setujui
  → Buat rekam baru di tabel branches (mode: "chat")
  → Buat percakapan bayangan (branch:{branchId})
  → Buat dokumen Plan (docs/plans/{slug}.md)
  → Kirim prompt implementasi ke Developer

Developer mengimplementasikan kode di dalam Branch ini. Karena terisolasi dari percakapan utama, bahkan jika implementasi gagal, tidak mempengaruhi percakapan utama.

Prompt yang dikirimkan ke Developer memiliki struktur seperti ini.

### 🔧 Mulai Implementasi
Plan: "Transisi Middleware Autentikasi ke OAuth2"
Instruksi kerja:
- docs/plans/auth-oauth-migration.md
- docs/plans/auth-oauth-migration-task-01.md
- docs/plans/auth-oauth-migration-task-02.md

Aturan:
1. Baca setiap file task dan implementasikan secara berurutan
2. Saat setiap selesai, keluarkan 
3. Saat semua selesai, keluarkan 

Penanda juga digunakan di sini. Ketika Developer menyelesaikan subtask, mengeluarkan penanda , dan tunaFlow mendeteksinya untuk memperbarui status Plan.

---

Review RT: Ulasan oleh Agen Berbeda

Ketika implementasi selesai, Review Roundtable (RT) dimulai secara otomatis. RT adalah struktur di mana beberapa agen berdiskusi (dibahas secara terperinci di bagian 4).

Developer selesai (deteksi impl-complete)
  → Buat Review Branch secara otomatis
  → Jalankan tes (run_project_tests)
  → Kirim prompt ulasan ke 2 Reviewer
  → Setiap Reviewer melakukan ulasan secara independen → keluarkan verdict

Prompt Reviewer mencakup dokumen Plan, ringkasan hasil implementasi, dan hasil tes. Reviewer mengeluarkan keputusan dengan penanda .

verdict: pass
findings:
- Implementasi sesuai dengan Plan
- Cakupan tes baik
recommendations:
- Perlu verifikasi cara memanggil autentikasi di ws_handler.rs
``

Reviewer Tidak Memodifikasi Kode

Ini adalah keputusan desain yang penting. Persona Reviewer memiliki aturan "Jangan modifikasi kode. Hanya baca dan putuskan."

Jangan ubah kode apa pun, buat commit, dorong perubahan.
HARUS membaca file untuk ulasan.
Hanya serahkan keputusan ulasan saja."

Alasan: Jika Reviewer memodifikasi kode, peran dengan Developer tercampur. Reviewer hanya **memutuskan**, perbaikan dilakukan oleh Developer. Sama seperti peninjau kode dalam tim manusia tidak melakukan commit langsung di PR.

---

Rework: Jika Gagal, Coba Lagi

Jika verdict Review adalah "fail", berubah ke tahap Rework.

Reviewer verdict: fail
  → Plan phase: "rework"
  → Teruskan umpan balik ke Developer
  → Developer memperbaiki
  → Jalankan Review RT lagi
  → Verifikasi verdict
  → Jika pass menjadi Done, jika fail kembali ke Rework

Masalah muncul di sini. Loop Tak Terbatas.

Developer memperbaiki → Reviewer fail → Developer memperbaiki → Reviewer fail → ... pengulangan ini terjadi 3 kali atau lebih, seringkali Developer mengulangi masalah yang sama dengan cara yang sama.

Deteksi Doom Loop

Jadi kami menambahkan deteksi Doom Loop. Kami menghitung jumlah peristiwa review_failed di tabel plan_events, dan jika 3 atau lebih, kami eskalasi.

// reviewWorkflow.ts
const freshEvents = await planApi.listPlanEvents(plan.id);
let lastEscalationIdx = freshEvents.length;
for (let i = freshEvents.length - 1; i >= 0; i--) {
    if (freshEvents[i].eventType === "doom_loop_escalated") {
        lastEscalationIdx = i;
        break;
    }
}

const failCount = eventsSinceReset
    .filter((e) => e.eventType === "review_failed").length;

Saat mencapai 3 kali:

"Ulasan gagal 3 kali — kami merekomendasikan ulasan desain ulang. 
Pilih redesain Architect atau lanjutkan rework Developer."

Memberi tahu pengguna "Ini mungkin bukan masalah implementasi tetapi masalah desain". Apakah akan melanjutkan Rework atau memodifikasi Plan itu sendiri adalah keputusan manusia.

Reset Rework Counter

Ada detail penting. Ketika Plan direvisi, counter kegagalan direset. Bahkan jika ada 3 kegagalan dalam Plan sebelumnya, ketika memulai dengan Plan yang direvisi, counter dimulai dari 0.

Ini terinspirasi dari alat otomasi GitHub CI bernama Optio. Optio menghitung "jumlah percobaan ulang otomatis setelah intervensi manual terakhir", dan tunaFlow mengikuti pola yang sama.

---

Titik Keterlibatan Manusia

Ada 3 tempat di mana manusia harus terlibat dalam seluruh alur.

1. Persetujuan Plan         — "Haruskah kita melanjutkan ke arah ini?"
2. Setelah Ulasan          — "Periksa hasil ulasan dan putuskan tindakan berikutnya"
3. Respons Doom Loop       — "3 kali gagal. Ubah desain atau terus coba?"

Sisanya (pembuatan Branch, pengiriman prompt Developer, memulai Review RT, transisi Rework) bersifat otomatis.

Awalnya kami berpikir "Bukankah lebih baik jika semuanya otomatis". Secara otomatis lakukan ulasan, dan jika pass secara otomatis merge. Tetapi masalah langsung terungkap dalam penggunaan nyata.

- Reviewer memberikan "pass" tetapi sebenarnya melewatkan kasus tepi

- Developer mengimplementasikan berbeda dari maksud Plan tetapi Reviewer juga tidak menangkapnya

- Semuanya berjalan otomatis tetapi hasilnya sama sekali bukan yang diinginkan

Biaya bagi manusia untuk memverifikasi (satu klik, baca 30 detik) jauh lebih kecil daripada biaya untuk memulihkan pekerjaan yang berjalan salah. Jadi prinsip "otomatisasi tetapi putuskan dengan manusia" dipertahankan.

---

Keterbatasan Saat Ini

1. Overhead Workflow

Bahkan untuk perbaikan sederhana (perbaikan typo, perubahan satu baris), jika melalui Plan → Persetujuan → Dev → Ulasan menjadi berlebihan. Saat ini pengguna dapat menilai dan melewati workflow untuk menyelesaikannya langsung melalui chat, tetapi "apakah ini memerlukan level workflow?" adalah biaya penilaian itu sendiri.

2. Penyimpangan Format Penanda

Masih ada kasus di mana agen tidak mengikuti format penanda. Terutama dengan model yang lebih kecil (Haiku, Gemini Flash) tingkat kepatuhan format penanda lebih rendah. Kami mengatasinya dengan parser yang toleran, tetapi pada dasarnya SDK function calling lebih stabil. Namun saat mempertahankan mode CLI subprocess, penanda adalah pilihan praktis.

3. Kualitas Ulasan

Reviewer memberikan "pass" tidak berarti benar-benar baik-baik saja. Karena Reviewer juga agen, ada yang terlewatkan. Terutama sulit menilai secara struktural "apakah perubahan ini mempengaruhi file lain". Ini juga alasan untuk mengintegrasikan code-review-graph (dibahas di bagian 7).

4. Masalah Konvergensi Rework

Bahkan saat loop Rework berjalan, dapat mengulangi masalah yang sama. Developer menerima umpan balik Reviewer dan memperbaiki, tetapi tidak menyelesaikan akar penyebab dan hanya melakukan perbaikan permukaan. Ini sebagian ditangani oleh sistem Failure Learning yang memberi Developer informasi "ada kegagalan serupa sebelumnya" (dibahas di bagian 9).

---

Angka Penggunaan Nyata

Hasil pengujian full-cycle workflow 4 kali di proyek tunaInsight.

- Waktu rata-rata Plan → Done: 3-5 menit waktu eksekusi agen (tidak termasuk waktu tunggu persetujuan pengguna)

- Kemungkinan terjadi Rework: sekitar 40% (2 dari 4 kali dengan 1+ Rework)

- Kejadian Doom Loop: 0 kali (tidak ada 3 kegagalan berturut-turut)

- Bug yang ditemukan selama full-cycle: 15 (sisa penanda dokumen yang dihasilkan otomatis, kontradiksi template Reviewer, dll)

15 bug berasal terutama dari "kualitas dokumen yang dihasilkan otomatis" dan "kasus tepi parser penanda". Lebih banyak masalah dalam infrastruktur sekitarnya (pembuatan dokumen, parsing penanda) daripada logika workflow itu sendiri.

---

Ringkasan Keputusan Inti

Pratinjau Bagian Berikutnya

Bagian 3: "Bercabang Percakapan" — Desain dan Penggunaan Branch

Kami membahas bagaimana Implementation Branch dan Review Branch dibuat, mengapa kami memilih UX drawer, dan bagaimana adopt (penggabungan hasil) bekerja. Hubungan antara workflow dan Branch adalah inti.

---

Daftar Seri

1. [Berikan Proses kepada Agen](./01-에이전트에게-프로세스를-줘라.md) — Apa yang kami Pelajari Saat Membuat AOC

2. Plan → Dev → Ulasan — Catatan Implementasi Pipeline Workflow (artikel ini)

3. Bercabang Percakapan — Desain dan Penggunaan Branch

4. Membuat Agen Berdiskusi — Desain dan Keterbatasan Roundtable

5. Percakapan Panjang — Catatan Implementasi Memori Jangka Panjang Agen

6. Menjalankan Workflow dengan Claude $20 — Arsitektur Mesin

7. Memberi Tahu Agen Struktur Kode — rawq + code-review-graph

8. Dari 246 Keterampilan, Hanya yang Diperlukan — Catatan Implementasi Aplikasi Keterampilan Otomatis

9. Jika Agen Mengulangi Kesalahan yang Sama — Desain Jaminan Kualitas

10. Menjalankan Full-Cycle dengan tunaFlow — Retrospektif Pengujian Workflow Praktis

- [Sudah Dipublikasikan] ContextPack — Desain Konteks Orkestrator Multi-Agen

---

Referensi

- Stavros Korokithakis — Pola Workflow Claude Code. Inspirasi aliran Plan → persetujuan → implementasi → ulasan. https://www.stavros.io/posts/how-i-write-software-with-llms/

- Optio (github.com/jonwiggins/optio) — Manajemen PR Otomatis Berbasis CI. Referensi pola "penghitungan setelah intervensi manual terakhir" Doom Loop.

- Addy Osmani — "Orchestrating Coding Agents": Pola Plan Approval Gate, Dedicated Reviewer. https://addyosmani.com/blog/code-agent-orchestra/

- Dokumen Intern tunaFlow

- Parser Penanda: src/lib/planProposalParser.ts

- Workflow: src/lib/workflow/ (modul 7 file)

- Status Plan: src-tauri/src/commands/plans.rs

- Ulasan: src/lib/workflow/reviewWorkflow.ts

- Doom Loop: src/lib/workflow/reviewWorkflow.ts:160