Panduan Kolaborasi Tim dengan Claude Code: handoff, review, dan izin

Claude Code sangat membantu saat dipakai sendiri: memahami kode, memperbaiki implementasi, dan menulis test menjadi lebih cepat. Saat dipakai tim, tantangannya berubah. Tim perlu tahu siapa yang menyetujui perintah tertentu, file apa saja yang dilihat Claude, risiko apa yang belum diverifikasi, dan apakah saran AI benar-benar diterima oleh manusia.

Panduan ini memberi alur kerja praktis untuk tim kecil dan menengah. Isinya mencakup handoff, pra-review PR, aturan CLAUDE.md, batas izin, onboarding, handoff insiden, dan kegagalan komunikasi. Batas izin berarti ruang file dan perintah yang boleh dibaca, diedit, atau dijalankan Claude Code. Tanda terima review adalah catatan singkat di PR tentang bagaimana tim menangani saran AI.

flowchart LR
  A["Permintaan developer"] --> B["CLAUDE.md dan aturan"]
  B --> C["Pekerjaan Claude Code"]
  C --> D["Test dan diff"]
  D --> E["Tanda terima review"]
  E --> F["Review PR oleh manusia"]

Empat Lokasi Bersama

Alur tim tidak bisa bergantung pada satu orang yang hafal prompt bagus. Aturan harus berada di file yang bisa digunakan ulang.

