Cara Menulis Spesifikasi yang Baik untuk Agen AI

 (addyosmani.com)
110 poin oleh GN⁺ 2026-01-19 | 2 komentar | Bagikan ke WhatsApp
  • Jika spesifikasi yang sangat besar sekaligus dilempar ke agen coding AI, hasilnya tidak akan berjalan dengan baik; kuncinya adalah menulis spesifikasi yang cerdas
  • Disarankan untuk terlebih dahulu menyajikan visi tingkat tinggi, membiarkan AI mengembangkan rencana detailnya, lalu meninjau rencana dalam Plan Mode secara read-only sebelum beralih ke tahap penulisan kode
  • Hasil analisis terhadap lebih dari 2.500 file konfigurasi agen di GitHub menunjukkan bahwa spesifikasi yang efektif mencakup 6 area inti: Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries
  • Untuk pekerjaan berskala besar, kualitas lebih terjaga jika dipecah menjadi tugas-tugas kecil yang modular alih-alih satu prompt raksasa, dan hanya konteks yang diperlukan untuk tiap tugas yang diberikan
  • Inti dari workflow pengembangan berbasis spesifikasi adalah menanamkan batasan 3 tahap (Always/Ask first/Never), verifikasi mandiri, pengujian kesesuaian, lalu terus menguji, mengulang, dan mengembangkannya

TL;DR

  • Tulislah spesifikasi yang jelas dengan tingkat detail yang tepat (struktur, gaya, pengujian, batasan, dll.)
  • Untuk pekerjaan besar, disarankan memecahnya menjadi unit-unit kecil alih-alih menggunakan satu prompt besar
  • Rencana sebaiknya disusun dulu dalam mode read-only, lalu dieksekusi dan terus disempurnakan

Prinsip inti: menulis spesifikasi yang cerdas

  • Pendekatan sekadar melempar spesifikasi yang sangat besar ke agen AI cenderung gagal karena terbentur batas context window dan attention budget model
  • “Spesifikasi cerdas” adalah dokumen yang memberi arahan jelas kepada agen, tetap berada dalam ukuran konteks yang praktis, dan berevolusi bersama proyek
  • Artikel ini merangkum prinsip-prinsip yang ditarik dari pengalaman menggunakan agen coding seperti Claude Code dan Gemini CLI dalam bentuk sebuah framework

Prinsip 1: berikan gambaran besar lebih dulu, biarkan AI menyusun detail awalnya

  • Daripada mencoba merancang semuanya secara berlebihan sejak awal, mulailah dengan pernyataan tujuan dan beberapa kebutuhan inti yang benar-benar jelas
  • Spesifikasi awal ini diposisikan seperti “product brief”, lalu agen diberi tugas untuk mengembangkannya menjadi spesifikasi detail
  • Agen berbasis LLM cenderung mampu mengisi detail dengan baik ketika instruksi tingkat tinggi jelas, tetapi mudah menyimpang jika misinya kabur
  • Karena itu, yang terpenting adalah menancapkan misi yang jelas sejak awal agar agen tidak kehilangan arah

  • Memanfaatkan Plan Mode

    • Plan Mode di Claude Code adalah mode yang menahan agen dalam kondisi read-only, sehingga ia hanya menganalisis codebase dan menyusun rencana terperinci
    • Setelah masuk ke Plan Mode dengan Shift+Tab dan menjelaskan “apa yang ingin dibuat”, agen akan menelusuri kode yang ada sambil menyusun draf spesifikasi
    • Pada tahap ini, agen juga bisa diminta meninjau arsitektur, best practice, risiko keamanan, hingga strategi pengujian dalam rencana tersebut
    • Plan Mode dipertahankan sampai rencana itu cukup matang dan tidak menyisakan ruang salah tafsir, lalu barulah Plan Mode dimatikan dan masuk ke tahap eksekusi

  • Menggunakan spesifikasi sebagai konteks

    • Spesifikasi yang sudah final disimpan ke file seperti SPEC.md, lalu saat bekerja hanya bagian yang diperlukan saja yang dipilih untuk diberikan kembali ke agen
    • Karena file spesifikasi tetap tersimpan lintas sesi, file itu membantu menambatkan AI pada titik acuan yang sama saat proyek dimulai lagi
    • Ini membantu mengurangi kelupaan yang muncul ketika riwayat percakapan makin panjang atau saat agen dijalankan ulang
    • Seperti tim yang menggunakan PRD (dokumen kebutuhan produk) sebagai acuan bersama, dokumen ini menjadi “satu sumber acuan” yang dirujuk baik oleh manusia maupun AI

  • Tetap berorientasi pada tujuan

    • Spesifikasi tingkat tinggi sebaiknya berfokus pada what/why alih-alih langsung menuliskan seluruh cara implementasinya, sementara how yang konkret ditunda ke belakang
    • Susun seperti user story dan acceptance criteria: “Siapa penggunanya? / Apa yang dibutuhkan? / Seperti apa bentuk keberhasilannya?”
    • GitHub Spec Kit juga menekankan alur “berikan penjelasan tingkat tinggi tentang apa yang dibuat dan mengapa, lalu biarkan agen coding menyusun spesifikasi rinci yang berpusat pada pengalaman pengguna dan kriteria keberhasilan”

