Dokumentasi ChatGPT
Bahasa Indonesia
Hubungi kami goolvyouyou@gmail.com

Instruksi khusus dengan AGENTS.md

Berikan instruksi dan konteks tambahan tentang proyek Anda kepada Codex

Codex membaca file AGENTS.md sebelum melakukan pekerjaan apa pun. Dengan menyusun panduan global berlapis bersama penggantian khusus proyek, Anda dapat memulai setiap tugas dengan ekspektasi yang konsisten, apa pun repositori yang Anda buka.

Cara Codex menemukan panduan

Codex menyusun rantai instruksi saat dimulai (satu kali per eksekusi; di TUI, ini biasanya berarti satu kali per sesi yang diluncurkan). Penemuan mengikuti urutan prioritas berikut:

  1. Cakupan global: Di direktori beranda Codex Anda (secara default ~/.codex, kecuali Anda menetapkan CODEX_HOME), Codex membaca AGENTS.override.md jika file tersebut ada. Jika tidak, Codex membaca AGENTS.md. Codex hanya menggunakan file pertama yang tidak kosong pada tingkat ini.
  2. Cakupan proyek: Dimulai dari root proyek (biasanya root Git), Codex menelusuri hierarki hingga direktori kerja Anda saat ini. Jika Codex tidak dapat menemukan root proyek, Codex hanya memeriksa direktori saat ini. Di setiap direktori pada jalur tersebut, Codex memeriksa AGENTS.override.md, kemudian AGENTS.md, lalu nama fallback apa pun dalam project_doc_fallback_filenames. Codex menyertakan paling banyak satu file per direktori.
  3. Urutan penggabungan: Codex menggabungkan file mulai dari root ke bawah dan memisahkannya dengan baris kosong. File yang lebih dekat dengan direktori Anda saat ini menggantikan panduan sebelumnya karena muncul belakangan dalam prompt gabungan.

Codex melewati file kosong dan berhenti menambahkan file setelah ukuran gabungan mencapai batas yang ditentukan oleh project_doc_max_bytes (32 KiB secara default). Untuk detail tentang pengaturan ini, lihat Penemuan instruksi proyek. Naikkan batas atau pisahkan instruksi ke beberapa direktori bertingkat jika Anda mencapai batas tersebut.

Membuat panduan global

Buat default persisten di direktori beranda Codex agar setiap repositori mewarisi kesepakatan kerja Anda.

  1. Pastikan direktori tersebut ada:

    mkdir -p ~/.codex

  2. Buat ~/.codex/AGENTS.md dengan preferensi yang dapat digunakan kembali:

    # ~/.codex/AGENTS.md

## Working agreements

- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.

  3. Jalankan Codex di lokasi mana pun untuk memastikan bahwa file tersebut dimuat:

    codex --ask-for-approval never "Summarize the current instructions."

    Hasil yang diharapkan: Codex mengutip butir-butir dari ~/.codex/AGENTS.md sebelum mengusulkan pekerjaan.

Gunakan ~/.codex/AGENTS.override.md saat Anda memerlukan penggantian global sementara tanpa menghapus file dasar. Hapus penggantian tersebut untuk memulihkan panduan bersama.

Menyusun instruksi proyek berlapis

File tingkat repositori membuat Codex tetap memahami norma proyek sekaligus mewarisi default global Anda.

  1. Di root repositori, tambahkan AGENTS.md yang mencakup penyiapan dasar:

    # AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.

  2. Tambahkan penggantian di direktori bertingkat saat tim tertentu memerlukan aturan berbeda. Misalnya, di dalam services/payments/, buat AGENTS.override.md:

    # services/payments/AGENTS.override.md

## Payments service rules

- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.

  3. Mulai Codex dari direktori pembayaran:

    codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

    Hasil yang diharapkan: Codex melaporkan file global terlebih dahulu, AGENTS.md di root repositori pada urutan kedua, dan penggantian pembayaran pada urutan terakhir.

Codex berhenti mencari setelah mencapai direktori Anda saat ini, jadi tempatkan penggantian sedekat mungkin dengan pekerjaan khusus terkait.

Berikut contoh repositori setelah Anda menambahkan file global dan penggantian khusus pembayaran:

<FileTree class="mt-4" tree={[ { name: "AGENTS.md", comment: "Ekspektasi repositori", highlight: true, }, { name: "services/", open: true, children: [ { name: "payments/", open: true, children: [ { name: "AGENTS.md", comment: "Diabaikan karena terdapat penggantian", }, { name: "AGENTS.override.md", comment: "Aturan layanan pembayaran", highlight: true, }, { name: "README.md" }, ], }, { name: "search/", children: [{ name: "AGENTS.md" }, { name: "…", placeholder: true }], }, ], }, ]} />

