Apa yang Akan Anda Pelajari

Panduan ini mencakup harness engineering dari prinsip pertama hingga implementasi praktis. Anda akan memahami apa itu harness engineering, mengapa OpenAI mempertaruhkan proyek internal terbesar mereka padanya, pola arsitektur spesifik yang membuatnya berhasil, dan cara menerapkan prinsip-prinsip ini pada alur kerja AI agent Anda sendiri — baik saat Anda menggunakan Codex, Claude Code, OpenCode, atau sistem agent lainnya.

Harness Engineering: Panduan Lengkap untuk Pengembangan AI Agent di Tahun 2026

Jika 2025 adalah tahun di mana AI agent membuktikan bahwa mereka dapat menulis kode, 2026 adalah tahun di mana kita belajar bahwa agent bukanlah bagian yang sulit — harness adalah kuncinya.

Tim Codex dari OpenAI menerbitkan postingan blog penting pada Februari 2026 yang menjelaskan bagaimana mereka membangun aplikasi produksi yang berisi sekitar satu juta baris kode di mana nol baris ditulis oleh tangan manusia. Rahasianya bukan pada model yang lebih baik atau prompt yang lebih cerdas. Rahasianya adalah sistem yang mereka bangun di sekitar agent tersebut — yaitu harness. Sumber

Panduan ini merinci setiap prinsip, pola, dan teknik praktis dari eksperimen tersebut dan gerakan harness engineering yang lebih luas yang muncul di sekitarnya.

Bagian 1: Apa Itu Harness Engineering?

Definisi

Harness engineering adalah disiplin merancang seluruh lingkungan — scaffolding, feedback loops, dokumentasi, batasan arsitektur, dan artefak yang dapat dibaca mesin — yang memungkinkan AI coding agents untuk melakukan pekerjaan yang andal dan berkualitas tinggi dalam skala besar dengan intervensi manusia yang minimal.

Istilah "harness" berasal dari perlengkapan kuda: kendali, pelana, mata pelana — rangkaian lengkap peralatan untuk mengarahkan hewan yang kuat namun tidak terduga ke arah yang benar. Seekor kuda yang tidak terkendali itu berbahaya. Seekor kuda yang dipasangi harness membangun peradaban. Hal yang sama berlaku untuk AI agents. Sumber

Mengapa Ini Muncul Sekarang

Pergeseran dari prompt engineering ke harness engineering mencerminkan pematangan lanskap pengembangan AI:

Sumber

Wawasan utama yang mendorong transisi ini: agent menjadi cukup mampu sehingga hambatan bergeser dari kualitas model ke kualitas lingkungan. Sebuah model state-of-the-art yang beroperasi di repository yang strukturnya buruk menghasilkan hasil yang lebih buruk daripada model biasa-biasa saja yang beroperasi di lingkungan dengan harness yang baik.

Bagian 2: Eksperimen OpenAI Codex

Skala

Dalam eksperimen internal selama lima bulan, engineer OpenAI membangun dan merilis produk beta yang berisi sekitar satu juta baris kode. Repository tersebut mencakup logika aplikasi, infrastruktur, tooling, dokumentasi, dan utilitas developer internal. Tidak ada kode buatan manusia yang sudah ada sebelumnya untuk menjadi jangkar sistem. Sumber

Tim

Proyek ini dimulai dengan hanya tiga engineer yang menjalankan Codex. Selama periode lima bulan, sekitar 1,500 pull requests dibuka dan digabungkan. Seiring bertambahnya tim menjadi tujuh engineer, throughput meningkat — sebuah hasil yang berlawanan dengan intuisi yang menunjukkan bahwa harness itu sendiri adalah pengganda produktivitas utama, bukan keterampilan individu.

OpenAI memperkirakan mereka membangun sistem tersebut dalam waktu kira-kira sepersepuluh dari waktu yang dibutuhkan untuk menulis kode secara manual. Sumber

Scaffold Awal

Proyek dimulai dengan Codex CLI yang menghasilkan scaffold awal menggunakan GPT-5, dipandu oleh sekumpulan kecil template yang ada:

• Struktur repository dan konvensi direktori
• Konfigurasi CI/CD
• Aturan pemformatan kode dan linting
• Pengaturan package manager
• Boilerplate framework aplikasi

