Peta codebase lama dengan Claude Code: workflow aman 45 menit

Saat membawa Claude Code ke codebase lama, output pertama sebaiknya bukan diff. Output pertama sebaiknya peta. Repo map menjelaskan dari mana aplikasi mulai berjalan, folder mana yang penting, area mana yang tidak boleh disentuh hari ini, bagaimana perubahan dibuktikan, dan apa yang harus diketahui orang berikutnya. Tanpa peta, sesi AI yang membantu bisa melebar menjadi cleanup besar, refactor sampingan, atau perubahan yang sulit direview.

Panduan ini memberikan workflow 45 menit untuk memetakan repository sebelum mengedit. Dokumentasi resmi Claude Code overview menjelaskan bahwa Claude Code bisa membaca codebase, mengedit file, dan menjalankan command. Karena kemampuannya besar, batasnya harus jelas sejak awal.

Bacaan terkait: prompt pertama untuk codebase lama, panduan permission Claude Code, dan CLAUDE.md starter template.

Repo map 45 menit

Gunakan 25 menit untuk eksplorasi read-only, 10 menit menulis peta, 5 menit memilih task aman pertama, dan 5 menit mereview rencana. Jangan mengejar dokumen arsitektur sempurna. Tujuannya adalah peta kerja untuk membuat perubahan kecil, mudah dibalik, dan bisa diverifikasi.

flowchart TD
  A["Inventaris read-only"] --> B["Temukan entry point"]
  B --> C["Pisahkan area aman dan berisiko"]
  C --> D["Pilih patch pertama"]
  D --> E["Tetapkan proof command"]
  E --> F["Tulis repo-map.md"]

Entry point adalah tempat aplikasi mulai berjalan: route, API handler, server bootstrap, command CLI, scheduled job, atau content loader. Area berisiko adalah tempat di mana kesalahan kecil bisa memengaruhi kepercayaan atau revenue: auth, billing, deletion, konfigurasi produksi, secrets, deploy script, analytics, dan ad tags.

Step 1: inventaris read-only

Mulai dengan command yang menggambarkan repo tanpa mengubahnya. Di Windows PowerShell, blok ini cukup untuk first pass.

git status --short
Get-ChildItem -Force | Select-Object Name, Mode, Length
Get-ChildItem -Recurse -File -Include package.json,astro.config.*,next.config.*,vite.config.*,README*,CLAUDE.md,AGENTS.md | Select-Object -ExpandProperty FullName
rg --files | Select-Object -First 120

Cari stack, dokumentasi, folder generated, cache, dan perubahan yang belum di-commit. Jika working tree dirty, pahami dulu perubahan itu milik siapa sebelum meminta Claude Code mengedit. Ini mencegah pekerjaan orang lain tertimpa.

Prompt pertama harus jelas read-only.

Read this repository as an existing codebase. Do not edit files yet.

Goal:
- Create a first repo map in 45 minutes
- Pick exactly one safe starter task
- Identify areas that should not be touched today

Return:
1. Up to 8 important directories
2. Up to 5 runtime or content entry points
3. Risky areas with reasons
4. Three safe starter task candidates
5. Candidate proof commands

If something is uncertain, write "unverified" instead of guessing.

Do not edit files yet menjaga sesi tetap eksploratif sampai rencana bisa direview.

Step 2: tulis repo-map.md

Jangan biarkan hasil discovery hanya ada di chat. Tulis repo-map.md singkat agar sesi berikutnya bisa reuse. Dokumentasi resmi memory menjelaskan bahwa CLAUDE.md dapat menyimpan instruksi proyek, tetapi hasil first-pass biasanya lebih aman dipisah dulu. Rule yang stabil bisa dipindah ke CLAUDE.md nanti.

# repo-map.md

## Purpose
- First working map for using Claude Code safely in this repository

## Entry points
| Type | File | Role | Proof |
| --- | --- | --- | --- |
| Web | site/src/pages/index.astro | Home page | npm run build |
| Content | site/src/content/blog | Article source | Open article URL |

## Safe candidates
- docs/
- site/src/content/blog/
- Small display copy

## Do not touch today
- .env and secrets
- Auth, billing, deletion flows
- Deploy scripts
- Generated dist and cache folders

## First safe task
- Improve one article CTA
- Change one file only
- Verify with build and preview

## Remaining risks
- Production data flow is unverified
- External service integrations need a separate pass

Ini bukan arsitektur lengkap. Ini guardrail untuk perubahan berguna pertama.

Step 3: perkuat dengan permissions

Instruksi membantu, tetapi bukan enforcement. Dokumentasi permissions menjelaskan allow, ask, dan deny. Untuk sesi pertama pada repo lama, izinkan read dan check aman, minta konfirmasi untuk build atau edit, dan tolak push, command destruktif, serta secrets.

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(rg *)",
      "Bash(npm run test *)",
      "Read"
    ],
    "ask": [
      "Bash(npm run build *)",
      "Edit(site/src/content/blog/**)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(.env)",
      "Read(**/.env)",
      "Edit(scripts/deploy*)"
    ]
  }
}

