Claude Code Plan Mode: Siklus Refactoring dengan Tinjauan Desain Terlebih Dahulu

Banyak developer mulai menggunakan Claude Code dengan cara yang sama: tempelkan tugas, jalankan, lalu tinjau diff. Cara ini berfungsi untuk perubahan kecil, tetapi akan mulai bermasalah saat menyentuh banyak file. 

Setiap keputusan tanpa arahan yang dibuat Claude mungkin benar sebagian besar waktu, terdengar baik sampai Anda menggabungkannya: Misalnya, jika Anda mengasumsikan akurasi 80% per keputusan, pada sebuah fitur dengan 20 titik keputusan, 0.8^20 menurunkan peluang Anda menjadi sekitar 1%.

Plan Mode mengubah perhitungannya dengan menambahkan fase hanya-baca. Anda memaksa Claude untuk membaca codebase, mengajukan pertanyaan, dan menghasilkan rencana yang Anda tinjau sebelum satu file pun disentuh. 

Tutorial ini memandu alur kerja tersebut menggunakan FastAPI blog API yang berantakan sebagai contoh berjalan, mencakup loop Explore-Plan-Execute, pengeditan rencana dengan Ctrl+G, dan skala ke refactor yang lebih besar dengan Agent Teams. 

Tutorial praktik terbaik Claude Code kami membahas masalah kesalahan berantai lebih mendalam, dan panduan Claude Code 2.1 memandu Anda melalui instalasi dan fitur jika Anda memerlukan bantuan penyiapan.

Untuk informasi lebih lanjut tentang model di balik Claude Code, lihat panduan kami untuk Claude Sonnet 4.6 dan Opus 4.6, atau ikuti kursus Introduction to Claude Models.

Apa Itu Claude Code Plan Mode?

Plan Mode mengunci Claude ke operasi hanya-baca. Ia dapat membaca file, menelusuri codebase, dan mengajukan pertanyaan, tetapi setiap upaya menulis file, mengedit kode, atau menjalankan perintah shell akan ditolak. Cobalah memintanya untuk "hanya melakukan satu perbaikan cepat" saat berada di Plan Mode, dan ia tidak akan bergeming.

Anda dapat mengaktifkannya dengan empat cara:

• Shift+Tab dua kali di kolom input untuk berputar melalui Normal, Auto-Accept, dan Plan Mode

• Perintah /plan masuk ke Plan Mode hingga Anda beralih mode lagi

• Flag CLI --permission-mode plan memulai sesi baru dalam Plan Mode

• Entri settings.json di bawah permissions.defaultMode menetapkan Plan Mode sebagai default permanen Anda

Setelah Claude selesai membuat rencana, hasilnya disimpan sebagai file markdown di ~/.claude/plans/ dengan nama acak (seperti dreamy-orbiting-quokka.md). 

File tersebut adalah kontrak yang dapat ditinjau: bertahan lintas sesi, tetap ada meski setelah /clear dan kompaksi konteks, dan tidak ada yang diimplementasikan sampai Anda menyetujuinya. Perhatikan bahwa meski file rencananya bertahan, Claude terkadang kehilangan jejaknya setelah kompaksi konteks kecuali Anda memintanya untuk membaca ulang rencana tersebut.

Jika Anda ingin rencana disimpan di dalam proyek untuk kontrol versi, atur plansDirectory di settings.json ke path relatif proyek seperti ./plans.

Rencana relatif proyek membuka alur kerja yang ~/.claude/plans/ tidak dapat dukung:

• Tinjau diff rencana dalam pull request sebelum siapa pun mulai ngoding
• Bawa anotasi ke depan lintas sesi tanpa bergantung pada kompaksi konteks
• Perlakukan file markdown sebagai spesifikasi hidup yang dapat diedit langsung oleh beberapa anggota tim

Untuk refactor jangka panjang atau pekerjaan multi-sesi, file rencana yang dikontrol versi memberi Anda lebih banyak kendali dibanding hanya Ctrl+G saja.

Menerapkan Alur Kerja Explore-Plan-Execute di Claude Code

Untuk melihat bagaimana ketiga fase bekerja bersama, kita akan me-refactor repo fastapi-blog-api. Repo ini tidak menyertakan pengujian apa pun dan memiliki tiga file yang masing-masing melakukan terlalu banyak hal: 

• main.py: semua route, pemeriksaan autentikasi inline, konfigurasi hardcode, pengiriman email

