Headless Mode Claude Code untuk Pipeline CI/CD

Kebanyakan orang mengenal Claude Code sebagai chat terminal interaktif: Anda mengetik, ia bekerja, Anda menyetujui. Loop itu bagus untuk coding eksploratif dan tak berguna untuk otomasi, karena sebuah CI runner tidak punya siapa pun untuk menjawab promptnya. Untuk menaruh agen di dalam pipeline, Anda butuh ia berjalan sekali, mengerjakan tugas, lalu menyingkir.

Headless mode adalah jalur non-interaktif itu. Anda memanggil Claude Code dengan sebuah prompt dan sekumpulan flag, ia berjalan sampai selesai tanpa percakapan, lalu melapor kembali dalam bentuk yang bisa diurai skrip. Panduan ini membahas perintah intinya, cara mengontrol apa yang boleh dilakukannya, dan cara menjalankannya dengan aman di CI tanpa membuka pintu lebar-lebar.

Apa itu headless mode

Headless mode, disebut juga print mode, adalah Claude Code yang dipanggil dengan flag -p dan sebuah prompt. Alih-alih memulai sesi interaktif, ia memproses prompt, memancarkan keluarannya ke standard out, lalu keluar dengan sebuah status code. Itu menjadikannya program baris perintah biasa yang bisa Anda pipe, redirect, dan panggil dari skrip atau job mana pun.

Beberapa sifat membuatnya cocok untuk otomasi ketimbang chat sehari-hari:

• Ia stateless secara default: tiap run dimulai dari awal, sehingga sebuah langkah pipeline bisa direproduksi dan tidak bergantung pada percakapan sebelumnya.
• Ia bisa diskripkan: Anda bisa memberikan prompt secara inline atau lewat standard input dan menangkap semua yang dicetaknya.
• Ia bisa dikomposisikan: exit code memberi tahu job di sekitarnya apakah langkah itu lulus, sehingga Anda bisa menggerbang sebuah build padanya.

Perintah inti dan format keluaran

Pemanggilan paling sederhana memberikan sebuah string prompt setelah -p. Untuk otomasi Anda hampir selalu menambahkan format keluaran, karena mengurai teks bebas itu rapuh. Minta JSON dan Anda mendapatkan objek terstruktur berisi hasil dan metadata seperti penggunaan token yang bisa Anda catat atau jadikan asersi.

Sebuah pemanggilan CI minimal yang membatasi tool dan mengembalikan JSON terlihat seperti ini:

claude -p "Review the staged diff and fail if any TODO is left" \
  --output-format json \
  --allowedTools "Read,Grep,Glob" \
  --permission-mode plan \
  --max-turns 12

Rangkai ke dalam CI/CD

Di dalam pipeline, headless Claude Code hanyalah satu langkah lagi yang entah berhasil atau gagal. Polanya sama di semua sistem CI: autentikasi, jalankan perintah dengan izin ketat, lalu bercabang berdasarkan hasilnya.

• Sediakan kredensial lewat sebuah secret, biasanya sebuah API key yang diekspos ke job sebagai variabel lingkungan, jangan pernah ditulis langsung di workflow.
• Beri langkah itu tugas sempit yang terdefinisi baik seperti mereview sebuah diff, menyusun catatan rilis, atau memilah tes yang gagal, alih-alih tujuan yang terbuka.
• Tangkap keluaran JSON dan gunakan exit code untuk meluluskan atau menggagalkan tahap itu, sehingga agen menjadi gerbang sungguhan dan bukan sekadar bising yang bersifat saran.
• Pasang batas seperti jumlah maksimum giliran, sehingga run yang bingung berhenti alih-alih berputar dan menghabiskan anggaran.

Jaga radius ledakannya

Agen non-interaktif persis seberbahaya izin yang Anda berikan kepadanya, karena tidak ada manusia dalam loop untuk menangkap langkah yang buruk. Seluruh model keamanan bertumpu pada mempersempit run ke minimum yang dibutuhkannya dan menjalankannya di tempat yang tidak bisa menimbulkan kerusakan permanen.

Dalam praktik itu berarti menggabungkan allowlist tool yang ketat dengan lingkungan yang terisolasi. Sebuah CI runner sudah bersifat sementara, yang membantu, tetapi sebuah job yang meng-clone repo Anda dan memegang API key sungguhan tetap layak di-sandbox, sehingga instruksi hasil prompt injection yang tersembunyi dalam kode yang dibacanya tidak bisa menjangkau lebih jauh dari runner.

Ide otomasi yang praktis

Begitu Claude Code menjadi sebuah perintah, job yang berguna adalah yang berulang, mudah dijelaskan, dan murah diverifikasi.

• Pemeriksaan pull request yang membaca sebuah diff dan menandai tes yang hilang, kode debug yang tertinggal, atau API publik yang tak berdokumentasi.
• Pre-commit hook yang menjalankan agen secara lokal dalam print mode untuk menangkap masalah yang jelas sebelum sampai ke CI.
• Job pemeliharaan terjadwal, seperti menyusun changelog dari commit yang telah di-merge atau meringkas kegagalan tes semalam.

Headless mode adalah sambungan antara Claude Code dan sisa toolchain Anda. Gunakan claude -p setiap kali Anda ingin agen berjalan sekali lalu melapor kembali, pasang tool dan izinnya secara ketat, baca JSON alih-alih mengorek teks, dan jaga tiap run tanpa pengawasan tetap di dalam sandbox. Lakukan itu dan agen menjadi sekadar satu langkah andal lagi dalam pipeline.