Cara Menavigasi Codebase Besar dengan Claude Code dan Codex

Saat masuk ke codebase besar, tujuan pertama bukan memahami semua file. Tujuan pertama adalah membuat peta: sistem mulai dari mana, folder mana yang generated, file mana yang membawa risiko bisnis, dan batas ownership mana yang tidak boleh dilewati tanpa review.

Claude Code dan Codex sangat membantu untuk pekerjaan ini, tetapi investigasinya harus disiplin. Jika kamu menempelkan file penuh, log panjang, dan ratusan hasil pencarian ke percakapan utama, teks bertambah tetapi sinyal menurun. Itulah context bloat: percakapan makin besar, kualitas keputusan makin kabur.

Panduan ini mengubah workflow yang saya pakai untuk handoff, audit, dan maintenance artikel ClaudeCodeLab menjadi command dan prompt packet yang bisa disalin. Untuk perilaku tool, saya memakai dokumentasi resmi: Claude Code common workflows, CLI reference, memory, Codex non-interactive mode, dan Codex AGENTS.md.

Mulai Dari Peta Repo

Sebelum meminta agent menjelaskan repository, kecilkan dulu bentuk luarnya. rg adalah ripgrep. Tool ini cepat, menghormati ignore rule umum, dan mudah dipakai untuk mengecualikan folder generated.

git status --short
git rev-parse --show-toplevel
git branch --show-current

rg --files \
  -g '!*node_modules*' \
  -g '!dist' \
  -g '!build' \
  -g '!coverage' \
  -g '!*.lock' \
  | sed 's#^[^/]*/##' \
  | sort \
  | uniq -c \
  | sort -nr \
  | head -40

find . -maxdepth 3 \( \
  -name package.json -o \
  -name pnpm-workspace.yaml -o \
  -name pyproject.toml -o \
  -name go.mod -o \
  -name Cargo.toml -o \
  -name Dockerfile -o \
  -name docker-compose.yml -o \
  -name AGENTS.md -o \
  -name CLAUDE.md \
\) -print

Setelah itu minta peta dalam mode read-only. Workflow resmi Claude Code menyarankan mulai dari pertanyaan luas, lalu menyempit ke komponen tertentu. Dokumentasi Codex menjelaskan bahwa codex exec berjalan dalam read-only sandbox secara default, sehingga cocok untuk ringkasan awal repository.

codex exec "Read only. Summarize the repository map: apps, packages, entrypoints, test commands, generated folders, and files that define project rules. Do not edit files."

Untuk Claude Code, gunakan -p saat ingin jawaban non-interaktif. CLI reference mendokumentasikannya sebagai print mode.

claude -p "
Read only. Buat peta repository untuk codebase ini.
Kembalikan jawaban dengan urutan:
1. Apps, packages, dan services
2. Runtime entrypoints, test entrypoints, dan build entrypoints
3. Folder generated dan folder yang sebaiknya diabaikan
4. Poin kunci dari AGENTS.md, CLAUDE.md, README, dan design notes
5. 10 file berikutnya yang perlu dibaca, dengan alasan masing-masing
Hanya sarankan edit atau command; jangan menjalankannya.
"

Pakai Pencarian Berlapis

Text match bukan pemahaman. Search hanya menghasilkan kandidat. Gunakan lima lapisan: struktur, kosakata domain, referensi, konfigurasi, dan histori.

# 1. Kandidat entrypoint
rg -n "createServer|listen\(|app\.use|router\.|main\(|bootstrap|hydrateRoot|createRoot" \
  src apps packages server web

# 2. Kosakata domain. Ganti istilah ini sesuai produk.
rg -n "Auth|Billing|Invoice|Notification|Search|FeatureFlag" \
  src apps packages test tests

# 3. Caller dan referensi area yang mungkin diubah
rg -n "AuthService|useAuth|requireAuth|authMiddleware" \
  src apps packages test tests

# 4. Konfigurasi dan environment variables
rg -n "process\.env|import\.meta\.env|PUBLIC_|DATABASE_URL|JWT|STRIPE|OPENAI|ANTHROPIC" \
  . -g '!node_modules' -g '!dist' -g '!build'

# 5. Histori: kenapa desain ini ada
git log --oneline --decorate --date=short --max-count=30 -- src/auth packages/auth

Jangan tempel semua hasil ke agent. Lihat bentuknya dulu, lalu berikan kandidat kecil untuk diklasifikasikan.

Kamu adalah reviewer navigasi codebase.
Klasifikasikan hasil rg berikut menjadi implementation entrypoint, caller, configuration, test, dan noise.
Batasi setiap kelas ke 5 file paling penting untuk dibaca berikutnya.
Untuk setiap file terpilih, beri satu alasan konkret.
Jika tidak yakin, tulis "needs another search" daripada menebak.

Buat Dependency Graph Ringan

Sebelum memasang analyzer lengkap, script Node kecil bisa memberi sinyal yang cukup. Ini bukan compiler TypeScript. Script ini hanya mengikuti local relative imports, tetapi sering cukup untuk melihat blast radius langsung.

