Panduan Lengkap Harness Engineering: Membangun Agen AI ala Claude Code

Era “tulis prompt bagus lalu biarkan AI mengurus semuanya” sudah lewat. Untuk membuat AI agent yang bisa dipakai di pekerjaan nyata, kita perlu harness engineering. Secara sederhana, harness adalah scaffold atau kerangka kerja di sekitar agent. Jika di software testing ada test harness untuk menjalankan dan memeriksa kode, maka di dunia AI harness mengatur model, tool, konteks, permission, verification, dan control loop.

Claude Code adalah contoh yang bagus karena ia bukan sekadar chat UI. Ia menggabungkan tool file, shell command, CLAUDE.md, hooks, permission mode, subagent, dan memory. Artikel ini menjelaskan mengapa harness engineering sedang naik, cara membuat mini harness Node.js yang bisa dijalankan, serta bagaimana menerapkannya pada content automation, code review, SaaS integration, cloud operations, dan security boundaries.

Mengapa Harness Engineering Sedang Tren

LLM kuat dalam memilih langkah berikutnya, tetapi pekerjaan nyata membutuhkan lebih banyak hal: membaca workspace, memilih konteks, memanggil tool, menangani error, membatasi aksi berbahaya, dan membuktikan output benar. Semua mekanisme luar model inilah yang disebut harness.

Dokumentasi Claude Agent SDK menjelaskan bahwa SDK bisa memuat fitur bergaya Claude Code seperti project instructions, skills, hooks, dan permissions. Dokumentasi permissions membahas allow rules, deny rules, permission modes, dan runtime callback. Dokumentasi prompt caching menjelaskan cara menggunakan ulang konteks statis yang panjang. Itu semua adalah engineering di sekitar model, bukan sekadar prompt.

Pikirkan dengan OODA loop:

Fase	Isi	Pemilik
Observe	membaca file, log, URL, tiket, status API	Harness
Orient	merapikan dan mengompresi konteks	Harness
Decide	memilih aksi berikutnya	LLM
Act	menjalankan tool, menulis file, memanggil API	Harness

Tiga dari empat fase berada terutama di harness. Karena itu prompt engineering saja tidak cukup.

Isi Harness Yang Praktis

Sebelum model bekerja, harness yang baik menjawab empat pertanyaan: apa yang boleh dibaca, output apa yang harus dibuat, pemeriksaan apa yang membuktikan sukses, dan aksi mana yang otomatis, ask-first, atau dilarang.

Untuk workflow blog, bukan hanya “tulis artikel.” Harness harus membaca slug lama, memilih topik non-duplikat, menulis MDX, mengecek frontmatter, memvalidasi code fence, menambahkan official links, internal links, CTA /products/ dan /training/, menjalankan build, lalu memeriksa public URL.

Layer	Contoh	pitfall
Context	aturan proyek, style guide, kegagalan lama	asumsi usang terus terbawa
Tools	read, grep, write, test, API call	terlalu banyak tool membingungkan model
Policy	allow, ask, deny, sandbox	aksi destruktif berjalan tanpa pengawasan
Verification	test, diff, screenshot, public URL	output terlihat benar tetapi rusak
Memory	preferensi dan keputusan reusable	catatan sementara jadi aturan permanen

Diagram Konsep

Harness adalah lapisan kontrol sebelum dan sesudah model. Prompt tetap penting, tetapi policy, context, tools, permission gate, dan verification loop menentukan apakah workflow bisa dipercaya.

flowchart LR
  A["Goal"] --> B["Harness policy"]
  B --> C["Context"]
  B --> D["Tools"]
  B --> E["Permissions"]
  C --> F["LLM decision"]
  D --> F
  E --> G["Safe action"]
  F --> G
  G --> H["Verification"]
  H --> I["Artifact"]
  H --> B

Mini Harness Node.js Yang Bisa Dijalankan

Contoh ini kecil, tetapi lengkap: model, dua tool, policy, loop, pembatasan path, dan error yang bisa dibaca model. Set ANTHROPIC_API_KEY dulu.

mkdir harness-demo
cd harness-demo
npm init -y
npm install @anthropic-ai/sdk
node -e "const fs=require('node:fs');fs.mkdirSync('sandbox',{recursive:true});fs.writeFileSync('sandbox/README.md','# Demo\nShip a safer agent workflow.\nKeep writes inside sandbox.\n');"