Prinsip 2: Strukturkan spesifikasi seperti PRD (atau SRS) profesional

  • Penting untuk memperlakukan spesifikasi AI bukan sebagai kumpulan catatan sederhana, melainkan sebagai dokumen terstruktur dengan bagian yang jelas
  • Bentuk yang komprehensif dan rapi seperti PRD atau dokumen desain sistem sangat cocok untuk AI yang menafsirkan isi secara harfiah
  • Hasil analisis lebih dari 2.500 file konfigurasi agen di GitHub menunjukkan bahwa spesifikasi yang efektif umumnya mencakup 6 area inti

    • 1. Commands

      • Letakkan perintah yang bisa dijalankan di bagian awal dokumen
      • Jangan hanya menulis nama alat, tetapi cantumkan perintah lengkap beserta flag: npm test, pytest -v, npm run build

    • 2. Testing

      • Jelaskan secara spesifik cara menjalankan pengujian, framework yang digunakan, lokasi file test, dan tingkat coverage yang diharapkan

    • 3. Project Structure

      • Bedakan dengan jelas lokasi source code, test, dan dokumentasi
      • Contoh: "src/ untuk kode aplikasi, tests/ untuk unit test, docs/ untuk dokumentasi"

    • 4. Code Style

      • Dibanding menjelaskan style secara panjang lebar, satu snippet kode nyata jauh lebih efektif
      • Sertakan aturan penamaan, standar formatting, dan contoh output yang diinginkan

    • 5. Git Workflow

      • Jika aturan penamaan branch, format commit message, dan persyaratan PR dijelaskan, agen juga akan mengikuti alur tersebut

    • 6. Boundaries

      • Tentukan dengan jelas area yang sama sekali tidak boleh disentuh agen
      • Seperti secret, direktori vendor, konfigurasi production, atau folder tertentu
      • Dalam riset GitHub, “jangan pernah commit secret” terkonfirmasi sebagai batasan berguna yang paling sering muncul

  • Jelaskan stack secara spesifik

    • Jangan menulis secara umum seperti “proyek React”; penting untuk menuliskannya secara spesifik seperti “React 18 + TypeScript + Vite + Tailwind CSS”
    • Versi dan dependensi utama juga harus dicantumkan; spesifikasi yang ambigu pada akhirnya menghasilkan kode yang ambigu

  • Gunakan format yang konsisten

  • Integrasikan spesifikasi ke toolchain

    • Perlakukan spesifikasi bukan sekadar dokumen, melainkan “artefak yang dapat dieksekusi” yang terhubung ke version control dan CI/CD
    • GitHub Spec Kit menggunakan workflow gerbang 4 tahap yang menempatkan spesifikasi di pusat proses engineering
      • Specify: memberikan penjelasan tingkat tinggi tentang apa yang dibuat dan mengapa, lalu coding agent menghasilkan spesifikasi terperinci
      • Plan: menyusun rencana teknis yang mencakup stack yang diinginkan, arsitektur, dan constraint
      • Tasks: memecah spesifikasi dan rencana menjadi unit kerja nyata, lalu menguraikan masing-masing ke ukuran yang bisa diuji
      • Implement: coding agent mengerjakan task satu per satu, atau secara paralel

  • Persona khusus melalui agents.md

    • Pada alat seperti GitHub Copilot, Anda dapat mendefinisikan persona agen yang terspesialisasi
    • Peran dapat dipisahkan seperti @docs-agent (dokumentasi teknis), @test-agent (QA), @security-agent (code review)
    • Setiap file agents.md berfungsi sebagai spesifikasi terfokus yang memuat cara kerja, perintah, dan batasan untuk persona tersebut

  • Mendesain Agent Experience (AX)

    • Seperti API dirancang sesuai developer experience (DX), spesifikasi juga perlu dirancang dengan mempertimbangkan agent experience (AX)
    • Format yang rapi dan mudah diparse itu penting
      • Skema OpenAPI untuk API yang akan digunakan agen
      • Ringkasan dokumentasi untuk konsumsi LLM (llms.txt)
      • Definisi tipe yang eksplisit
    • Semakin spesifikasi mengikuti standar seperti MCP (Model Context Protocol), semakin stabil agen memahaminya dan bertindak

  • Pertahankan sebagai dokumen hidup

    • Spesifikasi bukan dokumen yang ditulis sekali lalu selesai, tetapi harus terus diperbarui setiap kali keputusan dibuat bersama AI atau fakta baru terungkap
    • Dalam workflow berbasis spesifikasi, spesifikasi memandu implementasi, pengujian, dan pemecahan task, dan tahap berikutnya tidak dijalankan sebelum spesifikasi tervalidasi
    • Spesifikasi ini bukan dokumen hanya untuk AI, melainkan alat inti bagi developer untuk mengawasi keseluruhan alur dan memastikan hasil AI benar-benar memenuhi kebutuhan nyata

