Lewati ke konten utama / Skip to main content
v2.0·24 Mei 2026·45–60 menit

Panduan Agentic Engineer 2026

Panduan komprehensif membangun produk software dengan AI agent — dari mindset, perencanaan, setup, hingga operasi dan komersialisasi. Untuk pemula non-IT.

Untuk: Pemula non-IT yang ingin membangun produk software dengan AI agent

#agentic-engineering#ai-agent#product-development#doc-first#prompt-engineering

BAGIAN 0 — CARA MEMBACA PANDUAN INI

0.1 Filosofi Restruktur

Panduan ini dibagi menjadi dua jenis bagian:

  1. Linear path (Bagian 1, 2, 3, 4, 7, 8, 9) — mengikuti urutan waktu proyek: belajar mindset → planning → setup → build → operate → komersialisasi → growth.
  2. Cross-cutting concerns (Bagian 5, 6, 10) — topik yang diterapkan sepanjang proyek, bukan di tahap tertentu. Security, observability, compliance, i18n bukan “fitur yang ditambahkan di akhir” — mereka adalah disiplin yang diterapkan setiap milestone.

Pemisahan ini penting karena banyak panduan agentic engineering memperlakukan security/compliance sebagai “tugas akhir”, padahal retrofit jauh lebih mahal daripada built-in dari awal.

0.2 Cara Memakai untuk NotebookLM

Upload file ini sebagai sumber. Lalu coba prompt berikut untuk menguji pemahaman:

  • “Jelaskan urutan keputusan yang harus diambil di Bagian 2 (Perencanaan) dan dependency antar keputusan.”
  • “Apa hubungan antara DDS (Development Debug System) di Bagian 3 dengan testing strategy di Bagian 4?”
  • “Bagaimana compliance UU PDP Indonesia memengaruhi data model, audit log, dan support workflow?”
  • “Buatkan tabel cross-reference: milestone-tracking artifact → bab yang mendefinisikannya.”

0.3 Glossary Singkat (Detail di Appendix B)

Istilah Definisi cepat
Agent / AI agent Sistem berbasis LLM yang bisa mengambil keputusan dan memanggil tool untuk menyelesaikan tugas multi-langkah
ADR Architecture Decision Record — dokumen 1-2 halaman per keputusan struktural
DDS Development Debug System — aplikasi terpisah yang menangkap error app utama saat development
PKM Personal Knowledge Management — sistem catatan personal (umumnya Markdown + tool seperti Obsidian)
RAG Retrieval-Augmented Generation — pola arsitektur AI di mana LLM diberi konteks dari knowledge base
RLS Row Level Security — kontrol akses di level baris database
NFR Non-Functional Requirements — kebutuhan kualitas (performance, availability, dst), bukan fitur
C4 Model Cara mendokumentasikan arsitektur dalam 4 level zoom (Context, Container, Component, Code)
Atomic vertical slice Satu task = satu fitur end-to-end yang testable (UI + API + DB), bukan satu layer

0.4 Audience & Asumsi

  • Audience utama: orang non-IT yang baru pertama membangun produk software dengan bantuan AI agent.
  • Asumsi: pembaca tidak menulis kode sendiri, tapi mengarahkan agent untuk melakukannya.
  • Konsekuensi: panduan ini lebih banyak membahas arsitektur keputusan, dokumentasi, dan evaluasi output, bukan tutorial coding.

0.5 Cara Pakai per Profil

Profil pembaca Cara pakai
Belum punya ide proyek Baca Bagian 1 dulu, lalu kembali setelah punya problem statement
Punya ide tapi belum mulai Bagian 1 → 2 → 3, baru ke 4
Sedang build, banyak bug Bagian 4 + Bagian 5 (terutama security) + Bagian 3.4 (DDS)
Mau rilis produk Bagian 7 (operations) + Bagian 5 (compliance)
Sudah live, mikir bisnis Bagian 8 + 9
Mau audit pendekatan Baca semua linear

BAGIAN 1 — FONDASI MINDSET

Fase pre-proyek. Tujuan: membentuk cara berpikir sebelum menyentuh kode atau spec.

1.1 Apa Itu Agentic Engineer

Konsep Inti

Agentic engineer adalah orang yang membangun software dengan mengarahkan AI agent, bukan dengan menulis kode sendiri. Skill utamanya bukan coding, tapi kemampuan menginstruksikan, mengevaluasi, dan mengarahkan agent.

Dua Makna yang Sering Dipertukarkan

  1. Membangun AI agents — membuat sistem di mana LLM bisa bertindak otonom (memakai tool, mengambil keputusan, menyelesaikan tugas multi-langkah). Ini product development di domain AI.
  2. Bekerja secara agentik — mendelegasikan tugas development ke AI agent (Claude Code, Cursor, Gemini CLI, dsb), lalu me-review dan mengarahkan output. Ini engineering methodology.

Panduan ini menggunakan makna kedua sebagai default, dengan Bagian 6 membahas makna pertama.

Skill Kunci

  • Prompt engineering — cara instruksi yang efektif dan minim ambiguitas
  • Tool-use design & function calling — merancang tool yang bisa dipanggil agent
  • Workflow orchestration — memecah tugas besar menjadi rantai langkah yang testable
  • Evaluation & guardrails — mengukur kualitas output dan menetapkan batas perilaku
  • Project management & documentation — disiplin yang menentukan apakah proyek selesai atau berhenti di tengah

Prinsip Emas

Anda adalah sutradara, bukan aktor. Tugas anda mengarahkan, bukan mengerjakan sendiri. Tapi anda harus paham apa yang sedang terjadi — sutradara yang tidak paham proses syuting akan menghasilkan film buruk.

Sumber Pendalaman

1.2 Personal Knowledge Management (PKM)

Konsep Inti

PKM adalah sistem untuk menangkap, mengorganisir, dan menemukan kembali pengetahuan yang anda kumpulkan — dari percakapan AI, tutorial, error yang pernah ditemui, sampai keputusan yang pernah diambil. Tanpa PKM, anda akan kehilangan pengetahuan dalam hitungan minggu.

Kenapa di Awal

Sebagai agentic engineer, anda akan belajar BANYAK dalam waktu singkat: konsep teknis baru, error baru, library baru, pola prompt baru. Tanpa sistem penyimpanan yang konsisten, pelajaran yang sama akan diulang berkali-kali.

Struktur Folder PKM (Rekomendasi)

knowledge/
├── projects/       catatan per proyek (link ke docs/ proyek)
├── topics/         catatan per topik (docker, react, llm, prompt-eng, ...)
├── resources/      link artikel, video, tools (dengan ringkasan kenapa disimpan)
├── journal/        catatan harian / mingguan
└── inbox/          quick capture, proses nanti (max 1-2 minggu)

Workflow Harian

Frekuensi Durasi Aktivitas
Setiap insight muncul 30 detik Capture ke inbox/ tanpa filter
Harian 15 menit Process — pindahkan dari inbox/ ke folder yang tepat
Mingguan 30 menit Review — apa yang dipelajari minggu ini? Apa pattern yang muncul?

Template Wajib

  1. Error & Fix — error → konteks → root cause → solusi → pencegahan ke depan
  2. Learning Note — apa yang dipelajari → kenapa penting → contoh praktis
  3. Decision Record — konteks → opsi → keputusan → alasan → hasil (diisi kemudian)

Tools

  • Obsidian (rekomendasi utama) — gratis, offline-first, Markdown native, plugin ecosystem besar. https://obsidian.md
  • Logseq — alternatif open-source, outliner-based. https://logseq.com
  • Plain text + grep — paling minimal, paling portable, paling tahan tool churn

Sumber Pendalaman

  • Tiago Forte — Building a Second Brain (buku, 2022). Framework CODE (Capture, Organize, Distill, Express). Konseptual, bukan tool-specific.
  • Sönke Ahrens — How to Take Smart Notes (buku, 2017). Metode Zettelkasten — basis filosofi banyak sistem PKM modern.
  • Andy Matuschak — “Evergreen notes” (web essay). Pendekatan minimal namun kuat. https://notes.andymatuschak.org/Evergreen_notes
  • LessWrong — “How to do hard things” tag. Banyak praktisi memakai PKM untuk decision-making, tidak hanya note-taking.

1.3 Prompt Engineering Fundamentals

Konsep Inti

Prompt engineering adalah cara menulis instruksi ke AI agent supaya hasilnya sesuai harapan. Ini senjata utama agentic engineer — instruksi yang buruk menghasilkan output yang buruk, tidak peduli sehebat apa model-nya.

Prinsip Dasar

Agent AI seperti tukang yang sangat pintar tapi literal — mengerjakan persis apa yang anda bilang, tidak lebih tidak kurang. Asumsi yang tidak dieksplisitkan akan diisi dengan tebakan model.

Struktur Prompt yang Baik

[Konteks]      — siapa anda, apa proyeknya, di mana posisi tugas ini
[Tugas]        — apa yang harus dikerjakan, dalam satu kalimat
[Detail]       — visual (UI), data, perilaku
[Batasan]      — apa yang HARUS atau TIDAK BOLEH
[Pengecualian] — kasus edge yang harus di-handle
[Output]       — format hasil (kode? penjelasan dulu? diff?)

Enam Teknik Utama

  1. Gambar layout dengan teks (ASCII art / wireframe markdown) — lebih efektif dari 10 kalimat penjelasan.
  2. Berikan contoh input-output — agent tahu persis apa yang diharapkan (one-shot / few-shot prompting).
  3. Sebutkan apa yang JANGAN dilakukan — mencegah agent “berkreasi” sendiri.
  4. Minta penjelasan sebelum kode — validasi pendekatan sebelum implementasi. “Jelaskan rencanamu, baru tulis kode setelah saya konfirmasi.”
  5. Pecah tugas besar — satu sub-tugas per instruksi, test dulu baru lanjut. Konteks pendek lebih akurat dari konteks panjang.
  6. Berikan persona — “Kamu adalah senior developer yang mengutamakan kesederhanaan dan menolak abstraksi prematur.”

Kesalahan Umum

Kesalahan Konsekuensi
Terlalu vague (“Buatkan halaman login”) Agent mengarang 90% detail
Terlalu panjang sekaligus Agent kehilangan fokus, melompat-lompat
Tidak ada batasan negatif Agent menambah fitur tidak diminta
Minta semuanya sekaligus Hasil berantakan, sulit di-review
Tidak menyediakan contoh struktur Agent memilih konvensi acak

Praktik Operasional

Simpan template prompt di docs/PROMPTS.md untuk setiap situasi rutin:

  • Mulai milestone baru
  • Perbaiki bug (dengan format bug report standar)
  • Minta penjelasan kode sebelum perubahan
  • Review kode existing
  • Handover ke sesi baru
  • Refactor request

Sumber Pendalaman

1.4 Evaluasi Output Agent

Konsep Inti

Evaluasi output agent adalah cara menilai apakah kode yang ditulis agent bisa dipercaya — tanpa anda harus bisa coding sendiri. Ini skill yang paling sering diabaikan pemula non-IT, padahal paling kritis.

Mindset

Anda adalah quality inspector, bukan tukang. Anda tidak perlu merakit mesin, tapi harus tahu cara mengecek apakah mesin terpasang benar.

Lima Layer Evaluasi

Layer Pertanyaan kunci
1. Functional Apakah jalan? Apakah fitur bekerja sesuai spesifikasi?
2. Completeness Apakah lengkap? Loading state, empty state, error handling, tombol back, validasi input?
3. Consistency Apakah konsisten dengan konvensi proyek (CONVENTIONS.md)?
4. Safety Apakah aman? Tidak ada password plaintext, input di-sanitize, authz checks ada?
5. Maintainability Apakah sustainable? Fungsi tidak terlalu panjang, penamaan jelas, tidak over-engineered?

Enam Teknik Praktis (Tanpa Coding)

  1. “Jelaskan kode kamu” — kalau penjelasan agent membingungkan, kode juga berantakan.
  2. “Tunjukkan kelemahannya” — paksa agent jujur tentang kelemahan kodenya sendiri.
  3. “Second opinion” — minta agent atau sesi lain me-review tanpa tahu konteks penulisan.
  4. “Simulasi skenario” — apa yang terjadi kalau data kosong? 10.000 record? Input aneh? Network putus?
  5. “Diff review” — minta agent tunjukkan hanya bagian yang berubah (sebelum → sesudah).
  6. “Apa yang terjadi kalau dihapus?” — kalau tidak ada yang rusak, itu dead code.

Tujuh Red Flags

  • Agent install library tidak diminta → tanya kenapa, tolak kalau tidak esensial.
  • Agent ubah arsitektur tanpa diminta → tolak, minta justifikasi terpisah.
  • Agent klaim “best practice” untuk membenarkan keputusan tanpa konteks → pertanyakan.
  • Kode yang tidak pernah dipakai (orphan function) → hapus.
  • Kode terlalu pintar / ringkas / clever → minta tulis ulang supaya jelas.
  • Banyak TODO / FIXME / // hack → selesaikan sekarang atau buat issue eksplisit.
  • Response terlalu cepat untuk tugas kompleks → curigai shortcut, minta self-review.

Review Tier untuk Kode AI-Generated

Klasifikasikan setiap kode yang di-generate agent:

Tier Treatment Contoh
Tier 1 Line-by-line, anda baca tiap baris Auth, RLS policy, money calculation, audit log, migration SQL, security endpoint
Tier 2 Sample review (acak beberapa file) UI component, non-sensitive API route, helper function
Tier 3 Automated saja (CI lulus = OK) Build pass, lint, test pass, format
Tier 4 External (freelancer / konsultan) Security audit setelah modul foundation, legal review untuk kalkulator regulatif, UX review setelah primary flow, DevOps audit pre-production

Sumber Pendalaman

1.5 Technical Writing untuk Agent & Manusia

Konsep Inti

Technical writing adalah kemampuan menulis dokumentasi teknis yang jelas — untuk agent (yang akan mengeksekusi instruksi anda), untuk developer lain, untuk customer, dan untuk diri sendiri di masa depan.

Kenapa Penting Dua Kali Lipat untuk Agentic Engineer

Dokumentasi yang buruk = prompt yang buruk = output yang buruk. Tidak seperti developer manusia yang bisa “merasakan” konvensi tidak tertulis, agent literal menerjemahkan apa yang anda tulis. Dokumentasi anda adalah spek yang dieksekusi.

Prinsip Utama

  • Know your audience — internal (teknis) vs end user (non-teknis) vs bisnis (value-focused). Tulisan yang sama tidak melayani ketiganya.
  • Structure before content — buat outline dulu, baru tulis.
  • One idea per sentence — kalimat pendek, paragraf pendek.
  • Show, don’t tell — screenshot, diagram, dan contoh kode lebih kuat dari deskripsi.
  • Use templates — konsistensi di semua dokumen mempermudah agent untuk consume.
  • Maintain and iterate — dokumen yang tidak diupdate lebih berbahaya dari tidak ada dokumentasi (memberi rasa aman palsu).

Aturan Praktis

  • Kalimat maksimal 20 kata.
  • Paragraf maksimal 3 kalimat.
  • Active voice: “Klik tombol Upload” bukan “Tombol Upload harus diklik.”
  • Tandai tempat screenshot dengan eksplisit: [SCREENSHOT: deskripsi posisi & isi].
  • Setiap kode block sertakan bahasa (bash, typescript, dst) — agent menggunakan ini untuk syntax-aware editing.

Tiga Jenis Dokumen Utama (Detail di Bagian 2.6)

  1. Spec doc (untuk agent) — apa yang dibangun, bagaimana, dengan batasan eksplisit.
  2. ADR (untuk anda + future agent) — keputusan arsitektur, alasannya, dan alternatif yang ditolak.
  3. User-facing doc (untuk end user) — bagaimana memakai produk. Lihat Bagian 7.6.

Sumber Pendalaman

BAGIAN 2 — PERENCANAAN (DOC-FIRST)

Fase paling menentukan. Perencanaan yang kacau = development yang kacau, tidak peduli sebagus apa eksekusi. Untuk proyek sederhana, alokasikan 2-4 jam untuk fase ini sebelum menulis kode pertama.

Prinsip pemandu: Doc-first, code-later. Spec dokumen di-lock sebelum implementasi. Agent menghasilkan kode terbaik ketika diberi spec yang jelas dan ringkas.

2.1 Discovery — Memahami Masalah

Konsep Inti

Discovery adalah memahami masalah sebelum memikirkan solusi. Pemula umumnya melewati ini dan langsung memikirkan fitur — hasilnya produk yang jawab pertanyaan yang tidak ada yang tanya.

Enam Artefak Discovery (Sequential)