#!/usr/bin/env node
import { execFileSync } from "node:child_process";
import { readFileSync } from "node:fs";
import path from "node:path";

const target = process.argv[2]?.replace(/\\/g, "/");
if (!target) {
  console.error("Usage: node scripts/dependency-map.mjs src/path/to/file.ts");
  process.exit(1);
}

const tracked = execFileSync("git", ["ls-files"], { encoding: "utf8" })
  .split(/\r?\n/)
  .filter(Boolean)
  .map((file) => file.replace(/\\/g, "/"));

const trackedSet = new Set(tracked);
const sourceFiles = tracked.filter((file) => /\.(mjs|cjs|js|jsx|ts|tsx)$/.test(file));
const importPattern =
  /(?:from\s+["']([^"']+)["']|import\s*\(\s*["']([^"']+)["']\s*\)|require\s*\(\s*["']([^"']+)["']\s*\))/g;

function resolveLocalImport(specifier, fromFile) {
  if (!specifier.startsWith(".")) return null;
  const base = path.normalize(path.join(path.dirname(fromFile), specifier)).replace(/\\/g, "/");
  const candidates = [
    base,
    `${base}.ts`,
    `${base}.tsx`,
    `${base}.js`,
    `${base}.jsx`,
    `${base}/index.ts`,
    `${base}/index.tsx`,
    `${base}/index.js`,
  ];
  return candidates.find((candidate) => trackedSet.has(candidate)) ?? base;
}

const incoming = [];
for (const file of sourceFiles) {
  const source = readFileSync(file, "utf8");
  for (const match of source.matchAll(importPattern)) {
    const resolved = resolveLocalImport(match[1] || match[2] || match[3], file);
    if (resolved && (resolved === target || resolved.endsWith(`/${path.basename(target)}`))) {
      incoming.push(file);
    }
  }
}

console.log(`Target: ${target}`);
console.log("Direct importers:");
for (const file of incoming.sort()) console.log(`- ${file}`);

Simpan dan jalankan seperti ini.

mkdir -p scripts
$EDITOR scripts/dependency-map.mjs
node scripts/dependency-map.mjs src/services/AuthService.ts

Lalu ubah output menjadi risk map.

Berdasarkan direct importers ini, nilai blast radius jika AuthService.ts diubah.
Gunakan high / medium / low.
High berarti terkait authentication, billing, authorization, persistence, atau public API behavior.
Untuk setiap kelas, daftar test dan config file yang harus dibaca sebelum edit.

Trace Dari Entrypoint

Daftar file tidak menjelaskan perilaku runtime. Untuk backend, trace request, middleware, route, controller, service, repository, database. Untuk frontend, trace route, loader, state, API client, component, analytics.

rg -n "middleware|loader|action|controller|handler|route|repository|service" \
  src apps packages \
  -g '*.ts' -g '*.tsx' -g '*.js' -g '*.jsx'

rg -n "fetch\(|axios|graphql|trpc|prisma|drizzle|sequelize|typeorm" \
  src apps packages \
  -g '*.ts' -g '*.tsx' -g '*.js' -g '*.jsx'

Minta flow table, bukan paragraf.

Lensa	Output kuat	Output lemah
Entry	POST /login -> auth route -> AuthService.login	”Auth penting”
State	Cookie, session, DB, cache, atau queue mutation	Tidak ada state change
Failure	Error response, logging, audit event, retry	Happy path saja
Tests	Test existing dan missing cases	”Tambah test” generik

Trace login flow dari entrypoint sampai persistence.
Kembalikan tabel dengan kolom: order, file, function/class, state change, failure behavior, tests to read.
Jangan isi gap dengan tebakan. Jika step belum jelas, sebutkan file berikutnya yang harus diperiksa.

Petakan Ownership Dan Risiko

Di repository besar, pertanyaan pertama bukan “apakah berjalan?”, melainkan “ini batas milik siapa?”. Batas bisa berupa team, data, release, compliance, atau revenue.

find . -maxdepth 4 \( \
  -name CODEOWNERS -o \
  -name OWNERS -o \
  -name README.md -o \
  -name AGENTS.md -o \
  -name CLAUDE.md \
\) -print

rg -n "owner|maintainer|deprecated|legacy|do not edit|generated|migration|rollback|release" \
  . -g '!node_modules' -g '!dist' -g '!build'

Codex secara resmi membaca AGENTS.md, jadi aturan project layak ditaruh di sana. Claude Code dapat memakai CLAUDE.md dan memory untuk memperpendek session berikutnya. Untuk template lebih lengkap, lihat CLAUDE.md Best Practices.

## Codebase map

### Entry points
- Web: apps/web/src/main.tsx
- API: services/api/src/server.ts
- Jobs: services/jobs/src/index.ts

### Ownership boundaries
- services/payments: owned by payments team; never change schema without migration review.
- packages/ui: shared design system; visual regression test required.
- legacy/: read-only unless the issue is production severity.

### High-risk files
- services/api/src/auth/AuthService.ts: login, session rotation, audit log.
- packages/db/schema.ts: migrations affect API and jobs.
- apps/web/src/routes/checkout.tsx: revenue path and analytics.