Lokasi	Tujuan	Masuk Git
CLAUDE.md	Konvensi, larangan, perintah test	Ya
.claude/settings.json	Izin bersama, aturan deny, hooks	Ya
.claude/settings.local.json	URL pribadi dan setelan sementara	Tidak
.claude/prompts/*.md	Template handoff, review, investigasi	Ya

Dokumentasi resmi menjelaskan memori Claude Code, setelan, izin, dan keamanan. Untuk panduan internal, baca juga praktik terbaik CLAUDE.md, panduan hooks Claude Code, dan GitHub Actions lanjutan.

Kasus 1: handoff dari developer ke reviewer

Kesalahan paling umum adalah menyerahkan PR dengan kalimat “Claude sudah memperbaiki”. Reviewer perlu tahu file mana yang diperiksa, perintah apa yang disetujui, test mana yang gagal, dan keputusan apa yang masih harus dibuat manusia.

Buat .claude/prompts/handoff.md:

# Tulis catatan handoff tim

Baca diff saat ini dan tulis handoff dengan format berikut.

## Tujuan
- Masalah yang ingin diselesaikan:

## Cakupan
- File yang diubah:
- File yang tidak diubah tetapi mungkin terdampak:

## Verifikasi
- Perintah yang dijalankan:
- Hasil:
- Ringkasan log gagal:

## Fokus reviewer
- Keputusan produk:
- Keamanan:
- Performa:
- Test yang kurang:

## Pemilik berikutnya
- Perlu dicek dulu:
- Bisa menyusul:

Setelah diff siap, jalankan:

claude -p "Baca git diff dan buat catatan handoff tim dengan format .claude/prompts/handoff.md"

Tempel hasilnya ke isi PR. Reviewer bisa langsung melihat risiko yang diketahui, bukan membangun ulang konteks dari awal.

Kasus 2: pra-review PR dengan AI

Claude Code tidak boleh menggantikan persetujuan manusia. Ia lebih cocok menjadi pembacaan awal untuk menangkap bug jelas, test yang kurang, risiko keamanan, dan perubahan yang tidak konsisten.

Buat .claude/prompts/pr-review.md:

# Pra-review PR

Review diff dengan kriteria berikut:

1. Cabang logika, null/undefined, dan nilai batas yang bisa menjadi bug
2. Otorisasi, validasi input, dan kebocoran secret
3. Query N+1, rerender berlebihan, dan kerja sinkron berat
4. Pelanggaran aturan CLAUDE.md
5. Kasus test yang belum ada

Format keluaran:
- Tingkat: tinggi / sedang / rendah
- File:
- Baris atau fungsi:
- Alasan:
- Saran perbaikan:

Tandai temuan yang masih dugaan sebagai “perlu konfirmasi”.

Jalankan lokal dengan GitHub CLI:

gh pr diff 123 | claude -p "$(cat .claude/prompts/pr-review.md)"

Jika memakai GitHub Actions, batasi otomatisasi hanya untuk komentar. Keputusan merge tetap milik manusia.

name: Claude PR pre-review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  pre-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install tools
        run: npm install -g @anthropic-ai/claude-code
      - name: Run Claude Code review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          gh pr diff "$PR_NUMBER" > /tmp/pr.diff
          claude -p "$(cat .claude/prompts/pr-review.md)

          Diff:
          $(cat /tmp/pr.diff)" > /tmp/claude-review.md
          gh pr comment "$PR_NUMBER" --body-file /tmp/claude-review.md

Halaman resmi alur kerja umum juga membahas review dan test. Aturan tim harus jelas: komentar AI adalah masukan, persetujuan tetap oleh manusia.

Kasus 3: onboarding anggota baru

Anggota baru biasanya lebih sering bingung soal “perintah mana yang aman”, “aturan bisnis ada di mana”, dan “file apa yang dibaca dulu” daripada soal sintaks. Claude Code dapat membuat peta awal repository.

claude -p "
Jelaskan repository ini untuk anggota tim baru.
Wajib sertakan:
- Direktori utama dan tanggung jawabnya
- Perintah untuk local run, lint, test, dan build
- 3 file pertama yang perlu dibaca
- Aturan bisnis yang harus dicek sebelum mengubah kode
- Kesalahan umum dan cara menghindarinya
- Tugas latihan 30 menit

Jangan menebak. Tulis hal yang tidak jelas sebagai perlu konfirmasi.
"

Jangan terbitkan keluaran mentah. Minta anggota senior menambahkan batasan produksi, keputusan historis, dan risiko operasional. Untuk eksplorasi besar, pola subagent membantu memisahkan pencarian dan ringkasan.

Kasus 4: handoff insiden

Saat insiden, Claude Code bisa meringkas log dan menyusun hipotesis. Risikonya juga besar: secret ikut ditempel, dugaan yang belum diuji dibagikan seperti fakta, atau catatan “apa yang sudah dicoba” hilang saat pemilik berganti.

Simpan sebagai .claude/prompts/incident-handoff.md:

# Handoff insiden

## Gejala
- Sejak kapan:
- Cakupan:
- Dampak pengguna:

## Fakta yang diamati
- Log:
- Metrik:
- Langkah reproduksi:

## Sudah dicoba
- Perintah:
- Hasil:
- Hipotesis yang gagal:

## Risiko tersisa
- Kerusakan data:
- Dampak keamanan:
- Status rollback:

## Pemilik berikutnya
- Layar/log pertama yang dicek:
- Perintah yang tidak boleh dijalankan:

Sebelum memberi log ke Claude Code, samarkan email, access token, dan ID pelanggan. Dokumentasi keamanan resmi juga menjelaskan risiko izin dan prompt injection.

Aturan CLAUDE.md yang Berguna

CLAUDE.md berisi fakta yang terus diulang tim. Buat singkat, konkret, dan bisa diverifikasi.

# Instruksi proyek untuk Claude Code

## Sebelum bekerja
- Jalankan `git status --short` sebelum mengedit.
- Jangan mengembalikan perubahan orang lain.
- Jika perilaku produk tidak jelas, tulis “perlu konfirmasi” di PR.

## Aturan kode
- Validasi semua input API.
- Jelaskan batas transaksi untuk penulisan database.
- Gunakan translation key yang ada sebelum menambah teks UI.

## Test
- Tambahkan unit test untuk perubahan logika.
- Tambahkan satu regression test untuk setiap bug fix.
- Jika test tidak bisa dijalankan, tulis alasannya.

## PR
- Sertakan ringkasan, verifikasi, dan risiko tersisa.
- Pakai saran Claude Code hanya setelah review manusia.

Jika repository sudah memakai AGENTS.md, impor saja agar aturan tidak dobel.

@AGENTS.md

## Khusus Claude Code
- Gunakan plan mode untuk billing, auth, dan alur penghapusan.
- Manusia menjalankan `git push`, deploy produksi, dan migrasi.

Kunci Batas Izin

Risiko terbesar adalah membuka izin terlalu luas karena terasa nyaman. Mulai dari deny yang jelas dan allow yang minimal.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm test)",
      "Bash(git diff *)",
      "Bash(git status *)",
      "Edit(src/**)",
      "Edit(tests/**)"
    ],
    "ask": [
      "Bash(npm install *)",
      "Bash(git commit *)",
      "Write(.github/**)"
    ],
    "deny": [
      "Read(.env*)",
      "Read(**/secrets/**)",
      "Bash(git push --force*)",
      "Bash(rm -rf *)",
      "Bash(npm publish*)"
    ]
  }
}

Hooks bisa menjalankan pemeriksaan setelah edit atau memblokir perintah berisiko. Baca referensi hooks resmi sebelum menerapkannya.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --quiet"
          }
        ]
      }
    ]
  }
}

Contoh ini hanya cocok jika proyek memiliki npm run lint. Untuk monorepo besar, gunakan pemeriksaan per file atau pindahkan pekerjaan berat ke CI.

Tinggalkan Tanda Terima Review

Review AI berisiko jika tidak ada catatan saran mana yang diterima. Tambahkan ini ke template PR:

## Tanda terima review Claude Code

- Prompt yang dipakai:
- Diff yang dibaca Claude Code:
- Saran yang diterima:
- Saran yang ditolak dan alasan:
- Pemeriksaan manusia tambahan:
- Test yang dijalankan:
- Risiko tersisa:

Pemilik keputusan akhir:

Jika Claude Code tidak dipakai, tulis “tidak dipakai”. Tujuannya agar pekerjaan berbantuan AI setidaknya setransparan pekerjaan biasa.

Kegagalan Konkret dan Perbaikannya

Kegagalan	Dampak	Perbaikan
CLAUDE.md kedaluwarsa	Perintah lama dan API usang kembali dipakai	Review bulanan dari kegagalan nyata
Izin terlalu luas	Secret dan aksi produksi terlalu dekat	Tulis deny dulu, lalu allow minimal
Persetujuan hanya oleh AI	Keputusan produk dan tanggung jawab hilang	Persetujuan PR wajib manusia
Handoff lisan	Esok hari alasan tidak terlacak	Tempel catatan ke PR atau Issue
/clear menghapus konteks	Alasan perubahan hilang	Simpan ringkasan sebelum reset atau compact
Hooks terlalu berat	Tim mulai menghindari alur	Pakai hooks per file atau CI

Komunikasi juga sering gagal. “Tolong rapikan” membuat Claude Code menebak target. Lebih baik beri batas singkat: “hanya fungsi ini”, “jangan sentuh schema”, “baca log test gagal dulu”.

Checklist Minimum Tim

• CLAUDE.md berisi perintah, larangan, dan aturan PR
• .claude/settings.json memisahkan allow, ask, dan deny
• .claude/settings.local.json masuk .gitignore
• Prompt handoff, PR, dan insiden dibagikan
• Template PR memiliki tanda terima review
• Pemilik keputusan akhir jelas
• Ada tugas onboarding 30 menit

ClaudeCodeLab terus menyempurnakan template seperti ini untuk tim pengembangan berbantuan AI. Jika ingin mempercepat adopsi internal, lihat produk ClaudeCodeLab.

Kesimpulan

Menggunakan Claude Code dalam tim bukan soal mencari prompt ajaib. Kuncinya adalah instruksi bersama, izin sempit, handoff yang tersimpan, dan tanda terima review yang bisa diaudit.

Untuk kerja sendiri, beberapa prompt bagus mungkin cukup. Untuk tim, orang lain harus bisa mengulangi alur, menelusuri kegagalan, dan memisahkan saran Claude Code dari keputusan manusia.

Saat Masa mencoba struktur ini di repository validasi kecil, peningkatan paling cepat datang dari catatan handoff dan tanda terima review di PR. Reviewer lebih jarang bertanya “apa yang sudah dicek?”. Pengaturan terburuk adalah menjalankan lint penuh setelah setiap edit lewat hook; terlalu lambat, jadi CI lebih tepat. Mulailah dari CLAUDE.md, prompt pra-review PR, dan tanda terima review.