# Artefak Durasi Output File
1 Problem Statement 15-30 menit PROJECT.md (section 1)
2 User Persona 15 menit PROJECT.md (section 2)
3 User Stories 30-60 menit PROJECT.md (section 3)
4 User Flow 30 menit PROJECT.md (section 4)
5 Wireframe (low-fi) 30-60 menit wireframes/*.md atau ASCII di PROJECT.md
6 Acceptance Criteria 15-30 menit terlampir di setiap user story

Template Problem Statement

Empat pertanyaan minimal:

  1. Untuk siapa? — segmentasi spesifik, bukan “semua orang”.
  2. Masalah apa? — keadaan saat ini yang menyakitkan + biaya dari masalah itu (waktu/uang/frustrasi).
  3. Ukuran sukses? — bagaimana anda tahu produk berhasil? Metrik konkret, bukan “users love it”.
  4. Batasan? — apa yang TIDAK akan anda lakukan? (Scope limit = sanity check.)

Template User Persona

  • Profil — siapa, umur kasar, peran
  • Kemampuan teknis — non-teknis / familiar / expert
  • Kebiasaan — bagaimana mereka kerja sekarang
  • Frustrasi — apa yang bikin mereka mengeluh
  • “Job to be done” — apa yang sebenarnya mereka coba selesaikan (bukan fitur yang mereka minta)

Template User Story

Format Connextra:

Sebagai [siapa],
Saya ingin [apa],
Supaya [manfaat / outcome].

Acceptance criteria:
- Given [konteks], when [aksi], then [hasil yang diharapkan]
- ...

Klasifikasikan setiap story:

  • Must Have (MVP) — produk tidak masuk akal tanpa ini
  • Nice to Have (v1) — penting tapi bisa rilis tanpa ini
  • Later (v2+) — masukan tapi jangan dikerjakan sekarang

User Flow

Gambarkan langkah-langkah pengguna dari membuka app sampai menyelesaikan tugas utama. Format paling efektif: flowchart Mermaid atau numbered list dengan branching.

Contoh:

1. Buka app → halaman login
2. Login berhasil → dashboard
3. Klik "New Project"
   → form (wajib: nama, deskripsi)
   → submit → halaman project (kosong)
4. Klik "Upload Document"
   → file picker
   → progress bar
   → success: dokumen muncul di list
   → error: pesan error + retry button

Wireframe Low-Fi

Tidak perlu Figma. ASCII / Markdown sketch sudah cukup di tahap ini:

+----------------------------------+
| LOGO         [Dashboard] [Profile]|
+----------------------------------+
| Heading                          |
|                                  |
| [Action Button] [Secondary Btn]  |
|                                  |
| --- Card --- | --- Card --- |    |
+----------------------------------+

Agent dapat membaca ini dan menghasilkan layout yang akurat. Pikirkan ini sebagai “prompt visual”.

Sumber Pendalaman

  • Marty Cagan — Inspired: How to Create Tech Products Customers Love (buku). Klasik product discovery.
  • Teresa Torres — Continuous Discovery Habits (buku, 2021). Framework opportunity solution tree.
  • Jeff Patton — User Story Mapping (buku, 2014). Cara memetakan story menjadi roadmap.
  • IDEO — Design Thinking methodology. Free toolkit. https://www.designkit.org
  • The Mom Test oleh Rob Fitzpatrick — cara wawancara user tanpa bias.

2.2 Architecture Decision — Memilih Bentuk Sistem

Konsep Inti

Keputusan arsitektur sulit diubah setelah kode ditulis. Luangkan waktu di awal untuk memetakan sistem sebelum membangunnya. Output utama: satu set diagram C4 + ADR + data flow.

C4 Model — Empat Level Zoom

C4 adalah cara mendokumentasikan arsitektur secara berlapis. Mulai dari big picture, zoom in step by step.

Level Nama Apa yang digambar
1 System Context Siapa/apa berinteraksi dengan sistem (user, external system). Sistem digambar sebagai 1 kotak.
2 Container Kotak-kotak besar dalam sistem (frontend, backend, database, queue, dst) + bagaimana mereka berkomunikasi
3 Component Isi dari setiap container (routes, services, clients)
4 Code Detail kode (kelas, modul). Biasanya tidak perlu digambar, IDE sudah cukup.

Untuk MVP, level 1 dan 2 wajib. Level 3 perlu kalau sistem mulai kompleks. Level 4 hampir tidak pernah perlu.

Data Flow Diagram (DFD)

Gambarkan bagaimana data mengalir melalui sistem — dari input user sampai data tersimpan/ditampilkan. Dari DFD, banyak keputusan teknis sudah bisa diambil sebelum coding:

  • Di mana data divalidasi?
  • Di mana data ditransformasi?
  • Di mana data di-encrypt?
  • Mana yang sinkron, mana yang asinkron (queue)?

Architecture Decision Record (ADR)

ADR adalah dokumen pendek (1-2 halaman) yang mencatat keputusan arsitektur dan kenapa.

Format wajib (Michael Nygard’s template):

# ADR-001: [Judul keputusan]

## Status
[Proposed / Accepted / Deprecated / Superseded by ADR-XXX]

## Context
[Situasi yang memerlukan keputusan. Constraints. Force.]

## Decision
[Apa yang diputuskan. Satu kalimat tegas.]

## Consequences
[Apa yang berubah setelah keputusan ini. Positif dan negatif.]

## Alternatives Rejected
[Opsi yang dipertimbangkan dan kenapa ditolak.]

ADR di-versioning: tidak diedit setelah Accepted. Kalau ada revisi, buat ADR baru yang Supersedes ADR lama.

Setiap proyek minimal punya ADR untuk:

  • Monolith vs microservice
  • Tech stack utama (framework, database, hosting)
  • Auth approach
  • Multi-tenancy model
  • Deployment strategy
  • Data retention policy

Non-Functional Requirements (NFR)

NFR adalah kebutuhan kualitas (bukan fitur). Definisikan target konkret:

Kategori Target contoh
Performance API response < 200ms p95, LLM streaming < 3s first token
Availability 99.5% uptime (=allowable downtime ~3.6 jam/bulan)
Scalability 1000 concurrent users, 100K records, 50GB/tahun growth
Security Auth required, data encrypted at rest, no plaintext password
Usability Bisa dipakai user non-teknis tanpa training
Compliance UU PDP, PSE Kominfo (kalau qualifies)

NFR yang tidak terukur = tidak ada NFR. “Cepat” tidak terukur. “p95 < 200ms” terukur.

Integration Contract

Untuk sistem dengan > 1 service: definisikan format request/response sebelum coding. Ini memungkinkan development paralel — frontend bisa mock backend, backend bisa mock LLM, dst.

Standar de facto: OpenAPI (Swagger) untuk REST API.

Sumber Pendalaman

2.3 Tech Stack Selection

Konsep Inti

Tech stack adalah pilihan teknologi yang anda pakai. Pilihannya banyak dan terus berubah. Sebagai pemula, kriteria utama bukan “terbaik” tapi “paling cocok untuk situasi spesifik anda”.

Analogi Rumah Makan

Komponen Padanan
Frontend Ruang makan — yang dilihat pengunjung
Backend Dapur — proses di balik layar
Database Gudang bahan — tempat simpan data
API Pelayan — penghubung frontend ↔ backend
Hosting Lokasi fisik rumah makan

Pilihan Utama di 2026 (Default Pemula)

Layer Pilihan default Kenapa
Frontend React + Tailwind CSS Paling banyak contoh; agent AI paling lancar dengan stack ini
Backend Node.js (Next.js/Express) atau tanpa backend (offline-first) Bahasa yang sama dengan frontend = konteks kognitif minimal
Database SQLite (offline / single user) atau PostgreSQL (multi-user) SQLite untuk simplicity, Postgres kalau butuh concurrent users / RLS
Platform Web app (paling sederhana) → Capacitor (web → mobile) → Electron (web → desktop) Mulai web, deploy ke platform lain dari codebase yang sama
Hosting Vercel/Netlify (web, free tier), Supabase (backend + DB free tier), VPS (kontrol penuh), mesin sendiri (on-prem) Pilih berdasar control vs convenience trade-off

Prinsip Memilih

  • Pilih yang populer, bukan “terbaik” — lebih banyak contoh, agent lebih lancar, lebih banyak Stack Overflow answer.
  • Mulai sesederhana mungkin — tambah kompleksitas hanya kalau dibutuhkan. Premature complexity = mahal.
  • Keputusan tech stack bisa diubah tapi mahal — luangkan waktu di awal. Migrasi DB / framework adalah berhari-hari kerja.
  • Tulis ADR untuk setiap keputusan stack — supaya 3 bulan ke depan anda (atau agent baru) tahu kenapa pilih X bukan Y.

Decision Checklist Lima Pertanyaan

Pertanyaan Jawaban memengaruhi
1. Siapa user? Berapa banyak? Multi-user → Postgres + Auth. Single user → SQLite.
2. Perlu offline? Ya → offline-first arsitektur (Bagian 6.5).
3. Platform target? Web saja? Mobile? Desktop? Mempengaruhi pilihan UI framework.
4. Jenis data? Structured → SQL. Tidak terstruktur (dokumen, gambar) → blob storage / vector DB.
5. Budget hosting? Free tier → Vercel + Supabase. Kontrol penuh → VPS. Data sensitif → on-prem.

Catatan Khusus Konteks Indonesia

Untuk produk yang menyimpan data pribadi atau sensitif user Indonesia:

  • Pertimbangkan hosting Indonesia (Biznet Gio, IDCloudHost, Indonesian Cloud) untuk mengurangi kompleksitas compliance UU PDP terkait data sovereignty.
  • Hosting cloud asing (AWS Singapore, Vercel) tetap legal tapi memerlukan dokumentasi cross-border data transfer di kebijakan privasi.
  • Lihat Bagian 5.5 untuk detail compliance.

Sumber Pendalaman

  • The Pragmatic Programmer oleh Hunt & Thomas (edisi ke-20). Bab “Pragmatic Approach” tentang trade-off teknologi.
  • ThoughtWorks Technology Radar — review semi-tahunan tentang teknologi yang adopt/trial/assess/hold. https://www.thoughtworks.com/radar
  • StackShare — perbandingan stack populer. https://stackshare.io
  • Choose Boring Technology oleh Dan McKinley (essay). https://boringtechnology.club
  • Designing Data-Intensive Applications (DDIA) oleh Martin Kleppmann (2017). Untuk pilihan database & storage yang lebih dalam.

2.4 Risk Planning — Apa yang Bisa Salah

Konsep Inti

Risk planning adalah memikirkan apa yang bisa gagal sebelum membangun. Lebih murah memperbaiki di kertas daripada di production.

Tiga sub-disiplin: Capacity Planning, Failure Mode Analysis, Security Threat Modeling.

2.4.1 Capacity Planning

Hitung apakah hardware dan budget cukup untuk target NFR:

Resource Item budget
CPU Berapa core dibutuhkan per service di peak?
RAM Berapa GB per service? Total vs tersedia?
GPU (kalau pakai local LLM) VRAM per model. Apakah cukup untuk semua model bersamaan?
Disk Storage data + log. Growth rate per bulan.
Network Bandwidth per request × concurrent.

Output: CAPACITY-PLAN.md dengan tabel resource budget vs available.

2.4.2 Failure Mode Analysis

Untuk setiap komponen sistem, tanyakan: kalau ini gagal, apa yang terjadi?

Format per failure mode:

| Failure Mode | Penyebab | Dampak | Cara Deteksi | Mitigasi | Milestone |
|---|---|---|---|---|---|
| LLM service down | OOM, container crash | User dapat error 500 | Health check failure | Auto-restart + fallback message | M3 |
| DB corruption | Disk failure | Data hilang | Backup verify mingguan | Restore from backup | M0 |
| ... | ... | ... | ... | ... | ... |

Setiap mitigasi dikaitkan ke milestone — supaya tidak terlewat saat build.

2.4.3 Security Threat Modeling (Plan Awal)

Threat modeling = identifikasi siapa yang mungkin menyerang dan bagaimana. Untuk planning awal, gunakan STRIDE framework:

Kategori Pertanyaan
Spoofing Bisakah seseorang menyamar sebagai user lain?
Tampering Bisakah data diubah tanpa otorisasi?
Repudiation Bisakah user menyangkal tindakannya? (Audit log!)
Information Disclosure Bisakah data sensitif bocor?
Denial of Service Bisakah sistem dibuat tidak tersedia?
Elevation of Privilege Bisakah user biasa dapat akses admin?

Untuk setiap kategori: identifikasi aset terancam, vektor serangan, mitigasi.

Threat actor yang umum untuk aplikasi web:

  • Pengguna jahat yang sudah login
  • Bot yang scan internet
  • Insider (developer / admin)
  • Supply chain attack (library jahat)
  • Prompt injection (untuk aplikasi LLM)

2.4.4 Dependency Policy

Aturan menambah library — supaya tidak menjadi sarang vulnerability:

  • Bisakah tanpa library? (Banyak kasus, jawabannya ya — built-in cukup.)
  • Library actively maintained? (Cek commit terakhir, contributor count, issues activity.)
  • Populer? (npm download / week, GitHub stars.)
  • Berapa sub-dependency? (Library dengan 200 sub-deps = 200 attack surface.)
  • Known vulnerability? (npm audit, Snyk.)
  • License compatible dengan bisnis anda? (GPL → tidak untuk produk proprietary.)

Maintain docs/DEPENDENCY-POLICY.md dengan list approved & rejected.

Sumber Pendalaman

2.5 UX/UI & Accessibility — Plan Awal

Konsep Inti

UX/UI dan accessibility (a11y) harus masuk di tahap perencanaan, bukan diretrofit di akhir. Retrofit a11y untuk sistem yang sudah jadi adalah salah satu kerja paling thankless di software.

Sepuluh Prinsip UX Inti

# Prinsip Penjelasan singkat
1 Don’t Make Me Think Setiap halaman harus jelas tanpa penjelasan
2 Hierarki Visual Yang paling penting = paling menonjol
3 Feedback di setiap aksi User selalu tahu apa yang terjadi
4 Konsistensi Hal yang sama terlihat dan berperilaku sama di seluruh app
5 Prevent Errors Cegah error (validasi, disable button), bukan tampilkan pesan error
6 Progressive Disclosure Tunjukkan yang penting dulu, detail nanti (expandable, tab, modal)
7 Accessibility Bisa dipakai semua orang (kontras, ukuran, keyboard, screen reader)
8 Loading & Empty States Dua kondisi yang paling sering dilupakan; spec eksplisit per layar
9 Forgiving Interface Mudahkan user memperbaiki kesalahan (undo, draft, edit, konfirmasi destructive)
10 Performance = UX App lambat = UX buruk, terlepas dari design

Target Waktu Respons

Latency Persepsi user Tindakan
< 100ms Terasa instan Target untuk klik tombol, navigasi
100-300ms Terasa cepat Target untuk filter, search
> 1s Mulai terasa lambat Tampilkan visual feedback
> 3s Wajib ada loading indicator Spinner, progress bar, skeleton
> 10s User mungkin pergi Background job + notification
LLM (5-30s) Konteks khusus Streaming wajib — token per token

Accessibility (a11y) Baseline

Level minimum untuk semua proyek (WCAG 2.2 Level AA sebagai target):

  • Semua gambar punya alt text.
  • Semua form input punya <label>.
  • Kontras warna minimal 4.5:1 untuk teks normal, 3:1 untuk teks besar.
  • Navigasi keyboard berfungsi (Tab, Enter, Escape, arrow keys di mana relevan).
  • Tidak mengandalkan warna saja untuk konvey informasi (error merah + ikon + teks).
  • Focus indicator terlihat (jangan outline: none tanpa pengganti).

Implementasi Praktis

  • Semantic HTML — <button> bukan <div onclick>. Screen reader otomatis baca correctly.
  • ARIA labels untuk tombol icon-only (aria-label="Tutup").
  • Focus management — saat modal dibuka, focus ke modal; saat ditutup, kembalikan focus.
  • Responsive text — gunakan unit rem/em, bukan px. User bisa scale browser.
  • Test dengan keyboard saja — bisa selesaikan task tanpa mouse?

Sumber Pendalaman

  • Steve Krug — Don’t Make Me Think (buku, edisi ke-3, 2014). Klasik UX, sangat praktis.
  • Don Norman — The Design of Everyday Things (buku, edisi 2013). Foundation prinsip desain.
  • Nielsen Norman Group — banyak free article. https://www.nngroup.com
  • W3C — Web Content Accessibility Guidelines (WCAG) 2.2. https://www.w3.org/TR/WCAG22/
  • WebAIM — contrast checker + practical a11y guide. https://webaim.org
  • Refactoring UI oleh Adam Wathan & Steve Schoger (buku). Tactical visual design tips.
  • A11y Project — checklist praktis. https://www.a11yproject.com

2.6 Spec Document Suite — Output Akhir Perencanaan

Konsep Inti

Output dari fase perencanaan bukan kode — tapi set dokumen yang siap di-consume oleh agent untuk implementasi.

Struktur Folder docs/ untuk Proyek MVP

Struktur minimal yang direkomendasikan (detail lengkap di Appendix A):

docs/
├── PROJECT.md              # problem, persona, stories, flow
├── ARCHITECTURE.md         # C4 diagrams, tech stack, container map
├── DATA-FLOW.md            # alur data
├── DATA-MODEL.md           # skema database
├── NFR.md                  # non-functional requirements
├── DECISIONS.md            # ADR (atau folder docs/adr/)
├── INTEGRATION-CONTRACTS.md # API contract
├── CAPACITY-PLAN.md        # resource budget
├── FAILURE-MODES.md        # analisis kegagalan
├── SECURITY.md             # threat model
├── DEPENDENCY-POLICY.md    # aturan pilih library
├── MILESTONES.md           # breakdown milestone
├── MAP.md                  # peta kode (struktur folder rencana)
├── CONVENTIONS.md          # aturan penulisan kode
├── CONTEXT.md              # status proyek (update terus)
├── PROMPTS.md              # template prompt harian
├── HANDOVER.md             # template prompt handover
└── REVIEW-CHECKLIST.md     # checklist evaluasi per milestone

Tambahan saat build berjalan: ISSUES.md, CHANGELOG.md, GOTCHAS.md. Detail di Bagian 4.

Hierarki Dependency Antar Dokumen

PROJECT.md (problem, persona, stories)
    ↓
ARCHITECTURE.md (C4, tech stack) ← DECISIONS.md (ADR)
    ↓
DATA-FLOW.md → DATA-MODEL.md → INTEGRATION-CONTRACTS.md
    ↓
NFR.md → CAPACITY-PLAN.md → FAILURE-MODES.md → SECURITY.md
    ↓
MILESTONES.md (membawa semua di atas ke breakdown task)
    ↓
MAP.md + CONVENTIONS.md (siap untuk implementasi)

Milestone Breakdown

Pecah fitur menjadi milestone kecil yang bisa di-test sendiri. Aturan emas:

  • Atomic vertical slice — 1 milestone = 1 fitur end-to-end (UI + API + DB), bukan 1 layer.
  • Maksimal 2-5 hari kerja per milestone.
  • Selalu ada kriteria selesai yang testable (acceptance criteria dari user story).
  • Setiap milestone punya integration test di akhir.

Aturan Edit Dokumen

  • ADR yang sudah Accepted tidak diedit. Kalau revisi, buat ADR baru yang Supersedes ADR lama.
  • PROJECT.md boleh diedit, tapi changes besar masuk Change Log section.
  • CONTEXT.md di-update setiap sesi (status proyek saat ini).
  • CHANGELOG.md di-update setiap milestone selesai.

Sumber Pendalaman

BAGIAN 3 — SETUP FOUNDATION

Fase ini terjadi sebelum anda menulis kode fitur. Tujuan: membangun fondasi teknis yang membuat semua build berikutnya lebih cepat, lebih aman, dan lebih mudah di-debug.

Era timeline: hari 4-5 dari proyek (setelah hari 1-3 perencanaan).

3.1 Version Control (Git & GitHub)

Konsep Inti

Version control adalah sistem yang mencatat setiap perubahan kode. Tanpa ini, eksperimen agent yang gagal akan menghancurkan kerja anda. Dengan ini, anda punya safety net total — apapun yang rusak bisa dikembalikan.

Setup Awal

  1. Buat akun GitHub (gratis, private repo unlimited untuk akun pribadi).
  2. Setup SSH key untuk autentikasi (lebih aman dari password).
  3. Buat repo private (default untuk semua proyek pribadi).
  4. Hubungkan proyek lokal: git init → git remote add origin [email protected]:user/repo.git → push.

Alur Harian

Aksi Kapan
git checkout -b milestone-3-dashboard Mulai milestone baru — branch terpisah, jangan kerja di main langsung
git add . && git commit -m "M3: dashboard layout dengan ringkasan harian" Setiap sub-tugas selesai. Pesan deskriptif (prefix milestone + scope)
git push origin milestone-3-dashboard Setelah commit (backup ke remote, juga supaya agent lain bisa pull)
git checkout main && git merge milestone-3-dashboard Setelah milestone selesai dan ditest
git tag -a v1.2.0 -m "Dashboard release" Setelah merge ke main, untuk milestone besar

Git sebagai Safety Net

Perintah Kegunaan
git diff Lihat apa yang berubah sejak last commit
git status Lihat file mana yang ter-modify / staged / untracked
git checkout . Batalkan SEMUA perubahan yang belum committed
git restore <file> Batalkan perubahan satu file
git reset --hard <commit-hash> Kembali ke commit tertentu (DESTRUCTIVE — data hilang)
git reflog Lihat history semua HEAD movement (recovery dari git reset)
git branch <eksperimen> Coba sesuatu di branch terpisah, buang kalau jelek

Kalau agent kacaukan kode dan anda tidak yakin apa yang berubah: git diff untuk lihat semua, lalu git checkout . untuk reset semua kalau perlu.

.gitignore Essentials

File yang TIDAK boleh masuk repo:

# Dependencies (di-restore dari package.json)
node_modules/
vendor/

# Build output
dist/
build/
.next/
out/

# Environment & secrets
.env
.env.local
.env.*.local
*.pem
*.key

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

# Logs
logs/
*.log
npm-debug.log*

# Database (kecuali schema/migration)
*.db
*.sqlite
*.sqlite-journal

# DDS data (lihat 3.4)
dds/data/

File yang HARUS masuk: docs/, src/, package.json, package-lock.json, tsconfig.json, .gitignore, README.md, migration files, schema definition.

Aturan Hard

  • Jangan commit secret (API key, password, token). Pakai .env (di-gitignore) atau secret manager.
  • Jangan commit node_modules/ — restore dengan npm install dari package-lock.json.
  • Jangan force push ke main — itu menghancurkan history bersama. Force push hanya di branch pribadi.
  • Setiap merge ke main minimal lulus CI (lihat 3.6).

Sumber Pendalaman

3.2 Project Structure & Conventions

Konsep Inti

Struktur folder dan konvensi penamaan adalah kontrak implisit yang agent ikuti. Tanpa ini, agent akan invent struktur sendiri yang berbeda dari sesi ke sesi.

Dokumen Wajib

MAP.md — Peta Kode

Berisi:

  • Struktur folder dengan deskripsi per folder
  • File kunci yang penting untuk dipahami (entry point, config, schema)
  • Pola arsitektur yang dipakai (misal: “kita pakai route handler per resource, service layer untuk business logic”)

Contoh format:

# MAP.md

## Struktur Folder
src/
├── app/              # Next.js App Router pages
├── components/       # React components (atomic design: ui/, blocks/, forms/)
├── lib/              # Pure utility functions, no side effects
├── server/           # Server-only code (DB queries, auth, integrations)
│   ├── db/           # Drizzle schema + queries
│   ├── auth/         # Auth helpers (Better Auth)
│   └── trpc/         # tRPC routers
└── types/            # Shared TypeScript types

## File Kunci
- src/server/db/schema.ts — single source of truth schema database
- src/server/trpc/root.ts — root tRPC router
- src/lib/env.ts — environment variable validation (Zod)

CONVENTIONS.md — Aturan Penulisan

Berisi:

  • Penamaan (file, function, variable, constant)
  • Pola kode yang disukai/dilarang
  • Komentar (kapan ya, kapan tidak)
  • Error handling pattern
  • Test naming

Contoh:

# CONVENTIONS.md

## Penamaan
- File component: PascalCase (`UserCard.tsx`)
- File utility: kebab-case (`format-currency.ts`)
- Function: camelCase (`formatCurrency`)
- Constant: SCREAMING_SNAKE_CASE (`MAX_RETRIES`)

## Pola yang DIWAJIBKAN
- Money sebagai bigint sen + currency code. Tidak pernah float.
- Timestamp di DB sebagai timestamptz. JS sisi pakai Temporal kalau available.
- Setiap mutation tRPC: validasi input dengan Zod.
- Setiap error operasional: pakai custom Error class dengan code (bukan throw string).

## Pola yang DILARANG
- Tidak boleh ada `any` di TypeScript (kecuali third-party tanpa type).
- Tidak boleh hardcode string yang user-facing (i18n).
- Tidak boleh akses DB langsung dari komponen UI (lewat tRPC).
- Tidak boleh `// @ts-ignore` tanpa komentar penjelasan.

CONVENTIONS.md ada di context agent setiap sesi. Ini adalah cara paling efektif memastikan konsistensi.

Sumber Pendalaman

  • Clean Code oleh Robert C. Martin (buku, 2008). Klasik penamaan dan struktur. Note: beberapa rekomendasi kontroversial — ambil yang sesuai konteks.
  • A Philosophy of Software Design oleh John Ousterhout (buku, 2018). Counter-perspective ke Clean Code, lebih praktis.
  • Google Style Guides — per bahasa. https://google.github.io/styleguide/
  • Airbnb JavaScript Style Guide. https://github.com/airbnb/javascript

3.3 Development Environment Specification

Konsep Inti

DEV-ENVIRONMENT.md adalah dokumen yang menjelaskan cara setup proyek dari nol (mesin baru, OS bersih). Tujuan: anda atau agent baru bisa siap dalam < 30 menit.

Komponen Wajib

  1. Prerequisites — versi OS, runtime (Node, Python), tools (Docker, git).
  2. Langkah install — perintah persis, copy-paste able.
  3. Environment variables — daftar .env keys dengan deskripsi (jangan share values di repo).
  4. Port map — service mana di port berapa, supaya tidak konflik.
  5. Perintah sehari-hari — npm run dev, npm run test, docker compose up, dst.
  6. Cara verify — bagaimana tahu setup berhasil (URL untuk dicek, perintah health check).

Contoh Struktur

# DEV-ENVIRONMENT.md

## Prerequisites
- Node.js 22 LTS (cek: `node --version`)
- pnpm 9+ (install: `npm install -g pnpm`)
- PostgreSQL 18 (atau Docker)
- Git

## Setup dari Nol
1. Clone repo: `git clone [email protected]:user/repo.git`
2. Install deps: `pnpm install`
3. Copy env: `cp .env.example .env` dan isi sesuai docs
4. Setup DB: `docker compose up -d postgres` (atau install Postgres native)
5. Migrate: `pnpm db:migrate`
6. Seed (opsional): `pnpm db:seed`
7. Start dev: `pnpm dev`
8. Verify: buka http://localhost:3000

## Port Map
| Port | Service |
|---|---|
| 3000 | Next.js app |
| 5432 | PostgreSQL |
| 6379 | Redis (cache) |
| 9900 | DDS dashboard |

## Perintah Harian
- `pnpm dev` — start app
- `pnpm test` — jalankan tests
- `pnpm lint` — lint check
- `pnpm db:studio` — Drizzle Studio (DB UI)

Sumber Pendalaman

3.4 Development Debug System (DDS)

Konsep Inti

DDS adalah aplikasi terpisah yang tugasnya menangkap semua error, log, dan event dari app utama selama development. Dibuang saat rilis production.

Tujuan: ketika agent debug masalah, anda bisa kasih bug report yang lengkap dan terformat — bukan screenshot kabur atau “error-nya nggak jelas”.

Kenapa Aplikasi Terpisah?

  • Tidak mencemari kode produksi (zero dependency tambahan di app utama).
  • Tidak mempengaruhi performa produksi (cabut di build production).
  • Bisa di-restart independen tanpa restart app utama.
  • Bisa diakses dari device lain (kalau testing mobile).

Arsitektur

Komponen Lokasi Tugas
DDS Server Folder dds/ (project terpisah) Node.js + Express + SQLite + HTML dashboard. Port 9900. Terima log dari client, simpan ke DB, tampilkan dashboard.
DDS Client File tunggal src/debug/dds-client.ts di app utama Kirim log ke DDS server via HTTP. Conditional load (dev only).

Apa yang Ditangkap DDS

  • Error & crash — stack trace lengkap, browser/OS info, timestamp
  • User action trail — setiap klik, navigasi, form submit (untuk konteks sebelum error)
  • Performance metrics — load time, API latency, render time
  • State snapshots — state aplikasi saat error (Redux/Zustand store)
  • Code change tracking — kapan hot reload terjadi, file mana yang berubah

Fitur Dashboard Kunci

Fitur Kegunaan
Live feed Semua event real-time, scroll otomatis
Timeline Kronologi visual events
Error detail view Stack trace + user trail 30 detik sebelumnya + state
“Copy for Agent” Satu tombol → bug report terformat rapi, siap paste ke agent
Alert Bunyi saat error, tab title berubah jadi (!) App, recurring error detection
Export Session report (Markdown), full JSON dump
Filter By severity, by component, by time range

“Copy for Agent” — Fitur Paling Berharga

Tombol ini menghasilkan output seperti:

## Bug Report

**Time**: 2026-05-24 14:32:18 WIB
**URL**: http://localhost:3000/dashboard/projects/42
**Browser**: Chrome 120, macOS 14.2

### Error
TypeError: Cannot read property 'name' of undefined
  at ProjectCard (src/components/ProjectCard.tsx:23:18)

### User Trail (last 30s)
- 14:31:48 — Navigation: /dashboard → /dashboard/projects
- 14:31:52 — Click: "Filter by status"
- 14:31:55 — Select: "Archived"
- 14:32:18 — Render error in ProjectCard

### State Snapshot
{
  "filterStatus": "archived",
  "projects": [
    { "id": 1, "name": "Foo" },
    { "id": 2 }  // ← missing name
  ]
}

Anda paste ini ke agent. Agent langsung tahu konteks dan bisa identify root cause cepat.

Cara Cabut Saat Rilis

Pakai conditional import di app utama:

// src/main.tsx atau equivalent
if (process.env.NODE_ENV !== 'production') {
  import('./debug/dds-client').then(({ initDDS }) => initDDS());
}

Saat build production (NODE_ENV=production), bundler (Vite/Webpack) otomatis tree-shake import yang tidak terpakai. DDS tidak ikut ke production bundle.

Dampak ke Arsitektur App Utama

Yang bertambah:

  • 1 folder (dds/)
  • 1 file di app utama (src/debug/dds-client.ts)
  • 1 baris import conditional
  • Setengah hari untuk setup awal

Yang tidak berubah:

  • Tech stack app utama (DDS bisa pakai stack berbeda)
  • Dependency app utama (DDS punya package.json sendiri)
  • Production build (DDS tidak ada di sana)
  • Performa produksi (zero overhead)
  • Performa development (~< 5ms overhead per event, async fire-and-forget)

Pertimbangan Implementasi

  • Dua package.json terpisah (app utama + DDS).
  • Dua database terpisah — data aplikasi di DB utama, log DDS di SQLite-nya sendiri.
  • Mobile testing — DDS harus accessible dari HP. Solusi: device di WiFi yang sama, atau via Tailscale untuk akses lintas jaringan.
  • Storage — DDS SQLite bisa membengkak. Setting auto-cleanup setelah N hari.

Sumber Pendalaman

  • Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Software and Hardware Problems oleh David J. Agans (buku, 2002). Foundation debugging mindset.
  • Sentry, LogRocket, Bugsnag — produk komersial dengan filosofi mirip. Bisa dipakai langsung kalau tidak mau build DDS sendiri (tapi tradeoff: data ke pihak ketiga, biaya bulanan).
  • OpenTelemetry — standar open source untuk observability. Bisa dipakai untuk DDS production-grade. https://opentelemetry.io
  • Charity Majors — Observability Engineering (buku, 2022). Filosofi observability sebagai disiplin.

3.5 In-App Debug Layers

Konsep Inti

DDS (3.4) menangkap log secara sistemik. Tapi user (atau anda saat testing) juga butuh layer di dalam app sendiri untuk lihat error langsung dan kirim laporan.

Tiga lapis di dalam app utama:

Lapis 1: Error Boundary (Crash UI)

Tangkap crash framework UI (React error boundary, Vue errorCaptured, dst). Saat crash:

  • Tampilkan halaman fallback yang ramah (“Oops, sesuatu salah. Tim sedang dihubungi.”)
  • Tombol “Copy error details” — copy bug report ke clipboard
  • Tombol “Kembali ke beranda”
  • Otomatis kirim ke DDS

Lapis 2: Error Toast (Operasional)

Tangkap error operasional (network failed, validation error, dst). Tampilkan:

  • Banner merah ringkas: “Gagal menyimpan. Periksa koneksi internet.”
  • Tombol expand untuk detail (stack trace, response body)
  • Tombol “Copy” untuk paste ke support / agent

Lapis 3: Debug Panel (Hidden)

Panel tersembunyi yang dibuka dengan trigger khusus:

  • Web: Konami code, atau klik logo 5x cepat
  • Mobile: shake device 3x, atau tap logo 5x
  • Dev mode: selalu visible

Isi panel:

  • Action log (30 aksi terakhir)
  • Error log (10 error terakhir)
  • State snapshot (current state)
  • Device info (user agent, screen size, memory, network type)
  • Tombol “Export all” → file JSON
  • Tombol “Send to support”

Backend Logging

Untuk server-side:

  • Log file harian di logs/YYYY-MM-DD.log
  • Level: ERROR / WARN / INFO / DEBUG
  • Format structured (JSON) — bukan plain text. Memudahkan parsing.
  • Endpoint API untuk baca log dari frontend (auth-protected!), supaya bisa correlate frontend error dengan server log.

Aturan Logging

Yang BOLEH di-log Yang TIDAK BOLEH di-log
User ID (numeric) Password (apapun)
Endpoint yang diakses Token / API key
Status code PII tanpa hashing (email, KTP, no HP)
Latency Body request yang mengandung sensitive
Error message Authorization header

Sumber Pendalaman

3.6 CI/CD Pipeline

Konsep Inti

CI/CD (Continuous Integration / Continuous Deployment) adalah otomasi yang jalan setiap anda push kode: test → audit → build → deploy. Tidak pernah lupa, tidak pernah skip.

Tanpa CI/CD, anda manual setiap kali. Manual berarti lupa. Lupa berarti bug masuk production.

Tiga Workflow Esensial

Workflow 1: CI (setiap push & PR)

Tujuan: pastikan kode yang akan di-merge tidak rusak.

Langkah berurutan:

  1. Install dependencies — pnpm install --frozen-lockfile
  2. Lint — pnpm lint (kode style consistent)
  3. Type check — pnpm typecheck (TypeScript strict)
  4. Unit tests — pnpm test
  5. Security audit — pnpm audit --audit-level=high (atau Snyk)
  6. Build — pnpm build (pastikan build sukses)

Kalau hijau semua = aman merge. Kalau merah = tidak boleh merge ke main.

Workflow 2: CD (merge ke main)

Tujuan: build artifact final dan deploy.

Langkah:

  1. Build Docker image (kalau pakai container)
  2. Push image ke registry (GitHub Container Registry / Docker Hub)
  3. Deploy — manual approval untuk production, atau otomatis ke staging
  4. Smoke test post-deploy
  5. Notifikasi (Slack / Telegram)

Aturan: tidak ada auto-deploy ke production tanpa manual approval. Itu undangan disaster.

Workflow 3: Scheduled (mingguan)

Tujuan: temukan masalah yang muncul dari luar (dependency vulnerability baru).

Langkah:

  1. Run pnpm audit
  2. Run Snyk / Dependabot scan
  3. Kalau ada HIGH/CRITICAL → buat GitHub Issue otomatis dengan label security
  4. Notifikasi anda

Dampak ke Workflow

Sebelum CI/CD: anda manual test → manual audit → manual build → lupa langkah → bug masuk → kacau.

Sesudah CI/CD: git push → otomatis semua → lihat status CI (hijau atau merah) → kirim log ke agent kalau merah → fix → push lagi.

Tools

  • GitHub Actions (rekomendasi default) — gratis untuk public repo, 2000 menit/bulan gratis untuk private. Sintaks YAML.
  • GitLab CI — kalau pakai GitLab.
  • CircleCI / Travis — alternatif komersial.

Contoh Struktur File

.github/
└── workflows/
    ├── ci.yml          # CI workflow
    ├── deploy.yml      # CD workflow
    └── audit.yml       # Scheduled audit

Sumber Pendalaman

  • Continuous Delivery oleh Jez Humble & David Farley (buku, 2010). Bible CD. Konseptual + praktis.
  • GitHub — Quickstart for GitHub Actions. https://docs.github.com/en/actions/quickstart
  • The DevOps Handbook oleh Gene Kim et al. (buku, 2016). Konteks lebih luas DevOps culture.
  • Bret Fisher — Docker for Beginners and Beyond (course). Untuk CI/CD yang melibatkan Docker.
  • Snyk — Open Source Security Education. https://learn.snyk.io

3.7 Decision Discipline

Konsep Inti

Selama proyek berjalan, anda akan mengambil ratusan keputusan. Tanpa disiplin, keputusan lama akan terlupa atau di-revisit terus-menerus, menghabiskan energi.

Tiga kategori keputusan:

Kategori Definisi Aturan
Locked Sudah final, fundamental. Tidak di-revisit tanpa explicit reason.
Pending Belum diputuskan. Wajib tercatat dengan owner + deadline.
Obsolete Pernah diputuskan, sudah di-revisi. Tidak dihapus, dicatat di Change Log.

Praktik Operasional

Locked Decision

Catat di DECISIONS.md (atau folder docs/adr/):

## D-001: Stack frontend = Next.js 16 + tRPC + Drizzle

**Status**: Locked (2026-03-15)
**Context**: Butuh stack yang agent paling lancar, ada server component, type-safe end-to-end.
**Decision**: Next.js 16 LTS + tRPC v11 + Drizzle 0.45.x.
**Consequences**: Vercel / Node.js hosting; bukan PHP/Python; React knowledge required.
**Alternatives rejected**: Remix (lebih kecil ecosystem), Astro (tidak cocok app heavy interaktif), SvelteKit (agent kurang lancar).

Saat anda goyah / agent menyarankan ubah → tunjuk ke locked decision, minta justifikasi explicit revisit.

Pending Decision

Catat di handoff doc atau bagian khusus di DECISIONS.md:

## P-001: Auth strategy untuk multi-tenant

**Status**: Pending
**Owner**: Ziffany
**Deadline**: 2026-05-31
**Context**: Better Auth vs WorkOS. Better Auth lebih murah, WorkOS enterprise-ready.
**Options considered**: ...
**Next step**: Decide setelah validasi 3 calon enterprise customer.

Obsolete Decision

Saat keputusan lama digantikan, jangan hapus. Pindahkan ke Change Log section di DECISIONS.md:

## Change Log

### 2026-04-20: D-005 superseded by D-012
- D-005 (deprecated): pakai Tailwind v3.
- D-012 (active): migrasi ke Tailwind v4.
- Alasan: CSS-first config lebih sesuai dengan Next.js 16 RSC pattern.

Kenapa Ini Penting untuk Agentic Engineer

Agent tidak ingat sesi sebelumnya. Setiap sesi baru, agent akan re-evaluate keputusan dari nol kalau tidak ada dokumen. Tanpa decision discipline:

  • Sesi 1: anda + agent diskusi pilih X.
  • Sesi 5: agent baru saran ganti ke Y (tidak tahu kenapa X dipilih).
  • Anda terbujuk. Migrasi.
  • Sesi 10: agent lain saran kembali ke X.
  • Anda lelah.

Solusi: setiap locked decision di DECISIONS.md, baca tiap sesi handover.

Sumber Pendalaman

  • Michael Nygard — ADR format asli (sudah disebut di 2.2).
  • The Decision Book oleh Mikael Krogerus & Roman Tschäppeler (buku). 50 model decision-making singkat.
  • Annie Duke — Thinking in Bets (buku, 2018). Decision-making di bawah ketidakpastian.

BAGIAN 4 — BUILD LOOP PER MILESTONE

Fase di mana fitur dibangun, milestone demi milestone. Ritme yang konsisten lebih penting dari kecepatan.

4.1 Empat Era Proyek

Visualisasi proyek dari nol sampai live:

Era Hari (estimasi) Output
1. Perencanaan Hari 1-3 Folder docs/ lengkap (Bagian 2)
2. Fondasi Hari 4-5 Repo + setup + DDS + CI/CD (Bagian 3)
3. Pembangunan Hari 6-20+ Siklus berulang per milestone (Bagian 4)
4. Penyelesaian Hari 21-25+ Polish, security final, deploy, monitoring live (Bagian 5, 7)

Estimasi di atas untuk proyek MVP sederhana solo developer. Untuk proyek lebih kompleks, kalikan 2-4x.

Era Pembangunan (Hari 6-20+) Berisi

Per sub-tugas (~1-3 jam):

  1. Briefing → 2. Agent kerjakan → 3. Test → 4. Feedback loop → 5. Commit

Per milestone wrap-up (akhir milestone):

  1. Integration test → 2. Update docs (CONTEXT.md, CHANGELOG.md, MAP.md) → 3. Merge ke main

4.2 Daily Cycle per Milestone

Anatomi Siklus Satu Sub-Tugas

Fase Durasi Aktivitas
1. Briefing 5 menit Buka CONTEXT.md + spec milestone. Tulis prompt ke agent dengan konteks + tugas + batasan.
2. Agent kerjakan 15-30 menit Agent baca, mungkin tanya, lalu eksekusi. Anda tidak intervensi terlalu cepat — biarkan completion.
3. Testing 15-30 menit Happy path → input aneh → edge case → checklist. Catat issue kalau ada.
4. Feedback loop 15-30 menit (2-5 iterasi) Format bug report (dari DDS atau manual), kirim ke agent, agent perbaiki, test lagi.
5. Wrap-up 10 menit Integration test cepat, update docs kecil, commit dengan pesan deskriptif.

Total per sub-tugas: 1-3 jam. Untuk solo dev, target 1-2 sub-tugas per sesi.

Aturan Iterasi

  • 2-5 iterasi per fitur itu NORMAL. Pemula sering frustrasi kalau iterasi pertama tidak sempurna. Mindset: ini bagian dari proses, bukan kegagalan.
  • Kalau > 5 iterasi tanpa progres → STOP. Spec kurang jelas, atau pendekatan agent salah. Mundur, perjelas spec, atau coba pendekatan lain.
  • Kalau agent stuck → tanya alternatif. “Coba pendekatan berbeda” sering bekerja.

Ritual Harian (Solo Dev)

Saat duduk untuk sesi:

  1. Buka CONTEXT.md & ISSUES.md (refresh konteks)
  2. Tentukan target hari ini (1-2 sub-tugas konkret)
  3. Mulai siklus
  4. Akhir sesi: update CONTEXT.md, commit semua
  5. Total ~1-3 jam per sesi

Aturan: jangan multitask antar milestone dalam satu sesi. Konteks switching mahal.

4.3 Issue Tracking System

Konsep Inti

Tracking masalah secara konsisten = anda tidak lupa apa yang harus dikerjakan + agent baru tahu konteks issue terbuka.

Tiga Dokumen Tracking

ISSUES.md — Issue Log

Format standar per bug / feature request:

## ISSUE-042

**Status**: Open / In Progress / Done / Won't Fix
**Tipe**: Bug / Feature / Tech Debt / Refactor
**Prioritas**: P0 (urgent) / P1 (high) / P2 (medium) / P3 (low)
**Milestone**: M3 — Dashboard
**Reported**: 2026-05-20

### Deskripsi
Tombol "Save" tidak respon kalau diklik dua kali cepat.

### Langkah Reproduksi
1. Buka /projects/new
2. Isi form
3. Klik Save 2x dalam < 500ms
4. Form submit dua kali, dua duplicate records

### Expected vs Actual
Expected: 1 record dibuat, tombol disabled setelah klik pertama.
Actual: 2 records dibuat.

### Solusi (diisi saat resolve)
Disable button on submit + debounce 500ms.

### Catatan
Lihat juga ISSUE-038 (debounce pattern di form lain).

DECISIONS.md — Decision Log

Sudah dijelaskan di 3.7. Update tiap kali ada keputusan teknis.

CHANGELOG.md — Riwayat Perubahan per Milestone

Format Keep a Changelog:

# CHANGELOG

## [Unreleased]

### Added
- Dashboard ringkasan harian

### Changed
- Layout halaman project pakai grid

### Fixed
- ISSUE-042: double submit pada form
- ISSUE-038: debounce pattern di FormText

## [v1.2.0] — 2026-05-15

### Added
...

Test Checklist per Milestone

Setiap milestone punya checklist konkret:

## M3 — Dashboard Test Checklist

### Fungsional
- [ ] Buka dashboard sebagai user baru → empty state muncul
- [ ] Buka dashboard dengan data → cards muncul
- [ ] Klik card → navigate ke detail

### Validasi
- [ ] Form filter: input invalid → error message
- [ ] Date range invalid → error message

### Edge Case
- [ ] 0 data
- [ ] 1 data
- [ ] 1000 data (loading time?)
- [ ] Offline → fallback message

### Visual
- [ ] Mobile (375px)
- [ ] Tablet (768px)
- [ ] Desktop (1440px)

### A11y
- [ ] Keyboard navigation works
- [ ] Screen reader announces correct content
- [ ] Contrast > 4.5:1

Milestone tidak boleh ditutup sebelum semua checklist ✅.

Aturan Konsistensi

  • Sebelum mulai sesi → baca ISSUES.md.
  • Setelah setiap sub-tugas → update issues (status berubah, atau tambah issue baru).
  • Sebelum milestone selesai → jalankan seluruh test checklist.

Sumber Pendalaman

  • Keep a Changelog format. https://keepachangelog.com
  • Conventional Commits — format pesan commit yang machine-parsable. https://www.conventionalcommits.org
  • GitHub Issues / Linear / Plane — alternatif kalau anda tidak mau pakai file Markdown. Tapi ISSUES.md punya kelebihan: dalam repo, mudah di-grep oleh agent.

4.4 Handover Antar Session / Agent

Konsep Inti

Agent tidak punya memori antar sesi. Setiap sesi baru = halaman kosong. Semua konteks harus di file, bukan di “ingatan” agent.

Dokumen Wajib untuk Handover

Dokumen Isi
CONTEXT.md Status proyek saat ini — milestone aktif, progress %, blocker, hal penting yang harus diketahui agent baru
DECISIONS.md / ADR Keputusan arsitektur, alasan, alternatif yang ditolak. Termasuk section “JANGAN pernah” untuk mencegah agent baru mengulang debat
MAP.md Peta kode, file kunci, pola
CONVENTIONS.md Aturan penulisan, larangan
GOTCHAS.md Hal aneh yang ditemukan selama development (misal: “Library X tidak support feature Y di Safari, kita pakai workaround Z”)
HANDOVER.md Template prompt yang tinggal copy-paste saat mulai sesi baru

Template Prompt Handover

Baca dokumen berikut secara berurutan:
1. docs/PROJECT.md (konteks bisnis)
2. docs/ARCHITECTURE.md (sistem)
3. docs/DECISIONS.md (keputusan yang sudah locked)
4. docs/MAP.md (peta kode)
5. docs/CONVENTIONS.md (aturan)
6. docs/GOTCHAS.md (jebakan)
7. docs/CONTEXT.md (status saat ini)
8. docs/ISSUES.md (issue terbuka)

Sebelum kerjakan tugas, tunjukkan pemahaman kamu:
- Ringkas status proyek dalam 3 kalimat
- Sebutkan tech stack utama
- Sebutkan 2 gotcha terpenting
- Sebutkan 1 keputusan locked yang relevan dengan tugas ini

Setelah saya konfirmasi pemahamanmu benar, baru kerjakan tugas:
[___isi tugas konkret___]

Ini memaksa agent baca konteks sebelum action. Tanpa ini, agent akan loncat ke action dan miss konteks penting.

Aturan Update Dokumen Handover

  • CONTEXT.md update setiap sesi (status berubah cepat).
  • MAP.md update saat struktur folder berubah.
  • GOTCHAS.md update saat anda menemukan hal aneh (jangan biarkan terkubur di chat).
  • DECISIONS.md update saat ada keputusan baru.

HANDOFF_CONTEXT_v{n}.md Pattern

Untuk proyek dengan diskusi panjang yang mungkin span banyak sesi:

  • Buat versioned handoff doc: HANDOFF_CONTEXT_v1.md, v2.md, dst.
  • Increment version saat ada perubahan scope / decision fundamental.
  • Versi lama tetap di repo (untuk historical context), versi terbaru aktif.

Sumber Pendalaman

4.5 Code Review Tiers untuk AI-Generated Code

Konsep Inti

Tidak semua kode dari agent perlu di-review dengan intensitas yang sama. Klasifikasi dulu, lalu sesuaikan effort review.

Empat Tier Review

Tier Treatment Contoh kode
Tier 1 — Line-by-line wajib Anda baca tiap baris. Tidak boleh skip. Auth/session, RLS policy, multi-tenancy boundary, money calculation, audit log write path, state machine transitions, migration SQL, kalkulator bisnis-critical (voting/pricing/tax), security-sensitive endpoint
Tier 2 — Sample review Sampel acak (baca 30-50% file yang berubah). UI component non-sensitive, tRPC route non-sensitive, helper function, test scenario non-business-logic
Tier 3 — Automated saja CI lulus = OK. Tidak ada review manual rutin. Build pass, TS strict, lint, test pass, migration syntactically valid
Tier 4 — External (paid review) Hire freelance / konsultan untuk audit. Security audit setelah modul foundation, legal review untuk kalkulator regulatif, UX audit setelah primary flow, DevOps audit pre-production

Aturan per Tier

  • Tier 1 wajib sebelum merge ke main. Tidak ada pengecualian.
  • Tier 2 sample bisa fleksibel — kalau pattern sudah established dan agent konsisten, frekuensi sample bisa diturunkan.
  • Tier 3 ditegakkan oleh CI/CD (3.6) — tidak perlu effort manusia kalau setup benar.
  • Tier 4 dijadwalkan, bukan reaktif. Setiap quarter security review, sebelum public launch UX review, dst.

Anti-Pattern

  • “Trust the AI, ship the PR” tanpa Tier 1 review untuk kode sensitif → bom waktu.
  • Line-by-line untuk semua kode → burnout, anda akan skip-skip dan kualitas review malah turun.
  • Skip external review karena merasa cukup → blind spots tidak ketemu di self-review.

Sumber Pendalaman

  • Google — Engineering Practices: Code Review. https://google.github.io/eng-practices/review/
  • Code Complete oleh Steve McConnell (edisi 2). Chapter “Collaborative Construction” relevan.
  • Karl E. Wiegers — Peer Reviews in Software (buku). Pendekatan formal review.

4.6 Bug Tracking & Debugging

Mindset

Anda detektif yang mengumpulkan bukti. Agent mekanik yang memperbaiki. Detektif yang lemah memberi bukti seadanya — mekanik akan tebak-tebakan.

Proses Debugging 5 Langkah

  1. Reproduksi — bisa bikin bug muncul secara konsisten? Kalau tidak, kumpulkan bukti dulu sampai bisa.
  2. Isolasi — kapan terakhir bekerja? Apa yang berubah sejak itu? Hanya halaman ini? Hanya data tertentu? Hanya user tertentu?
  3. Dokumentasi — format bug report standar (langkah reproduksi, expected vs actual, error message, screenshot, environment).
  4. Instruksi ke agent — paste bug report, minta jelaskan penyebab dulu, baru perbaiki. Mencegah agent shot-in-the-dark.
  5. Verifikasi — bug asli hilang? Kasus normal masih bekerja? Tidak ada error baru yang muncul? Test edge case sekitar fix.

Format Bug Report (yang Agent Suka)

**Bug**: [judul singkat]

**Steps to reproduce**:
1. ...
2. ...
3. ...

**Expected**: ...
**Actual**: ...

**Environment**:
- Browser: Chrome 120
- OS: macOS 14.2
- App version: v1.2.3
- User role: admin

**Error**:
[stack trace dari DDS atau console]

**Related**: ISSUE-038, commit abc123

DDS (3.4) menghasilkan format mirip ini dengan satu klik “Copy for Agent”.

Lima Teknik Debugging Tanpa Coding

Teknik Cara
“Kapan terakhir bekerja?” Trace ke commit terakhir di mana fitur jalan. git log + manual test commit lama.
“Bagi dua” (bisection) Nonaktifkan separuh komponen → bug masih ada? Recurse. git bisect untuk commit-level bisection.
“Tambahkan log” Minta agent taruh console.log di setiap langkah eksekusi. Jalankan, lihat output.
“Bandingkan versi lama” git diff <commit-lama> <commit-baru> di file yang dicurigai.
“Minimal reproduction” Minta agent bikin versi paling sederhana yang memunculkan bug. Sering, di proses simplification, agent menemukan bug-nya.

Sumber Pendalaman

  • David J. Agans — Debugging (sudah disebut di 3.4).
  • Why Programs Fail oleh Andreas Zeller (buku, 2009). Akademik, mendalam.
  • Brian W. Kernighan & Rob Pike — The Practice of Programming. Chapter “Debugging”.
  • Julia Evans — debugging zines & blog. Visual, sangat approachable. https://jvns.ca

4.7 Testing Strategy

Konsep Inti

Testing pyramid: pilih distribusi yang sesuai (banyak unit, sedikit E2E).

Tiga Layer Test

Layer Jumlah Cepat? Realistis? Apa yang diuji
Unit test 50-100+ Sangat Tidak Satu fungsi terisolasi. Logic murni.
Integration test 15-30 Sedang Sedang Sambungan antar komponen. DB + API + business logic.
E2E test 5-10 Lambat Sangat Seluruh app dari sudut pandang user. UI → backend → DB → response.

Aturan: lebih banyak unit (cepat, murah), sedikit E2E (lambat, mahal, paling realistis).

Kapan Dijalankan

Tahap Test yang dijalankan
Development (per sub-tugas) Unit test relevan
Akhir milestone Integration test
Sebelum merge ke main E2E flow utama
CI/CD (push) Otomatis: unit + integration
CI/CD (scheduled) E2E + security audit

Apa yang Harus Di-Test

  • Pasti: business logic critical (kalkulator, validasi, state machine), money flow, auth/authz path.
  • Sebaiknya: edge case yang sering bug (date/time, locale, encoding, large data).
  • Tidak perlu: getter/setter trivial, framework code (sudah ditest framework).

Test Naming

Format yang mudah dibaca: [unit] should [expected behavior] when [condition].

Contoh:

formatCurrency() should return "Rp 1.000.000" when input is 1000000
validateEmail() should return false when input has no @ symbol
calculateInterest() should throw when rate is negative

Anti-Pattern

  • Test yang test mock, bukan code — mock setup lebih kompleks dari kode-nya.
  • Test E2E untuk semua skenario — lambat, brittle (sering false-fail).
  • Test yang depend pada urutan — flaky.
  • 100% coverage target — diminishing return, fokus ke critical path.

Sumber Pendalaman

  • Martin Fowler — Test Pyramid (blog). https://martinfowler.com/bliki/TestPyramid.html
  • Kent C. Dodds — Testing JavaScript (course, berbayar). https://testingjavascript.com
  • xUnit Test Patterns oleh Gerard Meszaros (buku). Pattern test design.
  • Vitest, Jest (unit), Playwright, Cypress (E2E) — tools default JS ecosystem.
  • Working Effectively with Unit Tests oleh Jay Fields (buku, 2014).

BAGIAN 5 — CROSS-CUTTING CONCERNS

Lima topik di bagian ini bukan fase, tapi disiplin yang diterapkan sepanjang proyek. Setiap milestone diuji terhadap lima dimensi ini.

5.1 Security — Implementasi & Testing

Konsep Inti

Security planning di Bagian 2.4 menghasilkan threat model. Bagian ini tentang menegakkan model itu sepanjang build dan saat rilis.

Per-Milestone Secure Coding Checklist

Setiap milestone wrap-up, jalankan checklist berikut:

Input Validation

  • Semua input user divalidasi di server-side (frontend validation hanya UX, bukan security).
  • Schema validation (Zod / Joi / Yup) di semua endpoint.
  • SQL parameterized query (tidak ada string concatenation).
  • File upload: validasi extension, MIME type, size limit, virus scan kalau perlu.
  • Limit panjang string untuk cegah resource exhaustion.

Data Handling

  • Password di-hash (bcrypt/argon2), tidak pernah plaintext.
  • Sensitive data tidak masuk log (lihat 3.5 aturan logging).
  • Data di transit pakai HTTPS / TLS (HSTS).
  • Data at rest di-encrypt (DB column-level encryption untuk PII).
  • PII di-mask saat tampilan default (KTP, no HP, email parsial).

Network & API

  • Rate limit per endpoint (cegah brute force, scraping, abuse).
  • Timeout di setiap external call.
  • Request body size limit (cegah upload bom).
  • CORS dikonfigurasi explicit (bukan wildcard *).
  • Headers security (CSP, X-Frame-Options, X-Content-Type-Options).

Authorization (yang sering missed)

  • Setiap endpoint sensitif punya authz check explicit — tidak rely pada “hanya admin yang punya UI ke endpoint ini”.
  • IDOR test: user A bisa akses resource user B dengan ganti URL ID? Harus tidak bisa.
  • RLS policy di DB level (defense in depth).
  • Audit log untuk action sensitif.

Pre-Release Security Checklist

Sekali sebelum rilis production, jalankan checklist lebih komprehensif:

Kategori Item
Configuration .env.production tidak punya value dev/test. Debug mode OFF. Error message tidak leak stack trace ke user.
Dependencies npm audit 0 HIGH/CRITICAL. Lock file di-commit. SBOM tersedia.
Docker Image jalan non-root. read_only: true di compose. Tidak privileged. Minimal base image.
Data Backup terjadwal jalan. Restore di-test. Retention policy enforced.
Network Service internal tidak expose port public. Firewall rules tegas.
Secrets Tidak ada secret di repo (cek dengan git secrets atau truffleHog). Secret rotation policy.
Code Static analysis (ESLint security, Bandit, dst). Dependency check. License check.

Penetration Testing — Self-Service

Minta agent berperan sebagai attacker. Daftar serangan untuk dicoba:

Serangan Test
Input injection SQLi, XSS, command injection — coba payload klasik (OWASP cheat sheet)
Prompt injection (LLM app) “Ignore previous instructions and…” via dokumen, query, atau metadata
Resource exhaustion Upload file besar, query yang return 1M rows, request berulang
Container escape Cek apakah container bisa akses host filesystem
Information disclosure Error message yang leak: stack trace, file path, library version, query SQL
Malformed file Upload .exe dengan extension .jpg, zip bomb, polyglot file
IDOR Akses /api/orders/123 dengan user yang tidak own order itu
Auth bypass Token expired masih bisa pakai? Token re-use setelah logout?

Final Dependency Audit

pnpm audit --audit-level=high
docker scout cves <image>   # atau Trivy / Grype
pnpm ls --depth=0           # review dependency tree
license-checker             # license audit

Maintenance Hygiene

  • Git hooks:
    • Pre-commit: cek tidak ada secret pattern (git-secrets).
    • Pre-push: npm audit lokal.
  • Mingguan: review DDS untuk event security-relevant.
  • Bulanan: full dependency update + audit.
  • Quarterly: external pentest (Tier 4 review, Bagian 4.5).

Sumber Pendalaman

5.2 Performance Optimization

Konsep Inti

Tiga aturan emas:

  1. Jangan optimasi sebelum ada masalah. Premature optimization = waktu hilang, kompleksitas naik.
  2. UKUR sebelum optimasi. 90% dugaan bottleneck salah. Pakai profiler.
  3. Optimasi yang paling berdampak dulu (Pareto — 20% effort untuk 80% gain).

Cara Mengukur

Layer Tool
Frontend Chrome DevTools Performance tab, Lighthouse, React Profiler, Web Vitals
Backend APM (DataDog, New Relic), Postgres EXPLAIN ANALYZE, slow query log
End-to-end Synthetic monitoring, real user monitoring (RUM)
LLM Token/sec, first token latency, end-to-end response time

Frontend Optimization

Gejala Optimasi
List panjang lambat Virtualization — render hanya yang terlihat (react-window, TanStack Virtual)
Re-render berlebihan React.memo, useMemo, useCallback. Atau migrasi ke component yang lebih kecil.
Bundle besar Code splitting (dynamic import), lazy load route, tree shaking, analyze dengan source-map-explorer
Image lambat Format modern (AVIF, WebP), responsive <picture>, lazy load, CDN
Font flash font-display: swap, preload critical font

Backend / RAG Optimization

Gejala Optimasi
LLM lambat Streaming, shorter context, smaller model, quantization (Q4_K_M), prompt caching
Indexing lambat Batch embedding, parallel processing, queue + worker pattern
Search tidak relevan Reranking (cross-encoder), hybrid search (semantic + keyword), chunk size tuning
Query DB lambat Index (BTREE, GIN, GiST sesuai use case), query plan analysis, materialized view
API lambat Cache (Redis), N+1 problem solved (eager load), pagination
OOM Stream besar response, limit query size, batch processing

Aturan Implementasi

  • Setiap optimasi → ukur sebelum dan sesudah. Kalau tidak terbukti berdampak, revert.
  • Optimasi merubah trade-off, tidak menghilangkan biaya — pahami apa yang dikorbankan (kompleksitas, memori, cache invalidation, dst).
  • Dokumentasikan optimasi non-trivial di GOTCHAS.md (kenapa kode lebih kompleks dari yang seharusnya).

Sumber Pendalaman

5.3 API Design & Versioning

Konsep Inti

API adalah kontrak antar service dan dengan client luar. Perubahan API yang tidak hati-hati = client rusak, integrasi rusak.

REST API Principles

Prinsip Contoh
Resource-based URL /api/v1/projects/42/documents (bukan /api/getDocumentsByProject?id=42)
HTTP verb sesuai semantik GET (read), POST (create), PUT/PATCH (update), DELETE (delete)
Status code konsisten 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Server Error
Response shape konsisten { data, error, meta } atau { success, data, error } — pilih satu, pakai di semua endpoint
Pagination untuk list ?page=1&limit=20 atau cursor-based untuk performance. Sertakan total count di meta.

Versioning

Cara Contoh
URL path (paling umum) /api/v1/..., /api/v2/...
Header Accept: application/vnd.example.v2+json
Query param /api/users?version=2 (jarang dipakai, tidak rekomendasi)

Aturan: v1 tetap jalan minimal 12 bulan setelah v2 dirilis. Beri waktu client migrasi.

Breaking vs Non-Breaking Changes

Non-breaking (safe, MINOR bump) Breaking (wajib MAJOR bump)
Tambah field optional di response Hapus field di response
Tambah endpoint baru Rename field
Tambah query param optional Ubah type field (string → number)
Tambah enum value baru Ubah behavior (idempotent → non-idempotent)
Ubah status code default

API Documentation

  • OpenAPI/Swagger spec — single source of truth.
  • Interactive docs — Swagger UI, Redoc, Stoplight.
  • Contoh request & response untuk setiap endpoint.
  • Authentication section di paling depan.
  • Quickstart dengan cURL — pengguna baru bisa coba dalam 5 menit.

Sumber Pendalaman

5.4 Internationalization (i18n)

Konsep Inti

Internationalization adalah merancang app supaya bisa diterjemahkan, bukan tentang menerjemahkannya. Yang kedua = localization (l10n).

Aturan Tunggal yang Mengubah Hidup

Tidak ada teks hardcoded di kode. Semua teks user-facing di file terjemahan terpisah (locales/id.json, locales/en.json).

Contoh:

// SALAH
<button>Save</button>

// BENAR
<button>{t('common.save')}</button>

Yang Sering Dilupakan

Aspek Catatan
Format angka Indonesia: 1.000.000,50. English: 1,000,000.50. Jangan format manual — pakai Intl.NumberFormat.
Format tanggal Indonesia: 24/05/2026. ISO: 2026-05-24. AS: 05/24/2026. Pakai Intl.DateTimeFormat.
Mata uang Rp 1.000.000 (Indonesia), $1,000.00 (US). Pakai Intl.NumberFormat dengan style currency.
Panjang teks Bahasa Jerman ~30% lebih panjang dari Inggris. Layout harus fleksibel.
Pluralization “1 file” vs “2 files”. Lebih kompleks di bahasa lain (Polski, Arab — multiple plural forms). Pakai library ICU MessageFormat.
Arah teks Arab, Hebrew = RTL. Layout harus support dir="rtl".
Format alamat Indonesia: RT/RW + kelurahan + kecamatan. AS: street + city + state + ZIP.

Biaya

Kapan implementasi Effort
Dari awal Kecil — disiplin di setiap component
Setelah app jadi Besar — refactor semua hardcoded string, fix layout RTL, ubah format date/number, ubah test

Rekomendasi: implementasi i18n dari hari pertama, bahkan kalau MVP hanya bahasa Indonesia. Cost kecil di awal vs cost besar di retrofit.

Stack Default

Framework Library
React/Next.js next-intl atau react-i18next
Vue vue-i18n
Universal lingui, formatjs

Sumber Pendalaman

  • W3C — Internationalization. https://www.w3.org/International/
  • Globalize documentation — CLDR-based number/date formatting.
  • Unicode CLDR — Common Locale Data Repository. Source data formatting per locale. https://cldr.unicode.org
  • Building i18n-Friendly React Apps oleh berbagai author di web.dev.

5.5 Compliance Indonesia (Cross-Cutting)

Konsep Inti

Untuk aplikasi yang melayani user Indonesia atau menyimpan data Indonesia, compliance bukan opsional. Tiga lapis regulasi:

  1. Umum: UU 27/2022 Perlindungan Data Pribadi (UU PDP).
  2. Platform: PSE Kominfo (Penyelenggara Sistem Elektronik) registration.
  3. Sektor: POJK (OJK), PBI (BI), PERMA (MA), dst untuk sektor spesifik.

5.5.1 UU 27/2022 PDP — Inti

UU 27/2022 (berlaku efektif Oktober 2024) mengatur perlindungan data pribadi di Indonesia. Mirip GDPR Eropa dengan adaptasi.

Hak User (Subjek Data)

Hak Implementasi praktis
Informasi Privacy policy yang jelas: data apa diambil, untuk apa, berapa lama disimpan
Akses Fitur “Download My Data” — user bisa export data mereka
Perbaikan UI untuk edit data pribadi
Hapus Fitur “Delete My Account” yang benar-benar menghapus (atau anonymize) data
Portabilitas Export dalam format machine-readable (JSON, CSV)
Penolakan otomatisasi Untuk decision automated yang berdampak signifikan (credit scoring, dst) — wajib opt-out

Kewajiban Pengendali Data (Anda)

Kewajiban Implementasi
Consent Eksplisit, granular per kategori data. Bukan checkbox tersembunyi di ToS.
Purpose limitation Data hanya untuk tujuan yang di-consent.
Data minimization Ambil seminimal mungkin. KTP tidak perlu kalau cukup nama + email.
Security Enkripsi, akses kontrol, audit log.
Breach notification 3 × 24 jam dari saat mengetahui breach, lapor ke Kominfo + notif user.
DPO (Data Protection Officer) Wajib untuk pengendali yang proses data dalam skala besar atau data sensitif.
DPIA (Data Protection Impact Assessment) Untuk processing high-risk.

Cross-Border Data Transfer

  • Boleh, tapi negara penerima harus punya tingkat perlindungan setara, atau ada perjanjian standar contract (SCC equivalent), atau consent user explicit.
  • Hosting di AWS Singapore, Vercel US, dst → masuk kategori cross-border. Wajib dokumentasi.

5.5.2 PSE Kominfo Registration

PSE = Penyelenggara Sistem Elektronik. Berdasarkan PP 71/2019 + PM Kominfo 5/2020.

Wajib Daftar Kalau

  • Layanan untuk publik Indonesia.
  • Memenuhi salah satu kriteria: menyediakan/mengelola data digital, transaksi berbayar, komunikasi multimedia, mesin pencari, social media.

Praktiknya hampir semua aplikasi B2C atau platform B2B masuk.

Konsekuensi Tidak Daftar

  • Akses ke layanan bisa diblokir Kominfo.
  • Pernah terjadi mass blocking 2022 untuk PSE asing yang tidak daftar (PayPal, dst).

Proses

Lewat OSS RBA. Dokumen yang dibutuhkan:

  • Domain & teknis aplikasi
  • Privacy policy & ToS
  • DPO contact (kalau berlaku)
  • Lokasi data
  • Bukti badan usaha (kalau PT/CV)

5.5.3 Sektor-Specific (Bila Berlaku)

Sektor Regulator Regulasi kunci
Keuangan / fintech OJK POJK seri 6/7/13 fintech, POJK pelindungan konsumen
Pembayaran BI PBI tentang sistem pembayaran, QRIS
Pasar modal OJK UU Pasar Modal, POJK turunan
Asuransi OJK POJK seri terkait asuransi
Kesehatan Kemenkes UU Kesehatan, PP rekam medis
Pendidikan Kemendikbud UU Sisdiknas

Hukum sektoral umumnya lebih ketat dari UU PDP umum.

5.5.4 Implementasi Praktis

Yang harus ada di app yang touch data pribadi:

  1. Privacy Policy halaman tersendiri, bahasa jelas (bukan jargon hukum).
  2. Consent management — UI untuk lihat & cabut consent.
  3. Data inventory — internal document (docs/legal/DATA-INVENTORY.md): data apa, tujuan, lokasi, retention.
  4. DSR (Data Subject Request) handling — alur jelas saat user minta akses/hapus/portabilitas.
  5. Breach response plan — siapa lapor ke siapa, dalam berapa jam. Drill setahun sekali.
  6. Audit log — tracking siapa akses data apa, kapan. RetentionMinimal 1 tahun.
  7. Encryption at rest untuk PII/data sensitif.
  8. Access control dengan principle of least privilege.

5.5.5 Offline-First sebagai Competitive Advantage

Untuk produk yang memungkinkan offline-first (data tersimpan di mesin user, tidak ada server processing):

  • Posisi privacy sangat kuat: “Data tidak pernah meninggalkan mesin Anda.”
  • Compliance jauh lebih sederhana (tidak ada pemrosesan terpusat).
  • Bisa jadi USP marketing yang kuat di pasar Indonesia 2026, di mana awareness privacy tumbuh.

Trade-off: tidak semua fitur cocok offline (collaborative, real-time, multi-device sync).

Sumber Pendalaman (Sumber Primer)

Sumber Pendalaman (Sumber Sekunder)

  • Asosiasi GDPR-equivalent practice: meskipun GDPR berbeda dengan UU PDP, banyak best practice (consent design, breach response, DPO function) overlap.
  • Future of Privacy Forum — research & policy analysis. https://fpf.org
  • IAPP — International Association of Privacy Professionals. Resource & sertifikasi. https://iapp.org
  • Untuk Indonesia: ELSAM (Lembaga Studi & Advokasi Masyarakat) — kajian implementasi UU PDP.

BAGIAN 6 — SPECIALIZED: AI/RAG HEAVY

Catatan: Bagian ini opsional. Hanya relevan kalau proyek anda punya komponen AI/RAG yang signifikan (knowledge base + LLM, chatbot dengan data sendiri, semantic search, autonomous agent system). Untuk aplikasi CRUD biasa yang hanya pakai LLM sesekali sebagai fitur, lompat ke Bagian 7.

6.1 Arsitektur Microservice untuk RAG

Konsep Inti

RAG (Retrieval-Augmented Generation) menggabungkan dua sistem berat: embedding model (mengubah teks ke vector) + LLM (menghasilkan jawaban). Plus vector DB, orchestrator, dan frontend. Menjalankan semua dalam satu proses sering tidak feasible karena keterbatasan VRAM.

Solusinya: pisah jadi microservice, masing-masing di container Docker, masing-masing punya alokasi resource sendiri.

Kenapa Pisah Service

Alasan Penjelasan
VRAM terbatas Embedding model 1-2GB VRAM, LLM 7-70GB VRAM. Kalau dimuat bersamaan di GPU yang sama, OOM atau swap mahal. Pisah ke GPU berbeda.
Scale independen Indexing (embedding-heavy) dan inference (LLM-heavy) punya pola load berbeda. Scale embedding service 5x tidak harus scale LLM 5x.
Fault isolation LLM crash karena prompt aneh? Embedding service tetap jalan. Vector DB crash? Orchestrator bisa fallback.
Development lebih mudah Mock satu service tanpa menjalankan semua. Test orchestrator tanpa LLM beneran (pakai fake LLM yang return canned response).
Tech stack berbeda LLM serving optimal di vLLM/llama.cpp (C++). Embedding di Python. Orchestrator di Node.js. Pisah service = pakai tool terbaik per layer.

Service Map (Contoh Setup Local RAG dengan 2 GPU)

Service Lokasi compute Port Tugas
Embedding GPU #0 11434 Ubah teks → vector (768-1024 dim)
LLM GPU #1 11435 Generate jawaban dari context + question
Vector DB (Qdrant) CPU 6333 Simpan & cari vector dengan ANN search
Orchestrator CPU 3000 Atur alur RAG: query → embed → search → re-rank → prompt LLM → return
Frontend CPU 8080 UI chat / search interface
DDS (dev only) CPU 9900 Debug system (lihat 3.4)

Alur Request RAG (Sederhana)

User question
    ↓
Frontend → Orchestrator
    ↓
Orchestrator → Embedding service (vectorize question)
    ↓
Orchestrator → Vector DB (cari top-K relevant chunks)
    ↓
Orchestrator → [opsional Reranker]
    ↓
Orchestrator → LLM (prompt = system + context chunks + question)
    ↓
LLM streams response → Orchestrator → Frontend → User

Keuntungan Setup Ini

  • VRAM terisolasi per GPU. Tidak ada race untuk memori.
  • Scale independen — kalau indexing pipeline overload, scale embedding service saja.
  • Fault isolation — satu crash tidak jatuhkan semua. Health check + auto-restart per container.
  • Development workflow lebih bersih — mock service yang belum ready, test integration step by step.

Trade-off

Aspek Impact Mitigasi
Kompleksitas naik Multi-container, network, orchestration Docker Compose untuk dev, Kubernetes hanya saat scale beneran
Latency antar service +20-45ms per hop Negligible vs LLM (5-30 detik)
Resource overhead +375MB RAM untuk container + network layer Kecil untuk mesin developer
Debugging lebih sulit Log scattered antar service Centralized logging + DDS (3.4)

Kapan TIDAK Perlu Microservice

  • App kecil dengan single user.
  • LLM dipanggil via API (OpenAI, Anthropic) — tidak ada local model di-host sendiri.
  • Embedding pakai service eksternal (Cohere, OpenAI embeddings).

Dalam kasus ini, monolith dengan satu Node.js process sudah cukup.

Sumber Pendalaman

  • Sam Newman — Building Microservices (edisi ke-2, 2021). Bible microservice patterns.
  • Sam Newman — Monolith to Microservices (2019). Untuk yang migrasi dari monolith.
  • Designing Data-Intensive Applications oleh Martin Kleppmann (sudah disebut). Chapter 4 (Encoding & Evolution), 9 (Consistency), 11 (Stream Processing) relevan.
  • Eugene Yan — “Patterns for Building LLM-based Systems” (blog). Banyak pattern RAG. https://eugeneyan.com/writing/llm-patterns/
  • Anthropic — “Building effective agents” (sudah disebut di 1.1).
  • Designing Machine Learning Systems oleh Chip Huyen (2022). Sistem ML production-grade.

6.2 Microservice Deep Dive

Enam Konsep Fundamental

Konsep Definisi singkat
Service Satu program yang melakukan satu hal dengan baik. Punya API yang jelas. Bisa di-deploy & di-scale independen.
API Contract Format komunikasi yang disepakati antar service (OpenAPI spec, gRPC proto, JSON Schema). Kontrak ini di-versioning dan stable.
Container Pembungkus portable berisi semua yang dibutuhkan service (kode, runtime, library, config). Docker adalah standar de facto.
Docker Compose Satu file YAML yang menjalankan semua container sekaligus. Untuk development & deployment sederhana.
Network Jaringan virtual yang menghubungkan container. Service A bisa panggil Service B via DNS internal (http://embedding:11434).
Volume Menyambungkan folder di host ke container. Data persist meskipun container di-restart/di-recreate.

Pola Komunikasi

Pola Kapan dipakai Contoh
Synchronous (request-response) Operasi cepat, butuh hasil langsung Frontend → Orchestrator query
Streaming Response bertahap, user butuh feedback cepat LLM generation: token per token
Asynchronous (queue) Operasi panjang, background, retryable Batch indexing 1000 dokumen ke vector DB

Untuk async, queue populer: Redis (BullMQ), pg-boss (di Postgres), Trigger.dev v3 (managed).

Resilience Patterns

Sistem dengan banyak service = banyak titik kegagalan. Empat pattern wajib:

Health Check

Setiap service expose endpoint /health:

GET /health
200 OK
{
  "status": "healthy",
  "uptime_seconds": 3600,
  "dependencies": {
    "database": "ok",
    "vector_db": "ok"
  }
}

Docker Compose healthcheck config → auto-restart kalau unhealthy.

Circuit Breaker

Setelah 3x panggilan gagal berturut-turut → berhenti memanggil 30 detik → coba lagi.

Tujuan: jangan buang resource pada service yang lagi mati. Jangan kasih cascading failure (service A crash → service B retry terus → service B juga crash).

Retry with Backoff (Exponential)

Kalau request gagal sementara: tunggu 1s, retry. Gagal lagi: tunggu 2s. Gagal lagi: 4s. Max retry 3-5x.

Tambah jitter (random delay) untuk hindari thundering herd.

Fallback

Kalau service utama mati, return jawaban degraded daripada error total.

Contoh:

  • LLM service mati → return raw chunks dari vector DB tanpa LLM summarization. User dapat sesuatu, bukan blank.
  • Reranker mati → skip rerank, return top-K dari vector DB langsung.
  • Vector DB mati → tampilkan pesan maintenance, jangan crash app.

Anti-Pattern

Anti-pattern Kenapa salah
Distributed monolith Service-service saling bergantung melingkar (A panggil B, B panggil C, C panggil A). Tidak ada keuntungan dari pemisahan, semua kompleksitas tetap ada.
Sharing database 2 service akses DB yang sama. Satu ubah skema → yang lain rusak. Coupling implisit yang tidak terlihat.
Terlalu banyak service Membuat 20 microservice untuk app yang sebenarnya cukup 3. Overhead operasional melebihi manfaat.
Sync semua-semua Semua call sync. Latency menumpuk. Cascading failure.
No observability Tidak tahu service mana yang lambat, mana yang error. Debugging jadi tebak-tebakan. Lihat 7.3.

Sumber Pendalaman

  • Sam Newman — Building Microservices (sudah disebut).
  • Michael T. Nygard — Release It! (edisi 2, 2018). Wajib untuk siapapun yang deploy ke production. Circuit breaker, bulkhead, dst.
  • Chris Richardson — Microservices Patterns (2018). Implementasi patterns yang detail.
  • Martin Fowler — kategori “Microservices” di blog. https://martinfowler.com/microservices/
  • Distributed systems: For fun and profit oleh Mikito Takada (gratis online). Foundation distributed systems. http://book.mixu.net/distsys/

6.3 AI-Specific Practices

Konsep Inti

Aplikasi yang menggunakan LLM butuh disiplin tambahan yang tidak ada di app non-AI: manajemen prompt, evaluasi kualitas output, dan versioning model. Tanpa ketiganya, app AI anda akan regress secara invisible — kualitas turun tanpa anda sadari.

6.3.1 Prompt Template Management

Aturan

Jangan hardcode prompt di kode aplikasi. Pisahkan sebagai file:

orchestrator/
└── prompts/
    ├── rag-system.v1.md
    ├── rag-system.v2.md
    ├── summarize.v1.md
    ├── classify-intent.v1.md
    └── _registry.yaml

Metadata per Prompt

Setiap file prompt punya frontmatter:

---
id: rag-system
version: 2
created: 2026-04-15
author: ziffany
tested_with_models:
  - claude-sonnet-4-6
  - claude-opus-4-7
  - gpt-4o
eval_score: 0.84
notes: "v2 menambah instruksi citation format"
---

# System Prompt

Kamu adalah asisten yang menjawab pertanyaan berdasarkan konteks
dokumen yang diberikan...

Load saat Runtime

App membaca file prompt saat startup atau per request, bukan compile-in.

Keuntungan:

  • Edit prompt tanpa redeploy.
  • Versioning prompt independen dari kode.
  • A/B test prompt (load v1 untuk 50% traffic, v2 untuk 50%).
  • Tracking: prompt versi berapa yang dipakai untuk request mana.

6.3.2 RAG Evaluation Pipeline

Masalah yang Diselesaikan

Anda ganti embedding model. Apakah retrieval lebih baik? Anda ubah prompt. Apakah jawaban lebih akurat? Tanpa eval, tebakan.

Komponen Eval Pipeline

  1. Eval dataset: 20-50 pertanyaan + jawaban yang diharapkan (golden answers). Dibuat manual oleh anda atau domain expert.
  2. Runner: script yang otomatis kirim setiap pertanyaan ke sistem, capture jawaban, simpan ke file.
  3. Scoring: bandingkan output dengan golden answer. Bisa pakai exact match (kalau jawaban deterministik), atau LLM-as-judge (Claude/GPT scoring kemiripan), atau metric khusus (BLEU, ROUGE untuk text generation).

Aturan Operasional

  • Jalankan eval sebelum dan sesudah perubahan signifikan (prompt change, model swap, retrieval pipeline tweak).
  • Kalau score turun > 10% → jangan deploy sampai investigasi.
  • Tracking score per versi prompt di MODEL-REGISTRY.md atau dashboard internal.

Tools

6.3.3 Model Versioning & Registry

Masalah

Anda coba 5 model embedding berbeda. Mana yang paling baik untuk dokumen anda? Mana yang paling cepat? VRAM-nya berapa?

Tanpa registry, anda lupa konteks setelah 2 minggu.

Format MODEL-REGISTRY.md

# Model Registry

## Embedding Models

| Model | VRAM | Speed (chunks/sec) | Eval score | Notes |
|---|---|---|---|---|
| bge-large-en-v1.5 | 1.4GB | 250 | 0.78 | Default, English-only |
| bge-m3 | 2.2GB | 180 | 0.82 | Multilingual, slightly slower |
| nomic-embed-text-v1.5 | 1.6GB | 220 | 0.75 | OK, prefer bge-m3 |

**Active**: bge-m3 (sejak 2026-04-20)

## LLM Models

| Model | VRAM | Speed (tok/s) | Eval RAG | Notes |
|---|---|---|---|---|
| Qwen2.5-7B-Q4 | 5GB | 45 | 0.71 | Cepat, lemah di reasoning |
| Llama-3.1-70B-Q4 | 42GB | 8 | 0.85 | Lambat, kualitas tinggi |
| Claude Sonnet 4.6 (API) | N/A | streaming | 0.91 | API, mahal di scale, paling stabil |

**Active**: Claude Sonnet 4.6 untuk prod, Qwen2.5-7B untuk dev local.

Peringatan Khusus

  • Ganti embedding model = harus re-index seluruh dokumen. Vector dari model lama tidak compatible dengan model baru. Pertimbangkan biaya re-indexing sebelum migrasi.
  • LLM swap relatif aman — input/output text. Tapi prompt tuning ulang sering diperlukan.

Sumber Pendalaman

6.4 Multi-Agent Orchestration

Konsep Inti

Multi-agent = beberapa LLM instance bekerja bersama untuk menyelesaikan tugas yang terlalu kompleks untuk satu agent. Tapi jangan dipakai prematur — single agent dengan tool-use lebih sederhana dan sering cukup.

Rule of thumb: pakai multi-agent kalau task butuh persona berbeda atau paralel work yang substansial.

Empat Model Multi-Agent

Model Pola Use case
Sequential Chain Agent A selesai → output ke Agent B → output ke Agent C Pipeline: research → outline → write → edit
Parallel Beberapa agent bekerja bersamaan pada tugas berbeda, hasil di-merge Generate 3 variant marketing copy, lalu pilih terbaik
Supervisor / Hierarchical Satu agent (manager) mendelegasikan ke agent spesialis Coding assistant: planner delegates ke coder, tester, reviewer
Debate Dua agent saling mengkritik, manusia ambil keputusan Architecture decision: agent-pro vs agent-contra

Implementasi Praktis untuk Agentic Engineer Pemula

Multi-agent tidak harus berarti sistem kompleks dengan framework khusus. Bisa sangat praktis:

Pola 1: Sesi Berbeda dengan Persona Berbeda

Buka 4 tab Claude dengan instruction berbeda:

  • Architect — diskusi keputusan struktural
  • Developer — implementasi kode
  • Reviewer — review output developer
  • QA — bikin test case dan edge case

Anda jadi orchestrator manual. Tidak butuh framework apa-apa.

Pola 2: Tool Berbeda untuk Tugas Berbeda

  • Claude chat (UI) untuk perencanaan & arsitektur.
  • Claude Code (CLI) untuk implementasi.
  • Cursor untuk inline edit & refactor.
  • Gemini CLI / Antigravity untuk experiment alternatif.

Setiap tool punya konteks & strength berbeda.

Pola 3: Model Berbeda untuk Task Berbeda

Tier model berdasar kompleksitas task:

Task Model
Routing simple, classification Haiku / GPT-4o mini (cepat, murah)
Implementation kode, refactor Sonnet (workhorse default)
Arsitektur kompleks, security review, decision dengan stakes tinggi Opus / GPT-4o (reasoning maksimal)

Ini disebut model tiering, dan menghemat 40-60% biaya API tanpa kompromi kualitas signifikan di task yang appropriate.

Framework Multi-Agent (Untuk yang Mau Lebih Jauh)

Framework Bahasa Kekuatan
LangGraph Python Graph-based agent orchestration, banyak primitives
CrewAI Python Role-based, easy mental model
Autogen Python (MS) Conversation-driven multi-agent
Anthropic Agent SDK TS/Python Native untuk Claude, MCP integration

Saran: jangan reach untuk framework sampai anda yakin butuh. Banyak use case selesai dengan plain function call + async + state object.

Anthropic MCP (Model Context Protocol)

MCP adalah protokol standar untuk menghubungkan LLM dengan tool dan data eksternal. Resmi dari Anthropic, sudah diadopsi vendor lain.

Kalau anda build app yang LLM-nya butuh akses tool (file, database, API eksternal), MCP adalah standar untuk diikuti — bukan reinvent wheel.

Sumber Pendalaman

6.5 Edge Computing & Offline Sync

Konsep Inti

Aplikasi yang harus jalan tanpa internet (atau dengan koneksi buruk) butuh arsitektur khusus: data tersimpan lokal, sync ke server saat online.

Penting untuk konteks Indonesia: koneksi mobile sering tidak stabil di luar kota besar.

Tiga Strategi Sync

Strategi Cara kerja Pro Kontra
Last Write Wins (LWW) Update terakhir berdasarkan timestamp menang Sederhana implementasi Data bisa hilang (write dari device A overwrite write dari device B yang lebih lama tapi penting)
Merge dengan conflict resolution Gabungkan perubahan yang berbeda field; tanya user kalau field sama dikonflikkan Tidak hilang data UX kompleks (user lihat dialog conflict), kode kompleks
CRDT (Conflict-free Replicated Data Type) Struktur data yang secara matematis tidak bisa konflik Otomatis merge tanpa conflict Tidak semua data cocok (number counter ya, structured complex no); kompleks implementasi

Offline-First Architecture

Pattern:

User action
    ↓
Write ke Local DB (SQLite, IndexedDB) — INSTAN
    ↓
UI update — INSTAN
    ↓
[Background] sync queue ke server
    ↓
[Background] kalau berhasil → mark synced
    ↓
[Background] kalau gagal → retry dengan backoff

User tidak perlu tahu apakah online/offline. App selalu responsive. Sync terjadi di belakang layar.

Komponen yang Dibutuhkan

Komponen Implementasi
Local DB SQLite (mobile), IndexedDB / SQLite WASM (web), Realm
Sync engine RxDB, PouchDB+CouchDB, Replicache, Yjs (CRDT), Automerge (CRDT)
Conflict UI Custom dialog atau auto-resolve berdasar policy
Indicator status sync UI yang menunjukkan sync state (pending / synced / failed) — subtle, tidak menakuti user

Trade-off

  • Pro: jalan offline, instant UI, resilient ke koneksi buruk, competitive privacy advantage untuk pasar Indonesia (lihat 5.5.5).
  • Kontra: kompleksitas signifikan, conflict edge case bisa nightmare, butuh skema data yang sync-friendly (no auto-increment ID, pakai UUID).

Kapan Pakai Offline-First

  • App produktivitas single-user (note-taking, todo, kalkulator).
  • App field worker (mobile, lokasi buruk koneksi).
  • App dengan privacy concern (data tidak perlu ke server).

Kapan Jangan

  • App collaborative real-time (Google Docs style) — butuh server.
  • App dengan data otoritatif di server (banking, e-commerce) — single source of truth penting.

Sumber Pendalaman

BAGIAN 7 — OPERATIONS

Operasi adalah disiplin yang membuat aplikasi tetap berjalan di production. Bagian ini relevan sebelum dan sesudah rilis.

7.1 Database Migration

Konsep Inti

Database migration adalah cara mengubah skema database secara terkontrol, bisa direplikasi, dan bisa di-rollback. Tanpa migration system, perubahan skema = mimpi buruk.

Prinsip

Aturan Penjelasan
Satu file per perubahan 001_add_users_table.sql, 002_add_email_index.sql, dst
Dijalankan berurutan Migration runner tahu urutan dari nomor/timestamp prefix
Hanya sekali per environment Tracking di table _migrations (apa yang sudah dijalankan)
Tidak boleh diedit setelah dirilis Kalau salah, buat migration baru yang fix; jangan edit migration lama
Bisa rollback Setiap migration punya down script (atau dokumentasi cara revert manual)
Backup sebelum migrate Wajib untuk production. Lihat 7.2.
Test di data realistis Migrate di copy production DB sebelum hit prod beneran

Backward Compatibility

Selama deployment, ada periode di mana kode lama dan skema baru harus jalan bersamaan (atau kode baru dan skema lama, tergantung urutan deploy).

Praktik yang aman:

Operation Tingkat risiko Catatan
ADD COLUMN (nullable) Rendah Kode lama abaikan kolom baru, kode baru pakai
ADD COLUMN (NOT NULL with default) Rendah Default value menghindari error untuk row existing
CREATE INDEX (concurrent) Rendah Tidak blocking di Postgres pakai CONCURRENTLY
RENAME COLUMN Tinggi Kode lama crash. Lakukan 2-step: add column baru → migrate data → drop kolom lama (di release berikutnya)
DROP COLUMN Tinggi Kode lama yang masih query kolom itu crash. Pastikan tidak ada deployment kode lama yang aktif.
ALTER COLUMN TYPE Tinggi Bisa lock table lama untuk data besar. Lakukan dengan add new column + migrate strategy.

Aturan emas: expand-contract pattern untuk perubahan berisiko.

1. Expand: tambah struktur baru (column, table) tanpa hapus lama
2. Migrate: kode baru pakai struktur baru, data lama di-migrate
3. Contract: hapus struktur lama, setelah semua deployment kode lama hilang

Tools

Tool Bahasa Catatan
Drizzle Kit TS Drizzle ORM ecosystem. SQL-first, type-safe.
Prisma Migrate TS Prisma ORM. Auto-generated dari schema.
Flyway Java, polyglot Tool migration yang database-agnostic.
Liquibase Java Enterprise feature-rich.
Plain SQL + custom runner Apapun Untuk sederhana, cukup script bash.

Sumber Pendalaman

7.2 Backup, Disaster Recovery & Data Migration

Konsep Inti

Backup yang belum di-test restore = bukan backup. Kalimat klise tapi terus terjadi: orang lapor “saya punya backup” tapi pas disaster, restore gagal karena tidak pernah dicoba.

7.2.1 Backup Strategy

Identifikasi Data Kritis

Kategori data Backup? Frekuensi
Database production Wajib Harian otomatis + transaction log continuous
Dokumen yang di-upload user Wajib Harian (atau snapshot S3-compatible)
Konfigurasi (.env, infrastructure) Wajib Per-perubahan, di git
Prompts (kalau di filesystem) Wajib Harian
Logs Opsional Mingguan, retention pendek
Build artifact Tidak Bisa di-rebuild dari source

Retention Policy (Contoh)

- 7 backup harian (rolling, hari ini sampai 7 hari lalu)
- 4 backup mingguan (setiap Minggu, 4 minggu terakhir)
- 12 backup bulanan (setiap tanggal 1, 12 bulan terakhir)
- 7 backup tahunan (setiap 1 Januari, 7 tahun terakhir)

Disebut GFS (Grandfather-Father-Son) rotation.

Storage Strategy

Aturan 3-2-1:

  • 3 salinan data (1 production + 2 backup)
  • 2 media berbeda (disk lokal + cloud storage / disk eksternal)
  • 1 off-site (di lokasi fisik berbeda — DR scenario kebakaran, banjir)

Tools

Tool Cocok untuk
pg_dump + cron Postgres backup logical
pg_basebackup + WAL archiving Postgres physical backup + PITR
Restic File-level backup with encryption + deduplication
BorgBackup Mirip Restic, encrypted incremental
rclone Sync ke S3-compatible storage
Velero Kubernetes backup
Snapshot di provider (RDS, DigitalOcean, dst) Convenient, tapi dependency vendor

7.2.2 Disaster Recovery

DR adalah prosedur saat disaster terjadi. Tanpa prosedur tertulis, panic-driven mistakes akan memperburuk.

Per Skenario

Skenario Target RTO* Prosedur
Container crash < 2 menit Docker auto-restart. Health check kembali OK.
Database corrupt 5-30 menit Restore dari backup harian. Replay transaction log kalau PITR enabled.
Disk failure 1-4 jam Replace disk. Restore dari backup (atau snapshot).
Mesin rusak total 4-8 jam Spin up server baru (IaC dari repo). Restore data. DNS switch.
Region down Tergantung Multi-region setup, atau backup di region lain.
Ransomware / breach Sangat tergantung Incident response plan terpisah, tidak cuma DR

RTO = Recovery Time Objective (berapa lama maksimal downtime). RPO = Recovery Point Objective (berapa banyak data yang acceptable hilang).

Kebutuhan Minimal

  • Repo di GitHub (untuk source).
  • Backup di disk eksternal (off-site) + cloud (off-site lainnya).
  • Dokumentasi offline (PDF di USB, atau di laptop) — kalau internet mati saat disaster.
  • Daftar credentials di password manager + paper backup di safe.

Drill Reguler

Restore drill minimal 2x setahun. Tanpa drill, backup yang tidak pernah di-test bisa corrupt tanpa anda tahu.

Drill = matikan service, restore dari backup terakhir, verifikasi data, time it. Catat ke DISASTER-RECOVERY-DRILL.md.

7.2.3 Data Migration (Antar Sistem)

Untuk ganti database engine, ganti mesin, atau merge data dari sistem lain.

Migration plan template:

1. Backup full source data
2. Setup target system kosong
3. Migrate data — script yang ETL (extract, transform, load)
4. Verifikasi:
   - Row count match
   - Sample data spot check
   - Foreign key integrity
   - Eval pipeline lulus (untuk AI app)
5. Switch — point app ke target system
6. Grace period — source system tetap online 1-4 minggu, monitor for issues
7. Decommission source system + final backup

Sumber Pendalaman

7.3 Observability & Monitoring

Konsep Inti

Observability adalah kemampuan memahami apa yang terjadi di sistem dari output-nya. Monitoring adalah mengamati metrik tertentu dan alert saat anomali.

Observability = pertanyaan terbuka. Monitoring = pertanyaan tertutup yang sudah anda tahu mau ditanya.

Tiga Pilar Observability

Pilar Apa Use case
Logs Catatan kronologis kejadian (text/JSON) Debugging error spesifik, audit trail
Metrics Angka kesehatan agregat (CPU, RAM, request rate, error rate, latency) Health dashboard, alerting threshold
Traces Perjalanan satu request melintasi semua service (distributed tracing) Bottleneck analysis, debug latency

Standar Industri

  • OpenTelemetry (OTel) — vendor-neutral standard untuk telemetry. Tools yang support OTel bisa di-swap tanpa rewrite instrumentasi. Pakai ini sebagai standar.

Implementasi untuk Solo Developer

Tidak perlu enterprise stack (Datadog $$, New Relic $$). Setup minimal yang berfungsi:

Layer 1: Health Dashboard

Endpoint /api/health/detailed:

{
  "status": "healthy",
  "timestamp": "2026-05-24T08:00:00Z",
  "uptime_seconds": 432000,
  "version": "v1.2.3",
  "services": {
    "database": { "status": "ok", "latency_ms": 3 },
    "vector_db": { "status": "ok", "latency_ms": 12 },
    "embedding": { "status": "ok", "latency_ms": 45 },
    "llm": { "status": "degraded", "latency_ms": 8000, "note": "slow today" }
  },
  "resources": {
    "cpu_percent": 35,
    "memory_percent": 62,
    "disk_percent": 41
  }
}

Frontend /health page yang call endpoint ini dan tampilkan visual.

Layer 2: Structured Logging

JSON logs, bukan plain text. Format konsisten:

{
  "timestamp": "2026-05-24T08:00:01.234Z",
  "level": "ERROR",
  "service": "orchestrator",
  "trace_id": "abc-123",
  "user_id": "u-42",
  "event": "llm_call_failed",
  "duration_ms": 30000,
  "error": "timeout"
}

Rotate harian, retention 30 hari (atau sesuai compliance).

Layer 3: Metrics

Minimal metrics:

  • Request rate per endpoint
  • Error rate per endpoint
  • Latency p50/p95/p99 per endpoint
  • CPU/RAM/disk
  • Custom: queue depth, LLM token usage, eval score over time

Tools gratis:

  • Prometheus (storage) + Grafana (dashboard) — self-hosted standar.
  • Grafana Cloud free tier — managed, gratis sampai limit tertentu.
  • Uptime Kuma — simple uptime monitoring, self-hosted. https://github.com/louislam/uptime-kuma

Layer 4: Alerting

Alert hanya untuk hal yang actionable. Alert yang tidak actionable = noise = ignored = alert fatigue.

Kanal alert solo dev (24/7):

  • Telegram bot (paling reliable, free).
  • Discord webhook (kalau anda aktif di Discord).
  • WhatsApp Business API atau Twilio SMS (untuk yang urgent banget).
  • Email (untuk yang non-urgent).

Layer 5: Alert File (untuk noise reduction)

Tulis alert ke file logs/alerts/YYYY-MM-DD.log. Hanya alert kritis di-broadcast ke channel real-time. Alert lain di-batch dan dikirim digest harian.

Anti-Pattern

  • Log everything: storage cost mahal, signal:noise jelek. Log yang penting, sample yang lain.
  • Alert untuk semua error: alert fatigue. Setting threshold dan deduplicate.
  • Dashboard berisi semua metric: useless. 4-8 metric kunci di first screen, rest di-drill down.
  • Tidak punya runbook: alert berbunyi, tidak ada panduan untuk fix. Setiap alert wajib link ke runbook (langkah resolusi).

Sumber Pendalaman

7.4 Versioning & Release Management

Konsep Inti

Versioning adalah cara komunikasi terstruktur ke user tentang apa yang berubah di setiap rilis. Release management adalah disiplin memastikan setiap rilis bersih.

Semantic Versioning (SemVer)

Format: MAJOR.MINOR.PATCH

Komponen Naik kapan
PATCH (1.2.3 → 1.2.4) Bug fix, perubahan internal yang tidak mempengaruhi public API
MINOR (1.2.3 → 1.3.0) Fitur baru, backward compatible
MAJOR (1.2.3 → 2.0.0) Breaking change yang tidak backward compatible

Pre-release: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1.

Aturan SemVer untuk Software (API & Library)

  • v0.x.x = unstable, breaking change boleh di MINOR.
  • v1.0.0 = first stable, dari sini disiplin SemVer ketat.
  • Public API yang sudah dirilis di MAJOR tidak break sampai MAJOR berikutnya.

Release Checklist

Sebelum tag rilis, jalankan checklist:

Code

  • Semua test lulus (CI hijau).
  • Security audit clean (npm audit 0 HIGH/CRITICAL).
  • Lint & typecheck lulus.
  • Tidak ada console.log debug yang tertinggal.
  • Performance regression cek (kalau ada baseline).

Documentation

  • CHANGELOG.md di-update.
  • User manual / docs sesuai dengan fitur baru.
  • Migration guide (kalau breaking).
  • Release notes draft.

Testing

  • Manual smoke test di staging.
  • Multi-platform test (kalau cross-platform).
  • Upgrade path test — install versi lama, upgrade ke versi baru, data masih intact.
  • Fresh install test.

Distribution

  • Build artifact (Docker image, installer, dst).
  • License file & key dibuat untuk versi ini.
  • Signature / checksum disediakan.

Communication

  • Release notes published.
  • Email / newsletter ke user (kalau ada).
  • Update website / pricing page (kalau perubahan fitur signifikan).
  • Post sosmed (kalau strategy include).

Git Tags untuk Release

# Tentukan versi
npm version minor   # auto-update package.json

# Tag commit
git tag -a v1.2.0 -m "Release v1.2.0 — dashboard analytics"

# Push tag (memicu CI/CD release workflow)
git push origin v1.2.0

CI/CD bisa di-setup untuk auto-build artifact saat tag dengan format v* di-push.

Release Cadence

Tipe Cadence Contoh
PATCH Sesuai kebutuhan Bug ditemukan → fix → release
MINOR Bi-weekly / monthly Fitur baru terakumulasi → batch release
MAJOR 6-12 bulan Breaking change yang dipersiapkan dengan migration guide

Sumber Pendalaman

7.5 DevOps for Solo Developer

Konsep Inti

DevOps sering diasosiasikan dengan tim besar dan tooling kompleks. Untuk solo developer, prinsipnya sama tapi implementasinya jauh lebih ringan: otomasi yang membayar diri sendiri.

Infrastructure as Code (IaC)

Aturan: jangan setup server manual. Setiap setup ditulis sebagai script.

Kenapa penting:

  • Server rusak total → jalankan script → server identik dalam menit.
  • Setup environment baru → konsisten, tidak ada drift.
  • Dokumentasi otomatis (script itu sendiri = dokumentasi).
  • Reviewable (script di git, history terlacak).

Implementasi Ringan

scripts/
├── setup-server.sh      # provision server dari kosong
├── deploy.sh            # deploy versi baru
├── backup.sh            # backup harian
├── restore.sh           # restore dari backup
└── health-check.sh      # health check (cron 5 menit)

Untuk yang lebih advance: Ansible (declarative, agentless), Terraform (multi-cloud), atau Docker Compose (sederhana, cukup untuk single-host).

Monitoring & Alerting Solo Setup

Health check script + cron + Telegram bot:

# /etc/cron.d/health-check
*/5 * * * * /opt/app/scripts/health-check.sh

