Design the Agent Interface

Failure pattern

Agent punya shell access dan banyak npm scripts. Tetapi nama command tidak selalu menjelaskan apakah command itu read-only, destructive, local-only, atau butuh approval. Shell access tanpa interface design membuat agent menebak.

Incident: Migration command yang terlalu bebas

Agent diminta memperbaiki membership backfill. Ia menemukan command db:migrate dan menjalankannya tanpa dry run. Di local mungkin aman, tetapi habit itu berbahaya jika harness yang sama dipakai di environment lain.

Masalahnya bukan hanya agent. Repo memberi action surface yang ambigu.

Harness principle

Design the agent interface berarti membuat repo menjadi UI yang aman. Command, tool, script, test, dan error message harus memberi affordance yang jelas.

Tool yang baik punya mode, batas, output schema, dan refusal message. Agent tidak perlu menebak dari nama command.

Operating practice

Tool contract:

Command	Mode	Allowed use
pnpm test auth	verify	focused auth tests
pnpm db:migration:plan	dry run	melihat SQL plan
pnpm db:migration:apply --env local	action	local only
pnpm lint	verify	changed files
pnpm seed reset	destructive local	hanya disposable DB

Setiap dangerous command harus punya safer path.

Coding-agent example

Alih-alih generic runSql, harness menyediakan operation:

{
  "name": "planMembershipBackfill",
  "mode": "dry_run",
  "requires": ["workspace_id", "rollback_plan"],
  "refuses_if": ["env != local", "missing_backup"]
}

Interface ini mengarahkan agent ke action yang bisa diaudit.

Common mistakes

Kesalahan umum adalah menganggap documentation cukup. Agent akan mengikuti affordance tercepat. Jika dangerous command lebih mudah daripada dry run, harness mendorong perilaku salah.

Kesalahan lain adalah tidak membuat structured output untuk PR summary. Reviewer butuh behavior, changed files, evidence, risk, dan rollback note.

Practical exercise

Daftar command yang agent boleh jalankan di repo Anda. Tandai read-only, safe mutation, dangerous mutation, dan approval-only. Pilih satu dangerous command lalu buat wrapper yang lebih aman.

Key takeaways

• Repo dan shell adalah UI untuk coding agent.
• Safe path harus lebih jelas daripada dangerous path.
• Tool output harus menjadi evidence, bukan hanya teks sukses.