Prinsip 3: Pecah tugas menjadi prompt dan konteks yang modular

  • Alih-alih memasukkan semuanya ke dalam satu prompt raksasa, berikan konteks agar agen hanya fokus pada satu tugas dalam satu waktu
  • Jika kebutuhan, kode, dan instruksi seluruh proyek dimasukkan ke satu prompt, hal itu justru mudah menambah kebingungan
  • Bukan hanya berisiko terkena batas token, "curse of instructions" juga dapat membuat fokus model turun drastis

  • Kutukan instruksi

    • Menurut hasil penelitian, semakin banyak instruksi atau data yang ditumpuk dalam prompt, kinerja untuk mengikuti tiap instruksi dengan akurat turun secara nyata
    • Bahkan model kuat seperti GPT-4 atau Claude juga kesulitan saat diminta memenuhi banyak persyaratan sekaligus
    • Misalnya, jika diberikan 10 aturan rinci dalam bentuk bullet, model cenderung hanya mematuhi beberapa yang awal lalu makin mengabaikan aturan di bagian belakang
    • Strategi yang lebih baik adalah fokus iteratif: arahkan agar hanya fokus pada satu submasalah dalam satu waktu, lalu setelah selesai pindah ke masalah berikutnya

  • Pecah spesifikasi menjadi tahap atau komponen

    • Jika dokumen spesifikasi panjang atau cakupannya luas, pertimbangkan untuk membaginya ke beberapa bagian
    • Contoh: pisahkan “Backend API Spec” dan “Frontend UI Spec” menjadi seksi terpisah
    • Saat mengerjakan backend, spesifikasi frontend tidak harus selalu ikut diberikan
    • Dalam lingkungan multi-agent, tiap area juga bisa memiliki agen atau subproses tersendiri
    • Panduan AI DigitalOcean juga memperingatkan agar “jangan mencampur tugas autentikasi dan perubahan skema database sekaligus”

  • TOC/ringkasan yang diperluas untuk spesifikasi skala besar

    • Salah satu caranya adalah meminta agen lebih dulu membuat daftar isi (TOC) yang diperluas yang merangkum seluruh spesifikasi
    • Tiap seksi dipadatkan menjadi beberapa poin inti atau kata kunci, sambil merujuk lokasi detailnya
    • Contoh: “Security: gunakan HTTPS, lindungi API key, implementasikan validasi input (lihat spesifikasi lengkap §4.2)”
    • Dengan membuat ringkasan hierarkis seperti ini, prompt bisa mempertahankan gambaran besar sementara detail hanya diberikan saat diperlukan
    • TOC yang diperluas berfungsi seperti indeks, sehingga agen menyadari “oh, ada seksi keamanan” lalu meminta bagian terkait
    • Pendekatan ringkasan hierarkis seperti ini membantu LLM mempertahankan struktur tingkat tinggi

  • Gunakan subagent atau “skill”

    • Seperti subagent (atau “skill”) yang disebut Anthropic, dimungkinkan memanfaatkan banyak agen dengan peran yang dipisahkan
    • Tiap subagent dikonfigurasi untuk bidang keahlian tertentu dan hanya menerima sebagian spesifikasi yang relevan dengan bidang itu
    • Contoh: subagent Database Designer hanya mengetahui seksi model data, sedangkan subagent API Coder hanya mengetahui spesifikasi endpoint API
    • Dengan begitu, tiap agen memiliki konteks yang lebih kecil dan peran yang lebih jelas sehingga akurasi meningkat dan pekerjaan bisa diparalelkan
    • Claude Code mendukung fitur untuk mendefinisikan subagent dengan system prompt dan alatnya sendiri

  • Agen paralel untuk throughput

    • Menjalankan banyak agen secara bersamaan sedang muncul sebagai tahap berikutnya dari produktivitas developer
    • Alih-alih menunggu satu agen selesai, agen bisa dipasang secara paralel pada pekerjaan yang tidak saling bertumpang tindih
    • Simon Willison menyebutnya sebagai “menerima agen coding paralel” dan mengatakan pendekatan ini sangat efektif, tetapi cukup melelahkan secara mental
    • Kuncinya adalah membagi cakupan tugas dengan jelas agar agen tidak saling mengganggu pekerjaan satu sama lain
    • Framework orkestrasi seperti LangGraph atau OpenAI Swarm membantu koordinasi semacam ini,
    • dan jika vector database seperti Chroma digunakan sebagai memori bersama, agen dapat mengakses konteks umum tanpa prompting yang berulang

  • Single vs multi-agent: kapan digunakan

    Aspek Single agent Paralel/multi-agent
    Kelebihan Setup sederhana, overhead rendah, mudah untuk debug dan melacak alur Throughput tinggi, mampu menangani ketergantungan kompleks dan spesialisasi per domain
    Kekurangan Overload konteks pada proyek besar, iterasi melambat, single point of failure Biaya koordinasi meningkat, potensi konflik, butuh memori bersama
    Cocok untuk Modul terisolasi, proyek kecil-menengah, prototyping awal Codebase besar, pemisahan coding-testing-review, pengembangan fitur yang independen
    Tip Gunakan ringkasan spesifikasi, perbarui konteks per tugas, sering reset sesi Di awal batasi ke 2~3 agen, bagikan alat dengan MCP, perjelas batas

  • Fokuskan tiap prompt pada satu tugas/seksi

    • Bahkan tanpa lingkungan multi-agent yang kompleks, modularitas tetap bisa dipaksakan secara manual
    • Contoh: setelah menulis spesifikasi, pada tahap “Step 1: implementasi skema database”, berikan hanya seksi Database dari spesifikasi
    • Setiap kali tugas utama berubah, susun ulang konteks agar gangguan dari informasi lama atau yang tidak relevan bisa dikurangi
    • Beberapa panduan merekomendasikan untuk memulai sesi baru saat ada pergantian fungsi utama agar konteks kembali rapi

  • Gunakan instruksi inline dan kode TODO

    • Tulis pekerjaan yang harus dilakukan dalam kode sebagai komentar // TODO, lalu minta agen mengisinya satu per satu
    • Setiap TODO berperan sebagai mini-spesifikasi untuk tugas kecil
    • Hasilnya, AI akan fokus pada cakupan yang sangat sempit, misalnya “implementasikan hanya fungsi ini sesuai potongan spesifikasi ini”

