Specify the Work Surface

Failure pattern

Raw coding agent menerima request:

Fix onboarding.

Model membuka repo, mengubah auth redirect, menyentuh onboarding copy, dashboard state, dan menambah test parsial. Kelihatannya produktif, tetapi work-nya tidak bounded. Reviewer tidak tahu behavior mana yang sebenarnya ingin diubah.

Reproduce the failure

const response = await model.complete({
  messages: [{ role: "user", content: "Fix onboarding." }],
});

Ini belum menjadi work surface. Tidak ada user-visible behavior, area file yang in-scope, out-of-scope boundary, required evidence, atau stop condition.

Successful Anvia pattern

Dengan Anvia, step pertama adalah structured work-surface brief. Agent harus mendefinisikan coding task yang bounded sebelum implementation.

import { z } from "zod";
import { AgentBuilder } from "@anvia/core";

const WorkSurface = z.object({
  behavior: z.string(),
  entryPoints: z.array(z.string()),
  inScope: z.array(z.string()),
  outOfScope: z.array(z.string()),
  requiredEvidence: z.array(z.string()),
  stopCondition: z.string(),
  readyToImplement: z.boolean(),
});

const codingAgent = new AgentBuilder("repo-coding-agent", model)
  .instructions(`
You are a coding agent working inside a SaaS repository.
Before editing, turn vague requests into a bounded work surface.
Keep one user-visible behavior active at a time.
If the behavior, evidence, or scope is unclear, return readyToImplement=false.
`)
  .outputSchema(WorkSurface)
  .defaultMaxTurns(2)
  .build();

Why it succeeds

Output pertama bukan lagi “langsung ubah code.” Output pertama adalah “jelaskan pekerjaannya.” Agent boleh mengusulkan fix, tetapi harness lebih dulu mengecek apakah request cukup sempit untuk diimplementasikan.

Success check

Run berhasil ketika agent mengembalikan behavior, entryPoints, inScope, outOfScope, requiredEvidence, stopCondition, dan readyToImplement.

Next move

Hanya setelah readyToImplement=true, agent boleh menerima tools untuk membaca file, menjalankan test, atau menyiapkan patch.