Lewati ke konten utama
Versi: 1.1

Langkah 1 — Persiapan Repo

Agent hanya sebagus konteks dan umpan balik yang tersedia di repomu. Sebelum menyerahkan pekerjaan, pastikan repo memberi agent dua hal: cara memverifikasi sendiri (test, lint, typecheck yang cepat) dan pengetahuan proyek (AGENTS.md). Tanpa keduanya, agent akan "berhasil" dengan percaya diri menghasilkan kode yang salah.

Pastikan ada satu perintah untuk test, dan hasilnya deterministik

Agent memverifikasi pekerjaannya dengan menjalankan test. Kalau test lambat, flaky, atau butuh setup manual, agent akan berputar-putar atau — lebih buruk — menyimpulkan "test gagal karena environment" lalu melanjutkan tanpa verifikasi.

Target: satu perintah, jalan dari checkout bersih, selesai di bawah ± 2 menit untuk suite yang sering dipakai.

# contoh package.json (sesuaikan dengan stack-mu)
npm test          # unit test, cepat, tanpa network
npm run test:e2e  # boleh lambat, dipisah dari suite utama

Kalau test butuh database/service, sediakan jalur lokal yang bisa dinyalakan satu perintah:

docker compose up -d db && npm test

Checkpoint: dari clone bersih, npm install && npm test (atau padanannya di stack-mu) lolos tanpa langkah manual, dua kali berturut-turut dengan hasil sama.

Satukan lint + format + typecheck dalam satu perintah

Ini gerbang kualitas termurah — agent bisa menjalankannya berkali-kali tanpa biaya besar.

# contoh: tambahkan script "check" yang menggabungkan semuanya
npm pkg set scripts.check="eslint . && prettier --check . && tsc --noEmit"
npm run check

Checkpoint: npm run check lolos di kondisi repo sekarang. Kalau ada ratusan error warisan, perbaiki dulu (ini task pertama yang bagus untuk agent — lihat langkah 2) atau turunkan aturannya; error baseline yang dibiarkan membuat agent tidak bisa membedakan error miliknya dari error lama.

Tulis AGENTS.md

AGENTS.md adalah konvensi standar file konteks untuk agent (Claude Code juga membaca CLAUDE.md; sebagian besar tool modern membaca keduanya — cukup buat satu dan symlink).

touch AGENTS.md
ln -s AGENTS.md CLAUDE.md   # Claude Code versi lama; versi baru sudah membaca AGENTS.md

Yang masuk (hal yang tidak bisa disimpulkan dari membaca kode):

AGENTS.md
# <Nama Proyek>

## Perintah penting
- Test: `npm test` (unit, ± 60 detik). E2E: `npm run test:e2e` (± 5 menit, jalankan hanya jika diminta).
- Lint + typecheck: `npm run check`
- Dev server: `npm run dev` (port 3000)

## Arsitektur singkat
- `src/api/` — route handlers (Fastify). Semua akses DB lewat `src/db/repos/`, jangan query langsung.
- `src/jobs/` — background worker (BullMQ). Idempotent wajib.

## Aturan proyek
- Jangan pernah edit file di `src/generated/` — hasil codegen, jalankan `npm run codegen`.
- Migrasi DB: buat lewat `npm run migrate:new`, jangan tulis SQL migrasi manual.
- Error handling: lempar `AppError`, jangan `throw new Error` mentah.

## Definisi selesai
- `npm run check` dan `npm test` hijau, dan perubahan punya test.

Yang TIDAK masuk: penjelasan panjang arsitektur yang bisa dibaca dari kode, style guide umum bahasa (agent sudah tahu), riwayat proyek, atau daftar semua file. File ini dibaca di setiap sesi — setiap paragraf yang tidak mengubah perilaku agent adalah pajak konteks.

Checkpoint: AGENTS.md ≤ ± 100 baris, dan setiap barisnya berupa instruksi yang bisa ditindaklanjuti, bukan deskripsi.

Strukturkan task agar agent-friendly

Agent bekerja paling baik dengan task yang punya batas jelas dan kriteria sukses eksplisit. Biasakan menulis issue (GitHub Issues, Linear, atau sekadar TASKS.md) dengan pola:

## Judul: perilaku yang diinginkan, bukan solusi
**Konteks:** di mana masalahnya terjadi, file/route yang relevan kalau tahu.
**Kriteria selesai:**
- [ ] perilaku X terjadi ketika Y
- [ ] test menutupi kasus Z
**Non-goal:** apa yang TIDAK boleh disentuh (mis. jangan ubah skema DB).

Bagian Non-goal adalah yang paling sering dilupakan dan paling besar dampaknya — ini yang mencegah agent "sekalian merapikan" separuh codebase.

Checkpoint: ada minimal 3 task nyata di backlog yang ditulis dengan pola ini — akan dipakai sebagai bahan uji di Langkah 2.

Bersihkan jebakan umum

Audit cepat hal-hal yang paling sering menjebak agent:

  • Secrets di repo — pastikan .env masuk .gitignore dan sediakan .env.example. Agent yang membaca .env bisa tanpa sengaja menyalin secret ke log/PR.
  • File raksasa hasil build (dist/, node_modules/, lockfile bukan) — pastikan ter-ignore, agar tidak memenuhi context window saat agent mencari kode.
  • Branch protection di branch utama: wajibkan PR + CI hijau. Ini gerbang terakhir kalau semua lapisan lain gagal.
# contoh dengan GitHub CLI
gh api repos/<OWNER>/<REPO>/branches/main/protection -X PUT \
  -f 'required_status_checks[strict]=true' \
  -f 'required_status_checks[contexts][]=ci' \
  -F 'enforce_admins=false' \
  -F 'required_pull_request_reviews=null' -F 'restrictions=null'

Checkpoint: push langsung ke main ditolak; PR tanpa CI hijau tidak bisa merge; git grep -iE "api[_-]?key|secret" -- ':!*.lock' tidak menemukan secret sungguhan.

:::tip Repo hygiene adalah pekerjaan agent juga Semua langkah di atas boleh kamu delegasikan ke agent begitu ia ter-setup — "tulis AGENTS.md berdasarkan eksplorasi repo ini, maksimal 100 baris" adalah salah satu task pertama terbaik. Tapi review hasilnya tetap milikmu: kamu yang tahu aturan mana yang benar. :::

Selanjutnya: Langkah 2 — Setup Agent

Diperbaharui pada