Script logic:

  1. Cek service utama (curl /health).
  2. Cek disk usage (> 80% → alert).
  3. Cek GPU (kalau pakai local LLM).
  4. Cek backup terakhir (terjadi dalam 24 jam?).
  5. Kirim notif ke Telegram kalau ada masalah.

Ini sudah cukup untuk solo dev MVP. Upgrade ke Prometheus + Grafana saat scale.

Automated Maintenance

Script mingguan (cron Sabtu malam):

- Backup full ke off-site storage
- Cleanup Docker (image lama, volume orphan): `docker system prune -af --volumes`
- Cleanup logs (> 30 hari)
- Dependency audit (npm audit, snyk)
- Disk usage report → log + email
- Certificate expiry check (renewal in 30 hari?)
- Database VACUUM (Postgres, kalau perlu)

Deployment Pattern Solo

  • Blue-Green: deploy ke environment baru, switch traffic. Rollback = switch balik. Kompleks tapi safe.
  • Rolling: update satu container dulu, kalau OK lanjut yang lain. Cocok untuk multi-instance.
  • Canary: deploy ke 5% user dulu, kalau OK ke 100%. Butuh load balancer.
  • Simple Replace (paling umum solo dev): turunkan service lama, naikkan service baru. Downtime ~30 detik. OK untuk MVP yang tidak SLA-critical.

