Kenapa agen sebaiknya melakukan staging alih-alih menyunting berkas langsung?

Karena satu item konten bisa menyentuh beberapa berkas yang saling terkait, dan suntingan separuh jalan adalah bug produksi yang senyap. Staging mengubah keluaran agen menjadi proposal yang divalidasi penuh oleh satu skrip deterministik — pohon kunci, metadata, aset — sebelum ia menulis apa pun ke repositori.

Apa kesalahan paling umum pada konten dwibahasa buatan agen?

Penyimpangan pohon kunci: satu poin tambahan atau bagian yang diganti nama, ditulis di satu bahasa dan tidak di bahasa lainnya. Ia tidak gagal dengan berisik, hanya merusak satu locale dari satu halaman di produksi, dan karena itulah kesetaraan kedua pohon kunci harus menjadi pemeriksaan keras, bukan sekadar butir tinjauan.

Apakah skrip validate-then-write otomatis aman?

Hanya kalau validasinya mencakup semua yang bisa gagal saat menulis. Skrip di sini memvalidasi seluruh kontennya dengan benar, lalu gagal di tengah penulisan karena konstanta yang menjadi titik sisipnya sudah pindah ke modul lain — meninggalkan repo dalam keadaan merge separuh. Penyelesaian anchor dan keberadaan path adalah milik fase validasi.

Bagaimana memberi kredit gambar dalam artikel secara berskala?

Ambil gambarnya dengan skrip yang membaca penulis dan lisensinya dari API sumber alih-alih mengetiknya manual, lalu simpan hasilnya di satu registry bertipe yang di-spread komponen artikel ke komponen figur. Satu gambar yang dipakai tiga artikel lalu membawa satu atribusi yang bisa diperbaiki di satu tempat.

Model itu kuat dan lemah di mana dalam pipeline konten?

Kuat di struktur, konsistensi gaya rumah, dan menghasilkan bahasa kedua yang wajar. Lemah dalam mengetahui apa yang benar dan dalam menahan diri — setiap angka spesifikasi butuh sumber, dan kerangka bagian yang tetap per jenis artikel mencegah bagian kelima yang mengulang bagian kedua.

Pipeline Konten Claude Code untuk Blog Next.js Dwibahasa

Bagaimana blog dwibahasa berisi ratusan artikel dihasilkan dengan Claude Code: folder staging, skrip merge validate-then-write, penjaga paritas, dan insidennya.

Ringkasan Utama

Menerbitkan satu artikel dwibahasa di sini menyentuh lima berkas yang saling terkait, jadi agen tidak pernah menyuntingnya langsung: ia menulis folder staging, dan satu skrip memvalidasi paritas pohon kunci, kelengkapan terjemahan, dan metadata sebelum menulis apa pun. Pagar pengamannya, bukan tulisannya, yang membuat konten buatan agen aman dirilis.

Situs ini punya beberapa ratus artikel, masing-masing ada dua kali — sekali dalam bahasa Inggris dan sekali dalam bahasa Indonesia — dengan pohon kunci yang sama, komponen yang sama, dan data terstruktur yang sama. Itu masalah konten yang tampak seperti masalah menulis padahal sebenarnya masalah konsistensi, dan konsistensi justru titik terlemah model bahasa sekaligus titik terkuat sebuah skrip.

Maka pipeline-nya dibangun di atas pembagian kerja: agen menulis prosa dan memilih struktur, dan skrip deterministik memutuskan apakah keluaran itu boleh masuk ke repositori. Berikut cara kerjanya, termasuk kegagalan yang ia alami hari ini.

Kenapa satu artikel berarti lima berkas, bukan satu

Satu artikel yang terbit tersebar di basis kode karena bagian-bagian framework membutuhkan potongan yang berbeda darinya.

Sebuah komponen React memegang strukturnya — heading, tabel, blok kode, callout — dan membaca setiap kalimat lewat kunci terjemahan.
Dua berkas pesan memegang prosanya, satu per locale, dan pohon kuncinya harus sama persis atau locale yang kurang akan melempar error saat runtime.
Satu entri registry memegang data kartunya: slug, kategori, sampul, tanggal, waktu baca.
Satu entri metadata memegang judul SEO, deskripsi, kata kunci, dan tanggal, dan berkas rute memetakan slug ke komponen yang diimpor secara dinamis.

Menyunting lima berkas dengan tangan untuk satu artikel itu melelahkan; menyuntingnya untuk dua puluh artikel adalah jaminan penyimpangan. Ketidakcocokannya juga tidak gagal dengan berisik — satu kunci yang hilang merusak satu locale dari satu artikel di produksi, jenis bug yang bisa bertahan berbulan-bulan.

