Onboarding Developer dengan Claude Code: dari Bulanan ke 2 Minggu

Onboarding engineer baru tidak selesai saat laptop diberikan. Onboarding adalah proses membawa seseorang dari “saya bisa membuka repository” ke “saya bisa mengirim perubahan kecil yang aman direview dan sesuai aturan tim”. Bagian yang biasanya lambat adalah pertanyaan setup berulang, codebase besar, ekspektasi review yang tidak jelas, dan tribal knowledge yang hanya diketahui anggota lama.

Claude Code tidak seharusnya menggantikan mentor. Perannya yang paling berguna adalah membuat jalur kerja yang aman: instruksi proyek di CLAUDE.md, script setup yang bisa diulang, permission yang jelas, checklist tugas pertama, template PR, dan cara membaca CI. Secara sederhana, codebase adalah seluruh source code aplikasi, PR adalah permintaan review atas perubahan, dan CI adalah sistem otomatis yang menjalankan test serta build sebelum merge.

Karena Claude Code bisa berubah, gunakan dokumentasi resmi sebagai sumber utama: Claude Code setup, CLI reference, memory, dan settings. Untuk konteks tambahan, baca codebase navigation, code review, dan CLAUDE.md templates.

flowchart LR
  A["Day 1: setup"] --> B["Day 2: codebase map"]
  B --> C["Day 3-5: first task"]
  C --> D["Week 2: PR review"]
  D --> E["Retrospective and docs update"]

1. Mulai dari CLAUDE.md

CLAUDE.md adalah memori proyek yang dibaca Claude Code sebagai instruksi bersama. Untuk onboarding, isi dengan command, batasan, dan aturan eskalasi, bukan hanya prinsip umum.

cat > CLAUDE.md <<'EOF'
# Project instructions for Claude Code

## Goal
Help new engineers make small, reviewable changes without bypassing tests or team rules.

## Daily commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test -- --runInBand
- Lint: npm run lint
- Build: npm run build

## Boundaries
- Do not edit files under migrations/ without human approval.
- Do not read .env, .env.*, secrets/, or production credentials.
- Do not push, commit, deploy, or publish packages.
- Prefer small diffs under 150 lines for first tasks.

## First PR rules
- Explain the intent before editing.
- Reuse existing patterns before adding dependencies.
- Add or update tests for behavior changes.
- Include command output in the PR description.

## When stuck
Ask the engineer to provide:
1. What they tried
2. The exact error
3. The file or command involved
4. What Claude Code inferred and what still needs human judgment
EOF

Tujuannya bukan membuat Claude Code menjadi senior ajaib. Tujuannya memperkecil scope agar anggota baru belajar standar tim sambil menghasilkan diff yang mudah direview.

2. Buat setup bisa diulang

Hambatan pertama biasanya versi Node, dependency, env var lokal, data test, dan command untuk membuktikan semuanya berjalan. Script membuat proses itu menjadi jalur yang jelas.

mkdir -p scripts
cat > scripts/onboarding-setup.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

echo "== Checking required tools =="
node --version
npm --version
git --version

if ! command -v claude >/dev/null 2>&1; then
  echo "Claude Code is not installed."
  echo "Install with: npm install -g @anthropic-ai/claude-code"
  exit 1
fi

echo "== Installing dependencies =="
npm ci

if [ ! -f .env ] && [ -f .env.example ]; then
  cp .env.example .env
  echo "Created .env from .env.example. Fill in local-only values before running the app."
fi

echo "== Running baseline checks =="
npm run lint
npm run typecheck
npm test -- --runInBand

echo "== Ask Claude Code for a local map =="
claude -p "Read README.md, package.json, and CLAUDE.md. Explain how to start this project locally, which checks just ran, and what a new engineer should verify before opening the first PR."
EOF
chmod +x scripts/onboarding-setup.sh

Untuk proyek npm biasa, script ini bisa langsung dicoba. Jika tim memakai pnpm, Yarn, Docker Compose, atau Makefile, ganti command-nya. Tetap pertahankan strukturnya: setup, verifikasi, lalu penjelasan dari Claude Code.

3. Batasi risiko dengan permission

Claude Code bisa membaca file, mencari kode, menjalankan command, dan mengedit jika diizinkan. Ini berguna, tetapi juga berisiko jika .env terbaca, command berbahaya dijalankan, atau diff menjadi terlalu besar.

mkdir -p .claude
cat > .claude/settings.json <<'EOF'
{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Glob",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(npm run lint)",
      "Bash(npm run typecheck)",
      "Bash(npm test:*)"
    ],
    "ask": [
      "Edit",
      "Write",
      "Bash(npm install:*)",
      "Bash(git checkout:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push:*)",
      "Bash(git commit:*)",
      "Bash(rm:*)",
      "Bash(curl:*)",
      "Bash(npm publish:*)"
    ]
  }
}
EOF