Anti-Pattern Solo Dev

  • “Saya ingat password server” — pakai password manager. Hilang akses = disaster.
  • SSH dengan password, bukan key — security & convenience kalah.
  • Tidak ada backup off-site — single point of failure.
  • Auto-deploy tanpa manual approval ke prod — undangan disaster.
  • Tidak monitor disk — disk penuh → service crash → kacau.

Sumber Pendalaman

  • Gene Kim et al. — The Phoenix Project (novel, 2013). Konsep DevOps dalam format cerita. Sangat readable.
  • Gene Kim et al. — The DevOps Handbook (sudah disebut di 3.6).
  • Site Reliability Engineering book (sudah disebut). Filosofi SRE = DevOps + ML.
  • DigitalOcean Community — banyak tutorial deployment praktis. https://www.digitalocean.com/community/tutorials
  • Server Setup guide oleh Linode / DigitalOcean — untuk awal.

7.6 End User Documentation

Konsep Inti

Dokumentasi end user bukan dokumentasi developer. Audience berbeda, tone berbeda, struktur berbeda. Mengabaikan ini = support ticket banjir.

Lima Jenis Dokumen End User

Jenis Panjang Format Audience
Quick Start Guide 1 halaman, 5 menit baca Step-by-step bergambar User baru, mau cepat coba
User Manual Per bab, task-oriented Screenshot di setiap langkah User yang mau pakai fitur tertentu
FAQ 15-20 pertanyaan Q&A User yang baca preview / mau lookup cepat
Troubleshooting Per masalah Masalah → kemungkinan penyebab → solusi User yang stuck
In-App Help Inline UI Tooltip, onboarding tour, contextual help, empty state guidance User saat pakai produk