Batu Rosetta, bertuliskan dekrit yang sama dalam tiga aksara — Masalah paritas tertua yang diketahui: satu pesan, beberapa aksara, dan pembaca yang hanya bisa memverifikasi versi yang bisa ia baca. Situs dwibahasa punya mode kegagalan yang sama, dan karena itulah kesetaraan pohon kunci ditegakkan skrip, bukan oleh ketelitian. Foto: Hans Hillewaert / Wikimedia Commons, CC BY-SA 4.0

Staging, validasi, baru menulis

Aturan yang membuat semuanya aman adalah agen menghasilkan proposal, bukan suntingan. Semuanya mendarat di direktori staging, dan hanya skrip merge yang boleh menyentuh repositori.

# The agent never edits the five coupled files by hand. It stages, then
# one script validates everything and only then writes anything.

/tmp/blog-staging/agent-a/
  registry.json   # slug, category, dates, cover, SEO title and description
  en.json         # the English fragment, keyed by translationKey
  id.json         # the Indonesian fragment, same key tree
  faqs.json       # five bilingual question and answer pairs

node scripts/merge-blog-staging.mjs   # validates, then edits 5 repo files
node scripts/merge-blog-faqs.mjs      # adds FAQPage schema data
npx tsc --noEmit && npm run build     # parity guard runs inside the build

Skrip itu memeriksa daftar spesifik sebelum menulis satu byte pun: slug dan kunci terjemahan yang unik, kategori dan bulan yang valid, tanggal yang benar, berkas sampul yang benar-benar ada di disk, berkas komponen yang ada, dua pohon kunci locale yang identik, tidak adanya karakter yang merusak format pesan, dan metadata yang lengkap. Baru setelah itu ia menyunting kelima berkasnya.

Penjaga yang benar-benar pernah menangkap sesuatu

Setiap pemeriksaan dalam daftar itu ada karena sesuatu pernah salah. Lima yang paling sering membuktikan kegunaannya adalah ini.

Kesetaraan pohon kunci antar locale. Ini kesalahan agen yang paling umum — satu poin tambahan yang ditulis di satu bahasa dan tidak di bahasa lainnya.
Komponen hanya membaca kunci yang ada. Menangkap judul bagian yang diganti nama sehingga menyisakan panggilan terjemahan menggantung.
Karakter tidak aman di string terjemahan. Kurung kurawal dan tanda kurung sudut adalah milik komponen, bukan prosa, dan satu saja yang nyasar berubah menjadi error format saat runtime.
Penegasan paritas saat build antara registry artikel dan registry metadata, agar sebuah artikel tidak pernah bisa rilis dalam keadaan terdaftar tetapi tanpa metadata.
Paragraf key takeaway yang wajib di setiap artikel, yang memang ada demi answer engine tetapi sekaligus menjadi pemeriksaan bahwa agen memahami artikel yang baru saja ia tulis.

Tak satu pun dari ini pintar. Semuanya murah, mekanis, dan mengubah satu kelas bug produksi yang senyap menjadi skrip yang menolak berjalan.

Buat validatornya bisa dijalankan terhadap artikel yang sudah terbit juga, bukan hanya yang di-staging. Retrofit sepenuhnya melewati jalur staging, dan terjemahan yang disunting tangan adalah persis tempat penyimpangan pohon kunci menyelinap kembali.

Hari ketika pipeline-nya merge separuh jalan

Saat menulis artikel ini, skrip merge-nya gagal dengan cara yang paling mendidik: ia memvalidasi semuanya dengan benar, mulai menulis, lalu melempar error di tengah jalan.