Pada minggu pertama, cukup izinkan read, search, diff, log, dan test. Edit bisa meminta konfirmasi. Push, commit, deploy, publish, dan akses secret sebaiknya tidak masuk jalur onboarding.

4. Tetapkan checklist PR pertama

PR pertama adalah latihan kerja tim. Kandidat yang baik: menambah unit test untuk perilaku yang sudah ada, memperbaiki teks UI kecil, memperjelas error message, atau merapikan helper duplikat di satu folder. Hindari auth, billing, permission, migration, formatting luas, dan upgrade dependency.

mkdir -p docs/onboarding
cat > docs/onboarding/first-task-checklist.md <<'EOF'
# First task checklist

## Before editing
- [ ] I can run `npm ci`.
- [ ] I can run `npm run lint`.
- [ ] I can run `npm run typecheck`.
- [ ] I can run the nearest test for the area I will touch.
- [ ] I understand the user-visible behavior being changed.

## Good first task examples
- [ ] Add a missing unit test around existing behavior.
- [ ] Fix a small UI copy typo with screenshot evidence.
- [ ] Replace duplicated helper logic in one folder.
- [ ] Improve one error message without changing API contracts.

## Not good for the first task
- [ ] Authentication, billing, permissions, or migrations.
- [ ] Broad formatting changes.
- [ ] Dependency upgrades.
- [ ] Refactors across multiple packages.

## PR evidence
- [ ] Summary of the change.
- [ ] Test commands and results.
- [ ] Screenshot or log if behavior changed.
- [ ] Open question for reviewer, if any.
EOF

Workflow ini mencakup use case nyata: setup mandiri, membaca codebase, memilih tugas pertama, dan self-review sebelum PR.

5. Standarkan permintaan review

Banyak PR pertama dikembalikan karena reviewer tidak tahu apa yang sudah dicek. Template memaksa engineer baru menulis intent, keamanan scope, verifikasi, dan fokus review.

mkdir -p .github
cat > .github/pull_request_template.md <<'EOF'
## Summary
- TODO

## Why this is safe for a first PR
- Scope:
- Files changed:
- Behavior changed:

## Verification
- [ ] `npm run lint`
- [ ] `npm run typecheck`
- [ ] `npm test -- --runInBand`

## Claude Code self-review prompt used
Ask Claude Code:
"Review git diff origin/main...HEAD for naming, tests, security, and consistency with CLAUDE.md. Return only actionable issues."

## Reviewer focus
- TODO

## Screenshots or logs
- TODO
EOF

Ini juga membantu mentor. Mereka bisa langsung tahu apakah review perlu fokus pada desain, test, perilaku, screenshot, atau pemahaman proses.

6. Jelaskan CI sejak hari pertama

CI berarti continuous integration. Ini sistem yang menjalankan check sebelum PR di-merge. Engineer baru perlu belajar mereproduksi failure secara lokal, bukan hanya melihat status merah.

name: onboarding-checks

on:
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --runInBand
      - run: npm run build

Walaupun memakai CI lain, dokumentasikan command yang sama. Setelah itu, minta Claude Code membaca log gagal dan menjelaskan command lokal pertama yang harus dijalankan.

Kesalahan umum

Pertama, menyerahkan keputusan bisnis ke Claude Code. Ia bisa menyimpulkan dari kode dan history, tetapi komitmen pelanggan, pengecualian, dan compliance tetap butuh manusia.

Kedua, membuat PR pertama terlalu besar. Usahakan di bawah 150 baris, ada test, dan mudah di-rollback.

Ketiga, membuka secret. Deny .env, credential, dan file production di settings, lalu pakai nilai contoh di dokumentasi.

Keempat, terlalu melarang pertanyaan manusia. “Tanya Claude dulu” hanya sehat jika dua minggu pertama tetap punya check-in mentor yang sering.

CTA

Untuk tim, standardisasi CLAUDE.md, permission, bukti PR, dan CI check secara bersamaan. Developer individu bisa mulai dari cheatsheet gratis. Untuk template yang bisa dipakai ulang, lihat ClaudeCodeLab products. Untuk training tim, desain permission, dan rollout ke repository nyata, gunakan Claude Code training and consultation.

Hasil setelah dicoba

Pada pekerjaan artikel ClaudeCodeLab dan perubahan kode kecil, peningkatan terbesar datang dari menulis aturan sebelum meminta implementasi. Dengan CLAUDE.md, permission terbatas, command verifikasi, dan template PR, diff jauh lebih mudah direview. Saat Claude Code salah, asumsi dan jejak command yang tersimpan membuat sumber salah paham cepat ditemukan.