Diátaxis Framework (Klasifikasi 4 Jenis)

Daniele Procida (sudah disebut di 1.5) membagi dokumen ke 4 kategori berdasar needs vs action:

Konteks Praktis (action) Kognitif (understanding)
Saat bekerja How-to guides (resep solusi spesifik) Reference (lookup definitif)
Saat belajar Tutorials (langkah belajar) Explanation (konsep dalam)

Pemetaan ke struktur sebelumnya:

  • Quick Start = Tutorial
  • User Manual = Mix of How-to + Reference
  • FAQ = How-to + Reference
  • Troubleshooting = How-to
  • In-App Help = Mix, tergantung konteks

Prinsip Penulisan

Prinsip Praktis
Satu topik per halaman Jangan campur “cara upload” + “cara delete” di satu halaman. Pemisahan = mudah cari.
Task-oriented “Cara mengirim invoice” bukan “Fitur invoicing”. User cari verb, bukan noun.
Asumsi user tidak tahu apa-apa Tapi jangan condescending. “Klik tombol biru bertuliskan ‘Save’.” Tidak “Click here.”
Screenshot annotated Lingkari/panah ke elemen yang relevan. Tools: ShareX, CleanShot X, Snagit.
Bahasa sederhana Kalimat pendek. Aktif voice. Tidak jargon. Lihat 1.5.
Konsistensi terminologi Kalau pakai “project”, jangan kadang “workspace”, “folder” untuk hal sama. Glossary di internal docs.