Dari benih ini, segala sesuatunya tumbuh melalui pengembangan yang digerakkan oleh agent.

Masalah Hari Jumat

Di awal eksperimen, tim menemukan masalah kritis: mereka menghabiskan setiap hari Jumat — 20% dari waktu engineering mereka — untuk membersihkan apa yang mereka sebut "AI slop." Ini termasuk pola yang tidak konsisten, logika yang duplikat, variabel yang salah nama, dan penyimpangan arsitektur.

Hal itu tidak dapat diskalakan. Solusinya adalah menyandikan standar mereka ke dalam harness itu sendiri sehingga agent akan menghasilkan output yang lebih bersih sejak awal, dan membangun sistem pembersihan otomatis untuk penyimpangan yang tersisa.

Bagian 3: Lima Prinsip Inti

Prinsip 1: Pengetahuan Berbasis Repository Terlebih Dahulu

Dari sudut pandang agent, apa pun yang tidak dapat diaksesnya dalam konteks saat berjalan secara efektif tidak ada. Pengetahuan yang berada di Google Docs, utas chat, pesan Slack, atau kepala orang tidak terlihat oleh sistem.

Ini berarti semua pengetahuan harus ada sebagai artefak lokal repository yang memiliki versi:

• Kode — artefak utama
• Dokumentasi Markdown — keputusan arsitektur, konvensi, panduan orientasi
• Schema — kontrak API, database schemas, definisi tipe
• Rencana yang dapat dieksekusi — rincian tugas langkah demi langkah yang dapat diikuti oleh agent
• Konfigurasi — aturan linter, CI pipelines, standar pemformatan

Tim belajar bahwa mereka perlu memasukkan lebih banyak konteks ke dalam repo seiring berjalannya waktu. Setiap kali agent membuat kesalahan karena kurangnya konteks, perbaikannya bukanlah prompt yang lebih baik — melainkan menambahkan konteks tersebut ke repository. Sumber

Implementasi praktis:

# ARCHITECTURE.md (lives in repo root)

## Dependency Rules
- UI components may import from Service layer but never from Repo layer
- Service layer may not import from Runtime layer
- All cross-domain communication goes through typed event bus

## Naming Conventions
- React components: PascalCase, suffixed with purpose (UserListPage, UserCard)
- Services: camelCase, suffixed with Service (userService, authService)
- Types: PascalCase, prefixed with domain (UserProfile, OrderItem)

## Testing Requirements
- All Service functions require unit tests
- All API endpoints require integration tests
- Coverage threshold: 80% per package

Prinsip 2: Golden Principles

Golden principles adalah aturan mekanis yang berpendapat yang disandikan langsung ke dalam repository untuk menjaga agar codebase tetap terbaca dan konsisten untuk dijalankan oleh agent di masa mendatang. Ini bukan sekadar panduan aspirasional — ini adalah batasan yang ditegakkan.

Contoh dari eksperimen OpenAI:

1. Lebih memilih paket utilitas bersama daripada helper buatan sendiri — memusatkan invarian sehingga ketika perilaku perlu berubah, ia berubah di satu tempat
2. Jangan menyelidiki data gaya YOLO — validasi batasan atau andalkan typed SDKs sehingga agent tidak sengaja membangun di atas bentuk data yang ditebak
3. Satu konsep, satu file — setiap file harus mewakili satu konsep, memudahkan agent untuk menemukan dan memodifikasi lokasi yang tepat
4. Eksplisit daripada implisit — hindari perilaku ajaib yang membutuhkan pengetahuan kesukuan untuk dipahami oleh agent

Sumber

Prinsip-prinsip ini bukan sekadar dokumentasi. Mereka ditegakkan oleh:

• Aturan linter — linter khusus (yang dibuat sendiri oleh Codex) yang menandai pelanggaran
• Uji struktural — tes yang memvalidasi kepatuhan arsitektur
• CI gates — pull requests yang melanggar golden principles secara otomatis ditolak

Prinsip 3: Arsitektur Berlapis dengan Penegakan Mekanis

Setiap domain bisnis dalam proyek OpenAI dibagi menjadi kumpulan lapisan tetap dengan arah dependensi yang divalidasi secara ketat:

