Mengurangi Tech Debt dengan Claude Code: Panduan Aman untuk Tim

Hampir semua tim ingin mengurangi tech debt. Namun saat sprint berjalan, fitur baru biasanya menang. Lama-kelamaan any menyebar, dependency tertinggal beberapa versi, CI kadang gagal, dan komentar TODO berubah menjadi bagian permanen dari arsitektur.

Claude Code tidak membuat refactoring otomatis menjadi bebas risiko. Nilai praktisnya adalah membantu tim menginventarisasi debt, menambahkan bukti, menentukan prioritas, dan memecah pembayaran debt menjadi PR kecil yang bisa direview. Dengan begitu, pengurangan tech debt menjadi kebiasaan engineering, bukan proyek bersih-bersih besar yang berisiko.

Panduan ini membahas inventarisasi code smell, dependency debt, flaky test (test yang kadang gagal tanpa alasan jelas), duplicated logic, TODO berbahaya, prioritas ICE/RICE, strategi PR kecil, dan governance. Untuk acuan resmi, lihat Claude Code Common workflows, Memory, dan Settings. Untuk materi terkait di ClaudeCodeLab, baca juga strategi testing, praktik terbaik CLAUDE.md, dan panduan approval dan sandbox.

Jadikan Debt sebagai Siklus Pembayaran

Kesalahan umum adalah memperlakukan debt sebagai proyek refactor besar. Branch membesar, reviewer sulit memastikan perilaku tetap sama, dan pekerjaan akhirnya ditunda menjelang rilis.

Gunakan siklus pendek.

flowchart LR
  A["Inventarisasi"] --> B["Kumpulkan bukti"]
  B --> C["Skor ICE/RICE"]
  C --> D["PR kecil"]
  D --> E["Test dan review"]
  E --> F["Update register"]
  F --> A

Inventarisasi tidak boleh hanya berdasarkan rasa. Kumpulkan path file, nomor baris, log CI, package usang, penggunaan any, file besar, logic duplikat, serta komentar TODO/FIXME.

Pendekatan	Cocok untuk	Risiko	Peran Claude Code
Refactor besar	Migrasi framework dengan batas jelas	Diff terlalu besar untuk direview	Riset dan rencana migrasi
PR debt kecil	Maintenance rutin	Dampaknya terlihat kecil	Register, scoring, checklist
Sprint dependency	Patch keamanan dan package EOL	Breaking change tersembunyi	Ringkasan changelog dan rencana test
Cleanup flaky test	CI tidak lagi dipercaya	Retry menutupi bug asli	Klasifikasi failure dan langkah reproduksi

Use Case 1: Inventarisasi Code Smell

Code smell bukan selalu bug. Ini adalah tanda bahwa perubahan di masa depan akan lebih sulit: function terlalu besar, class dengan tanggung jawab berlebihan, validasi duplikat, magic number, atau pelarian dari sistem tipe.

Mulai dengan meminta Claude Code melakukan inspeksi, bukan edit.

claude -p "
Inspeksi src/ dan tests/ untuk menemukan technical debt. Jangan edit file dulu.

Cari:
- Function lebih dari 80 baris
- File lebih dari 300 baris
- Nesting lebih dalam dari 4 level
- Validasi, date handling, atau permission check yang duplikat
- TypeScript any, as any, dan @ts-ignore
- Komentar TODO / FIXME / HACK
- Branch tanpa test atau test yang hanya memeriksa rendering

Kembalikan tabel Markdown yang bisa saya tempel ke docs/tech-debt/register.md.
Kolom: ID, File, Line, Debt type, Evidence, Risk, Suggested first PR, Confidence.
"

Kalimat “Jangan edit file dulu” penting. Jika langsung meminta perbaikan, perubahan spekulatif mudah masuk. Biarkan Claude Code meneliti, mengelompokkan, dan memberi usulan. Tim tetap memilih debt mana yang dibayar pertama.

Use Case 2: Menemukan Dependency Debt

Library usang, package tanpa maintenance, vulnerability, dan library ganda untuk tugas yang sama juga termasuk debt. Jumlah peringatan npm audit saja bukan sinyal prioritas yang baik: advisory yang ramai bisa menutupi package inti yang mendekati end of life.

claude -p "
Berdasarkan package.json, lockfile, npm outdated, dan npm audit output, klasifikasikan dependency debt.

Kategori:
1. Perlu security fix
2. Perlu major update dengan kemungkinan breaking change
3. Tidak dimaintain atau disarankan diganti
4. Library duplikat untuk pekerjaan yang sama
5. Aman ditunda

