Pelajaran #3: Create a CLAUDE.md File + Design an Agent Harness
1 November 2026
Kemarin kamu belajar SKILL.md dan DESIGN.md, dua file pendamping AGENTS.md. Hari ini kamu naik satu tingkat. CLAUDE.md mengatur cara Claude Code bekerja di satu repo. Agent harness mengatur cara sebuah agent boleh bertindak di dalam produk. Yang pertama soal instruksi. Yang kedua soal rangka kerja dan izin.
1. Create a CLAUDE.md File
Apa itu dan kapan dipakai
Prompt ini menulis CLAUDE.md, yaitu file instruksi proyek khusus untuk Claude Code. Isinya gambaran proyek, perintah yang biasa dipakai, konvensi tim, aturan desain, alat yang tersedia, dan batas persetujuan. Pakai prompt ini kalau tim kamu bekerja terutama di Claude Code dan butuh aturan yang lebih spesifik daripada AGENTS.md. Kalau AGENTS.md sudah ada, jaga agar aturan bersama tetap di sana. CLAUDE.md dibuat lebih tipis, hanya berisi perintah, alat Claude, dan kebiasaan khusus Claude.
Mengapa bekerja
Prompt ini bekerja karena ia memisahkan tiga hal sebelum menulis. Konteks proyek, cara tim bekerja, dan pemakaian khusus Claude. Agent jadi tahu apa produknya, bagaimana tim bekerja, dan apa yang boleh ia lakukan sendiri. Format keluarannya dikunci lewat 12 bagian wajib, dari gambaran proyek sampai perilaku eskalasi. Dua pengaman penting ada di sini. Bagian yang belum diketahui harus ditandai NEEDS TEAM INPUT, bukan dikarang. Kalimat pembuka file menjelaskan kapan memakai AGENTS.md dan kapan memakai CLAUDE.md, jadi dua file tidak saling bertabrakan.
Catatan gaya: prompt ini tidak cenderung menghasilkan gaya slop, karena keluarannya berupa instruksi singkat yang tegas. Risikonya justru di sisi lain. Kalau kurung dibiarkan kosong, agent mengarang perintah dan aturan, dan file itu terlihat meyakinkan padahal isinya tebakan. Isi kurung dengan perintah dan aturan yang nyata.
Teks prompt
You write Claude Code project files. Create a CLAUDE.md for this workspace.
## Project
- Name and purpose: [project]
- Target users: [users]
- Product stage: [stage]
- Tech stack: [stack]
- Repository structure: [structure]
- Important directories and source files: [files]
## How the team works
- Setup or common commands: [commands]
- Coding conventions: [conventions]
- Design-system references and requirements: [references]
- Content and UX writing rules: [rules]
- Testing and QA standards: [standards]
- Accessibility, privacy, and security requirements: [requirements]
## Claude-specific usage
- Typical tasks Claude should help with: [tasks]
- Tools, MCP servers, or integrations available: [tools]
- External actions requiring approval: [actions]
- Actions Claude must never take: [actions]
- Preferred task handoff format: [format]
Write CLAUDE.md with:
1. Project overview
2. How to orient in the workspace
3. Source-of-truth documents
4. Build, test, and verification commands
5. Code and design conventions
6. UI, design-system, and accessibility rules
7. Task-planning and clarification behavior
8. Tool-use and approval rules
9. Definition of done
10. Reporting and handoff format
11. Prohibited actions
12. Escalation behavior
Use short directive Markdown. Add [NEEDS TEAM INPUT] for anything missing.
Start the file with this note:
Use AGENTS.md when you want one instruction file many tools can read. Use CLAUDE.md when the team works mainly in Claude Code and needs Claude-specific setup.Contoh terisi
Contoh ini untuk PindaiKu, aplikasi pemindai dokumen dan perkakas PDF yang sudah live.
You write Claude Code project files. Create a CLAUDE.md for this workspace.
## Project
- Name and purpose: PindaiKu, aplikasi web pemindai dokumen dan perkakas PDF untuk pengguna umum
- Target users: pengguna umum yang memindai dokumen lewat HP atau laptop
- Product stage: live, versi beta
- Tech stack: HTML, CSS, dan JavaScript tanpa framework, dihost di Cloudflare Pages
- Repository structure: folder sumber aplikasi web dengan file utama, file gaya, dan service worker
- Important directories and source files: file aplikasi utama, file gaya, service worker, dan halaman hub
## How the team works
- Setup or common commands: deploy lewat wrangler ke Cloudflare Pages, dan cek tampilan di WebKit pada ukuran HP
- Coding conventions: tanpa komentar di file live, dan naikkan versi file gaya dan skrip bersamaan dengan nama cache service worker setiap deploy
- Design-system references and requirements: DESIGN.md PindaiKu dan biru Kumbang
- Content and UX writing rules: label saja, bahasa netral, tanpa slogan
- Testing and QA standards: uji jalan penuh sebagai pengguna sebelum deploy, bukan hanya cek mekanis
- Accessibility, privacy, and security requirements: kontras kuat, tombol mudah disentuh, dukungan keyboard, dan data pengguna tidak dikirim ke server
## Claude-specific usage
- Typical tasks Claude should help with: memperbaiki filter dokumen, menambah perkakas PDF, dan memperbaiki tampilan
- Tools, MCP servers, or integrations available: Claude Code, WebKit untuk cek tampilan, dan wrangler untuk deploy
- External actions requiring approval: deploy ke situs live dan perubahan susunan layar
- Actions Claude must never take: mengubah data pengguna, menambah iklan, dan mengubah identitas aplikasi
- Preferred task handoff format: daftar perubahan bernomor dengan bukti tangkapan layar
Write CLAUDE.md with:
1. Project overview
2. How to orient in the workspace
3. Source-of-truth documents
4. Build, test, and verification commands
5. Code and design conventions
6. UI, design-system, and accessibility rules
7. Task-planning and clarification behavior
8. Tool-use and approval rules
9. Definition of done
10. Reporting and handoff format
11. Prohibited actions
12. Escalation behavior
Use short directive Markdown. Add [NEEDS TEAM INPUT] for anything missing.
Start the file with this note:
Use AGENTS.md when you want one instruction file many tools can read. Use CLAUDE.md when the team works mainly in Claude Code and needs Claude-specific setup.Tugas praktik hari ini
Pakai prompt ini untuk menulis CLAUDE.md satu repo Kumbang, misalnya PindaiKu. Setelah itu jalankan satu tugas kecil di Claude Code. Perhatikan bagian mana yang diabaikan agent, lalu perketat bagian itu. Itu cara file ini menjadi lebih tajam.
2. Design an Agent Harness
Apa itu dan kapan dipakai
Harness adalah rangka kerja tempat sebuah agent berjalan. Isinya instruksi, alat yang boleh dipakai, matriks izin, gerbang review, cara memulihkan kegagalan, dan cara memeriksa hasil. Prompt ini merancang harness itu sebelum agent boleh bertindak. Pakai prompt ini saat agent akan menyentuh data nyata, file produksi, atau aksi yang sulit dibatalkan. Jangan mulai dari tampilan atau dari prompt percakapan. Mulai dari harness.
Mengapa bekerja
Prompt ini bekerja karena ia memaksa kamu menjawab pertanyaan sulit di awal. Apa tugas agent. Apa yang bisa ia lakukan. Apa risikonya kalau ia salah. Apa yang boleh otomatis, apa yang butuh persetujuan kamu, dan apa yang dilarang sama sekali. Keluaran dikunci lewat 12 bagian, termasuk matriks izin dengan enam tingkat, dari sekadar memberi tahu sampai dilarang, dan loop kerja tujuh langkah, dari menerima tugas sampai mencatat hasil. Kalimat pengaman di akhir penting. Jangan merekomendasikan eksekusi otomatis untuk aksi yang tidak bisa dibatalkan, berdampak besar, atau sulit diverifikasi. Harness yang bagus membuat agent yang cepat sekaligus aman.
Catatan gaya: dokumen harness bisa jadi panjang. Itu wajar untuk rancangan. Untuk versi pertama, pakai rencana MVP di bagian 11 dan jalankan dulu versi yang aksi berisikonya masih butuh persetujuan kamu.
Teks prompt
You design how AI agents run in products. Design the harness for this workflow.
## Agent purpose
- Agent name: [name]
- User problem to solve: [problem]
- Primary users: [users]
- Desired outcome: [outcome]
- Product or workflow context: [context]
## Agent capabilities
- What the agent can analyze, generate, retrieve, or do: [capabilities]
- Tools and integrations available: [tools]
- Data and source systems available: [sources]
- Persistent instructions or project files available: [AGENTS.md, DESIGN.md, skills, docs]
- Memory requirements: [memory needs]
## Risk and boundaries
- Consequences of error: [risk]
- Sensitive data or policy constraints: [constraints]
- Actions requiring explicit approval: [actions]
- Actions allowed automatically: [actions]
- Prohibited actions: [actions]
- Reversal or rollback options: [options]
## Quality requirements
- What a good outcome looks like: [quality bar]
- How work should be verified: [verification]
- User feedback mechanisms: [feedback]
- Metrics to track: [metrics]
Produce:
1. What the agent is for, and what it is not for
2. System instructions and operating rules
3. Context layout: persistent, task, retrieved, working memory, and long-term memory if needed
4. Tool list and tool-use rules
5. Permission matrix: inform, recommend, draft, execute with approval, execute automatically, prohibited
6. Agent loop: intake, clarify, plan, act, verify, report, log
7. Where a person reviews or escalates
8. UX states for progress, uncertainty, approval, failure, and completion
9. A simple scorecard: accuracy, usefulness, safety, evidence, appropriate uncertainty
10. Failure, retry, rollback, and partial-completion behavior
11. A phased MVP plan
12. Open risks and questions that need a human decision
Use tables where they help. Do not recommend auto-execute for irreversible, high-impact, or hard-to-verify actions.Contoh terisi
Contoh ini untuk pekerjaan dinas Aulia yang nyata, yaitu agent yang membantu konsolidasi laporan bulanan UPTD ke POPULASI 2026.xlsx.
You design how AI agents run in products. Design the harness for this workflow.
## Agent purpose
- Agent name: Agen Konsolidasi Laporan UPTD
- User problem to solve: laporan bulanan UPTD datang sebagai PDF pindaian dan harus diringkas ke POPULASI 2026.xlsx
- Primary users: Aulia di bagian data dan informasi dinas
- Desired outcome: angka JUMLAH tiap kecamatan masuk ke sheet bulan yang benar, tanpa mengubah template
- Product or workflow context: file template POPULASI 2026.xlsx dan folder laporan bulanan UPTD
## Agent capabilities
- What the agent can analyze, generate, retrieve, or do: membaca PDF pindaian, mengekstrak tabel Laporan Populasi, dan menulis angka ke sel yang tepat
- Tools and integrations available: pembaca PDF dan pengolah spreadsheet
- Data and source systems available: PDF laporan UPTD dan template POPULASI 2026.xlsx
- Persistent instructions or project files available: AGENTS.md repo dan aturan konsolidasi, yaitu isi baris JUMLAH saja, dan pindai semua halaman karena satu PDF bisa memuat dua kecamatan
- Memory requirements: daftar kecamatan yang sudah diisi per bulan, dan catatan kolom Itik yang menggabungkan Itik dan Itik Manila
## Risk and boundaries
- Consequences of error: angka yang salah masuk ke laporan dinas dan dipakai untuk keputusan
- Sensitive data or policy constraints: data dinas tidak dikirim ke layanan luar tanpa persetujuan, dan struktur template tidak boleh diubah
- Actions requiring explicit approval: menulis angka ke template, dan menandai kecamatan sebagai selesai
- Actions allowed automatically: membaca PDF, mengekstrak angka, dan menyusun draf per kecamatan
- Prohibited actions: mengubah rumus template, menghapus data bulan lain, dan mengirim laporan ke pihak luar
- Reversal or rollback options: simpan salinan template sebelum ditulis, dan kembalikan dari salinan bila angka terbukti salah
## Quality requirements
- What a good outcome looks like: setiap angka bisa dilacak ke halaman PDF sumbernya
- How work should be verified: Aulia memeriksa draf per kecamatan sebelum angka ditulis ke template
- User feedback mechanisms: daftar sel yang meragukan, dengan alasan dan halaman sumbernya
- Metrics to track: jumlah kecamatan selesai per bulan, dan jumlah koreksi setelah pemeriksaan
Produce:
1. What the agent is for, and what it is not for
2. System instructions and operating rules
3. Context layout: persistent, task, retrieved, working memory, and long-term memory if needed
4. Tool list and tool-use rules
5. Permission matrix: inform, recommend, draft, execute with approval, execute automatically, prohibited
6. Agent loop: intake, clarify, plan, act, verify, report, log
7. Where a person reviews or escalates
8. UX states for progress, uncertainty, approval, failure, and completion
9. A simple scorecard: accuracy, usefulness, safety, evidence, appropriate uncertainty
10. Failure, retry, rollback, and partial-completion behavior
11. A phased MVP plan
12. Open risks and questions that need a human decision
Use tables where they help. Do not recommend auto-execute for irreversible, high-impact, or hard-to-verify actions.Tugas praktik hari ini
Rancang harness untuk satu pekerjaan agent yang kamu jalankan minggu ini, misalnya agent pemeriksa tampilan sebelum deploy. Tulis matriks izinnya dengan jujur, lalu jalankan satu tugas dengan aturan itu. Kalau ada aksi yang kamu biarkan otomatis padahal sulit dibatalkan, pindahkan ke kolom butuh persetujuan.