Cheat sheet harness agen: komponen, file, masalah, dan daftar periksa peluncuran

Lima subsistem harness

Urutan penerapan dari nol: umpan balik → instruksi → status → lingkungan → alat.

File harness

Kerangka AGENTS.md

# Proyek: backend pembayaran (FastAPI, PostgreSQL)

## Menjalankan
docker compose up -d && ./scripts/init.sh

## Pemeriksaan
make check   # lint, tipe, unit, arch-check
make e2e     # skenario end-to-end

## Definition of Done
- make check dan make e2e — kode 0
- fitur dipindahkan ke passing oleh skrip scripts/verify.sh
- PROGRESS.md diperbarui

## MUST
- kueri ke basis data hanya lewat repository
- rahasia hanya dari variabel lingkungan

## Dokumen
- docs/payments.md — ketika tugas menyentuh pembayaran dan pengembalian dana
- docs/migrations.md — ketika skema basis data berubah

Status fitur

Tingkat verifikasi

Hak untuk menyatakan «selesai» hanya setelah tingkat teratas. Tes unit yang hijau bukan kesiapan.

Mekanisasi aturan

#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WHY: service tidak mengakses basis data secara langsung"
  echo "FIX: gunakan repository dari app/repositories/"
  fail=1
fi
exit $fail

Masalah umum dan solusinya

Peran untuk tugas panjang

Anggaran kerja otonom

• Tujuan — satu kalimat (misalnya membawa semua fitur ke passing).
• WIP=1, batas waktu dan percobaan per fitur.
• Metrik naik secara monoton; regresi berarti rollback segera.
• Migrasi, infrastruktur, uang — eskalasi ke manusia.
• Setelah beberapa review yang gagal, mulai fitur dengan konteks bersih.

Daftar periksa peluncuran agen

1. Ada AGENTS.md: stack, cara menjalankan, perintah pemeriksaan, DoD.
2. make check lulus pada klon yang bersih.
3. Lingkungan dapat direproduksi: file lock, Docker, atau devcontainer.
4. Perintah yang diperlukan tersedia untuk agen; yang berbahaya dilarang atau dijalankan di sandbox.
5. Ada E2E minimal untuk skenario utama.
6. Ada PROGRESS.md dan aturan membacanya di awal sesi.
7. Fitur ada dalam daftar dengan status, hanya satu yang aktif.
8. Status passing ditetapkan oleh skrip.
9. Pesan pemeriksaan memuat WHY dan FIX.
10. Tugas dirumuskan dengan kriteria penerimaan dan batas lingkup.
11. Sudah ditetapkan apa saja yang membutuhkan keputusan manusia.
12. Verification gap sudah dihitung sebelum perubahan, sebagai pembanding.

Metrik harness

Kesimpulan

Harness adalah lingkaran, bukan satu file: instruksi, alat, lingkungan, status, dan umpan balik. Mulailah dari pemeriksaan, jaga AGENTS.md tetap singkat, serahkan status selesai kepada skrip, dan tinjau harness secara berkala. Semua ini dirangkai menjadi satu kesatuan pada proyek contoh di kursus harness engineering.