Prinsip 4: Integrasikan pemeriksaan mandiri, batasan, dan keahlian manusia

  • Perlakukan spesifikasi bukan sekadar sebagai daftar tugas agen, tetapi sebagai panduan untuk mengelola kualitas, dan refleksikan keahlian Anda secara aktif di dalamnya
  • Spesifikasi yang baik mengidentifikasi lebih dulu di mana AI bisa melakukan kesalahan, lalu menyiapkan guardrail di titik-titik tersebut
  • Masukkan pengetahuan domain, edge case, dan berbagai “hal yang perlu diperhatikan” agar AI tidak bekerja dalam ruang hampa tanpa konteks
  • Cara mudah memahaminya adalah dengan menganggap spesifikasi sebagai pelatih sekaligus wasit bagi AI: mengarahkan pendekatan yang benar dan segera menghentikan perilaku yang salah
  • Menurut hasil analisis GitHub terhadap lebih dari 2.500 file agen, spesifikasi yang paling efektif bukan sekadar daftar larangan, melainkan menggunakan sistem batas 3 tahap
    • Menjelaskan dengan jelas kapan agen boleh langsung lanjut, kapan harus berhenti dan bertanya, dan kapan harus berhenti total

    • ✅ Always do (selalu lakukan)

      • Tugas yang harus dilakukan tanpa perlu bertanya
      • Contoh: “selalu jalankan tes sebelum commit”, “selalu patuhi naming convention dalam style guide”, “selalu catat error ke layanan monitoring”

    • ⚠️ Ask first (tanya dulu)

      • Tugas yang membutuhkan persetujuan manusia
      • Contoh: “tanya sebelum mengubah skema database”, “tanya sebelum menambahkan dependensi baru”, “tanya sebelum mengubah konfigurasi CI/CD”
      • Meskipun secara teknis mungkin dilakukan, perubahan yang memerlukan pertimbangan manusia karena cakupan dampaknya besar disaring di sini

    • 🚫 Never do (jangan pernah lakukan)

      • Area hard stop yang jelas
      • Contoh: “jangan pernah commit secret atau API key”, “jangan pernah mengedit node_modules/ atau vendor/”, “jangan hapus tes yang gagal tanpa persetujuan eksplisit”
      • Dalam penelitian tersebut, “jangan pernah commit secret” juga dikonfirmasi sebagai batasan berguna yang paling sering muncul

  • Dorong validasi mandiri

    • Dorong agen untuk memeriksa hasilnya sendiri berdasarkan spesifikasi
    • Jika alat diperbolehkan, masukkan ke alur kerja agar agen langsung menjalankan unit test atau linting setelah menghasilkan kode
    • Pada level prompt pun instruksi pemeriksaan ulang bisa diberikan
      • Contoh: “setelah implementasi, bandingkan hasil dengan spesifikasi untuk memastikan semua kebutuhan terpenuhi, dan jika ada yang belum terpenuhi, daftarkan”
    • Ini membantu LLM membandingkan outputnya sendiri dengan spesifikasi sehingga mengurangi hal-hal yang terlewat

  • LLM-as-a-Judge untuk penilaian subjektif

    • Untuk kriteria yang sulit diotomatisasi seperti style kode, keterbacaan, atau kepatuhan pada pola arsitektur, gunakan pendekatan LLM-as-a-Judge
    • Agen kedua (atau prompt terpisah) meninjau output agen pertama berdasarkan standar kualitas dalam spesifikasi
    • Contoh: “tinjau apakah kode ini mematuhi style guide kami, lalu tandai pelanggarannya”
    • Agen yang berperan sebagai wasit mengembalikan umpan balik, lalu itu digunakan untuk diterapkan atau sebagai pemicu revisi

  • Uji kesesuaian

    • Willison merekomendasikan pembuatan conformance suite
    • Ini adalah tes yang tidak bergantung pada bahasa pemrograman, sering kali berbasis YAML, yang berfungsi sebagai kontrak yang harus dilalui semua implementasi
    • Jika Anda membuat API, conformance suite mendefinisikan input dan output yang diharapkan, dan kode buatan agen harus memenuhi semuanya
    • Nyatakan kriterianya di bagian Success dalam spesifikasi, misalnya “wajib lulus semua case di conformance/api-tests.yaml”

  • Gunakan tes dalam spesifikasi

    • Jika memungkinkan, sertakan langsung rencana pengujian atau tes nyata ke dalam spesifikasi dan alur prompt
    • Seperti TDD, gunakan test case untuk memperjelas requirement
      • Contoh: di Success Criteria, tulis “input sampel ini harus menghasilkan output ini”
    • Willison menyebut test suite yang solid sebagai sesuatu yang praktis memberi agen kekuatan super
    • Karena saat tes gagal, agen bisa langsung memverifikasi dan mengulang
    • Dalam konfigurasi subagen, Anda juga bisa memiliki agen pengujian khusus yang menerima standar spesifikasi dan terus memverifikasi output kode

  • Refleksikan pengetahuan domain

    • Spesifikasi harus memuat insight praktis yang biasanya hanya diketahui developer berpengalaman atau orang yang memahami konteks
    • Contoh: saat membuat agen e-commerce, jelaskan dengan tegas bahwa “products” dan “categories” memiliki relasi many-to-many
      • Jangan berharap AI akan menyimpulkannya sendiri
    • Jika library tertentu rumit, nyatakan juga jebakan umum atau hal yang perlu diperhatikan
    • Ini adalah cara menuangkan mentorship Anda ke dalam spesifikasi
      • Contoh: “saat menggunakan library X, versi Y memiliki masalah memory leak, jadi terapkan solusi Z”

  • Minimalisme untuk tugas sederhana

    • Meskipun spesifikasi yang teliti itu penting, bagian dari keahlian adalah mengetahui kapan harus tetap sederhana
    • Untuk tugas yang relatif sederhana dan terisolasi, spesifikasi yang berlebihan justru bisa menambah kebingungan
    • Contoh: untuk tugas seperti “memusatkan div di halaman”
      • cukup beri arahan seperti “jaga solusi tetap ringkas, dan jangan tambahkan markup atau style yang tidak perlu”
    • Sebaliknya, tugas kompleks seperti “mengimplementasikan alur OAuth yang mencakup token refresh dan penanganan error” memerlukan spesifikasi yang detail
    • Patokan praktisnya adalah menyesuaikan kepadatan spesifikasi dengan kompleksitas tugas

  • Pertahankan manusia sebagai filter kualitas terakhir

    • Spesifikasi memang mendelegasikan wewenang ke agen, tetapi tanggung jawab akhir atas kualitas tetap ada pada developer
    • Bahkan jika agen secara teknis memenuhi spesifikasi, jika rasanya atau konteksnya tidak tepat, percayalah pada penilaian Anda sendiri
    • Jika perlu, menyempurnakan kembali spesifikasi atau mengedit hasil secara langsung juga merupakan proses yang wajar
    • Willison menggambarkan bekerja dengan agen AI sebagai “bentuk manajemen yang sangat aneh” dan “sangat mirip dengan mengelola human intern, sampai terasa tidak nyaman”
    • Pada akhirnya, memberikan instruksi yang jelas (spesifikasi), konteks yang cukup, dan umpan balik yang bisa ditindaklanjuti tetap merupakan peran manusia