• models.py: model ORM, skema Pydantic, fungsi kueri, data seed

• utils.py: hashing kata sandi, token JWT, upload S3, rendering markdown, caching, pembatasan laju, ekspor CSV

Fase 1: Kumpulkan konteks sebelum apa pun

Mulai tugas dalam Plan Mode (klon repo GitHub secara lokal terlebih dahulu). Prompt pembuka harus memberi tahu Claude apa yang Anda inginkan dan mengarahkannya untuk membaca file yang relevan:

I want to refactor this FastAPI blog API into a clean module structure with proper separation of concerns and full test coverage. Read through main.py, models.py, and utils.py first. Map out which functions belong together, flag any shared state or circular dependency risks, and identify what needs testing most.

Claude mendelegasikan riset codebase ke subagent bawaan yang dibatasi pada alat hanya-baca. Ia membaca ketiga file, menelusuri impor antar file, dan menggunakan AskUserQuestion untuk menonjolkan ambiguitas. 

Pertanyaannya mencakup beberapa keputusan tingkat tinggi:

• Kedalaman arsitektur (router datar vs. lapisan layanan penuh)
• Cara menangani konfigurasi hardcode
• Apakah fungsi utilitas yang tidak terpakai harus dihapus atau dipertahankan
• Framework pengujian yang akan digunakan

Pertanyaan-pertanyaan tersebut penting. Pertanyaan arsitektur saja bisa menjadi tebak koin tanpa masukan manusia. Claude cenderung default ke pola yang paling sering ia lihat di data latihannya, yang, untuk FastAPI, biasanya struktur router datar. Menjawab "gunakan service layer" di sini menghemat satu putaran refactoring ulang di kemudian hari.

Jika Anda memiliki proyek referensi yang sesuai dengan arsitektur target, sertakan tautannya di prompt Anda. Claude menghasilkan rencana yang lebih baik saat memiliki contoh kerja untuk dijadikan acuan ketimbang deskripsi abstrak.

Satu hal yang perlu diperiksa sebelum menerima rencana apa pun: apakah pertanyaan Claude merujuk fungsi spesifik dan detail tingkat baris, atau hanya nama file? Jika ia bertanya tentang "sistem auth" tetapi tidak pernah menyebut verify_jwt_token atau rantai middleware di main.py, berarti ia hanya mengintip file bukannya membacanya. Dorong ia untuk membaca lebih saksama sebelum beralih ke Fase 2.

Fase 2: Hasilkan dan edit rencana

Setelah Anda menjawab pertanyaan Claude, ia secara otomatis menghasilkan rencana. Tidak perlu prompt terpisah. Rencana disimpan ke ~/.claude/plans/ dan mencakup: 

• Ringkasan konteks
• Struktur direktori target
• Urutan implementasi langkah demi langkah
• Bagian verifikasi dengan perintah untuk mengonfirmasi refactoring berhasil

Sebelum memilih cara melanjutkan, tekan Ctrl+G untuk membuka rencana di editor teks default Anda (diatur oleh $EDITOR). Alternatifnya, gunakan /plan open untuk membuka file rencana aktif secara langsung.

Plan Mode membayar dirinya di langkah ini. Anda dapat memberi anotasi pada langkah dengan catatan inline, menghapus langkah yang tidak Anda setujui, mengubah urutan operasi, lalu simpan. Claude akan menangkap setiap suntingan saat Anda kembali ke terminal.

Untuk rencana blog API, anotasi mungkin terlihat seperti:

## Step 3: Extract auth module
Move JWT validation and password hashing to auth/
> NOTE: extract auth middleware BEFORE splitting routes,
> otherwise the route files will import from utils.py
> and we'll have to update imports twice
 
## Step 5: Database layer
Create a repository pattern for database operations
> NOTE: keep the SQLAlchemy session factory in a shared
> db.py, don't put it in models.py

Untuk rencana yang kompleks, satu kali Ctrl+G mungkin tidak cukup. Beri anotasi, kembali, beri tahu Claude "atasi semua anotasi dalam rencana, jangan implementasikan dulu," tinjau versi yang direvisi, lalu Ctrl+G lagi. Setiap putaran anotasi menghilangkan ambiguitas yang jika tidak akan menjadi keputusan implementasi yang salah.

Setelah kontrak terlihat tepat, Claude menawarkan beberapa opsi: 

