Define the Work Surface

Failure pattern

Developer meminta coding agent “fix onboarding.” Agent lalu menyentuh auth, email copy, dashboard, analytics, dan test sekaligus. Hasilnya terlihat aktif, tetapi scope-nya tidak bisa direview dengan sehat.

Work surface untuk coding agent adalah batas pekerjaan: behavior apa yang diubah, file mana yang masuk akal, command apa yang membuktikan hasil, dan apa yang harus ditolak.

Incident: Onboarding bug yang melebar

Bug sebenarnya sederhana: invited user menerima link, tetapi redirect terlalu cepat sebelum workspace membership siap. Karena request hanya berbunyi “fix onboarding,” agent memperbaiki copy email, mengubah checklist, menambah analytics event, dan menyentuh billing trial state.

Patch besar itu sulit ditolak satu per satu. Reviewer tidak tahu apakah behavior utama benar-benar fixed.

Agent task

Brief yang lebih baik:

Behavior: invited user lands in workspace setup after accepting valid invite.
In scope: token validation, membership creation, redirect target, acceptance test.
Out of scope: email copy, billing trial, dashboard checklist, analytics.
Evidence: failing test before patch, passing acceptance test after patch.

Ini cukup sempit untuk dikerjakan dan cukup jelas untuk direview.

Harness principle

Work surface bukan sekadar prompt. Ia ditegakkan oleh test, allowed commands, branch policy, dan review gate. Agent boleh menemukan masalah lain, tetapi harus menaruhnya di queued atau blocked, bukan diam-diam memperluas patch.

Operating practice

Gunakan brief table:

Field	Contoh
User-visible behavior	invite acceptance redirect
Entry point	/invite/:token
In scope	route, membership event, focused e2e
Out of scope	email copy, billing, dashboard
Evidence	failing/passing test pair
Stop condition	upstream auth bug ditemukan

Jika stop condition terjadi, agent berhenti dan melaporkan work surface baru.

Coding-agent example

Harnessed agent membuat patch kecil: route fix dan regression test. Ia tidak memperbaiki seluruh onboarding. Ia menulis evidence:

Before: invite acceptance e2e fails on redirect.
After: invite acceptance e2e passes.
Regression: expired token path still passes.

Patch ini bisa direview.

Common mistakes

Kesalahan umum adalah menjadikan nama produk sebagai scope. “Onboarding” terlalu luas. “Invite acceptance redirects before membership exists” adalah work surface.

Kesalahan lain adalah membiarkan agent mengambil cleanup oportunistik. Cleanup boleh dicatat, tetapi tidak otomatis masuk active work.

Practical exercise

Ambil satu issue dari repo. Tulis ulang menjadi work-surface brief dengan behavior, in scope, out of scope, evidence, dan stop condition.

Key takeaways

• Coding agent butuh batas behavior, bukan hanya goal.
• Scope drift harus punya tempat: queued, blocked, atau rejected.
• Completion harus dibuktikan lewat evidence yang disebut sejak awal.