CS 319 · Pertemuan 3 dari 10

Spec
dan Loop

Tempat intent manusia menjadi bisa dicek mesin — dan anatomi mesin yang mengeceknya.

Agenda · 100 menit

Spec sebagai kode: lima field (25')
Anatomi loop: trigger, state, exit (25')
Stagnation circuit breaker (10')
Studi kasus: loop update-dependency Kirana (10')
Spec kata (20') · briefing A3 (10')

Bacaan: bab 6–7

Konsep inti · bab 6

Saat agen menulis kode, spec-lah source of truth

PRD — untuk manusia

Intent, pasar, narasi. Dibaca orang yang memutuskan apa dan mengapa. Bisa berubah lewat percakapan.

Spec — untuk mesin dan test

Batasan, kriteria, kondisi penolakan. Dikonsumsi agen dan diubah jadi cek pass/fail. Hanya berubah lewat edit — seperti kode, karena memang kode.

Tanpa spec yang baik, tak ada loop yang bisa tahu apakah ia berhasil. Spec adalah beda antara loop yang mengirim dan loop yang mengembara.

Artefaknya · hafalkan ini

Lima field yang mengubah perilaku agen

1 · task boundary — satu kalimat: apa tugas ini, ditulis supaya hal yang bersebelahan tak menyusup masuk

2 · tool allowlist — tool persis yang diizinkan; yang tak ada = larangan keras

3 · refusal conditions — kapan agen wajib berhenti dan eskalasi alih-alih berimprovisasi

4 · kriteria penerimaan bernomor — AC-1…AC-n, masing-masing biner pass/fail, masing-masing terpetakan ke cek

5 · daftar out-of-scope — non-goal eksplisit; bug termurah adalah yang tak pernah ditulis

Contoh · artefak spec-nya sendiri

spec.md, terisi

task: update patch dependency di web/ (minor + patch saja)
boundary: naikkan versi di package.json, jalankan test, buka SATU PR
tools: [read_files, edit_files, run_tests, open_pr]     # allowlist
refusal:
  - butuh bump major version        # stop, jangan berimprovisasi
  - ada test gagal setelah bump
  - perubahan lisensi terdeteksi
acceptance:
  AC-1: versi package.json berubah, lockfile konsisten   [check: npm ci]
  AC-2: npm test exit 0                                  [check: npm test]
  AC-3: body PR memuat versi lama→baru + ringkasan test   [check: regex]
  AC-4: diff HANYA menyentuh file dependency              [check: path glob]
out_of_scope: refactor, edit changelog, pinning peer deps

Setiap AC terpetakan ke mekanisme dalam kurung. Kriteria yang tak bisa dibuat pass/fail adalah pertanyaan, bukan kriteria.

Konsep inti · bab 7

Anatomi loop

4 bagian bergerak
trigger · struktur file · tools · codebase siap-agen

3 trigger
cron (waktu) · webhook (event) · agen-ke-agen (delegasi)

3 primitif operasional
state yang durable · plugin · guardrail

Pembagian state
hot — di context window
warm — di file yang dibaca/ditulis loop
cold — di DB, untuk audit dan replay

4 kondisi keluar
tujuan tercapai · iterasi maksimum · stagnation breaker · eskalasi manusia

Satu soal ujian

Stagnation circuit breaker

Loop tanpa breaker tidak berhenti saat berhenti berprogres — ia berhenti saat kehabisan iterasi atau uang. Breaker mengajukan pertanyaan yang berbeda dari verifier:

verifier bertanya

"Apakah outputnya benar?"

breaker bertanya

"Apakah kita masih bergerak? Apakah run N berbeda dari run N−1?"

# breaker: hash state yang berarti; identik dua kali = macet
H=hash(output+diff_stats)
if H == LAST_H: STAGNANT++; else STAGNANT=0
[ $STAGNANT -ge 2 ] && escalate "stagnation: output identik x2"

Mandor yang tak bisa mendesain trigger, state, dan exit dari sebuah loop hanyalah pengasuh.

Studi kasus · bagian 3 dari 10

Kirana menulis spec pertama mereka yang sungguhan

Sasaran: loop tugas rutin update dependency (lead dev "Rasa" mengerjakannya manual tiap Jumat, 90 menit, benci). Draf pertama berisi 12 kriteria penerimaan — semuanya dianggap kriteria. Dikata-kan turun jadi 4.

Field yang menarik: refusal conditions. Insting tim: "tangani semuanya." Pekerjaan spec justru sebaliknya — bump major? stop. konflik peer-dep? stop. lisensi berubah? stop. Tiga cara menolak, ditulis sebelum satu baris kode loop.

Minggu pertama: 6 run, 4 menolak dengan benar, 2 menghasilkan PR bersih. Jumat Rasa: 90 → 15 menit (review saja). Spec-nya — bukan modelnya — yang jadi tuasnya.

Spec kata · 20 menit

Refusal conditions + kriteria pass/fail

Tugas Anda (berpasangan)

"Triage inbox support setiap pagi: label, prioritas, draft balasan untuk yang mudah."

Tulis 3 refusal conditions. Kapan loop ini wajib berhenti dan memanggil manusia?
Tulis 4 kriteria penerimaan bernomor, masing-masing dengan mekanisme verifikasinya dalam kurung siku.
Tulis 3 item out-of-scope yang kalau tidak akan menyusup masuk.

Tes: tukar dengan pasangan sebelah. Coba tulis output yang lolos kriteria mereka tapi jelas salah. Kalau bisa, kriteria mereka bolong.

Tugas A3 · dikumpulkan sebelum Pertemuan 4

Tulis spec lengkap untuk tugas berulang nyata

Tugas
Pilih tugas yang Anda (atau tim yang Anda kenal) kerjakan ≥3×/minggu. Hasilkan spec.md lengkap: lima field, kriteria bernomor dan masing-masing terpetakan ke cek.

Deliverable
spec.md · pembelaan 150 kata untuk satu refusal condition (mengapa berhenti di situ?) · hole-hunt: minta teman sekelas mencoba lolos dari kriteria Anda dengan output buruk, dokumentasikan percobaannya.

Rubrik
Kualitas kriteria (biner + terpetakan) 40% · refusal conditions 30% · dokumentasi hole-hunt 30%.

Berikutnya: pipeline empat fase dan enam dokumen — apa yang dihasilkan dewan yang bekerja dengan benar. Baca bab 8–9.

Specdan Loop