Struktur User Manual yang Bagus

docs/user/
├── index.md                    # ToC + quick start
├── quick-start.md
├── concepts/                   # Explanation
│   ├── projects-and-workspaces.md
│   └── how-search-works.md
├── how-to/                     # How-to
│   ├── create-project.md
│   ├── upload-documents.md
│   ├── invite-team.md
│   └── ...
├── reference/                  # Reference
│   ├── keyboard-shortcuts.md
│   ├── file-format-support.md
│   └── api.md
└── troubleshooting/
    ├── upload-failed.md
    ├── search-not-finding.md
    └── ...

In-App Help Implementation

  • Tooltip untuk icon-only buttons / abbreviation.
  • Onboarding tour untuk first-time user. Tools: Intro.js, Shepherd, Driver.js. Max 5-7 step.
  • Empty state guidance — saat list kosong, jelaskan apa yang harus dilakukan.
  • Contextual help — link “?” yang membuka panel relevan.
  • Inline tutorial — tab “What’s this?” yang menjelaskan fitur.

Tools

Tool Untuk
MkDocs Static site dari Markdown, theme Material populer
Docusaurus Meta’s docs framework, React-based
GitBook Hosted, polished UI
Notion Quick, tapi vendor lock-in
Astro Starlight Modern, fast, light
VuePress Vue ecosystem

Sumber Pendalaman

BAGIAN 8 — BISNIS & KOMERSIALISASI

Fase di mana produk berubah menjadi bisnis. Banyak developer solo gagal di sini bukan karena produknya jelek, tapi karena melewatkan validasi atau salah harga.

Catatan: Compliance (UU PDP Indonesia, PSE Kominfo, sektor regulasi) sudah dibahas di Bagian 5.5 sebagai cross-cutting concern. Bagian ini fokus pada bisnis & monetisasi.

8.1 Pre-Launch Validation Pipeline

Konsep Inti

Bangun setelah validated, bukan sebaliknya. Membangun dulu lalu cari market = pattern paling umum failure solo dev. Validation pipeline adalah disiplin untuk membuktikan ada demand sebelum invest waktu bulan-bulanan ke produk.

Tahap ini sering di-skip karena “saya yakin ide bagus.” Kepercayaan diri ≠ validasi.

Tujuh Tahap Validasi

Tahap Aktivitas Output
1. Problem validation Wawancara 10-15 calon user. Tanyakan masalah, bukan solusi. Konfirmasi: masalah real, sering, mahal
2. Solution validation Tunjukkan mockup/wireframe ke calon user. Tanyakan: “Ini solusinya?” Konfirmasi: solusi anda diinginkan
3. Willingness to pay Tanyakan: “Kalau ini ada, anda mau bayar berapa?” Hati-hati bias — orang sering bilang ya tapi tidak benar-benar bayar Indikasi harga + segment
4. Pre-sale / waitlist Landing page → kumpulkan email. Bonus: deposit / preorder. Conversion rate signal lebih kuat dari survey List leads + commit
5. MVP launch ke early adopter Bangun versi minimal (Bagian 2-4). Rilis ke waitlist. First paying customer + feedback
6. Iterasi berdasarkan feedback Refine produk dengan data nyata, bukan asumsi Product-market fit
7. Scale Setelah retention solid, baru scale marketing/team Growth phase (Bagian 9)

Mom Test — Aturan Wawancara

Rob Fitzpatrick menulis aturan untuk wawancara user yang tidak bias:

  1. Bicarakan kehidupan mereka, bukan ide anda. “Bagaimana anda menyelesaikan X sekarang?” bukan “Apakah produk ini menarik?”
  2. Tanyakan tentang spesifik di masa lalu, bukan opini umum atau prediksi masa depan. “Kapan terakhir anda mengalami masalah X?” bukan “Apakah anda biasa mengalami X?”
  3. Bicaralah lebih sedikit, dengarkan lebih banyak.

User bilang “ide bagus” terus karena tidak mau menyakiti perasaan anda. Itu bukan data. Yang valid: cerita konkret pengalaman buruk mereka dengan status quo.

Signal Lemah vs Signal Kuat

Signal lemah (jangan percaya) Signal kuat (boleh percaya)
“Ide bagus!” “Saya akan beli sekarang. Apakah ada beta?”
“Saya akan rekomendasikan” “Ini email saya, kirim kalau sudah ready”
“Pasti banyak yang butuh” Mereka pre-order / bayar deposit
Survey form filled Wawancara langsung di kalender
Like di sosmed Komen detail tentang use case

Validation Anti-Pattern

  • Skip validation karena terlalu sibuk build. “Saya tahu marketnya” tanpa data = ide gagal mahal.
  • Validate ke teman & keluarga. Mereka bias. Cari calon user real, bahkan kalau awkward.
  • Validate dengan survey tanpa wawancara. Survey jawab “what”, wawancara jawab “why”.
  • Stop validation setelah 3 ya. Cari diversity 10-15 minimum.

Sumber Pendalaman

  • Rob Fitzpatrick — The Mom Test (buku, 2013). Pendek (~100 halaman), salah satu buku paling underrated untuk founder.
  • Steve Blank — The Four Steps to the Epiphany (buku, 2005). Customer development methodology asli.
  • Steve Blank — The Startup Owner’s Manual (buku, 2012). Operational manual dari konsep customer dev.
  • Eric Ries — The Lean Startup (buku, 2011). Build-Measure-Learn loop.
  • Indie Hackers — komunitas + podcast tentang bootstrapped founder journey. https://www.indiehackers.com

8.2 Pricing Strategy

Konsep Inti

Harga berdasarkan nilai (berapa jam/uang yang dihemat user), bukan biaya (berapa listrik server). Pemula sering pricing terlalu rendah karena cost-plus thinking. Hasil: revenue tidak menutupi support time.

Prinsip Pricing

Prinsip Penjelasan
Value-based, bukan cost-based Hitung berapa value yang anda berikan ke customer. Charge 10-20% dari value.
Tampilkan tier mahal dulu Anchor effect — tier mahal membuat tier menengah terasa wajar
Pahami dalam 10 detik Pricing page kompleks = abandonment. 3 tier max, fitur jelas.
Annual discount 15-25% Memperbaiki cash flow + reduce churn
Hindari tier “Custom”/“Contact us” untuk SMB Friction terlalu tinggi. Cuma untuk enterprise.

Cara Menentukan Harga

  1. Identifikasi target customer spesifik (Bagian 2.1 user persona).
  2. Hitung nilai yang diberikan — berapa jam/uang yang dihemat per bulan?
  3. Riset kompetitor — apa range market saat ini?
  4. Test 3 angka — high / medium / low. Yang paling banyak konversi (atau revenue), wins.
  5. Iterasi — pricing bukan keputusan sekali. Re-evaluate per quarter.

Sweet spot indikator: beberapa orang bilang “mahal” tapi tetap beli. Kalau tidak ada yang bilang mahal, kemungkinan anda kemurahan.

Tier Structure Klasik (SaaS)

+----------------------------------------------------+
| Free / Trial    | Pro            | Business / Team |
|-----------------+----------------+-----------------|
| 14-day free     | $19/mo         | $49/mo per user |
| Limited usage   | Solo features  | Team features   |
| No credit card  | Most popular   | + Admin, SSO    |
+----------------------------------------------------+

Aturan:

  • Free / Trial untuk friction-free trial.
  • Pro ditandai “Most Popular” — itu yang anda mau orang pilih (highest margin × volume).
  • Business untuk yang serius. Fitur kunci: team, admin, SSO, audit log, priority support.

Pricing Model Alternatif

Model Cocok untuk Contoh
Per seat / per user B2B tools Slack, Notion
Usage-based Infra, API, AI tools OpenAI API, AWS
Tiered fixed SaaS produktivitas Most SaaS
Freemium Mass-market, network effect Dropbox, Zoom
Perpetual license + maintenance Desktop software, on-prem JetBrains, Photoshop (dulu)
One-time purchase Small tool, mobile app Banyak iOS app

Pilih satu, jangan campur 3 model di pricing page. Confusion = abandonment.

Pricing Page Anatomy

[Hero — value proposition + CTA]
[3 tier side-by-side, dengan checkmarks]
[Comparison table — fitur lengkap]
[FAQ — "Bisa cancel kapan saja?" "Refund policy?"]
[Trust elements — testimonial, garansi, logo customer]
[Final CTA + secondary CTA "Talk to sales"]

Konteks Indonesia

  • Payment methods penting: prefer transfer bank + e-wallet (GoPay/OVO/Dana/ShopeePay) + QRIS. Kartu kredit minoritas. Stripe bekerja untuk B2B, tapi B2C Indonesia underserved oleh Stripe.
  • Currency display: Rupiah dengan separator Indonesia (Rp 99.000). USD pricing OK untuk B2B global, tapi rasanya lebih mahal untuk customer Indonesia.
  • Tax: PPN 11% wajib display (kalau anda PKP). Bisa pakai “Harga sudah termasuk PPN” atau “Harga belum termasuk PPN”.

Sumber Pendalaman

  • Patrick Campbell (ProfitWell/Paddle) — pricing & growth content. https://www.paddle.com/resources
  • Madhavan Ramanujam — Monetizing Innovation (buku, 2016). Framework untuk pricing decision.
  • The Strategy and Tactics of Pricing oleh Nagle & Müller. Akademik tapi komprehensif.
  • Indie Hackers pricing case studies. Berbagai founder share pricing journey.
  • Stripe — Pricing experimentation guide. https://stripe.com/atlas/guides

8.3 Lisensi, Distribusi & Proteksi Kode

Konsep Inti

Untuk produk yang dijual (terutama desktop / on-prem / mobile app), anda butuh model lisensi dan proteksi minimal. Tapi jangan over-engineer — proteksi sophisticated saat belum ada demand = waktu sia-sia.

Model Lisensi

Model Cocok untuk Contoh
Per machine Desktop software Adobe (dulu), Visual Studio
Subscription SaaS, modern desktop JetBrains, Microsoft 365
Usage-based API, infra AWS, OpenAI API
Tiered SaaS produktivitas Notion, Linear
One-time + maintenance Enterprise on-prem Banyak software lawas + renewal

Sistem Lisensi Per Mesin (Untuk Desktop / On-Prem)

Konsep:

  1. Machine ID — hash dari CPU + MAC + disk + motherboard + OS ID.
  2. Aktivasi — install dijalankan → call ke license server dengan machine ID + license key.
  3. License file — server return file (signed, encrypted) yang valid untuk machine ID itu.
  4. Verifikasi — saat startup dan berkala (misal harian). License file dicek signature + expiry.

Aturan implementasi:

  • Signature pakai public-key crypto (RSA / Ed25519). Public key di app, private key di server.
  • Allow offline grace period (7-30 hari). Tidak semua user selalu online.
  • Reactivation flow yang reasonable kalau ganti mesin / format ulang.

Lima Layer Proteksi Kode

Layer Cara Effort
1. Business Harga wajar, value di server, frequent updates, support yang ramah, fokus B2B (mereka tidak crack license company) Tinggi value, low effort
2. Legal EULA jelas, daftar hak cipta, trademark, takedown DMCA Medium
3. Obfuscation Minification → obfuscation → bytecode compilation. Mempersulit reverse engineering, tidak menghentikan determined attacker Low effort
4. Runtime Integrity check (hash file sendiri), anti-debug (cek debugger), distributed license check (panggilan random ke server), delayed response (kalau invalid, jangan crash langsung — return data busuk perlahan) High effort
5. Architecture Critical logic di server (anda tidak kirim source/binary), feature flags, partial processing di server, encrypted model High effort, paling efektif

Prinsip Proteksi

Aturan Penjelasan
Jangan over-engineer di awal 99% user jujur. Fokus ke produk bagus + harga wajar.
Determined attacker akan crack apapun Game industry pakai DRM paling mahal, masih di-crack day-one.
Proteksi sophisticated setelah produk laku Crack target audience = produk yang sudah punya value. Sebelum laku, crack tidak relevan.
B2B lebih aman dari B2C Perusahaan tidak crack software karena legal exposure. Focus B2B = proteksi berkurang.
SaaS model paling aman Tidak ada binary yang dikirim. Tidak ada yang di-crack.

Distribusi

Channel Cocok untuk
Website langsung Desktop / mobile sideload. Full control.
App Store / Play Store Mobile. 30% cut tapi distribusi luas + payment built-in.
Microsoft Store / Mac App Store Desktop. 15-30% cut, less reach dari direct.
GitHub Releases Open source, technical audience.
Reseller / Channel partner B2B enterprise. Cut bervariasi.

Sumber Pendalaman

  • The Choose Your Own License — overview model lisensi software. https://choosealicense.com
  • Software Freedom Law Center — guides on open source licensing. https://www.softwarefreedom.org
  • Software Licensing for Beginners di IndieHackers dan ProductHunt makers.
  • Cryptlex, Keygen, LicenseSpring — service untuk license management (kalau tidak mau build sendiri).
  • Indonesian Trademark database (DJKI). https://www.dgip.go.id

Konsep Inti

Untuk bisnis software di Indonesia, anda harus pilih bentuk badan usaha + paham pajak + paham kontrak. Tidak perlu jadi pakar — cukup tahu kapan butuh konsultan.

Catatan: Bagian ini bukan nasihat hukum. Konsultasi ke advokat/notaris untuk implementasi spesifik. Sumber primer di akhir.

Badan Usaha Indonesia

Bentuk Cocok untuk Karakteristik
Perorangan / UD Revenue rendah, single founder, low risk Tidak ada pemisahan aset pribadi & bisnis. Pajak: PPh OP.
CV (Commanditaire Vennootschap) Multi founder, revenue medium Sekutu aktif & pasif. Tidak terpisah dari pribadi sekutu aktif. Pajak: PPh OP sekutu.
PT (Perseroan Terbatas) Target B2B, planning growth, butuh kredibilitas Badan hukum terpisah. Pemisahan aset. Pajak: PPh Badan 22% (atau Final UMKM 0.5%).
PT PMA Foreign investor Investasi asing, butuh persetujuan BKPM.
Persero Perorangan (PP) Solo founder yang ingin badan hukum tapi simpel Hybrid antara perorangan & PT. Diperkenalkan via UU Cipta Kerja.

Rule of Thumb

  • Revenue < Rp 100 juta/tahun → Perorangan cukup.
  • Rp 100 juta - 500 juta → CV atau Persero Perorangan.

  • Rp 500 juta atau target B2B serius → PT.

  • Target investor / equity raise → langsung PT.

Pajak

PPh (Pajak Penghasilan)

Skema Tarif Berlaku untuk
PPh Final UMKM 0.5% dari omzet Wajib pajak dengan peredaran bruto < Rp 4.8 miliar/tahun, max 7 tahun untuk OP, max 4 tahun untuk PT. Dasar: PP 23/2018 jo PP 55/2022.
PPh OP Progresif 5%-35% Orang pribadi yang tidak pakai final UMKM atau lewat 7 tahun
PPh Badan 22% PT yang tidak pakai final UMKM. Diskon 50% untuk omzet ≤ Rp 50 miliar (efektif 11% untuk bagian ≤ Rp 4.8 miliar).

PPN (Pajak Pertambahan Nilai)

  • Wajib kalau peredaran bruto > Rp 4.8 miliar (pengusaha kena pajak / PKP).
  • Tarif: 11% (per April 2022, akan naik ke 12% per Januari 2025 berdasarkan UU HPP).
  • Untuk ekspor jasa digital, sering 0%.

Praktis Solo Dev

  • Pisahkan rekening bisnis & pribadi sejak hari 1. Sangat penting saat audit.
  • Catat semua transaksi — pakai apps akuntansi (Jurnal, Kledo, Mekari) atau spreadsheet disiplin.
  • Konsultan pajak mulai bermanfaat saat revenue > Rp 100 juta/tahun. Sebelum itu, baca peraturan langsung + tanya komunitas.
  • Lapor pajak tepat waktu — denda terlambat menumpuk.

Kontrak

EULA (End User License Agreement)

Untuk B2C software. Klausul minimal:

  • Hak penggunaan (lisensi: non-exclusive, non-transferable, revocable)
  • Batasan (no reverse engineer, no redistribute)
  • Garansi (limited warranty, “as is”)
  • Limitation of liability
  • Terminasi
  • Jurisdiksi & hukum yang berlaku (umumnya Indonesia + arbitrase BANI atau pengadilan)

PKS (Perjanjian Kerja Sama) — B2B

Untuk klien B2B. Klausul kunci:

  • Scope of work (SOW) — detail!
  • Timeline & milestone
  • Payment terms (DP, termin, due date)
  • Acceptance criteria
  • Warranty & support period
  • IP ownership (siapa pemilik kode setelah delivery?)
  • Confidentiality
  • Termination clause
  • Force majeure

SLA (Service Level Agreement)

Untuk SaaS B2B. Spesifikasi service level:

  • Uptime guarantee (99.5%, 99.9%, 99.99% — tiap “9” tambahan = effort eksponensial)
  • Response time untuk support ticket per severity
  • Maintenance window
  • Penalty / credit kalau SLA missed

NDA (Non-Disclosure Agreement)

Untuk pre-engagement / partnership. Mutual NDA = aman untuk kedua pihak. Biasanya 2-3 tahun period.

Invoice / Faktur

Wajib mengandung:

  • Nomor invoice unik (sequential)
  • Tanggal
  • Detail penjual & pembeli (NPWP kalau ada)
  • Detail jasa/produk
  • Subtotal, PPN, total
  • Rekening pembayaran
  • Due date
  • Untuk PKP: faktur pajak dengan nomor seri faktur (NSFP)

Sumber Pendalaman (Sumber Primer)

  • UU 40/2007 Perseroan Terbatas — basis hukum PT. https://peraturan.bpk.go.id
  • UU 11/2020 Cipta Kerja - digantikan dengan Undang-undang Nomor 6 Tahun 2023 tentang Penetapan Peraturan Pemerintah Pengganti Undang-undang Nomor 2 Tahun 2022 tentang Cipta Kerja menjadi Undang-undang. + peraturan turunan — perubahan banyak hal termasuk Persero Perorangan.
  • UU 28/2007 KUP (Ketentuan Umum Perpajakan). https://peraturan.bpk.go.id
  • UU 36/2008 PPh + UU HPP (UU 7/2021). https://peraturan.bpk.go.id
  • PP 23/2018 jo PP 55/2022 — PPh Final UMKM.
  • KUHPerdata untuk dasar kontrak.
  • DJP (Direktorat Jenderal Pajak) — semua peraturan pajak. https://www.pajak.go.id
  • OSS RBA — pendaftaran usaha. https://oss.go.id

Catatan: harap diperiksa kembali keberlakuannya karena peraturan dapat berubah sewaktu-waktu.

Sumber Pendalaman (Sumber Sekunder)

8.5 Marketing untuk Developer Solo

Konsep Inti

Sebagai solo dev tanpa budget besar, marketing bukan ad-spend tapi content + community + product-led growth. Strategi yang sustainable jangka panjang, bukan growth hacking.

Empat Channel Utama

Content Marketing

  • Blog tentang MASALAH (bukan produk). User cari “cara X”, bukan “produk Y”.
  • Video demo — pendek (60-90 detik), tunjukkan hasil cepat.
  • Posting sosmed — di mana audience anda ada. LinkedIn untuk B2B Indonesia. Twitter/X untuk tech audience. TikTok/Instagram untuk B2C.
  • Newsletter — owned channel, tidak tergantung algoritma platform.

Community

  • Hadir di forum/chat komunitas relevan (Discord, Telegram, Reddit, Stack Overflow, Indonesian dev community).
  • Bantu genuine dulu, baru promosi. Aturan tak tertulis di hampir semua komunitas.
  • Build in public — share progress, learnings, failures. Vulnerability membangun trust.

Product-Led Growth

  • Free trial tanpa kartu kredit — friction nol untuk coba.
  • Freemium tier dengan limit yang membatasi tapi tidak menyiksa.
  • Referral program — discount untuk referrer + referee.
  • Embed-able / shareable output — setiap kali user share output, brand anda viral.

SEO

  • Long-tail keyword — “cara mengonversi dokumen DOCX ke PDF di Linux” lebih achievable dari “PDF converter”.
  • Content depth — Google reward konten panjang & informatif.
  • Internal linking disiplin.
  • Page speed sebagai ranking factor (lihat Bagian 5.2).

Landing Page Anatomy

[Hero]
  - Headline yang clearly state value (5-9 kata)
  - Sub-headline yang elaborate
  - CTA primer ("Coba Gratis", bukan "Pelajari Lebih Lanjut")
  - Demo video / GIF / animated screenshot

[Problem section]
  - "Apakah anda mengalami...?"
  - Identifikasi pain dengan empati

[Solution section]
  - "Inilah yang kami buat untuk anda"
  - Connect ke pain di atas

[Features]
  - 3-6 feature blocks
  - Tiap block: ikon + judul + 1-2 kalimat
  - Bukan list semua feature; pilih top 6

[Social proof]
  - Testimonial dengan nama + foto + perusahaan
  - Logo customer (kalau ada)
  - Metric ("digunakan 1000+ pengguna")

[Pricing]
  - 3 tier (lihat 8.2)

[FAQ]
  - 5-10 pertanyaan paling umum

[Final CTA]
  - Ulang CTA hero
  - Atau "Talk to founder" untuk B2B

Marketing Indonesia: Catatan Konteks

  • Trust barrier tinggi di sektor sensitif (finansial, hukum, kesehatan). Legitimacy proxy penting: PSE Kominfo registration, partnership asosiasi, foto founder, foto kantor (kalau ada).
  • Bukti sosial lokal lebih kuat dari international. “Digunakan 100 UMKM Indonesia” > “Used by Fortune 500”.
  • WhatsApp + Telegram sebagai customer touchpoint hampir wajib untuk B2C/SMB. Email kurang responsif di market Indonesia.
  • LinkedIn untuk B2B Indonesia sangat efektif (vs di US di mana banyak orang abandon LinkedIn).

