Lewati ke konten utama
Versi: Next

Template AGENTS.md

AGENTS.md (atau CLAUDE.md untuk Claude Code) adalah kontrak antara kamu dan agent: satu file yang dibaca otomatis di awal tiap sesi. Ini investasi dengan return tertinggi di seluruh playbook — 30 menit menulisnya menghemat ribuan token dan puluhan koreksi setiap hari.

:::tip Satu sumber kebenaran Tulis sekali sebagai AGENTS.md, lalu untuk Claude Code cukup buat symlink: ln -s AGENTS.md CLAUDE.md. Semua tool membaca file yang sama, tidak ada drift. :::

Varian minimal​

Untuk repo kecil / proyek pribadi. Mulai dari sini, tambah bagian lain saat agent mulai mengulangi kesalahan yang sama.

# AGENTS.md

## Proyek
API backend untuk aplikasi marathon-helper. Stack: Node.js 20, Fastify, PostgreSQL, Prisma.

## Perintah penting
- Install: `npm install`
- Dev server: `npm run dev` (port 3000)
- Test: `npm test` — WAJIB hijau sebelum menganggap task selesai
- Lint + typecheck: `npm run lint && npm run typecheck`

## Aturan
- Jangan pernah edit file di `prisma/migrations/` yang sudah ada; buat migration baru.
- Jangan commit langsung ke `main`; selalu buat branch `feat/...` atau `fix/...`.
- Rahasia hanya lewat env var; jangan pernah tulis credential di kode atau log.

Varian lengkap​

Untuk repo yang dikerjakan agent secara rutin/otonom. Anotasi per bagian ada di bawahnya.

# AGENTS.md

## Gambaran proyek
<!-- (1) Dua-tiga kalimat: apa sistem ini, siapa penggunanya, bagian mana yang paling sensitif. -->
Aplikasi manajemen pelatihan marathon. Monorepo: `apps/api` (Fastify),
`apps/web` (Next.js), `packages/shared` (tipe & util bersama).
Bagian paling sensitif: modul pembayaran di `apps/api/src/billing/`.

## Setup & perintah
<!-- (2) Perintah persis, bukan deskripsi. Agent akan menjalankannya verbatim. -->
- Install: `pnpm install`
- Dev: `pnpm dev` (api :3000, web :3001)
- Test cepat (unit): `pnpm test:unit`
- Test penuh: `pnpm test` (butuh Docker untuk Postgres)
- Lint + typecheck: `pnpm check`
- Build produksi: `pnpm build`

## Definisi "selesai"
<!-- (3) Bagian terpenting. Tanpa ini, agent menganggap "kode tertulis" = selesai. -->
Sebuah task baru boleh dianggap selesai jika:
1. `pnpm check` lolos tanpa error.
2. `pnpm test:unit` hijau, plus test baru untuk perilaku baru.
3. Perubahan berupa diff sekecil mungkin — jangan reformat file yang tidak disentuh.
4. Tidak ada TODO/console.log/dead code tersisa dari proses kerja.

## Gaya kode
<!-- (4) Hanya yang TIDAK ditangkap linter. Aturan yang sudah di-enforce eslint tidak perlu ditulis. -->
- Error handling: lempar `AppError` dari `packages/shared/errors.ts`, jangan `throw new Error` mentah.
- Query DB hanya lewat repository layer (`src/repos/`), tidak boleh Prisma langsung di handler.
- Komentar hanya untuk menjelaskan "kenapa", bukan "apa".

## Batasan keras
<!-- (5) Hal yang tidak boleh dilakukan agent tanpa persetujuan eksplisit manusia. -->
- JANGAN mengubah skema DB / membuat migration tanpa konfirmasi.
- JANGAN menyentuh `apps/api/src/billing/` tanpa konfirmasi.
- JANGAN menjalankan perintah destruktif (`drop`, `rm -rf`, `--force`) di luar direktori repo.
- JANGAN upgrade dependency mayor; patch/minor boleh jika test tetap hijau.
- Jangan pernah menulis PII/credential ke file, commit, atau log.

## Konteks & keputusan arsitektur
<!-- (6) Keputusan yang sering dipertanyakan ulang oleh agent. Tulis sekali di sini. -->
- Kita sengaja TIDAK pakai ORM relations Prisma untuk query berat — pakai raw SQL
  di `src/repos/raw/`, alasannya performa (lihat ADR-007).
- Autentikasi pakai session cookie, BUKAN JWT — jangan sarankan migrasi ke JWT.

## Workflow git
<!-- (7) Konvensi commit/branch/PR supaya output agent langsung rapi. -->
- Branch: `feat/<slug>`, `fix/<slug>`, `chore/<slug>`.
- Commit: Conventional Commits (`feat: ...`, `fix: ...`), imperatif, ≤72 karakter.
- PR: deskripsi wajib berisi "apa berubah", "kenapa", dan "cara verifikasi".

Anotasi​

  1. Gambaran proyek — agent baru "masuk kerja" tiap sesi; dua kalimat orientasi mencegah eksplorasi buta yang mahal.
  2. Setup & perintah — perintah persis membuat agent langsung produktif; ini juga yang dipakai agent untuk self-verify.
  3. Definisi "selesai" — bagian dengan dampak terbesar. Agent secara default berhenti terlalu cepat; definisi eksplisit memaksa loop verifikasi.
  4. Gaya kode — jangan duplikasi aturan linter; tulis hanya konvensi yang butuh pemahaman konteks.
  5. Batasan keras — daftar "jangan" yang spesifik jauh lebih efektif daripada himbauan umum "hati-hati".
  6. Keputusan arsitektur — mencegah agent "memperbaiki" hal yang sengaja dibuat begitu. Sumber frustrasi klasik.
  7. Workflow git — output agent (branch, commit, PR) langsung mengikuti standar tim tanpa diedit manual.

Aturan praktis​

  • Pendek lebih baik. File ini masuk ke context window setiap sesi. Target di bawah ±150 baris; kalau membengkak, pindahkan detail ke docs terpisah dan rujuk path-nya.
  • Rawat seperti kode. Setiap kali agent salah karena tidak tahu sesuatu, tanya dirimu: "harusnya ini ada di AGENTS.md?" — lalu tambahkan lewat PR.
  • Jangan tulis yang bisa ditemukan sendiri. Struktur folder dan isi package.json bisa dibaca agent; yang perlu ditulis adalah hal yang tidak terlihat dari kode: alasan, batasan, definisi selesai.

Lanjut praktik: Playbook — Persiapan Repo.

Diperbaharui pada