Prinsip 5: uji, iterasi, dan evolusi spesifikasi (memanfaatkan alat yang tepat)

  • Anggap penulisan spesifikasi dan pembangunan agen bukan sebagai pekerjaan sekali jadi, melainkan loop iteratif
    • Alurnya adalah menguji dengan cepat, mengumpulkan umpan balik, menyempurnakan spesifikasi, dan mengotomatiskan pemeriksaan dengan alat
  • Spesifikasi awal bukan hasil akhir, melainkan titik awal dari sebuah siklus

  • Pengujian berkelanjutan

    • Jangan menunggu sampai seluruh implementasi selesai; lakukan pengujian atau pemeriksaan manual sederhana pada milestone utama atau di tingkat fungsi
    • Jika ditemukan kegagalan, jangan lanjut begitu saja; revisi dulu spesifikasi atau prompt
    • Pengujian otomatis sangat efektif, dan jika ada test, Anda bisa membiarkan agen menjalankan langsung perintah seperti npm test
    • Gunakan hasil kegagalan test apa adanya sebagai input untuk prompt berikutnya
      • Contoh: “Output belum memenuhi spesifikasi pada X, Y, Z, jadi perbaiki”
    • Loop agentic berupa kode → test → perbaikan → ulangi adalah pendekatan yang sangat kuat

  • Iterasi pada spesifikasi itu sendiri

    • Jika ternyata agen salah paham atau ada kebutuhan yang terlewat, jangan menutupi masalah itu; perbarui dulu dokumen spesifikasi
    • Sinkronkan kembali spesifikasi yang telah direvisi dengan agen secara eksplisit
      • Contoh: “Spesifikasi telah saya perbarui sebagai berikut. Sesuaikan rencana atau refactor kode untuk mencerminkan perubahan ini”
    • Selalu pertahankan spesifikasi sebagai single source of truth
    • Jika memungkinkan, simpan riwayat versinya lewat commit message atau catatan agar bisa dilacak apa yang berubah dan mengapa

  • Manajemen konteks dan pemanfaatan alat memori

    • Ekosistem alat untuk membantu pengelolaan konteks dan pengetahuan agen AI berkembang sangat cepat
    • Dengan memanfaatkan pola RAG (retrieval-augmented generation), agen bisa langsung mengambil hanya informasi yang dibutuhkan dari knowledge base seperti basis data vektor
    • Jika spesifikasi sangat besar, sematkan tiap bagiannya lalu atur agar agen mengambil hanya bagian yang paling relevan alih-alih menerima semuanya
    • Framework berbasis MCP (Model Context Protocol) menyediakan konteks yang sesuai dengan task saat ini secara otomatis
    • Alat seperti Context7(context7.com) secara otomatis memuat snippet yang relevan dari dokumentasi sesuai dengan pekerjaan yang sedang dilakukan

  • Paralelisasi yang hati-hati

    • Beberapa developer meningkatkan kecepatan dengan menjalankan beberapa instance agen secara paralel pada task yang berbeda
    • Contoh: satu agen membuat kode, sementara agen lain menulis test pada saat yang sama
    • Jika memilih pendekatan ini, task benar-benar harus independen atau terpisah dengan jelas agar tidak terjadi konflik
    • Contoh: batasi agar dua agen tidak mengedit file yang sama secara bersamaan
    • Untuk mengurangi beban pengelolaan, di tahap awal realistis untuk memulai dengan maksimal 2–3 agen

  • Version control dan penguncian spesifikasi

    • Lacak pekerjaan agen secara cermat dengan alat version control seperti Git
    • Semakin banyak memanfaatkan AI, semakin penting kebiasaan version control yang baik
    • Commit juga file spesifikasi itu sendiri ke repositori agar riwayat perubahannya tercatat
    • Agen juga bisa membaca git diff atau blame untuk memahami konteks perubahan
      • Faktanya, LLM cukup piawai dalam menafsirkan diff
    • Dengan menempatkan spesifikasi di repo, developer dan AI bisa sama-sama melacak evolusi proyek
    • Willison menggambarkan model sebagai “sangat luar biasa kompeten dalam Git”

  • Pertimbangan biaya dan kecepatan

    • Pekerjaan yang menggunakan model besar dan konteks panjang bisa lambat dan mahal
    • Pisahkan pemilihan model secara strategis
      • Gunakan model yang cepat dan murah untuk draft awal atau pekerjaan berulang
      • Gunakan model yang paling mumpuni (dan mahal) untuk output akhir atau penalaran yang kompleks
    • Contoh: GPT-4 atau Claude dipakai untuk penyusunan rencana dan langkah inti, sementara ekspansi sederhana atau refactor diserahkan ke model lokal atau model API kecil
    • Agen untuk menjalankan test atau linter biasanya cukup memakai model yang relatif kecil
    • Ukuran konteks juga perlu dikelola

  • Pantau dan log semuanya

    • Dalam workflow agen yang kompleks, log perilaku dan output agen itu wajib
    • Melalui log, Anda bisa memeriksa apakah agen menyimpang dari maksud awal atau terjadi error
    • Banyak framework menyediakan trace log atau mendukung output proses berpikir langkah demi langkah
    • Dengan meninjau log, akan terlihat di bagian mana spesifikasi atau instruksi disalahartikan

  • Belajar dan meningkatkan

    • Jadikan setiap proyek sebagai kesempatan belajar untuk mempertajam kemampuan menulis spesifikasi
    • Anda bisa mengamati apakah ungkapan tertentu berulang kali membingungkan AI, atau struktur spesifikasi mana yang lebih konsisten dipatuhi
    • Terapkan pelajaran itu secara aktif pada spesifikasi berikutnya
    • Bidang agen AI berkembang pesat, dan alat serta praktik terbaik baru terus bermunculan