Untuk tiap item, tulis area dampak, changelog yang harus dibaca dulu, test yang diperlukan, dan PR aman paling kecil.
Pisahkan perubahan yang bisa diautomasi dari perubahan yang wajib direview manusia.
"

Update dependency tidak otomatis aman hanya karena test lolos sekali. Date handling, auth, crypto, routing, build tools, dan test runner sebaiknya memakai branch terpisah serta catatan rollback yang jelas.

Use Case 3: Membayar Flaky Test dan Logic Duplikat

Flaky test merusak kepercayaan pada CI. Begitu engineer berpikir “rerun saja nanti pass”, test suite berhenti menjadi jaring pengaman.

claude -p "
Baca 20 log kegagalan CI terakhir dan klasifikasikan kandidat flaky test.

Klasifikasikan berdasarkan:
- Bergantung pada waktu, timezone, atau data random
- Bergantung pada network atau API eksternal
- Shared state bocor antar test
- Async waiting tidak stabil
- Kemungkinan product bug yang tidak boleh disebut flaky

Untuk tiap kandidat, berikan command reproduksi, minimal fix, dan assertion yang perlu ditambahkan.
"

Untuk duplicated logic, PR pertama harus membosankan. Jika permission check disalin di empat file, pertama ekstrak helper murni dan kunci perilaku dengan test. Ganti call site satu per satu di PR berikutnya agar reviewer bisa menilai dengan jelas.

Scanner yang Bisa Dicopy

Claude Code berguna untuk analisis, tetapi marker mekanis juga sebaiknya bisa dijalankan sebagai script. Simpan sebagai scripts/debt-scan.mjs, lalu jalankan node scripts/debt-scan.mjs src.

import fs from "node:fs";
import path from "node:path";

const root = process.argv[2] || "src";
const maxLines = Number(process.env.MAX_LINES || 300);
const extensions = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"]);
const findings = [];

function walk(dir) {
  if (!fs.existsSync(dir)) return;

  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const fullPath = path.join(dir, entry.name);

    if (entry.isDirectory()) {
      if ([".git", "node_modules", "dist", "build", ".next", "coverage"].includes(entry.name)) continue;
      walk(fullPath);
      continue;
    }

    if (entry.isFile() && extensions.has(path.extname(entry.name))) {
      scanFile(fullPath);
    }
  }
}

function add(file, line, type, severity, detail) {
  findings.push({ file, line, type, severity, detail });
}

function scanFile(file) {
  const text = fs.readFileSync(file, "utf8");
  const lines = text.split(/\r?\n/);

  if (lines.length > maxLines) {
    add(file, 1, "large-file", 3, `${lines.length} lines`);
  }

  lines.forEach((line, index) => {
    const lineNumber = index + 1;

    if (/\b(FIXME|TODO|HACK)\b/i.test(line)) {
      add(file, lineNumber, "unsafe-comment", /FIXME|HACK/i.test(line) ? 4 : 3, line.trim());
    }

    if (/\.(ts|tsx)$/.test(file) && /(:\s*any\b|as\s+any\b|<any>)/.test(line)) {
      add(file, lineNumber, "typescript-any", 4, line.trim());
    }
  });
}

walk(root);

console.log("| file | line | type | severity | detail |");
console.log("| --- | ---: | --- | ---: | --- |");
for (const item of findings.sort((a, b) => b.severity - a.severity || a.file.localeCompare(b.file))) {
  const detail = item.detail.replaceAll("|", "\\|");
  console.log(`| ${item.file} | ${item.line} | ${item.type} | ${item.severity} | ${detail} |`);
}

if (findings.length === 0) {
  console.error("No obvious debt markers found.");
}

Scanner ini tidak memahami arsitektur dan tidak menemukan semua duplikasi. Namun, ia memberi baseline mingguan yang konsisten untuk TODO, FIXME, any, dan file besar.

Template Debt Register

Sebelum membuat issue, kumpulkan temuan dalam satu register agar prioritas mudah dibandingkan.

# Technical Debt Register

| ID | Area | Evidence | User or team impact | ICE | RICE | Owner | Next PR | Status |
| --- | --- | --- | --- | ---: | ---: | --- | --- | --- |
| TD-001 | Auth permissions | src/auth/guard.ts duplicates role checks in 4 places | New role changes take 2 days and often miss one path | 420 | 1680 | Backend | Extract pure canAccess() with tests | Ready |
| TD-002 | Dependencies | vite is 2 major versions behind | Security patches and plugin updates are blocked | 280 | 900 | Platform | Upgrade in isolated branch and run build/test | Investigating |