### Handoff notes
- Always start with rg search, then read top files.
- Prefer small diffs with tests.
- Do not paste large logs into the main conversation; summarize first.

Gunakan Prompt Explorer Read-Only

Pada eksplorasi pertama, biarkan agent tetap konsultatif. Kamu butuh map, hypothesis, dan unknowns sebelum tool mulai mengubah file.

Investigasi dalam mode read-only. Jangan edit file, jangan tambah dependency, jangan format code, dan jangan run test.

Goal:
Memahami implementation scope dan change risk untuk [feature name].

Return:
1. Entrypoint files
2. Core data models
3. Direct dan indirect dependencies
4. Ownership boundaries
5. Risk map: high / medium / low
6. Files to inspect next
7. Hypotheses yang belum confirmed

Rules:
Labeli tebakan sebagai hypothesis.
Sertakan file names dan evidence.
Jangan quote file body yang besar.

Subagents Claude Code berguna saat eksplorasi akan memenuhi percakapan utama dengan pembacaan file. Dokumentasi resmi menjelaskan subagent bekerja dalam konteks sendiri dan mengembalikan ringkasan. Codex subagents juga didokumentasikan untuk eksplorasi codebase paralel. Gunakan dengan batas jelas karena tetap memakai tokens. Lihat Subagent Patterns.

Jalankan tiga read-only subagents:
1. API entrypoints dan auth boundaries
2. DB schema dan migration boundaries
3. UI routes dan revenue path

Setiap subagent boleh membaca maksimal 8 file dan hanya mengembalikan final findings.
Setelah selesai, parent agent menggabungkan duplicate, conflict, dan unknowns.

Hindari Context Bloat

Aturan paling sederhana: pisahkan evidence dan decision. Full file, log panjang, dan seratus search hits terlalu berat sebagai evidence. Filter dulu, lalu minta agent mengambil keputusan.

OpenAI compaction adalah fitur API, tetapi prinsipnya berlaku di workflow manusia-agent: simpan ringkasan penting dan buang detail lama.

Compress investigasi ini agar worker berikutnya bisa lanjut dalam kurang dari 300 kata.
Keep:
- Confirmed entrypoints
- High-risk files
- Boundaries yang tidak boleh dilanggar
- Unconfirmed hypotheses
- Next command to run

Drop:
- Hypotheses yang sudah terbukti salah
- Long logs
- Generated files yang tidak perlu dibaca

Handoff notes penting untuk development dan content operations. Untuk artikel multibahasa, catat locale files yang kamu miliki. Untuk app, catat entrypoint yang sudah di-trace. Untuk bug, catat hypothesis yang gagal. Pasangkan dengan Claude Code Testing Strategies dan approval and sandbox guide.

Tiga Use Case Konkret

Pertama, handoff SaaS. Di hari pertama, petakan login, billing, admin, dan notifications. Temukan importers untuk AuthService dan BillingService, lalu trace checkout dari route sampai database. Jangan edit dulu. Output-nya harus berupa risk map dan urutan baca.

Kedua, migrasi legacy. Cari legacy, deprecated, dan migration sebelum meminta replacement code. Tanyakan compatibility risks. DB migrations, public APIs, batch jobs, dan cron perlu perhatian khusus karena rollback mahal.

Ketiga, situs content dan monetization seperti ClaudeCodeLab. Articles, CTA components, internal links, product pages, dan translations berada di folder berbeda. Bekerja per slug. Minta agent hanya memiliki satu slug dan memakai artikel lain hanya untuk link checks. Ini membuat parallel editing lebih aman.

Failure Mode Umum

• Terlalu percaya README. Entrypoint nyata sering drift dari dokumentasi lama.
• Menganggap search hits sebagai execution flow. Hit adalah kandidat, bukan bukti.
• Membiarkan agent edit sebelum ownership jelas.
• Memasukkan generated folders, lockfiles, coverage, atau dist ke percakapan.
• Memberi subagents scope yang terlalu luas.
• Mengatakan “fix safely” tanpa mendefinisikan high / medium / low.

CTA Untuk Tim

Navigasi codebase besar juga memengaruhi revenue work. Checkout, lead forms, paid content, analytics, dan ads berada di balik risk boundaries. Repo map sebelum editing mengurangi rework.

Jika tim mengadopsi Claude Code atau Codex, mulai dari template repo map, guidance AGENTS.md/CLAUDE.md, aturan review, dan prompt explorer read-only. Developer individu bisa mulai dari free cheat sheet. Untuk training berbasis repository nyata, lihat Claude Code training and consulting.

Catatan Verifikasi Praktis

Saat memakai workflow ini, prompt implementasi berikutnya lebih stabil dibanding mulai dengan menempelkan file besar. Artefak paling berguna adalah repo map, hasil rg yang diklasifikasikan, tabel dependency kecil, dan risk map high / medium / low. Saat langkah ini dilewati, generated folders, test lama, dan modul tim lain masuk ke percakapan. Sebelum publikasi, saya mengecek command, prompt packet, dan script Node agar bisa disalin serta memiliki struktur JavaScript dasar yang benar.