1. Mengerjakan rencana dan mengosongkan konteks (bagus saat sesi mulai basi), 
2. Bekerja tanpa mengosongkan (untuk menjaga riwayat percakapan), atau 
3. Terus berdiskusi tentang rencana. 

Pilih berdasarkan seberapa banyak konteks yang telah Anda bangun. Jika Anda sudah jauh dalam sesi panjang, mengosongkan memberi Claude jendela baru untuk mengeksekusi.

Fase 3: Eksekusi rencana yang disetujui

Pilih opsi kerja, dan Claude mulai mengimplementasikan langkah demi langkah. Ia menuntaskan setiap langkah dan berhenti saat membutuhkan intervensi manual (seperti autentikasi interaktif di terminal) atau saat seluruh rencana selesai.

Waspadai drift. Rencana mengatakan untuk mengekstrak auth ke modulnya sendiri terlebih dahulu, tetapi Claude mungkin mulai menarik route dan logika auth secara bersamaan karena melihat jalan pintas. Langkah seperti itu dapat membuat codebase setengah bermigrasi di mana beberapa impor menunjuk ke lokasi lama dan lainnya ke yang baru. 

Sinyal drift lainnya: 

• Mengedit file yang tidak disebutkan di langkah saat ini
• Diam-diam membuat keputusan arsitektur yang dibiarkan terbuka oleh rencana
• Menggabungkan dua langkah yang dipisahkan oleh rencana

Saat drift terjadi, tekan Shift+Tab kembali ke Plan Mode. Claude membaca status file saat ini, menghasilkan rencana yang direvisi untuk langkah yang tersisa, dan Anda meninjaunya sebelum melanjutkan. Ini bukan langkah darurat. Sebagian besar refactor lintas banyak file mengalami 2–3 revisi rencana sebelum selesai.

Untuk refactor yang tidak muat dalam satu sesi, pecah pekerjaan menjadi rencana berurutan alih-alih satu rencana besar. Selesaikan ekstraksi auth di bawah rencananya sendiri, lalu mulai sesi baru dan rencana untuk pemisahan route. 

Gunakan /rename untuk memberi label setiap sesi (mis., "blog-api-auth-extraction") sehingga Anda dapat melanjutkan dari titik terakhir dengan /resume. Rencana yang lebih kecil menjaga jendela konteks tetap fokus dan memberi Anda titik pemeriksaan alami antar fase.

Strategi Praktis untuk Claude Code Plan Mode

Sekarang kita telah melalui seluruh proses sekali, mari lihat beberapa praktik terbaik untuk memastikan Anda memaksimalkan Plan Mode.

Kapan menggunakan Plan Mode (dan kapan melewatinya)

Tidak setiap tugas membutuhkan rencana. Perbaikan satu baris, koreksi typo, dan pembaruan fungsi terisolasi lebih cepat tanpa overhead perencanaan. Hal yang sama berlaku untuk perubahan mekanis, seperti mengganti nama variabel di seluruh file.

Heuristik yang baik: jika perubahan menyentuh tiga atau lebih file, atau Anda tidak bisa menggambarkan seluruh perubahan dalam satu kalimat, rencanakan terlebih dahulu. Tiga file kira-kira di titik di mana kesalahan berantai mulai menyakitkan, karena setiap file menambah serangkaian keputusan yang harus benar oleh Claude.

Tugas yang selalu diuntungkan dari Plan Mode:

• Refactor yang memindahkan kode antar file atau mengganti nama antarmuka bersama
• Fitur baru yang menyentuh modul yang ada
• Peningkatan dependensi dengan perubahan API yang breaking
• Tugas apa pun saat Anda tidak yakin bagaimana codebase menangani kasus tertentu
• Sesi brainstorming saat Anda ingin mengiterasi pendekatan dengan Claude tanpa risiko edit prematur

Mendeteksi rencana lemah sebelum merugikan Anda

Rencana yang tampak terstruktur tidak selalu berarti bagus. Dengan versi Claude Code saat ini, referensi file yang mengada-ada dan langkah "update sesuai kebutuhan" yang samar jarang terjadi. Masalah yang lebih mungkin Anda temui adalah rencana yang menaruh semua langkah implementasi di awal dan menambahkan "tambahkan pengujian" di akhir.

Rencana yang disusun demikian menghasilkan hasil yang lebih buruk dari yang Anda harapkan. Tanpa pengujian selama implementasi, Claude tidak memiliki cara untuk memverifikasi pekerjaannya sendiri di tengah sesi. Untuk refactoring blog API, rencana yang mengatakan "Langkah 1–6: ekstrak semua modul, Langkah 7: tulis pengujian" berarti enam langkah kode tanpa loop umpan balik. 