Simpan sebagai policy.json.

{
  "workspace": "./sandbox",
  "maxSteps": 6,
  "tools": {
    "read_file": {
      "allow": true,
      "risk": "Read UTF-8 text only inside workspace"
    },
    "write_file": {
      "allow": true,
      "risk": "Write UTF-8 text only inside workspace"
    }
  }
}

Simpan sebagai mini-harness.mjs.

import Anthropic from "@anthropic-ai/sdk";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import path from "node:path";

const client = new Anthropic();
const policy = JSON.parse(await readFile(new URL("./policy.json", import.meta.url), "utf8"));
const model = process.env.ANTHROPIC_MODEL || "claude-sonnet-4-6";
const workspace = path.resolve(policy.workspace);

function safePath(requestedPath) {
  const resolved = path.resolve(workspace, requestedPath);
  const inside = resolved === workspace || resolved.startsWith(workspace + path.sep);
  if (!inside) {
    throw new Error(`Path escapes workspace: ${requestedPath}. Use a path under ${policy.workspace}.`);
  }
  return resolved;
}

function ensureAllowed(toolName) {
  const rule = policy.tools?.[toolName];
  if (!rule?.allow) {
    throw new Error(`Tool '${toolName}' is not allowed by policy.json.`);
  }
}

const tools = [
  {
    name: "read_file",
    description: "Read a UTF-8 text file from the allowed workspace.",
    input_schema: {
      type: "object",
      properties: { path: { type: "string" } },
      required: ["path"],
      additionalProperties: false
    }
  },
  {
    name: "write_file",
    description: "Write a UTF-8 text file inside the allowed workspace.",
    input_schema: {
      type: "object",
      properties: {
        path: { type: "string" },
        content: { type: "string" }
      },
      required: ["path", "content"],
      additionalProperties: false
    }
  }
];

async function executeTool(name, input) {
  ensureAllowed(name);
  if (name === "read_file") {
    return await readFile(safePath(input.path), "utf8");
  }
  if (name === "write_file") {
    const target = safePath(input.path);
    await mkdir(path.dirname(target), { recursive: true });
    await writeFile(target, input.content, "utf8");
    return `written ${input.path}`;
  }
  throw new Error(`Unknown tool: ${name}`);
}

async function run(goal) {
  const messages = [{ role: "user", content: goal }];

  for (let step = 0; step < policy.maxSteps; step++) {
    const response = await client.messages.create({
      model,
      max_tokens: 1200,
      tools,
      system: "You are a careful file assistant. Use tools when needed. Keep writes under policy workspace.",
      messages
    });

    messages.push({ role: "assistant", content: response.content });
    const toolUses = response.content.filter((block) => block.type === "tool_use");

    if (toolUses.length === 0) {
      const text = response.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(text);
      return;
    }

    const results = [];
    for (const toolUse of toolUses) {
      try {
        const output = await executeTool(toolUse.name, toolUse.input);
        results.push({ type: "tool_result", tool_use_id: toolUse.id, content: String(output).slice(0, 8000) });
      } catch (error) {
        results.push({
          type: "tool_result",
          tool_use_id: toolUse.id,
          is_error: true,
          content: error instanceof Error ? error.message : String(error)
        });
      }
    }
    messages.push({ role: "user", content: results });
  }

  throw new Error(`Max steps reached: ${policy.maxSteps}`);
}

const goal = process.argv.slice(2).join(" ") || "Read README.md and write summary.md with three bullet points.";
await run(goal);

Jalankan:

node mini-harness.mjs

Contoh ini sudah memperlihatkan pola inti: tool schema, policy, sandbox path, batas langkah, error yang jelas, dan artifact konkret. Tambahkan grep, test runner, approval UI, SaaS API, dan hooks untuk mendekati arsitektur Claude Code.

Lima Use Case Konkret

1. content automation Prompt lemah berbunyi “tulis artikel.” Harness yang kuat membaca artikel lama, memilih topik yang tidak duplikat, menulis MDX, mengecek frontmatter dan code fence, menambahkan official links, internal links, CTA /products/ dan /training/, menjalankan build, lalu memeriksa public URL. Pitfall utamanya adalah mengejar kuantitas sehingga artikel lokal hanya menjadi ringkasan tipis.