Sumber Pendalaman

  • April Dunford — Obviously Awesome (buku, 2019). Positioning untuk product founder.
  • Traction oleh Gabriel Weinberg & Justin Mares (buku, 2015). 19 channel framework.
  • Patrick McKenzie (patio11) — banyak essay tentang B2B marketing untuk small software. https://www.kalzumeus.com
  • ProductHunt launch guide — kalau target US/global. https://www.producthunt.com/launch
  • Indonesian: kompasiana, sub-reddit Indonesian dev, komunitas Indonesia tech di LinkedIn.

8.6 Customer Support Workflow

Konsep Inti

Customer support yang baik adalah retention engine. Untuk solo dev, struktur self-service yang kuat menangani 70-80% pertanyaan tanpa intervensi manusia.

Struktur Tiga Tingkat

Level Channel Target volume Response time
L1 — Self-service FAQ, manual, in-app help, chatbot AI 70-80% Instan
L2 — Async Email, support ticket, contact form 15-25% < 24 jam (1 hari kerja)
L3 — Direct WhatsApp, call, video meeting 5-10% < 4 jam untuk paid tier

Prinsip Self-Service

  • Setiap support ticket → kandidat FAQ. Kalau pertanyaan sama muncul 3x, wajib masuk dokumentasi.
  • Onboarding yang baik mengurangi 50% pertanyaan. Tooltips, empty state, contextual help.
  • Chatbot AI bukan pengganti support manusia — pengganti search. Harus ada escalation ke manusia kalau bot tidak bisa.

Bug Report Workflow

Customer lapor bug
    ↓
Auto-response (sudah diterima, akan di-process)
    ↓
Kategorisasi:
  - P0 (urgent, blocker, security) → respons < 2 jam
  - P1 (high, fitur penting rusak) → respons < 24 jam
  - P2 (medium, workaround ada) → respons < 1 minggu
  - P3 (low, cosmetic) → backlog
    ↓
Minta info tambahan kalau kurang (bug report template)
    ↓
Reproduksi di environment dev
    ↓
Instruksi ke agent untuk fix
    ↓
Test fix
    ↓
Release patch (per cadence di Bagian 7.4)
    ↓
Notifikasi customer + release notes

Template Respons

Siapkan template untuk situasi rutin (di support/templates/):

Template Use case
bug-report-received.md Auto-response saat bug report masuk
bug-fixed.md Notifikasi setelah patch rilis
feature-request-acknowledged.md “Kami catat, akan dievaluasi di roadmap”
feature-request-declined.md “Tidak masuk roadmap karena X, alternatif: Y”
license-expired.md Reminder pembayaran subscription
refund-request.md Sesuai policy refund
account-deletion.md Konfirmasi penghapusan + retention period
service-outage.md Status update saat downtime

Template bukan boilerplate yang dikirim mentah-mentah. Customize per case, tapi struktur dari template hemat waktu.

Tools

Kategori Tool
Help desk Helpscout, Zendesk, Freshdesk (enterprise); Crisp, Plain (modern SaaS)
Self-hosted Zammad, FreeScout
Knowledge base MkDocs / Docusaurus (free, lihat 7.6); Helpscout Docs, Intercom
In-app help Intercom, Crisp, Plain widget
Live chat Crisp (free tier), Tawk.to (free), Intercom
Status page Statuspage.io, Instatus, Atlassian Statuspage

Aturan untuk Solo Dev

  • Set support hours — tidak harus 24/7. “Senin-Jumat 9-17 WIB” itu OK.
  • Office hours mingguan — slot kalendar untuk video call dengan customer. Lebih efisien dari async kalau masalah kompleks.
  • Quarterly retrospective — review semua support ticket, identifikasi pattern, fix di produk.
  • Automate sebelum hire — sebelum hire support, automate semua yang bisa.

Sumber Pendalaman

  • Delivering Happiness oleh Tony Hsieh (Zappos founder, 2010). Filosofi customer service obsessive.
  • The Effortless Experience oleh Matthew Dixon et al. (2013). Mengurangi friction lebih efektif dari “wow” moment.
  • Helpscout — banyak free content tentang support best practice. https://www.helpscout.com/blog/
  • Support Operations Handbook oleh Plain. https://www.plain.com/support-operations-handbook

8.7 Cost Management

Konsep Inti

Sebagai solo dev, biaya yang tidak di-track akan mengejutkan anda. Cost management yang baik = revenue lebih banyak yang masuk kantong + decision lebih informed.

Kategori Biaya

Development (Satu Kali)

Item Range (Rupiah)
Hardware (kalau belum punya) 15-50 juta
Domain & branding 1-5 juta
Legal (PT setup, EULA review) 3-10 juta
Tools setup awal (subscription tahunan) 2-5 juta
Total ~20-70 juta

Operasional (Bulanan)

Item Range (Rupiah)
Listrik & internet 300-800K
Tools subscription (IDE, design, monitoring) 500K-2 juta
Backup off-site / cloud storage 100-500K
Domain renewal (amortized) 50-200K
LLM API (kalau pakai) 500K-10 juta (depends on usage)
Hosting / VPS / cloud 500K-5 juta
Total self-hosted MVP ~Rp 2-5 juta/bulan

Per Customer (Variable)

Item Estimasi
Support time Rp 30-100K (1-2 jam @ rate anda × frekuensi)
Cloud API (LLM/embed/storage) Rp 50-200K
Payment processing fee 2-3% transaction
Total per active customer ~Rp 100-300K/bulan

Optimasi AI Cost

Untuk app yang heavy LLM:

Teknik Savings
Prompt caching 30-50% reduction. Anthropic, OpenAI, Google support.
Model tiering Simple task → smaller/cheaper model. Complex → larger. 40-60% savings.
Context window optimization Send less context. Smart retrieval, summary. 50-75% savings.
Batch processing Untuk non-realtime task: batch API 50% diskon di Anthropic & OpenAI.
Streaming + early stopping Stop generation kalau user dismiss.
Fine-tuning vs prompting panjang Untuk task repetitif, fine-tune model kecil bisa lebih murah long-term.
Local model Untuk volume tinggi + privacy requirement. Trade-off: hardware investment + ops overhead.

Unit Economics

Formula dasar:

Revenue per customer - Cost per customer = Margin per customer

Target healthy SaaS:

  • Gross margin 70-85% untuk software.
  • CAC (Customer Acquisition Cost) payback < 12 bulan.
  • LTV:CAC ratio > 3:1.

Break-even:

Break-even = Biaya tetap / Margin per customer

Contoh: biaya tetap Rp 5 juta/bulan, margin per customer Rp 200K/bulan → break-even di 25 customer aktif.

Cost Tracking

Buat COST-TRACKING.md (di docs/) atau spreadsheet:

# Cost Tracking — Mei 2026

## Budget vs Actual
| Kategori | Budget | Actual | Variance |
|---|---|---|---|
| Tools subscription | 1.5jt | 1.7jt | +200K (added Linear) |
| LLM API | 2jt | 2.8jt | +800K (usage spike) |
| Hosting | 800K | 800K | OK |

## Revenue per Tier
| Tier | Customer | MRR |
|---|---|---|
| Pro | 12 | 2.4jt |
| Business | 3 | 1.5jt |
| Total | 15 | 3.9jt |

## Unit Economics
- ARPU: Rp 260K
- CAC: Rp 800K (estimasi)
- Payback period: 3 bulan
- LTV (12mo retention assumption): Rp 3.1jt
- LTV:CAC: 3.9:1 ✓

Anti-Pattern Cost Management

  • Tidak track sama sekali — tiba-tiba kehabisan dana.
  • Track terlalu detail — perfectionism yang menghabiskan waktu.
  • Over-invest tools — banyak tool $10-50/bulan menumpuk jadi 5 juta/bulan.
  • Ignore unit economics — scale customer tanpa tahu margin = scale loss.

Sumber Pendalaman

BAGIAN 9 — PERTUMBUHAN

Setelah produk live dan ada customer. Fokus geser dari “build” ke “improve & expand”.

9.1 Feedback Loop

Konsep Inti

Feedback loop = sistem mengumpulkan input dari user → prioritisasi → eksekusi → measure → ulang. Tanpa sistem, anda akan kerja berdasar suara terkeras (bukan masalah terbesar).

Channel Feedback

Channel Karakteristik
In-app feedback Tombol “Send feedback” di app. Rating per fitur. Survey bulanan (NPS, CSAT).
Support ticket analysis Issue yang sering muncul = product gap.
Usage analytics Mana fitur dipakai, mana yang ditinggal. Privacy-respecting (lihat 5.5).
Direct conversation Wawancara 10 customer teratas setiap bulan. Mahal tapi insight tertinggi.
Sosmed listening Twitter, LinkedIn, Reddit — orang complain di publik.
Churn interview Wawancara yang baru cancel. Ouch tapi gold.

Prioritisasi: RICE Score

Untuk setiap feature request / bug:

RICE = (Reach × Impact × Confidence) / Effort
Komponen Definisi Skala
Reach Berapa user terkena dampak per quarter Angka real
Impact Seberapa besar dampak per user 0.25, 0.5, 1, 2, 3
Confidence Seberapa yakin estimasi Reach × Impact benar 50%, 80%, 100%
Effort Person-month untuk implementasi Angka

Score tertinggi = dikerjakan duluan. Bagus untuk debat objektif vs “menurut gue”.

Feedback Database (FEEDBACK-LOG.md)

## F-042: Export to PDF

**Source**: 3x support ticket, 1x sosmed mention
**Date logged**: 2026-05-10
**Category**: Feature request
**Dampak**: User saat ini copy-paste manual ke Word
**RICE**:
  - Reach: 200 (mostly Pro tier)
  - Impact: 2 (significant)
  - Confidence: 80%
  - Effort: 0.5 month
  - **Score: 640**
**Status**: Backlog, target Q3 2026
**Related ISSUES**: ISSUE-038, ISSUE-045
**Response template**: feature-request-acknowledged.md

Anti-Pattern

  • Feature creep dari customer paling vocal — bias ke yang teriak, bukan ke majority needs.
  • Track feedback tapi tidak action — credibility hancur. Better tracking sedikit + action.
  • Tidak follow-up ke pelapor — saat fitur live, beri tahu mereka. Loyal customer.

Sumber Pendalaman

9.2 Roadmap Planning

Konsep Inti

Roadmap adalah komunikasi arah (bukan janji deadline). Pemula bikin roadmap dengan tanggal spesifik, lalu missed → trust hancur. Solusi: time horizon kategori, bukan tanggal.

Time Horizon Framework (Now-Next-Later-Future)

Horizon Detail level Cocok untuk
NOW (minggu ini, bulan ini) Sangat spesifik, granular task Sprint planning
NEXT (1-3 bulan) Cukup detail, sudah scoped Quarterly planning
LATER (3-6 bulan) Gambaran besar, area, bukan fitur spesifik Half-year planning
FUTURE (6-12+ bulan) Sangat high-level, exploration ideas Vision

Prinsip Sharing Roadmap

  • Share NOW dan NEXT publik — customer butuh visibilitas.
  • Share LATER dengan caveat — “tentative, akan berubah”.
  • Jangan share FUTURE — masih banyak pivot, customer dapat ekspektasi salah.
  • Update bulanan — roadmap stale = jelek.

Balance Allocation

Aturan klasik untuk solo dev / small team:

Kategori Allocation
Bug fix 30-40%
Fitur baru 30-40%
Improvement / refactor 15-25%
Tech debt / infra 10-15%
Exploration 5-10%

Adjust per fase. Saat product-market fit fase: 50% feature. Saat mature: 50% improvement & infra.

Under-Promise, Over-Deliver

  • Estimasi sendiri, lalu kalikan 1.5x sebelum sharing public. Solo dev cenderung optimis.
  • Buffer untuk hal tidak terduga — selalu ada.
  • Jangan commit deadline kalau tidak yakin 90% — kasih range (“Q3 2026”) bukan tanggal (“15 Juli 2026”).

Roadmap Tools

Tool Cocok untuk
Notion / GitHub Projects Free, lightweight
ProductBoard / Productboard Roadmap dengan feedback link
Aha! Enterprise roadmap
Linear Modern dev roadmap, integrate dengan kode
Markdown file di repo (ROADMAP.md) Paling sederhana, version controlled

Sumber Pendalaman

  • C. Todd Lombardo et al. — Product Roadmaps Relaunched (buku, 2017).
  • Janna Bastow — Now-Next-Later Roadmap framework. https://www.prodpad.com
  • Marty Cagan — banyak essay tentang roadmap di SVPG. https://www.svpg.com
  • Atlassian — Roadmap templates dan guide.

9.3 Competitor Analysis

Konsep Inti

Analisis kompetitor bukan untuk copy, tapi untuk positioning. Pahami market landscape supaya tahu di mana anda fit dan apa differentiator anda.

Framework Analisis

Identifikasi Kompetitor

Tipe Definisi Contoh untuk legaltech Indonesia
Langsung Produk sejenis untuk audience sama LegalTracker, ContractbookID
Tidak langsung Solusi berbeda untuk masalah sama Excel + Google Drive (manual workflow)
Substitute Cara alternatif menyelesaikan job-to-be-done Hire associate / paralegal manual

Jangan abaikan substitute — “Excel” sering jadi pesaing utama tanpa disadari.

Data per Kompetitor

## Competitor: ContractbookID

**Website**: ...
**Pricing**: Rp X/bulan per user
**Target market**: Mid-size law firm Indonesia
**Funding stage**: Series A
**Team size**: ~50

### Kelebihan
- Brand awareness tinggi di Jakarta
- Integration dengan dokumen Microsoft

### Kekurangan
- Tidak support bahasa selain ID & EN
- UI klutsy untuk legal-specific workflow
- Tidak ada API untuk integrasi

### Gap yang bisa diisi
- Workflow yang lebih spesifik untuk litigasi (bukan corporate)
- API untuk integrasi sistem internal firm

Competitive Matrix

Fitur Anda Kompetitor A Kompetitor B Substitute
Search semantic ✓ ✗ ✓ ✗
API access ✓ ✗ ✗ ✗
Offline mode ✓ ✗ ✗ ✓ (manual)
Pricing Mid High Low Low (time-cost)
Onboarding < 30 min ✓ ✗ ✓ N/A

Identifikasi celah — fitur yang hanya anda support, atau yang anda lebih baik signifikan.

Differentiation Strategy

Pilih 1-2 keunggulan utama:

Strategi Penjelasan
Feature Anda satu-satunya yang punya X
Price Lebih murah signifikan (hati-hati race to bottom)
Market Niche spesifik (bukan “untuk semua firma” tapi “untuk firma litigasi PKPU”)
Experience UX/setup time / support kualitas
Trust Compliance certification (PSE, ISO), founder kredibilitas
Speed Faster solution di task spesifik

Aturan: lebih baik TERBAIK di 1-2 hal daripada LUMAYAN di 10 hal. Specificity menjual.

Positioning Statement

Template:

[Produk] adalah satu-satunya [kategori] yang [keunggulan unik]
untuk [target market spesifik], tidak seperti [kompetitor utama]
yang [kekurangan mereka yang relevan ke audience anda].

Contoh:

LexHarmoni adalah satu-satunya AI regulatory stress-testing tool
yang dibangun khusus untuk regulasi keuangan Indonesia, untuk firma
hukum boutique sektor finansial, tidak seperti tool legaltech generik
yang gagal menangkap nuansa POJK & PBI cross-referencing.

Sumber Pendalaman

  • April Dunford — Obviously Awesome (sudah disebut di 8.5). Best book on positioning.
  • Geoffrey Moore — Crossing the Chasm (1991, terus revisi). Tech market positioning klasik.
  • Al Ries & Jack Trout — Positioning: The Battle for Your Mind (1981). Foundational positioning book.
  • Crunchbase, Producthunt — tool research kompetitor & funding.
  • SimilarWeb, Semrush — traffic & SEO analysis kompetitor.

9.4 Community Building

Konsep Inti

Community bukan strategi marketing dengan ROI cepat. Ini long-term investment untuk membangun ecosystem di mana user saling bantu, dan brand anda jadi default di category.

Tiga Fase Community

Fase Size Approach
Phase 1 — Seeding 0-50 orang Personal outreach, exclusive access, direct communication. WhatsApp/Telegram group kecil. Anda tahu nama setiap orang.
Phase 2 — Growth 50-500 orang Public community (Discord/forum/Slack). Content reguler (blog, newsletter). Recognize early contributors.
Phase 3 — Self-Sustaining 500+ orang User-generated content. Community events (meetup, conference). Ambassador / champion program. Moderation team.

Aktivitas per Fase

Phase 1

  • DM ke 50 calon pengguna ideal. Tawarkan free access dengan condition: feedback rutin.
  • Onboarding 1-on-1 video call.
  • WhatsApp/Telegram group untuk feedback fast turn.
  • Office hours mingguan untuk Q&A.

Phase 2

  • Buat public space (Discord paling umum untuk tech, Telegram untuk Indonesia).
  • Content: weekly newsletter, blog post, demo video.
  • “Customer of the month” — feature use case menarik.
  • Build in public — share metric, learning, failure.

Phase 3

  • Annual user conference / meetup (online OK kalau budget terbatas).
  • Ambassador program — power user dapat perk + advocacy role.
  • Open source contribute path (kalau open core, lihat 9.5).
  • Moderation tim (mungkin volunteer dari community).

Anti-Pattern

  • Membangun community sebelum produk — orang join, tidak ada yang dibahas, dies.
  • Channel terlalu banyak — Discord + Slack + Telegram + Forum. Pilih 1-2.
  • Auto-promote produk anda — community jadi spam. Ratio promosi : value = 1:10 minimum.
  • Tidak active anda sendiri — community dies kalau founder tidak hadir.

Tools

Kategori Tool
Chat platform Discord (tech-friendly, free), Slack (B2B, free tier limit), Telegram (Indonesia native)
Forum Discourse (self-hosted), Circle, Mighty Networks
Newsletter Substack, Beehiiv, Buttondown, ConvertKit
Event Luma, Meetup.com, Eventbrite

Sumber Pendalaman

  • David Spinks — The Business of Belonging (buku, 2021). Community-led growth manifesto.
  • Charles Vogl — The Art of Community (buku, 2016). Lebih konseptual.
  • Community OS — guide oleh Commsor. https://www.commsor.com
  • Rosie Sherry — Rosieland newsletter & resources. https://rosie.land
  • Indonesia: Indonesia Tech Community (Slack), Tech in Asia, DailySocial untuk konteks lokal.

9.5 Open Source Strategy

Konsep Inti

Open source bukan binary “open” vs “closed”. Ada spectrum, dan keputusan strategis tergantung tujuan bisnis.

Model Open Source untuk Produk Komersial

Model Definisi Contoh
Proprietary Kode tertutup. Mungkin ada free tier. Most SaaS
Open Core Core (basic features) gratis dan open source; premium feature proprietary GitLab, Sentry, Cal.com
Source Available Kode bisa dilihat, tapi tidak boleh dijual / kompete. License: BSL, SSPL, FCL. MongoDB (SSPL), HashiCorp (BSL), CockroachDB (BSL)
Fully Open Source OSI-approved license (MIT, Apache 2.0, GPL). Linux, PostgreSQL, React

Decision Framework

Pertanyaan untuk memutuskan:

  1. Apa tujuan strategis? Adoption (open core), trust (open source untuk security audit), community contribution (fully OSS), atau proteksi (proprietary)?
  2. Bisnis model kompatibel? SaaS-only → open source bisa OK (hosting & operations adalah value). On-prem → open source = customer self-host & tidak bayar.
  3. Ada risiko cloud provider mengambil? AWS clone MongoDB → MongoDB ubah ke SSPL. Similar story Elastic, HashiCorp.
  4. Anda siap kerja extra untuk community? Open source = issue PR review, docs maintenance, community management.

Rekomendasi per Fase Bisnis

Fase Rekomendasi
Pre-PMF Proprietary. Fokus 100% pada product, jangan ditarik ke community management.
Post-PMF, growing Evaluate open core kalau strategis untuk adoption / developer mindshare.
Mature, mau expand market Open core untuk accelerate adoption + ecosystem. Premium feature & cloud-hosted untuk monetisasi.

Lisensi Populer (Untuk Reference)

License Karakteristik Use case
MIT Sangat permissive. Boleh dipakai komersial, modifikasi, tidak share back. Default untuk small lib.
Apache 2.0 Permissive + patent grant. Standard untuk corporate OSS. Kafka, Spring, banyak Apache Foundation project.
GPL v3 Copyleft. Derivative work harus juga GPL. Linux kernel.
AGPL Stronger copyleft — termasuk SaaS deployment. MongoDB (sebelum SSPL), some federated apps.
BSL (Business Source License) Source available, restricted commercial, auto-convert ke OSS setelah 4 tahun. HashiCorp (banyak), CockroachDB.
SSPL (Server Side Public License) AGPL extension, copyleft termasuk SaaS infrastructure. MongoDB. Tidak diakui sebagai OSS oleh OSI.

Sumber Pendalaman

9.6 Networking & Partnership

Konsep Inti

Solo dev bukan berarti solo journey. Networking & partnership memperluas reach, kredibilitas, dan kemampuan tanpa harus hire.

Tiga Level Engagement

Level 1 — Online

  • Komunitas developer: GitHub, Stack Overflow, Discord/Slack komunitas, Reddit.
  • Sosmed profesional: LinkedIn (B2B Indonesia), Twitter/X (tech), niche platform per domain.
  • Aturan: bantu dulu (jawab pertanyaan, share insight), baru promosi. Reciprocity rule.

Level 2 — Offline

  • Meetup lokal — search di Meetup.com, komunitas Indonesia tech.
  • Conference — sebagai attendee dulu, baru speaker.
  • Co-working space — co-located builder lebih mudah jadi network.
  • Aturan: datang → dengarkan → kenalan → follow up dalam 48 jam.

Level 3 — Strategic Partnership

Tipe partnership Mekanisme
Technology partner Produk komplementer. Integration. Co-marketing.
Channel / reseller Mereka jual produk anda, dapat komisi 20-40%.
Content partner Reviewer/influencer. Mereka content, anda kasih akses + komisi.
Integration partner Mereka build plugin/integration ke produk anda.
Affiliate Pure performance — bayar per conversion.

Networking Toolkit

Asset Konten
Elevator pitch (30 detik) Problem + solution + differentiator + ask
Demo siap (2 menit) Video atau live, fokus 1 use case kuat
Landing page Untuk send link saat ditanya
Business card (digital + fisik) Indonesia masih ada kebutuhan offline
Follow-up template Email + LinkedIn DM versi short
Calendar booking (Cal.com / Calendly) Reduce friction untuk meeting

Anti-Pattern

  • Hard-sell first interaction — backfire. Build relationship dulu.
  • Tidak follow up — 80% value networking ada di follow up.
  • Spam connect tanpa konteks — LinkedIn DM “Hi, mau jualan X” = ignored.
  • Quantity over quality — 10 relationship dalam = 100 superficial connection.

Sumber Pendalaman

  • Keith Ferrazzi — Never Eat Alone (buku, 2005). Klasik networking.
  • Give and Take oleh Adam Grant (2013). Reciprocity research.
  • Superconnector oleh Scott Gerber & Ryan Paugh (2018).
  • Patrick McKenzie — banyak essay tentang B2B networking & sales untuk introvert solo dev.
  • Indonesia konteks: HKHSK, PERADI (untuk legal); ICCN, Tech in Asia events (untuk tech).

9.7 Scaling dari Solo ke Tim

Konsep Inti

Hire ketika bottleneck bisnis lebih besar dari biaya hire, bukan ketika “anda ingin tim”. Hire prematur = burn rate naik, drama tim, slowdown.

Kapan Hire

Tanda Hire untuk
Support ticket overwhelming, < 24h response sulit Customer support / community manager
Bug menumpuk, fitur baru stagnan Developer (full-stack atau spesifik gap)
Revenue plateau meskipun product solid Marketing / growth
Sales meeting backlog Sales / BD
Anda jadi bottleneck di setiap keputusan Operations / GM

Aturan Praktis Revenue → Tim

Revenue/bulan Setup ideal
< Rp 20 juta Solo
Rp 20-50 juta Solo + 1 freelancer / virtual assistant
Rp 50-100 juta 1-2 full-time + freelancer per kebutuhan
Rp 100-300 juta Tim kecil 3-5 orang
> Rp 300 juta Tim 6+ dengan struktur

Ini guideline, bukan rule. Konteks per industri berbeda.

Hire Sequence Umum

  1. Customer support / VA — tugas repetitif paling mudah delegated. Hire pertama biasanya part-time.
  2. Developer #2 — beri ruang untuk fokus arsitektur & strategy.
  3. Marketing / content — kalau growth jadi bottleneck.
  4. Sales / BD — untuk B2B yang butuh outbound.
  5. Operations — saat orang sudah > 5.