Rencana yang lebih kuat menggunakan test-driven development (TDD) dan menyelang-nyelingkan pengujian dengan implementasi: tulis pengujian untuk auth/ sebelum mengekstrak fungsi auth, pastikan lulus, lalu tulis pengujian untuk posts/ sebelum memisahkan route. Setiap pengujian yang lulus memberi Claude sinyal jelas bahwa refactoring berada di jalur yang benar. 

Menambahkan konvensi TDD ke CLAUDE.md proyek Anda membuat Claude menyertakan langkah pengujian sebagai default. Claude Code Hooks dapat mengotomatiskan penegakan semacam ini dengan menjalankan skrip validasi yang memeriksa kualitas rencana sebelum menyetujui eksekusi.

Menskalakan refactor besar dengan Agent Teams

Rencana yang menyentuh tujuh atau lebih file mulai kehilangan kualitas karena jendela konteks terisi selama eksekusi. Refactoring blog API mencapai ambang ini ketika Anda menghitung route, model, layanan, konfigurasi, pengujian, dan struktur direktori baru.

Agent Teams adalah fitur eksperimental yang mendistribusikan jenis pekerjaan ini ke beberapa instance Claude Code. Satu sesi bertindak sebagai ketua tim sementara rekan tim masing-masing mendapatkan jendela konteks independen.

Untuk blog API, Anda dapat membaginya menjadi tiga rekan tim: satu menangani ekstraksi route, satu menangani layer basis data dan model, dan satu bertanggung jawab atas cakupan pengujian. Ketua menetapkan tugas, rekan tim mengklaim dan menyelesaikannya, dan tugas yang terblokir (seperti "perbarui impor" bergantung pada "ekstrak modul") akan terbuka otomatis saat dependensi selesai. 

Pembagian yang sama berfungsi lintas repositori: jika API Anda bergantung pada library bersama, satu rekan tim dapat me-refactor library sementara yang lain memperbarui konsumsi API terhadapnya.

Pengaturan terbaik untuk Plan Mode adalah mewajibkan persetujuan rencana bagi rekan tim. Katakan kepada ketua: "Buat tiga rekan tim untuk refactoring blog API. Wajibkan persetujuan rencana sebelum mereka melakukan perubahan." 

1. Setiap rekan tim merencanakan dalam mode hanya-baca
2. Ketua meninjau dan menyetujui atau menolak dengan umpan balik
3. Hanya rencana yang disetujui yang dieksekusi

Anda dapat membentuk penilaian ketua dengan memberinya kriteria: "hanya setujui rencana yang menyertakan cakupan pengujian" atau "tolak rencana yang memodifikasi skema basis data secara langsung." Aktifkan Agent Teams dengan menambahkan "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" ke blok env di settings.json Anda.

Untuk paralelisasi yang lebih sederhana tanpa flag eksperimental, git worktrees memungkinkan Anda menjalankan sesi Plan Mode terpisah pada branch berbeda, masing-masing bekerja melalui rencananya secara independen.

Jika sesi jangka panjang mengalami kompaksi konteks, minta rekan tim secara eksplisit membuka kembali dan membaca ulang file rencana mereka untuk menghindari drift.

Tutorial plugin Claude Code membahas pola tambahan untuk mengelola pekerjaan multi-fase.

Kesimpulan

Nilai Plan Mode bermuara pada satu hal: tinjauan sebelum eksekusi. Setiap putaran anotasi yang Anda tambahkan, setiap pertanyaan yang diajukan Claude alih-alih menebak, menghapus satu keputusan yang kemungkinan akan salah. 

Mulailah dengan perubahan multi-file berikutnya, paksa Claude untuk merencanakan terlebih dahulu, dan edit rencana tersebut dengan Ctrl+G sebelum memberikan akses tulis. Untuk konfigurasi CLAUDE.md, manajemen konteks, dan pagar pembatas berbasis hook, tutorial praktik terbaik melanjutkan dari titik ini. 

Untuk gambaran yang lebih luas tentang pengodean berbantuan AI, saya sarankan melihat jalur keterampilan AI for Software Engineering kami, yang mengajarkan konsep dasar dan memberi Anda pengalaman langsung dalam alat serupa seperti GitHub Copilot, Windsurf, atau Replit.