2. code review Review harness membaca git diff, hasil test, file yang berubah, dan aturan review proyek. Output harus findings-first: bug, risk, regression, dan missing tests lebih dulu. Pitfall-nya model hanya merangkum perubahan tanpa menemukan masalah.

3. SaaS integration Untuk Notion, HubSpot, Stripe, atau CRM, pisahkan read-only lookup, dry-run mutation, dan approved write. Misalnya lead consultation boleh diklasifikasi otomatis dan dibuatkan draft update, tetapi write ke CRM harus menunggu persetujuan. Risk-nya adalah salah klasifikasi langsung masuk ke sistem produksi.

4. cloud operations Cloud workflow bukan sekadar deploy. Harness perlu mengecek environment variables, build, diff, target environment, rollback plan, health endpoint, dan public URL. Pitfall-nya adalah memperbaiki baris log terakhir tanpa memahami root cause. Batasi retry dan ringkas log dengan jelas.

5. security boundaries Security boundaries harus dirancang sejak awal. Read bisa cukup luas, tetapi Write harus dibatasi ke workspace. Shell command sebaiknya allow-list. rm, force push, production DB, billing, dan secret access harus deny atau ask-first. Harness dibuat agar kita tidak terlalu percaya pada agent.

Pelajaran Dari Claude Code

Pertama, pisahkan konteks berdasarkan masa hidup. Aturan proyek stabil masuk ke CLAUDE.md atau config sejenis, progres sesi masuk ke plan, preferensi jangka panjang masuk ke memory.

Kedua, pindahkan pemeriksaan deterministik ke hooks. Formatting, lint, test, link check, dan screenshot verification lebih stabil bila dijalankan sebagai command. Claude cukup membaca error dan memperbaiki.

Ketiga, isolasi pekerjaan berisik. Log panjang, pencarian luas, terjemahan banyak bahasa, dan refactor besar cocok didelegasikan ke subagent atau tahap workflow terpisah.

Pitfall Umum

Terlalu banyak tool membuat model bingung. Mulailah dengan 5 sampai 10 tool yang jelas.

Error yang tidak terbaca menghambat self-repair. Jangan kirim Error: failed; jelaskan apa yang hilang dan apa langkah berikutnya.

Mengabaikan prompt caching membuat konteks statis panjang dikirim berulang kali. Pisahkan konteks tetap dan dinamis.

Tanpa verification, output yang tampak rapi bisa langsung rusak di produksi. Artikel butuh frontmatter dan code fence checks, kode butuh test, cloud butuh health check, SaaS butuh audit log.

Permission drift juga berbahaya. Review allow, ask, dan deny secara berkala.

Langkah Berikutnya

Untuk mulai dari keamanan, baca Claude Code Permissions Guide. Untuk konteks proyek, lanjutkan ke CLAUDE.md Best Practices. Untuk memecah pekerjaan berat, lihat Claude Code subagent patterns. Untuk biaya, baca Claude Code token optimization.

Sebagai referensi cepat, simpan Claude Code Quick Reference Cheatsheet. Template dan playbook tersedia dari /products/. Jika tim Anda perlu desain permission, review gate, verification, publishing, dan revenue workflow, mulai dari /training/.

Hasil Yang Saya Verifikasi

Pada workflow artikel ClaudeCodeLab, nilai terbesar harness adalah membuat kegagalan terlihat. Prompt bisa membuat artikel, tetapi harness memeriksa kedalaman isi, code fence, frontmatter, link, CTA, dan public URL. Dengan begitu tim tidak sekadar percaya pada output, tetapi mengoperasikan workflow yang punya gerbang pemeriksaan.

Ringkasan

Harness engineering adalah disiplin untuk menentukan apa yang boleh dilihat model, apa yang boleh dilakukan, kapan harus berhenti, dan bagaimana hasil diverifikasi. Claude Code adalah contoh yang kuat karena nilai utamanya bukan hanya model, melainkan scaffold di sekitarnya. Jalankan mini harness di atas, lalu tambahkan satu boundary dan satu verification step untuk use case Anda.

Referensi

• Claude Agent SDK: Claude Code features
• Claude Agent SDK permissions
• Claude Agent SDK hooks
• Claude API models overview
• Prompt caching