Menambahkan aturan peninjauan kode

Untuk peninjauan kode Codex di GitHub, tambahkan bagian ## Code Review Rules ke AGENTS.md yang paling dekat dengan kode yang diatur oleh aturan tersebut. Tempatkan pemeriksaan untuk seluruh repositori di root dan pemeriksaan khusus layanan dalam file bertingkat.

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

Buat aturan tetap ringkas, jelaskan perilaku yang perlu ditandai serta setiap jalur aman atau pengecualian, dan serahkan pemeriksaan pemformatan serta lint kepada CI. Lihat Menyesuaikan hal yang ditinjau Codex untuk panduan penyiapan dan penulisan aturan.

Menyesuaikan nama file fallback

Jika repositori Anda sudah menggunakan nama file lain (misalnya TEAM_GUIDE.md), tambahkan nama tersebut ke daftar fallback agar Codex memperlakukannya seperti file instruksi.

  1. Edit konfigurasi Codex Anda:

    # ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

  2. Mulai ulang Codex atau jalankan perintah baru agar konfigurasi yang diperbarui dimuat.

Sekarang Codex memeriksa setiap direktori dengan urutan berikut: AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. Nama file yang tidak ada dalam daftar ini diabaikan selama penemuan instruksi. Batas byte yang lebih besar memungkinkan lebih banyak panduan gabungan sebelum terpotong.

Dengan daftar fallback tersebut, Codex memperlakukan file alternatif sebagai instruksi:

<FileTree class="mt-4" tree={[ { name: "TEAM_GUIDE.md", comment: "Terdeteksi melalui daftar fallback", highlight: true, }, { name: ".agents.md", comment: "File fallback di root", }, { name: "support/", open: true, children: [ { name: "AGENTS.override.md", comment: "Menggantikan panduan fallback", highlight: true, }, { name: "playbooks/", children: [{ name: "…", placeholder: true }], }, ], }, ]} />

Tetapkan variabel lingkungan CODEX_HOME saat Anda menginginkan profil berbeda, seperti pengguna otomatisasi khusus proyek:

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

Hasil yang diharapkan: Output mencantumkan file relatif terhadap direktori khusus .codex.

Memverifikasi penyiapan Anda

  • Jalankan codex --ask-for-approval never "Summarize the current instructions." dari root repositori. Codex seharusnya menampilkan kembali panduan dari file global dan proyek sesuai urutan prioritas.
  • Gunakan codex --cd subdir --ask-for-approval never "Show which instruction files are active." untuk memastikan penggantian bertingkat menggantikan aturan yang lebih luas.
  • Untuk mengaudit file instruksi yang dimuat Codex, aktifkan log TUI teks biasa dengan codex -c log_dir=./.codex-log dan periksa ./.codex-log/codex-tui.log, atau periksa file session-*.jsonl terbaru jika Anda mengaktifkan pencatatan sesi.
  • Jika instruksi tampak usang, mulai ulang Codex di direktori target. Codex menyusun ulang rantai instruksi pada setiap eksekusi (dan pada awal setiap sesi TUI), sehingga tidak ada cache yang perlu dihapus secara manual.

Memecahkan masalah penemuan

  • Tidak ada yang dimuat: Pastikan Anda berada di repositori yang dimaksud dan bahwa codex status melaporkan root ruang kerja yang Anda harapkan. Pastikan file instruksi berisi konten; Codex mengabaikan file kosong.
  • Panduan yang salah muncul: Cari AGENTS.override.md yang lebih tinggi dalam hierarki direktori atau di bawah beranda Codex Anda. Ganti nama atau hapus penggantian tersebut untuk kembali menggunakan file biasa.
  • Codex mengabaikan nama fallback: Pastikan Anda mencantumkan nama tersebut dalam project_doc_fallback_filenames tanpa kesalahan ketik, lalu mulai ulang Codex agar konfigurasi yang diperbarui diterapkan.
  • Instruksi terpotong: Naikkan project_doc_max_bytes atau pisahkan file besar ke beberapa direktori bertingkat agar panduan penting tetap utuh.
  • Kebingungan profil: Jalankan echo $CODEX_HOME sebelum meluncurkan Codex. Nilai non-default mengarahkan Codex ke direktori beranda yang berbeda dari direktori yang Anda edit.

Langkah selanjutnya