## Scoring note

- ICE = Impact x Confidence x Ease
- RICE = Reach x Impact x Confidence / Effort
- Keep evidence links concrete: file path, line, CI run, or user-facing incident.

ICE cepat untuk mengurutkan. RICE lebih cocok ketika reach dan effort perlu dibuat eksplisit. Keduanya bukan kebenaran mutlak; keduanya alat untuk membuat diskusi lebih rapi.

Prompt untuk Rencana Refactor Aman

Setelah item dipilih, minta rencana sebelum mengedit.

claude -p "
Buat rencana pembayaran aman untuk TD-001. Jangan edit file dulu.

Scope:
- src/auth/guard.ts
- src/auth/roles.ts
- tests/auth/guard.test.ts

Constraint:
- Jangan ubah perilaku external API
- Periksa test yang ada terlebih dahulu
- Jika behavior belum cukup dites, tambahkan characterization tests sebelum refactor
- Targetkan PR di bawah 300 changed lines
- Sertakan risiko, rollback plan, dan fokus reviewer

Output:
1. Ringkasan perilaku saat ini
2. Non-goals eksplisit
3. Rencana diff untuk PR pertama
4. Command test yang harus dijalankan
5. Pesan permintaan review PR
"

Bagian non-goals mencegah scope melebar. Claude Code bisa terlalu membantu jika batas PR tidak ditulis dengan jelas.

Checklist PR Refactor

## Refactor PR checklist

- [ ] This PR changes structure, not product behavior.
- [ ] Existing behavior is covered by tests before the refactor.
- [ ] New helper names describe domain behavior, not implementation detail.
- [ ] Public API, response shape, permissions, and logging are unchanged or explicitly documented.
- [ ] The diff is small enough to review in one sitting.
- [ ] Rollback is simple: revert this PR without reverting unrelated work.
- [ ] The debt register is updated with status and follow-up PRs.

Masukkan checklist ini ke body PR yang dirancang Claude Code. Ini mengubah “percaya saja, ini refactor” menjadi bukti yang bisa direview.

Jebakan Konkret

Terlalu percaya otomatisasi Type check yang lolos belum cukup. Authorization, billing, date logic, async behavior, dan migration perlu characterization tests serta review manusia.

Menghapus semua TODO Sebagian TODO adalah blocker rilis, sebagian hanya catatan. Prioritaskan kata seperti remove before release, bypass auth, temporary token, dan FIXME.

Menggabungkan banyak update dependency Sepuluh major update dalam satu PR membuat kegagalan sulit diisolasi. Pisahkan build tools, UI library, auth library, dan test runner.

Memakai skor sebagai politik ICE/RICE harus membawa bukti: path file, run CI, incident, dan asumsi effort.

Tidak menyimpan memori tim Aturan seperti “kode permission perlu approval” dan “PR refactor di bawah 300 baris” sebaiknya masuk ke CLAUDE.md atau settings. Memory dan Settings mengurangi prompt berulang.

Governance untuk Tim

Cadence yang praktis adalah review debt 30 menit setiap minggu:

1. Baca hasil scanner dan inventaris Claude Code.
2. Update ICE/RICE hanya untuk 10 item teratas.
3. Pilih satu PR pembayaran untuk sprint berikutnya.
4. Naikkan prioritas flaky test dan dependency keamanan.
5. Catat di register apa yang menjadi lebih mudah setelah PR selesai.

ClaudeCodeLab dapat membantu mengubah workflow ini menjadi sistem nyata: template debt register, checklist PR, settings, dan aturan awal CLAUDE.md. Untuk menyesuaikannya dengan repository dan budaya review tim Anda, lihat Claude Code training, templates, dan consultation.

Ringkasan

Cara aman mengurangi tech debt dengan Claude Code bukan meminta “refactor semuanya”. Cara yang benar adalah mengumpulkan bukti, memberi skor, lalu membayar satu debt kecil per PR. Code smell, dependency debt, flaky test, duplicated logic, dan TODO berbahaya bisa masuk ke loop yang sama.

Setelah workflow ini dicoba pada proyek kecil Masa, manfaat terbesarnya adalah pemisahan antara debt yang mendesak dan debt yang cukup dicatat dulu. Membersihkan any dan TODO lama lewat PR kecil mengurangi risiko tanpa banyak menambah beban review. Sebaliknya, major update dependency ternyata lebih berat dari perkiraan, sehingga lebih aman menambahkan test dan catatan rilis sebelum meminta Claude Code menyusun perubahan sebenarnya.