Hindari kesalahan yang sering terjadi

  • Hasil analisis terhadap lebih dari 2.500 file agen di GitHub menunjukkan bahwa penyebab kegagalan terbesar adalah spesifikasi dan instruksi yang terlalu ambigu

  • Prompt yang ambigu

    • Permintaan seperti “buat sesuatu yang keren” atau “buat agar bekerja lebih baik” tidak memberi agen kriteria penilaian yang jelas
    • Input, output, dan batasan harus dinyatakan sejelas mungkin
    • Penetapan peran umum seperti “Anda adalah coding assistant yang membantu” hampir tidak efektif
    • Sebaliknya, jika Anda menetapkan peran, cakupan, dan batasan sekaligus, seperti “Anda adalah test engineer yang menulis test untuk komponen React, ikuti contoh ini, dan jangan pernah mengubah source code”, hasilnya jauh lebih baik

  • Konteks berlebihan tanpa ringkasan

    • Membuang dokumen 50 halaman mentah-mentah ke dalam prompt dan berharap model memahaminya sendiri hampir selalu gagal
    • Anda perlu memakai ringkasan hierarkis atau RAG agar hanya isi yang terkait langsung dengan task saat ini yang ditampilkan
    • Menambah panjang konteks tidak bisa menggantikan kurangnya kualitas konteks

  • Melewatkan tinjauan manusia

    • Prinsip pribadi Willison: “Jangan commit kode yang tidak bisa Anda jelaskan kepada orang lain”
    • Hanya karena agen membuat sesuatu yang lolos test, bukan berarti kode itu otomatis benar, aman, dan mudah dipelihara
    • Terutama untuk jalur kode yang penting, manusia harus selalu meninjaunya langsung
    • Kode hasil AI sering tampak kokoh di permukaan, tetapi bisa runtuh pada edge case yang belum diuji; karena itu analogi “rumah kartu” terasa tepat

  • Mencampuradukkan vibe coding dan rekayasa production

    • Prototyping cepat dengan bantuan AI, yang sering disebut “vibe coding”, cocok untuk tahap eksplorasi atau proyek sekali pakai
    • Jika hasilnya langsung didorong ke production tanpa spesifikasi, test, dan review yang ketat, kemungkinan besar akan timbul masalah
    • “Vibe coding” dan “AI-assisted engineering” harus dibedakan dengan jelas; yang kedua membutuhkan disiplin dan prosedur yang dijelaskan dalam panduan ini
    • Penting untuk menyadari mode kerja apa yang sedang Anda jalankan saat ini

  • Mengabaikan “trio fatal”

    • Tiga karakteristik yang menurut Willison membuat agen AI berbahaya
      • Kecepatan: menghasilkan output lebih cepat daripada kemampuan manusia untuk meninjaunya
      • Non-determinisme: output berbeda di setiap eksekusi meski inputnya sama
      • Biaya: mendorong orang mengambil jalan pintas alih-alih melakukan verifikasi yang memadai
    • Proses spesifikasi dan review harus dirancang dengan mengasumsikan ketiga hal ini
    • Terutama, perlu kontrol sadar agar kecepatan tidak melampaui kemampuan verifikasi

  • Menghilangkan 6 area inti

    • Jika spesifikasi tidak mencakup Commands, Testing, Project Structure, Code Style, Git Workflow, dan Boundaries, agen mudah melewatkan informasi penting yang dibutuhkan untuk bekerja
    • Sebelum menyerahkannya ke agen, lebih aman memeriksanya sekali lagi dengan checklist 6 area