Types → Config → Repo → Service → Runtime → UI

Dependensi mengalir ke satu arah saja. Komponen UI dapat bergantung pada Runtime dan Service, tetapi Service tidak boleh mengimpor dari UI. Repo dapat bergantung pada Config dan Types, tetapi tidak pernah pada Service. Sumber

Batasan ini ditegakkan secara mekanis:

// structural-test.ts — enforces dependency boundaries
import { analyzeImports } from './tools/import-analyzer';

describe('Dependency Layer Enforcement', () => {
  it('Service layer must not import from Runtime', () => {
    const violations = analyzeImports({
      sourceLayer: 'service',
      forbiddenLayers: ['runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });

  it('Repo layer must not import from Service', () => {
    const violations = analyzeImports({
      sourceLayer: 'repo',
      forbiddenLayers: ['service', 'runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });
});

Uji struktural memvalidasi kepatuhan dan mencegah pelanggaran pelapisan modular. Ini bukan saran — ini ditegakkan oleh CI. Setiap pull request, baik dibuat oleh manusia maupun agent, harus lulus tes ini.

Prinsip 4: Automated Garbage Collection

Bahkan dengan golden principles dan penegakan struktural, kode yang dihasilkan agent akan menyimpang seiring waktu. Tim OpenAI memecahkan masalah ini dengan menerapkan automated garbage collection — tugas latar belakang berulang yang:

1. Memindai penyimpangan dari golden principles di seluruh codebase
2. Memperbarui tingkat kualitas untuk setiap modul berdasarkan skor kepatuhan
3. Membuka pull request refactoring yang ditargetkan yang memperbaiki kategori penyimpangan tertentu

Ini menggantikan "pembersihan hari Jumat" manual dengan sistem yang berjalan terus-menerus. Garbage collector itu sendiri didukung oleh agent Codex, menciptakan loop pemeliharaan mandiri. Sumber

# .github/workflows/garbage-collection.yml
name: Codebase Garbage Collection
on:
  schedule:
    - cron: '0 2 * * *'  # Run nightly at 2 AM

jobs:
  gc-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run golden principle scanner
        run: npx codex-gc scan --principles ./GOLDEN_PRINCIPLES.md
      - name: Generate refactoring PRs
        run: npx codex-gc fix --auto-pr --max-prs 5

Prinsip 5: Rencana yang Dapat Dieksekusi

Sebelum agent menulis kode, mereka menulis rencana. Rencana ini bukan catatan informal — mereka adalah dokumen terstruktur dan dapat dieksekusi yang menentukan:

• Objektif: Apa yang dicapai oleh tugas tersebut
• File yang akan dimodifikasi: Daftar eksplisit file yang akan disentuh oleh agent
• Dependensi: Tugas atau modul lain yang menjadi ketergantungan pekerjaan ini
• Kriteria penerimaan: Cara memverifikasi bahwa pekerjaan telah selesai
• Batasan: Aturan arsitektur yang tidak boleh dilanggar

# Plan: Add user notification preferences

## Objective
Allow users to configure which notification channels (email, SMS, push) they
receive alerts on, with per-category granularity.

## Files to Modify
- src/types/user.ts — Add NotificationPreferences type
- src/repo/userRepo.ts — Add getPreferences/setPreferences methods
- src/service/notificationService.ts — Filter notifications by preferences
- src/ui/pages/SettingsPage.tsx — Add preferences UI section

## Constraints
- Must follow Types → Repo → Service → UI dependency flow
- NotificationPreferences type must be shared, not duplicated
- All new methods require unit tests

## Acceptance Criteria
- [ ] User can toggle email/SMS/push per notification category
- [ ] Preferences persist across sessions
- [ ] Toggling a channel off stops notifications on that channel within 30s

Rencana disimpan di repository sebagai file markdown, dikontrol versinya, dan dapat ditinjau sebelum dieksekusi — memberi manusia titik pemeriksaan antara niat dan implementasi.

Bagian 4: Loop Agent Codex

Memahami bagaimana loop agent Codex beroperasi di dalam sebuah harness sangat penting untuk harness engineering yang efektif.

Arsitektur Loop

OpenAI menerbitkan rincian mendetail tentang loop agent Codex dalam postingan blog pendamping mereka "Unrolling the Codex agent loop." Sumber Loop tersebut mengikuti siklus ini:

Read Context → Plan → Execute → Validate → Commit (or Retry)

Setiap iterasi:

1. Read Context: Agent membaca file yang relevan, dokumentasi, schema, dan rencana tugas dari repository
2. Plan: Berdasarkan konteks, agent menentukan perubahan apa yang akan dilakukan
3. Execute: Agent menulis atau memodifikasi kode
4. Validate: Harness menjalankan tes, linter, dan pemeriksaan struktural terhadap perubahan tersebut
5. Commit or Retry: Jika validasi lulus, agent melakukan commit. Jika gagal, agent membaca output kesalahan dan mencoba lagi.

Peran harness adalah membuat langkah 1 dan 4 sekaya mungkin dengan informasi. Semakin banyak konteks yang dibaca agent, semakin baik rencananya. Semakin spesifik umpan balik validasi, semakin cepat ia menyatu pada solusi yang berhasil.

App Server Harness

Dalam postingan mereka "Unlocking the Codex harness: how we built the App Server," OpenAI mendeskripsikan infrastruktur konkret yang menggerakkan loop agent. Sumber App Server menyediakan:

• Lingkungan eksekusi sandboxed untuk setiap tugas agent
• Akses alat yang dikonfigurasi sebelumnya (file system, terminal, browser)
• Injeksi konteks otomatis dari artefak repository
• Umpan balik validasi streaming sehingga agent dapat melihat kegagalan tes secara real time

Bagian 5: Menerapkan Harness Engineering ke Tim Anda

Memulai: Minimum Viable Harness

Anda tidak perlu mereplikasi seluruh infrastruktur OpenAI untuk mendapatkan manfaat dari harness engineering. Mulailah dengan elemen dasar berikut:

Langkah 1: Buat ARCHITECTURE.md

Dokumentasikan aturan arsitektur proyek Anda dalam format yang dapat dibaca mesin di root repository Anda. Sertakan:

• Batasan modul dan dependensi yang diizinkan
• Konvensi penamaan
• Aturan pengorganisasian file
• Persyaratan pengujian

Satu file ini secara drastis meningkatkan kualitas output agent karena agent membacanya sebelum melakukan perubahan.

Langkah 2: Tambahkan Uji Struktural

Tulis tes yang memvalidasi aturan arsitektur Anda. Tes ini tidak memeriksa logika bisnis — mereka memeriksa apakah kode diatur dengan benar:

// No service file should import from a UI module
test('service layer isolation', () => {
  const serviceFiles = glob('src/services/**/*.ts');
  for (const file of serviceFiles) {
    const imports = extractImports(file);
    const uiImports = imports.filter(i => i.startsWith('../ui/'));
    expect(uiImports).toHaveLength(0);
  }
});

Langkah 3: Konfigurasikan Validasi CI

Pastikan pipeline CI Anda menjalankan uji struktural, linter, dan pemeriksaan tipe pada setiap pull request — termasuk yang dibuat oleh agent. Agent harus melihat output validasi yang sama dengan yang dilihat oleh developer manusia.

Langkah 4: Tulis Rencana Tugas Sebelum Eksekusi Agent

Sebelum meminta agent untuk mengimplementasikan sebuah fitur, tulis dokumen rencana terstruktur yang menentukan file yang akan dimodifikasi, batasan yang harus diikuti, dan kriteria penerimaan. Simpan rencana ini di repository Anda.

Langkah 5: Siapkan Pembersihan Otomatis

Terapkan pekerjaan CI mingguan atau malam hari yang memindai codebase Anda untuk mencari penyimpangan dari standar yang didokumentasikan dan buat PR refactoring yang terfokus.

Memilih Sistem Agent Anda

Prinsip harness engineering berlaku terlepas dari agent mana yang Anda gunakan:

Harness berada di repository Anda, bukan di agent Anda. Ini berarti Anda dapat mengganti agent tanpa kehilangan investasi harness Anda.

Menskalakan dari Satu Agent ke Banyak Agent

Eksperimen OpenAI menunjukkan bahwa harness engineering memungkinkan eksekusi agent secara paralel. Karena harness menegakkan batasan arsitektur, banyak agent dapat bekerja pada bagian codebase yang berbeda secara bersamaan tanpa menimbulkan konflik.

Persyaratan utama untuk eksekusi agent paralel:

1. Kepemilikan modul yang jelas — setiap agent bekerja dalam batasan yang ditentukan
2. Typed interfaces antar modul — agent dapat mengodekan terhadap interface tanpa mengetahui detail implementasi
3. Pencegahan konflik penggabungan — tugas dicakupkan untuk meminimalkan tumpang tindih file
4. Validasi terpusat — semua agent mengirimkan ke pipeline CI yang sama

Bagian 6: Kesalahan Umum dan Anti-Pattern

Anti-Pattern 1: Menganggap Agent Sebagai Harness

Agent bukanlah harness. Harness adalah lingkungan tempat agent beroperasi. Meminta model yang lebih cerdas untuk mengompensasi repository yang strukturnya buruk adalah pendekatan yang salah. Perbaiki lingkungannya, bukan prompt-nya.

Anti-Pattern 2: Dokumentasi di Tempat yang Salah

Jika keputusan arsitektur Anda berada di Confluence, Notion, atau Google Docs, agent tidak dapat melihatnya. Perbaikannya sederhana tetapi membutuhkan disiplin: pindahkan semua dokumentasi yang relevan dengan pengembangan ke dalam repository.

Anti-Pattern 3: Pembersihan Manual Alih-alih Penegakan Otomatis

Jika Anda menghabiskan banyak waktu untuk membersihkan kode yang dihasilkan agent, Anda memerlukan penegakan yang lebih baik, bukan lebih banyak sesi pembersihan. Setiap tugas pembersihan yang berulang harus menjadi aturan linter, uji struktural, atau pekerjaan refactoring otomatis.

Anti-Pattern 4: Terlalu Membatasi

Harness yang terlalu kaku mencegah agent menemukan solusi kreatif. Tujuannya adalah untuk membatasi arsitektur, bukan implementasi. Beritahu agent modul mana yang dapat mereka modifikasi dan dependensi mana yang diizinkan, tetapi biarkan mereka memutuskan cara mengimplementasikan logika dalam batasan tersebut.

Anti-Pattern 5: Mengabaikan Umpan Balik Agent

Ketika sebuah agent berulang kali gagal pada tugas-tugas tertentu, kegagalan tersebut biasanya menunjukkan adanya celah dalam harness, bukan keterbatasan agent. Lacak pola kegagalan dan gunakan untuk meningkatkan dokumentasi, uji struktural, atau batasan arsitektur Anda.

Bagian 7: Masa Depan Harness Engineering

Perspektif Martin Fowler

Martin Fowler menerbitkan analisis tentang harness engineering di blognya, mencatat bahwa ini mewakili pergeseran mendasar dalam cara tim software beroperasi. Disiplin ini meminjam dari praktik terbaik software engineering selama puluhan tahun — continuous integration, architecture decision records, dependency injection — tetapi menggunakannya kembali untuk dunia yang digerakkan oleh agent. Sumber

Framework HumanLayer

Tim di HumanLayer menerbitkan analisis mereka yang menyebut harness engineering sebagai "masalah keterampilan" — dengan argumen bahwa kemampuan untuk merancang harness yang efektif akan menjadi pembeda utama antara tim engineering yang berkinerja tinggi dan yang kesulitan. Sumber

Apa Artinya Bagi Developer

Harness engineering tidak menggantikan keterampilan developer — melainkan mengarahkannya. Alih-alih menulis kode, senior engineers merancang sistem yang memungkinkan agent menulis kode dengan baik. Keterampilan yang penting bergeser dari implementasi ke arsitektur, dari coding ke desain sistem, dari menulis tes ke merancang framework pengujian.

Untuk tim yang membangun aplikasi, platform seperti ZBuild sudah menggabungkan prinsip-prinsip harness engineering ke dalam alur kerja pembuat aplikasi mereka. Daripada mengharuskan developer untuk merancang harness mereka sendiri dari awal, ZBuild menyediakan pola arsitektur, manajemen dependensi, dan sistem validasi yang dikonfigurasi sebelumnya yang memandu AI agents menuju output berkualitas tinggi — membiarkan developer fokus pada keputusan produk daripada infrastruktur.

Tiga Horizon

Kedepannya, harness engineering kemungkinan akan berkembang melalui tiga fase:

1. Jangka pendek (2026): Tim mengadopsi dokumentasi repository-first, uji struktural, dan golden principles. Pengembangan yang dibantu agent menjadi praktik standar untuk proyek-proyek dengan harness yang baik.

2. Jangka menengah (2027): Pembuatan harness itu sendiri menjadi digerakkan oleh agent. Agent menganalisis codebase yang ada dan mengusulkan konfigurasi harness — aturan linter, uji struktural, batasan dependensi — berdasarkan pola yang mereka amati.

3. Jangka panjang (2028+): Harness menjadi adaptif. Alih-alih aturan statis, mereka berkembang berdasarkan hasil dari kode yang dihasilkan agent, secara otomatis memperketat batasan di area di mana agent sering menghasilkan kesalahan dan melonggarkan batasan di mana mereka secara konsisten berhasil.

Bagian 8: Daftar Periksa Praktis

Gunakan daftar periksa ini untuk mengevaluasi kematangan harness engineering tim Anda:

Dasar (Mulai Di Sini)

• ARCHITECTURE.md ada di root repository
• Pemformatan kode dilakukan secara otomatis (Prettier, Black, gofmt)
• Linting berjalan pada setiap pull request
• Pemeriksaan tipe ditegakkan (TypeScript strict, mypy, dll.)

Menengah

• Uji struktural memvalidasi batasan dependensi
• Golden principles didokumentasikan dan dapat ditegakkan oleh mesin
• Rencana tugas ditulis sebelum eksekusi agent
• PR yang dihasilkan agent melalui CI yang sama dengan PR manusia

Lanjutan

• Automated garbage collection berjalan sesuai jadwal
• Banyak agent dapat bekerja secara paralel tanpa konflik
• Pola kegagalan agent dilacak dan digunakan untuk meningkatkan harness
• Harness itu sendiri dikontrol versinya dan ditinjau seperti kode

Pakar

• Agent menghasilkan bagian dari harness (aturan linter, uji struktural)
• Tingkat kualitas secara otomatis diberikan ke setiap modul
• Peningkatan harness didorong oleh data berdasarkan tingkat keberhasilan agent
• Tim mengirimkan lebih banyak kode per engineer per minggu daripada sebelum mengadopsi agent

Kesimpulan

Harness engineering bukanlah sebuah tren sesaat. Ini adalah evolusi alami dari software engineering di era di mana AI agent cukup mampu untuk menulis kode produksi tetapi membutuhkan lingkungan terstruktur untuk melakukannya dengan baik. Eksperimen sejuta baris OpenAI membuktikan konsep tersebut dalam skala besar, dan prinsip-prinsip yang mereka artikulasikan — repository-first knowledge, golden principles, layered architecture, automated garbage collection, dan rencana yang dapat dieksekusi — dapat diterapkan pada tim dengan ukuran apa pun.

Tim yang menguasai harness engineering pada tahun 2026 akan merilis produk lebih cepat, mempertahankan kualitas kode yang lebih tinggi, dan menskalakan secara lebih efektif daripada mereka yang memperlakukan AI agent sebagai autocomplete yang dimuliakan. Agent adalah kudanya. Harness adalah apa yang membuatnya berguna.

Sumber

• Harness Engineering: Leveraging Codex in an Agent-First World — OpenAI
• Unlocking the Codex Harness: How We Built the App Server — OpenAI
• Unrolling the Codex Agent Loop — OpenAI
• OpenAI Introduces Harness Engineering — InfoQ
• Harness Engineering — Martin Fowler
• Skill Issue: Harness Engineering for Coding Agents — HumanLayer
• From Prompt Engineering to Harness Engineering — SoftmaxData
• How to Build an Agent Harness — Study Notes
• Harness Engineering — GTCode
• OpenAI Harness Engineering: Ship 1M Lines of Code — The Neuron
• How OpenAI Built 1M Lines of Code Using Only Agents — TonyLee
• Harness Engineering — The New Discipline — CodeNote