Error: anchor not found in lib/blog-posts-static.ts:
  export const REAL_IMAGE_SLUGS = new Set([

# What had happened: the constant moved to lib/blog-display.ts months ago.
# The merge script validated the staged content perfectly, started writing,
# updated messages/en.json, messages/id.json and the post registry, and
# THEN failed on an anchor it could no longer find.

# The repo was left half-merged: translations present, metadata missing.
# Re-running would not help either, because the script skips slugs that
# already exist in en.json — it considered the work done.

Penyebabnya adalah anchor. Skrip menyisipkan entri baru setelah baris kode tertentu, dan salah satu konstanta itu sudah pindah ke modul lain beberapa waktu lalu. Karena anchor diselesaikan saat menulis alih-alih saat validasi, skrip sudah memperbarui kedua berkas pesan dan registry artikel sebelum menemukan bahwa target ketiganya tidak ada. Lebih buruk lagi, menjalankan ulang bukan jalur pemulihan: skrip melewati slug yang sudah ada di pesan bahasa Inggris, jadi ia menganggap pekerjaannya selesai.

Skrip validate-then-write hanya atomik kalau validasinya mencakup semua yang bisa gagal saat penulisan. Penyelesaian anchor, izin berkas, dan keberadaan path semuanya adalah milik fase validasi — kalau tidak, Anda punya skrip yang hati-hati terhadap data Anda dan ceroboh terhadap prasyaratnya sendiri.

Gambar dan sampul adalah skrip, bukan penilaian manusia

Prinsip yang sama berlaku untuk aset. Gambar sampul dihasilkan dari template situs sendiri, sehingga selalu berukuran benar, selalu sesuai merek, dan tidak pernah berupa foto stok yang lisensinya tak seorang pun periksa. Gambar dalam artikel diunduh dari Wikimedia Commons oleh skrip yang membaca penulis dan lisensinya dari API lalu menuliskannya ke registry bertipe.

# Covers are generated from the site's own template, not downloaded.
node scripts/generate-blog-cover.mjs --manifest covers.json

# In-article images are fetched from Wikimedia Commons, re-encoded, and
# their author and licence are read from the API rather than typed by hand.
node scripts/fetch-blog-inline-images.mjs \
  --manifest images.json --report report.json

# The report becomes a typed registry, so one image reused by three posts
# carries exactly one credit line that can be corrected in one place.
export const BLOG_FIGURES: Record<string, BlogFigureSource> = { ... };

Registry itulah bagian yang akan saya rekomendasikan kepada siapa pun yang melakukan hal serupa. Karena kredit tinggal di satu berkas alih-alih diketik ulang di tiap artikel, gambar yang dipakai tiga artikel membawa satu string atribusi, dan memperbaiki yang keliru cukup satu suntingan, bukan pencarian ke seluruh katalog.

Terminal dengan beberapa panel menjalankan perintah berbeda — Seperti inilah lingkar kerjanya: build staging di satu panel, skrip merge di panel lain, typecheck dan build di panel ketiga. Agen menulis; ketiga panel inilah yang memutuskan apakah hasilnya bertahan. Tangkapan layar: Avelino0 / Wikimedia Commons, CC BY-SA 4.0

Apa yang dikuasai agen, dan apa yang tidak

Setelah beberapa ratus artikel melewati pipeline ini, pembagiannya jelas dan sedikit berlawanan dengan dugaan.

Kuat di struktur. Diberi topik dan gaya rumah, pembagian bagian, tabel, dan contoh kodenya keluar konsisten dan masuk akal.
Kuat di bahasa kedua, dengan satu catatan: bahasa Indonesianya terbaca wajar, tetapi istilah teknis butuh glosarium rumah atau ia akan berayun antara menerjemahkan dan mentransliterasikannya.
Lemah dalam mengetahui apa yang benar. Setiap angka spesifikasi, flag perintah, dan klaim produk butuh sumber, dan karena itulah pipeline ini memperlakukan daftar kutipan sebagai wajib, bukan hiasan.
Lemah dalam menahan diri. Dibiarkan sendiri, ia dengan senang hati menulis bagian kelima yang mengulang bagian kedua, jadi kerangka tetap per jenis artikel lebih berharga daripada prompt apa pun tentang keringkasan.

Ringkasan jujurnya: modelnya penulis draf yang kuat sekaligus pemeriksa fakta yang tidak bisa diandalkan, jadi harness-nya harus menyediakan faktanya dan memverifikasi bentuknya.

Membangun versi Anda sendiri

Kalau Anda memelihara konten di dalam repositori, empat langkah memberi Anda sebagian besar dari ini.

Daftar setiap berkas yang disentuh satu item konten. Kalau jawabannya lebih dari dua, agen sebaiknya melakukan staging alih-alih menyunting.
Tulis satu skrip yang memvalidasi item yang di-staging secara lengkap dan hanya menulis kalau semuanya lolos — termasuk prasyaratnya sendiri.
Taruh invarian yang penting ke dalam build, bukan ke dalam checklist. Satu penegasan paritas yang menggagalkan build setara dengan sepuluh paragraf instruksi.
Otomatiskan asetnya dengan cara yang sama. Sampul yang digenerasi dan gambar yang diambil skrip lengkap dengan atribusi menghapus dua kategori kesalahan sekaligus.

Bagian menarik dari konten buatan agen bukanlah tulisannya, yang justru separuh mudahnya. Yang menarik adalah membangun harness yang cukup ketat sehingga penulis yang percaya diri, fasih, dan sesekali keliru tidak bisa merusak produksi — lalu menjaga harness itu tetap jujur, termasuk pada hari ia menemukan bug pada dirinya sendiri.

Sumber dan bacaan lanjutan