Kesimpulan

  • Penulisan spesifikasi yang efektif untuk agen coding AI memerlukan perpaduan antara prinsip rekayasa perangkat lunak yang kuat dan pendekatan yang memahami karakteristik LLM lalu menyesuaikannya
  • Semuanya dimulai dari menetapkan tujuan dengan jelas, lalu membagi peran agar AI mengembangkan rencana dan detail di atas dasar tersebut
  • Spesifikasi harus diperlakukan bukan sebagai memo, melainkan dokumen desain yang serius, serta dianggap sebagai artefak yang dapat dieksekusi yang mencakup 6 area inti dan terhubung dengan toolchain
  • Daripada memberikan semuanya sekaligus, pecah dan berikan per unit kerja agar agen tetap fokus
    (TOC ringkasan, sub-agent, dan orkestrasi paralel adalah sarana praktis untuk menangani spesifikasi berskala besar)
  • Melalui batas 3 tahap (Always / Ask first / Never), pemeriksaan mandiri, dan uji kesesuaian, jebakan yang mudah menimpa AI bisa dicegah sejak awal
  • Kuncinya adalah memperlakukan spesifikasi dan implementasi bukan sebagai hasil akhir yang tetap, melainkan sebagai proses iteratif, lalu terus menyempurnakan spesifikasi dan kode bersama-sama melalui pengujian dan umpan balik
  • Dengan mengikuti panduan ini, kemungkinan agen AI kehilangan arah dalam konteks berskala besar atau terjebak dalam halusinasi dapat berkurang secara nyata

Bacaan terkait

2 komentar

 
qor0923 2026-01-20

Terima kasih.
 
googol 2026-01-19

Secara pribadi, ketika saya mengembangkan proyek dengan SDD (Specs Driven Development), pada awalnya saya merasakan peningkatan produktivitas yang jelas, tetapi karena masih belum semua kode bisa ditulis berdasarkan spesifikasi dan setiap kali perlu melakukan perbaikan langsung saya juga harus memperbarui kode dan spesifikasinya sekaligus, saya justru mengalami penurunan produktivitas.