Onboarding Developer Baru

Berkat dokumentasi disiplin (Bagian 2.6, 3, 4), onboarding bisa cepat:

Hari Aktivitas
Hari 1 Baca docs/ lengkap. Setup environment lokal pakai DEV-ENVIRONMENT.md. Verify by running app.
Hari 2 Bug kecil dari ISSUES.md (tag “good first issue”). Review oleh anda.
Hari 3-5 Bug kompleks atau fitur kecil. Familiar dengan codebase.
Setelah minggu 1 Bekerja semi-mandiri. Sync 30-menit harian dulu, lalu kurangi.
Setelah bulan 1 Owner satu modul.

Tanpa dokumentasi, onboarding bisa makan 2-4 minggu dengan banyak handholding.

Anti-Pattern

  • Hire untuk role yang anda belum tahu what good looks like — anda tidak bisa evaluate, end up frustrated.
  • Hire teman tanpa kontrak jelas — friend → enemy fast.
  • No probation period — sulit terminate kalau tidak fit.
  • Equity sebagai pengganti gaji untuk early hire — sering jadi resentment kalau exit gagal.
  • Tim grow > productivity grow — Brooks’ law: adding people to late project makes it later.

Sumber Pendalaman

  • The Hard Thing About Hard Things oleh Ben Horowitz (2014). Real talk tentang scaling.
  • High Output Management oleh Andy Grove (1983). Klasik manajemen.
  • The Manager’s Path oleh Camille Fournier (2017). Untuk yang transition ke management.
  • Patrick McKenzie — Salary Negotiation essay. Untuk hire & negotiate properly. https://www.kalzumeus.com/2012/01/23/salary-negotiation/
  • Rework oleh Jason Fried & DHH (2010). Filosofi small team productive.

BAGIAN 10 — ETHICAL AI & PENUTUP

10.1 Tanggung Jawab Builder AI

Konsep Inti

Sebagai builder produk AI, anda bertanggung jawab atas output produk anda. User bisa membuat keputusan buruk berdasarkan jawaban yang salah. “AI yang salah” bukan alasan — anda yang merilis ke publik.

Tanggung jawab ini tidak bisa di-outsource ke model provider (Anthropic, OpenAI) — mereka kasih tool, anda yang build product.

Domain dengan Stakes Tinggi

Domain Risiko
Hukum Salah interpretasi hukum → user merugikan diri / klien
Medis Salah diagnosa → harm fisik
Finansial Salah saran → kerugian uang
Pendidikan Salah info → misinformation yang merambat
Berita / fakta Hallucination → disinformation

Untuk domain ini, disclaimer + human-in-the-loop wajib, bukan opsional.

10.2 Lima Prinsip Ethical AI

1. Transparency

User harus tahu:

  • Mereka berinteraksi dengan AI (bukan manusia).
  • AI bisa salah, dengan probabilitas tertentu.
  • Sumber jawaban (di mana AI ambil informasi).
  • Limitations (apa yang AI tidak bisa).

Implementasi:

  • Banner “Powered by AI” di entry point.
  • Source attribution di setiap jawaban faktual.
  • Confidence indicator (jika feasible).
  • Clear disclaimer di hasil yang sensitif.

2. Accuracy

AI menolak menjawab kalau tidak tahu, bukan mengarang. Hallucination adalah kegagalan terbesar.

Implementasi:

  • RAG dengan source grounding (jawaban harus link ke chunk sumber).
  • “I don’t know” sebagai valid output (refusal training / prompt).
  • Confidence threshold — di bawah threshold, refuse atau escalate.
  • Fact-checking layer untuk klaim kritis.

3. Fairness

AI tidak boleh bias terhadap kelompok tertentu (gender, ras, agama, status sosial, bahasa, dialek).

Implementasi:

  • Test bias di berbagai bahasa, dialek, topik, perspektif.
  • Eval dataset yang representatif demografi target.
  • Red-team test untuk skenario sensitif.
  • Untuk Indonesia: test di Bahasa Indonesia + Bahasa daerah, perspektif berbagai agama, perspektif berbagai status sosioekonomi.

4. Safety

Mencegah output berbahaya (instruksi kekerasan, self-harm, illegal activity, harm ke minor).

Implementasi:

  • Content filter pada input dan output (Claude punya built-in).
  • Refusal training untuk topik berbahaya.
  • Reporting mechanism untuk user yang temukan output berbahaya.
  • Rate limit untuk cegah abuse / automated harm.

5. Accountability

Saat ada masalah, ada jalur akuntabilitas yang jelas.

Implementasi:

  • EULA jelas — pengguna setuju syarat sebelum pakai.
  • Logging untuk audit trail (siapa minta apa, jawaban apa, kapan).
  • Kill switch — anda bisa segera matikan fitur kalau ada incident.
  • Incident response plan — siapa lapor ke siapa, dalam berapa jam.
  • User feedback channel — laporan harm ditangani serius.

10.3 Implementasi Praktis Ethical AI

Per Halaman Output

[Jawaban AI]

---
⚠ Hasil ini di-generate oleh AI dan bisa salah.
📚 Sumber: [link ke dokumen sumber]
🎯 Confidence: 78%
👤 Untuk keputusan penting, konsultasikan dengan ahli.
[Tombol: Apakah jawaban ini akurat? ✓ / ✗]

Di Architecture

  • Audit log untuk setiap query AI: timestamp, user, input, output, model version, latency.
  • Versioning prompt dan model (lihat 6.3.3).
  • Eval pipeline terus berjalan (lihat 6.3.2) — kalau quality regress, anda tahu duluan.
  • Refuse list — daftar topik di mana AI auto-refuse jawab.
  • Human escalation path — saat AI tidak yakin, route ke human reviewer.

Sumber Pendalaman

APPENDIX

Appendix A — Struktur Folder docs/ Lengkap

Reference struktur folder yang ideal untuk proyek matang. Tidak perlu semua sejak awal — tambah saat butuh.

project/
├── docs/
│   ├── PROJECT.md                      problem, persona, stories, flow
│   ├── ARCHITECTURE.md                 C4 diagrams, service map, tech stack
│   ├── DATA-FLOW.md                    alur data antar component
│   ├── DATA-MODEL.md                   skema database
│   ├── INTEGRATION-CONTRACTS.md        API contract antar service
│   ├── NFR.md                          non-functional requirements
│   ├── CAPACITY-PLAN.md                resource budget per service
│   ├── FAILURE-MODES.md                failure mode analysis & mitigasi
│   ├── SECURITY.md                     threat model
│   ├── DEPENDENCY-POLICY.md            aturan pilih library
│   ├── DECISIONS.md                    ADR (atau folder docs/adr/)
│   ├── MILESTONES.md                   breakdown milestone
│   ├── MAP.md                          peta kode + file kunci
│   ├── CONVENTIONS.md                  aturan penulisan kode
│   ├── DEV-ENVIRONMENT.md              setup dari nol
│   ├── CONTEXT.md                      status proyek (update setiap sesi)
│   ├── ISSUES.md                       tracking masalah
│   ├── CHANGELOG.md                    riwayat perubahan per milestone
│   ├── GOTCHAS.md                      jebakan teknis yang ditemukan
│   ├── HANDOVER.md                     template prompt handover
│   ├── PROMPTS.md                      template prompt harian
│   ├── REVIEW-CHECKLIST.md             checklist evaluasi per milestone
│   ├── RELEASE-CHECKLIST.md            checklist rilis
│   ├── OBSERVABILITY.md                metrics, logging, alerting setup
│   ├── INCIDENT-RESPONSE.md            prosedur saat incident
│   ├── BACKUP.md                       strategi backup
│   ├── DISASTER-RECOVERY.md            prosedur recovery
│   ├── MIGRATIONS.md                   rencana migrasi data
│   ├── MODEL-REGISTRY.md               perbandingan model AI (kalau RAG/AI)
│   ├── VERSIONING.md                   aturan semantic versioning
│   ├── ACCESSIBILITY-AUDIT.md          audit aksesibilitas
│   ├── FEEDBACK-LOG.md                 masukan user + RICE score
│   ├── ROADMAP.md                      rencana 3-12 bulan
│   ├── COMPETITOR-ANALYSIS.md          analisis kompetitor
│   ├── COST-TRACKING.md                tracking biaya
│   ├── LICENSING.md                    model bisnis lisensi
│   ├── DISTRIBUTION.md                 cara distribute
│   ├── SECURITY-LOG.md                 riwayat audit security
│   ├── user/                           dokumentasi end user
│   │   ├── quick-start.md
│   │   ├── how-to/
│   │   ├── reference/
│   │   └── troubleshooting/
│   ├── legal/                          legal documents
│   │   ├── EULA.md
│   │   ├── privacy-policy.md
│   │   ├── terms-of-service.md
│   │   └── DATA-INVENTORY.md           (UU PDP compliance internal)
│   ├── support/                        template respons support
│   ├── adr/                            kalau pakai folder ADR terpisah
│   └── checklists/                     checklist per milestone
├── src/                                kode app utama
├── dds/                                Development Debug System (dev only)
├── scripts/                            automation scripts (IaC, backup, dst)
├── eval/                               RAG evaluation pipeline (kalau pakai)
├── migrations/                         database migrations
├── .github/workflows/                  CI/CD
└── knowledge/                          PKM pribadi (lihat 1.2; bisa di repo terpisah)

Appendix B — Glossary Lengkap

Istilah Definisi
a11y Accessibility — disiplin membuat produk dapat diakses oleh semua orang termasuk penyandang disabilitas
ADR Architecture Decision Record — dokumen 1-2 halaman per keputusan struktural
Agent / AI agent Sistem berbasis LLM yang bisa mengambil keputusan dan memanggil tool untuk menyelesaikan tugas multi-langkah
Atomic vertical slice Satu task = satu fitur end-to-end yang testable (UI + API + DB), bukan satu layer
C4 Model Cara mendokumentasikan arsitektur dalam 4 level zoom (Context, Container, Component, Code)
CAC Customer Acquisition Cost — biaya untuk acquire satu customer baru
CI/CD Continuous Integration / Continuous Deployment — otomasi build, test, deploy
Circuit breaker Pattern resilience — berhenti memanggil service yang gagal terus, retry setelah cooldown
CRDT Conflict-free Replicated Data Type — struktur data yang otomatis merge tanpa konflik
CSP Content Security Policy — HTTP header untuk mitigasi XSS
CSRF Cross-Site Request Forgery — serangan di mana request datang dari konteks user authenticated
DDS Development Debug System — aplikasi terpisah yang menangkap error app utama saat development
DFD Data Flow Diagram — visualisasi aliran data di sistem
DPIA Data Protection Impact Assessment — penilaian dampak pemrosesan data pribadi
DPO Data Protection Officer — pejabat yang bertanggung jawab atas compliance privacy
DSR Data Subject Request — permintaan user terkait hak atas data pribadi (akses, hapus, dst)
E2E End-to-End (test) — test yang menjalankan flow lengkap dari UI ke backend ke DB
EULA End User License Agreement — perjanjian lisensi end user
Eval / Evaluation Untuk LLM apps: pipeline pengukuran kualitas output
GFS Grandfather-Father-Son — pattern rotation backup (daily, weekly, monthly)
i18n Internationalization — disiplin merancang app supaya bisa diterjemahkan
IaC Infrastructure as Code — infrastruktur didefinisikan dalam kode/script
IDOR Insecure Direct Object Reference — vulnerability di mana user bisa akses object orang lain dengan ganti ID
JWT JSON Web Token — format token authentication
L1/L2/L3 Support Tingkat support (self-service, async, direct)
l10n Localization — adaptasi konten ke locale spesifik (terjemahan, format)
LLM Large Language Model
LTV Lifetime Value — total revenue dari satu customer sepanjang lifecycle
LWW Last Write Wins — strategi sync paling sederhana, write terakhir menang
MCP Model Context Protocol — standar Anthropic untuk LLM-tool integration
MRR Monthly Recurring Revenue
MVP Minimum Viable Product
NFR Non-Functional Requirements — kebutuhan kualitas (performance, dst), bukan fitur
NPS Net Promoter Score — metrik loyalty 0-10
OTel OpenTelemetry — vendor-neutral observability standard
OWASP Open Web Application Security Project
p50/p95/p99 Latency percentile (median, 95th, 99th)
PII Personally Identifiable Information
PITR Point-In-Time Recovery — restore database ke titik waktu tertentu
PKM Personal Knowledge Management
PMF Product-Market Fit
PSE Penyelenggara Sistem Elektronik (regulasi Kominfo)
PWA Progressive Web App
RAG Retrieval-Augmented Generation — pola RAG: retrieve context → augment prompt → generate
RBAC Role-Based Access Control
RICE Reach × Impact × Confidence / Effort — prioritization framework
RLS Row Level Security — kontrol akses di level baris database
RPO Recovery Point Objective — berapa banyak data acceptable hilang
RTO Recovery Time Objective — berapa lama maksimal downtime acceptable
SBOM Software Bill of Materials — daftar component & dependency software
SDK Software Development Kit
SemVer Semantic Versioning (MAJOR.MINOR.PATCH)
SLA Service Level Agreement
SOW Statement of Work
SQL injection Vulnerability di mana input user di-execute sebagai SQL
SSO Single Sign-On
STRIDE Threat modeling framework (Spoofing, Tampering, Repudiation, Info Disclosure, DoS, Elevation of Privilege)
TLS Transport Layer Security — encryption di transit (HTTPS)
UAT User Acceptance Testing
UU PDP UU 27/2022 Perlindungan Data Pribadi
WAF Web Application Firewall
WCAG Web Content Accessibility Guidelines
XSS Cross-Site Scripting — vulnerability injection script ke halaman

Appendix C — Daftar Sumber Primer Konsolidasi

Buku Fundamental

Topik Buku Author
Software craftsmanship The Pragmatic Programmer (ed. 20) Hunt & Thomas
System design Designing Data-Intensive Applications Martin Kleppmann
Reliability Site Reliability Engineering (free) Google
Microservices Building Microservices (ed. 2) Sam Newman
Production resilience Release It! (ed. 2) Michael T. Nygard
Continuous delivery Continuous Delivery Humble & Farley
DevOps culture The Phoenix Project (novel) + The DevOps Handbook Gene Kim et al.
Observability Observability Engineering Charity Majors et al.
Threat modeling Threat Modeling: Designing for Security Adam Shostack
AI engineering AI Engineering Chip Huyen
ML systems Designing Machine Learning Systems Chip Huyen
Customer development The Mom Test Rob Fitzpatrick
Customer development The Four Steps to the Epiphany Steve Blank
Lean methodology The Lean Startup Eric Ries
Product discovery Inspired Marty Cagan
Continuous discovery Continuous Discovery Habits Teresa Torres
User story User Story Mapping Jeff Patton
Positioning Obviously Awesome April Dunford
Pricing Monetizing Innovation Madhavan Ramanujam
Open source Working in Public Nadia Eghbal
Scaling team The Hard Thing About Hard Things Ben Horowitz
Management High Output Management Andy Grove
Community The Business of Belonging David Spinks
UX Don’t Make Me Think (ed. 3) Steve Krug
UX The Design of Everyday Things Don Norman
Technical writing Docs for Developers Bhatti et al.
PKM Building a Second Brain Tiago Forte
PKM How to Take Smart Notes Sönke Ahrens
Debugging Debugging David J. Agans
Database refactoring Refactoring Databases Ambler & Sadalage
AI ethics Atlas of AI Kate Crawford

Documentation Resmi Wajib

Sumber Primer Regulasi Indonesia

Course Gratis

  • Google Technical Writing One & Two. https://developers.google.com/tech-writing
  • Stanford CS25 — Transformers (YouTube). Modern LLM understanding.
  • MIT 6.824 — Distributed Systems (YouTube). Foundational.
  • freeCodeCamp — banyak full-stack course.
  • The Odin Project — full-stack web dev path.

Komunitas & Blog

Appendix D — Checklist Kesiapan Mulai

Sebelum mulai proyek baru, centang:

□ Saya paham peran agentic engineer (sutradara, bukan aktor) — Bagian 1.1
□ Saya punya sistem PKM (Obsidian atau setara) — Bagian 1.2
□ Saya bisa menulis prompt yang spesifik & dengan batasan — Bagian 1.3
□ Saya tahu cara evaluate output agent tanpa coding — Bagian 1.4
□ Saya punya ide proyek dengan problem statement jelas — Bagian 2.1
□ Saya sudah validasi problem dengan minimal 5 calon user — Bagian 8.1
□ Saya punya akun GitHub & SSH key setup — Bagian 3.1
□ Saya siap meluangkan 2-4 jam untuk perencanaan sebelum coding — Bagian 2
□ Saya paham bahwa 2-5 iterasi per fitur itu NORMAL — Bagian 4.2
□ Saya siap belajar sambil jalan (just-in-time learning)
□ Saya tahu kapan harus konsultasi profesional (legal, security audit, dst)
□ Untuk app touch data pribadi: saya paham UU PDP basics — Bagian 5.5

Kalau semua tercentang → mulai dari Bagian 2 (Perencanaan).

Kalau ada yang belum → kembali ke bagian yang relevant.

Appendix E — Cross-Reference Matrix (Original → Restruktur)

Untuk pembaca yang familiar dengan edisi original (52 topik), berikut pemetaan ke struktur baru.

Topik Original Judul Bab Restruktur
1 Pengenalan Agentic Engineer 1.1
2 Personal Knowledge Management 1.2
3 Prompt Engineering 1.3
4 Evaluasi Output Agent 1.4
5 Technical Writing 1.5
6 Detail Perencanaan 2.1, 2.6
7 Sistem Tracking Masalah 4.3 (dipindah dari planning)
8 Handover ke Agent Lain 4.4 (dipindah dari planning)
9 Arsitektur & Tech Stack untuk Pemula 2.3
10 Perencanaan Lanjutan 2026 2.2 + 2.3
11 Capacity Planning & Failure Mode Analysis 2.4.1, 2.4.2
12 Keamanan (Perencanaan) 2.4.3, 2.4.4
13 UX/UI Design Principles 2.5
14 Accessibility (a11y) 2.5 (digabung dengan UX)
15 GitHub Private Repository 3.1
16 Tahapan Proyek Fullstack 4.1, 4.2
17 Development Debug System 3.4
18 Dampak DDS ke Arsitektur 3.4 (digabung)
19 Debugging Frontend & Backend 3.5
20 CI/CD 3.6
21 DevOps for Solo Developer 7.5 (dipindah ke operations)
22 Debugging 4.6
23 Arsitektur Microservice untuk RAG 6.1
24 Microservice Deep Dive 6.2
25 AI-specific 6.3
26 API Design & Versioning 5.3 (jadi cross-cutting)
27 Edge Computing & Offline Sync 6.5
28 AI Agent Orchestration 6.4
29 Database Migration 7.1
30 Internationalization 5.4 (jadi cross-cutting)
31 Testing Strategy 4.7
32 Proses Eksekusi Detail 4.1, 4.2 (digabung)
33 Performance Optimization 5.2 (jadi cross-cutting)
34 Keamanan (Implementasi) 5.1 (jadi cross-cutting, digabung dengan 12)
35 Versioning & Release Management 7.4
36 Backup, Disaster Recovery & Data Migration 7.2
37 Observability & Monitoring 7.3
38 Documentation for End Users 7.6
39 Lisensi, Distribusi & Proteksi Kode 8.3
40 Pricing Strategy 8.2
41 Legal Basics 8.4
42 Data Privacy & Compliance 5.5 (dipromosikan jadi cross-cutting)
43 Marketing untuk Developer Solo 8.5
44 Customer Support Workflow 8.6
45 Cost Management 8.7
46 Feedback Loop 9.1
47 Roadmap Planning 9.2
48 Competitor Analysis 9.3
49 Community Building 9.4
50 Open Source Strategy 9.5
51 Networking & Partnership 9.6
52 Scaling dari Solo ke Tim 9.7
Penutup Ethical AI Bagian 10 (dipromosikan jadi bagian penuh)

Penambahan di Restruktur (Tidak Ada di Original)

Bab Topik Alasan ditambah
0 Cara Membaca Panduan Meta-doc untuk NotebookLM consumption
0.3 Glossary singkat NotebookLM friendly
3.3 Development Environment Spec Operations critical, sering dilupakan
3.7 Decision Discipline Locked/Pending/Obsolete framework
4.5 Code Review Tiers Eksplisit framework Tier 1-4
5.5 Compliance Indonesia Dipromosikan sebagai cross-cutting concern
6.4 (sub) MCP & Anthropic Agent SDK Modern multi-agent standard
8.1 Pre-Launch Validation Pipeline Validation sebelum spin-off bisnis
Appendix A-E Glossary lengkap, sumber konsolidasi, cross-ref matrix NotebookLM consumption

Restrukturisasi Bagian Tidak Linear di Original

Original Masalah Solusi di Restruktur
Topik 17, 18, 19 (DDS) Bercampur dengan CI/CD, debugging Konsolidasi di 3.4 + 3.5
Topik 5, 8, 38 (documentation) Terpencar 3 tahap 1.5 (foundation), 4.4 (handover), 7.6 (end user) dengan cross-reference
Topik 12 + 34 (security) Split tanpa cross-ref 2.4 (planning) + 5.1 (cross-cutting implementation) dengan referensi eksplisit
Topik 23, 24 (microservice) Di tahap “pembangunan” padahal harusnya arsitektur 6.1 + 6.2 di Bagian Specialized
Topik 21 (DevOps) Di tahap setup, padahal operations Pindah ke 7.5 Operations
Topik 33, 37 (performance + observability) Operations family scattered 5.2 (cross-cutting) + 7.3 (operations)
Topik 7, 8 (issue tracking + handover) Di Tahap B planning, padahal continuous practice 4.3 + 4.4 di Build Loop
Topik 46-48 (feedback, roadmap, competitor) Di Tahap G “pertumbuhan”, padahal mulai sejak discovery 9.1-9.3 di Pertumbuhan TAPI dengan catatan validasi awal di 8.1
Topik 42 (UU PDP) Bagian dari bisnis, padahal cross-cutting 5.5 (cross-cutting concern, sektor-specific masuk)

Appendix F — Tentang Dokumen Ini

Versi: 2.0 (Restruktur) Tanggal: Mei 2026 Format: Markdown untuk konsumsi NotebookLM atau pembacaan langsung Lisensi: Bebas dipakai untuk pembelajaran pribadi

Asal Dokumen

Disusun ulang dari edisi asli “Panduan Lengkap Agentic Engineer 2026 — Dari Nol Sampai Produk” (Maret 2026, 52 topik) yang dihasilkan dari percakapan Ziffan dan Claude.

Perubahan Utama dari Edisi Asli

  1. Restrukturisasi 52 topik linear → 10 bagian (7 linear + 3 cross-cutting + appendix). Lihat Appendix E untuk mapping detail.
  2. Sumber pendalaman per sub-bab — 3-7 referensi primer (buku, dokumentasi resmi, course gratis).
  3. Pemisahan linear path vs cross-cutting concerns — Bagian 5 dan 6 jadi konsep terpisah.
  4. Promotion of compliance Indonesia ke cross-cutting concern (Bagian 5.5) dengan sumber primer ke peraturan.bpk.go.id.
  5. Glossary lengkap + cross-reference matrix untuk NotebookLM searchability.
  6. Validation pipeline ditambah sebagai langkah eksplisit pre-business (Bagian 8.1).

Cara Improve Lebih Lanjut

Sebagai dokumen pembelajaran, panduan ini bisa di-improve dengan:

  • Per-modul deep dive — masing-masing bagian (security, observability, RAG) bisa jadi panduan terpisah dengan lebih banyak contoh kode.
  • Case study Indonesia — apply framework ini ke produk Indonesia real.
  • Integration dengan toolchain modern — Claude Code workflow patterns, MCP server building.
  • Update reguler — referensi peraturan & versi library berubah; review tahunan.

Disclaimer

  • Panduan ini bukan nasihat hukum, pajak, finansial, atau medis. Untuk implementasi spesifik di domain regulasi, konsultasikan dengan profesional yang relevan.
  • Referensi & link valid pada tanggal publikasi. Beberapa mungkin obsolete seiring waktu.
  • Best practice di software engineering terus berevolusi. Tetap kritis dan terus belajar.

dokumen ini hasil Prompt dan diskusi saya dengan Claude Opus 4.7 - Adaptive Thinking via Claude.ai

Akhir dokumen.

Untuk feedback atau update, kembali ke percakapan asli atau session baru dengan upload ulang dokumen ini.