JSON ini titik awal. Project Anda mungkin tidak punya npm run test, atau path edit-nya berbeda. Hal pentingnya adalah menentukan deny sebelum memperluas allow.

Step 4: pilih patch aman pertama

Setelah peta ada, pilih task yang kecil, reversible, dan mudah diverifikasi. Tiga use case ini cocok.

Pertama, perbaikan CTA konten. Misalnya memastikan artikel populer mengarah secara natural ke produk dan training. Biasanya hanya satu file konten dan bisa dicek dengan build serta preview.

Kedua, dokumentasi proof command di README atau CLAUDE.md. Menuliskan build, test, lint, dan preview mengurangi biaya sesi berikutnya tanpa mengubah perilaku aplikasi.

Ketiga, perubahan copy atau format tanggal pada satu layar. Batasi patch ke satu atau dua file, lalu verifikasi dengan test, screenshot, atau preview lokal. Auth, billing, permission, dan deletion jangan dijadikan patch pertama.

Using repo-map.md, implement only the first safe task.

Target:
- site/src/content/blog/example.mdx

Requirements:
- Make the final CTA more natural
- Keep internal links to /products/ and /training/
- Do not change pubDate, category, tags, author, or heroImage
- Change this one file only

After finishing, report:
1. Changed files
2. Why they changed
3. Proof commands run
4. Remaining risks

Prompt ini mengubah permintaan luas menjadi patch yang bisa direview.

Step 5: cek peta itu sendiri

Repo map adalah teks, tetapi section minimum bisa dicek. Simpan sebagai check-repo-map.js.

const fs = require("node:fs");

const file = process.argv[2] || "repo-map.md";
const text = fs.readFileSync(file, "utf8");
const required = ["Entry points", "Safe candidates", "Do not touch today", "First safe task", "Remaining risks"];
const missing = required.filter((heading) => !text.includes(heading));

if (missing.length > 0) {
  console.error(`Missing repo-map sections: ${missing.join(", ")}`);
  process.exit(1);
}

console.log(`OK: ${file} has the minimum repo-map sections.`);

node check-repo-map.js repo-map.md

Script ini sederhana, tetapi memaksa setiap sesi meninggalkan handoff minimum yang konsisten.

Kesalahan umum

Kesalahan pertama adalah memulai dengan request terlalu luas seperti “refactor app” atau “improve quality”. Solusinya: tetapkan eksplorasi read-only, batas jumlah file, area yang tidak boleh disentuh, dan proof command sebelum edit.

Kesalahan kedua adalah mencampur artefak generated ke peta. dist, .astro, .next, coverage, dan node_modules membuat repo terlihat besar tapi tidak membantu pemahaman awal. Kecualikan kecuali memang target deployment yang perlu diperiksa.

Kesalahan ketiga adalah meremehkan layanan eksternal. Email, payment webhook, ads, analytics, dan CRM bisa punya sedikit kode tetapi dampak bisnis besar. Baca dulu; edit di task terpisah.

Kesalahan keempat adalah berhenti setelah build. Build bisa lulus saat layout mobile, code block, CTA, atau internal link rusak. Untuk content site, buka preview dan cek body, code block, /products/, dan /training/.

Checklist review

Lensa	Cek	Sinyal buruk
Diff	Hanya file yang diminta berubah	Formatting sampingan besar
Entry	Jalur loading dipahami	File edit tidak pernah dipakai
Risk	Auth, billing, delete, prod aman	Secrets atau deploy berubah
Proof	Ada command atau manual check	Hanya “probably fine”
Funnel	CTA dan internal link cocok	Link produk terasa dipaksakan
Handoff	Risiko tersisa ditulis	Sesi berikutnya mengulang discovery

Checklist ini bukan untuk tidak percaya pada Claude Code. Tujuannya membuat pekerjaan bisa diulang.

Masukkan jalur revenue

Untuk situs seperti ClaudeCodeLab, map juga harus memuat monetization path. Artikel mana yang membawa traffic? Di mana pembaca melihat download, produk, atau konsultasi? Template siap pakai ada di product library. Untuk rollout tim, permissions, dan content operations, lihat Claude Code training.

Jika revenue path masuk peta, patch CTA kecil bukan sekadar copy edit. Anda juga mengecek internal link, halaman produk, form, analytics, dan iklan. Kode yang benar tidak menghasilkan revenue jika pembaca tidak punya next step yang jelas.

Ringkasan

Gunakan 45 menit pertama dengan Claude Code untuk memetakan codebase, bukan menulis ulang. Inventaris repo, temukan entry point, tandai risiko, pilih satu task aman, tetapkan proof command, dan tinggalkan repo-map.md. Setelah itu baru buat patch kecil di satu atau dua file.