Thinking engineer toolkit untuk Git hook dan CI adalah cara menyatukan standar kerja tim ke dalam alur yang bisa dijalankan otomatis, bukan hanya disimpan di dokumen wiki. Tujuannya sederhana: kesalahan dasar tertangkap lebih cepat di mesin developer, sementara aturan yang wajib dan konsisten ditegakkan di CI sebelum kode digabung.

Inspirasi gagasan ini sejalan dengan tren diskusi komunitas engineer tentang toolkit kerja yang lebih sistematis, termasuk konteks dari DEV Community. Namun nilai utamanya bukan pada daftar tool, melainkan pada bagaimana checklist review, linting, formatting, type-check, test cepat, validasi commit message, dan template PR diubah menjadi workflow yang benar-benar mengurangi beban review dan mempercepat feedback.

Apa yang dimaksud thinking engineer toolkit

Dalam konteks workflow tim, thinking engineer toolkit adalah kumpulan guardrail teknis dan kebiasaan review yang dirancang agar keputusan rutin tidak selalu mengandalkan ingatan manusia. Engineer tetap berpikir, tetapi hal-hal yang bisa divalidasi otomatis dipindahkan ke tooling.

Toolkit ini biasanya mencakup:

  • Formatting agar diff konsisten dan reviewer tidak membahas spasi atau style kecil.
  • Linting untuk menangkap pola rawan bug atau pelanggaran konvensi.
  • Type-check untuk memverifikasi kontrak data sejak awal.
  • Test cepat untuk mendeteksi regresi dasar sebelum push.
  • Commit message validation agar histori repo tetap rapi dan mendukung automasi release bila diperlukan.
  • PR template untuk memaksa konteks perubahan, risiko, dan langkah verifikasi tertulis dengan jelas.
  • Checklist review agar reviewer fokus pada desain, keamanan, dan dampak bisnis, bukan isu mekanis.

Prinsip pentingnya: otomatisasi untuk hal mekanis, manusia untuk penilaian konseptual.

Arsitektur workflow: apa dijalankan di Git hook, apa dijalankan di CI

Kesalahan umum saat membangun workflow adalah menaruh semua pemeriksaan di semua tempat. Akibatnya developer menunggu lama saat commit, lalu mulai mencari cara untuk melewati hook. Desain yang lebih sehat adalah membagi beban kerja berdasarkan tujuan.

Tanggung jawab Git hook lokal

Git hook lokal cocok untuk feedback yang cepat, deterministik, dan relevan dengan file yang sedang diubah.

  • Format file yang di-stage.
  • Lint pada file yang di-stage atau scope terbatas.
  • Type-check ringan bila biayanya masih masuk akal.
  • Unit test cepat atau subset test yang terkait dengan perubahan.
  • Validasi format commit message.

Targetnya adalah feedback dalam hitungan detik, bukan menit.

Tanggung jawab CI

CI adalah sumber kebenaran bersama tim. Semua aturan yang wajib lulus sebelum merge harus bisa dijalankan di CI tanpa bergantung pada kondisi laptop developer.

  • Full lint seluruh repo.
  • Full type-check.
  • Full test suite yang relevan.
  • Build atau packaging validation.
  • Security scan ringan jika memang sudah matang.
  • Pemeriksaan branch protection dan status check wajib.

Aturan praktis: jika sebuah pemeriksaan wajib untuk merge, ia harus ada di CI. Hook lokal boleh mempercepat feedback, tetapi tidak boleh menjadi satu-satunya penegak aturan.

Struktur repo yang praktis

Supaya toolkit mudah dirawat, simpan artefaknya di lokasi yang jelas. Contoh struktur repo:

repo-root/
├─ .githooks/
│  ├─ pre-commit
│  ├─ commit-msg
├─ .github/
│  ├─ pull_request_template.md
│  └─ workflows/
│     └─ ci.yml
├─ scripts/
│  ├─ check-staged.sh
│  ├─ validate-commit-msg.sh
│  ├─ test-fast.sh
│  └─ review-checklist.md
├─ src/
├─ tests/
├─ package.json
├─ Makefile
└─ README.md

Jika tim memakai beberapa bahasa atau package manager, prinsipnya tetap sama: pisahkan hook scripts, CI definition, dan documentation artifacts.

Implementasi dasar thinking engineer toolkit

1. Pre-commit untuk format, lint, dan test cepat

Contoh berikut menggunakan pendekatan generik berbasis shell agar mudah dipahami. Anda bisa menjalankannya lewat tool manapun yang disukai tim.

#!/usr/bin/env sh
set -eu

# .githooks/pre-commit

echo "Menjalankan formatting dan lint untuk file yang di-stage..."
./scripts/check-staged.sh

echo "Menjalankan test cepat..."
./scripts/test-fast.sh

echo "Pre-commit selesai."

Isi scripts/check-staged.sh bisa disesuaikan dengan stack. Untuk proyek JavaScript/TypeScript, pola umumnya:

#!/usr/bin/env sh
set -eu

STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
[ -z "$STAGED_FILES" ] && exit 0

echo "$STAGED_FILES" | grep -E '\.(js|ts|tsx|json|md)$' >/dev/null 2>&1 || exit 0

# Contoh perintah, sesuaikan dengan tool di repo Anda
npm run format:staged
npm run lint:staged
npm run typecheck:changed

Poin pentingnya bukan nama command, melainkan scope yang dibatasi pada file yang berubah agar hook tetap cepat.

2. Commit message validation

Validasi commit message berguna jika tim ingin histori lebih konsisten, lebih mudah ditelusuri, atau dipakai untuk automasi changelog. Jangan membuat formatnya terlalu rumit.

#!/usr/bin/env sh
set -eu

# .githooks/commit-msg
./scripts/validate-commit-msg.sh "$1"
#!/usr/bin/env sh
set -eu

MSG_FILE="$1"
MSG=$(head -n 1 "$MSG_FILE")

case "$MSG" in
  feat:*|fix:*|docs:*|refactor:*|test:*|chore:*)
    exit 0
    ;;
  *)
    echo "Format commit message tidak valid. Gunakan misalnya: feat: tambah validasi login"
    exit 1
    ;;
esac

Aturan di atas sengaja sederhana. Jika terlalu ketat sejak awal, resistensi tim biasanya naik.

3. Template PR yang memaksa konteks

PR template bukan sekadar formalitas. Ia memindahkan pertanyaan reviewer yang berulang menjadi input wajib dari penulis PR.

<!-- .github/pull_request_template.md -->
## Ringkasan
- Apa yang diubah?
- Mengapa perubahan ini diperlukan?

## Cara verifikasi
- [ ] Unit test relevan sudah dijalankan
- [ ] Perubahan sudah diuji secara manual bila perlu

## Risiko
- Dampak ke area lain:
- Migration/config/env yang berubah:

## Checklist penulis
- [ ] Naming dan struktur kode masuk akal
- [ ] Error handling dipertimbangkan
- [ ] Logging/observability dipertimbangkan bila relevan
- [ ] Tidak ada data sensitif yang terekspos

## Bukti
- Screenshot/log/output bila diperlukan

Template ini efektif bila singkat dan memaksa konteks yang benar, bukan daftar panjang yang selalu dicentang tanpa dibaca.

4. Checklist review untuk reviewer

Checklist reviewer sebaiknya fokus pada hal yang sulit diotomasi. Simpan sebagai referensi ringan di repo atau dokumentasi internal.

# scripts/review-checklist.md

- Apakah perubahan ini memecah kontrak API atau skema data?
- Apakah ada risiko race condition, retry ganda, atau idempotency issue?
- Apakah validasi input dan error handling memadai?
- Apakah query, loop, atau rendering berpotensi menimbulkan bottleneck?
- Apakah log, metric, atau trace cukup untuk debugging?
- Apakah test benar-benar memverifikasi perilaku penting, bukan hanya happy path?
- Apakah perubahan ini bisa diperkecil scope-nya?

Checklist review yang baik membantu reviewer bertanya lebih tajam, bukan menambah birokrasi.

Contoh integrasi CI sederhana

Di CI, jalankan pemeriksaan yang sama atau lebih lengkap dari lokal. Contoh generik berikut menunjukkan urutan yang lazim:

name: ci

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup runtime
        run: echo "Siapkan runtime dan dependency sesuai stack proyek"

      - name: Install dependencies
        run: echo "Install dependency"

      - name: Format check
        run: npm run format:check

      - name: Lint
        run: npm run lint

      - name: Type check
        run: npm run typecheck

      - name: Test
        run: npm test

Perintah di atas hanya contoh struktur. Anda harus menyesuaikan langkah setup runtime dan instalasi dependency dengan stack yang dipakai tim.

Yang lebih penting adalah urutannya:

  1. Format check dan lint ditempatkan di awal karena cepat dan memberi sinyal kegagalan yang jelas.
  2. Type-check menyusul untuk memverifikasi kontrak.
  3. Test dijalankan setelah masalah mekanis disaring.

Jika pipeline mulai lambat, pertimbangkan pemisahan job, caching dependency, atau pembagian test berdasarkan jenisnya. Namun jangan mengorbankan determinisme hanya demi sedikit percepatan.

Trade-off: local hook vs CI

Kelebihan local hook

  • Feedback sangat cepat.
  • Mengurangi push yang jelas-jelas akan gagal.
  • Mendidik kebiasaan engineering tanpa menunggu review.

Kekurangan local hook

  • Lingkungan developer tidak seragam.
  • Mudah dilewati jika tim frustrasi atau ada kebutuhan darurat.
  • Bisa terasa mengganggu bila terlalu lambat.

Kelebihan CI

  • Eksekusi konsisten di lingkungan bersama.
  • Bisa dijadikan syarat merge melalui branch protection.
  • Lebih mudah diaudit dan dipantau hasilnya.

Kekurangan CI

  • Feedback datang lebih lambat daripada lokal.
  • Biaya komputasi lebih tinggi.
  • Jika banyak kegagalan trivial, antrian review ikut tersendat.

Pilihan terbaik hampir selalu kombinasi keduanya: hook lokal untuk percepatan feedback, CI untuk penegakan aturan final.

Strategi adopsi bertahap yang realistis

Banyak inisiatif workflow gagal bukan karena tooling salah, tetapi karena cakupannya terlalu besar di awal. Adopsi bertahap biasanya lebih berhasil.

Tahap 1: kurangi noise review

  • Tambahkan formatter.
  • Tambahkan lint dasar.
  • Gunakan PR template singkat.

Ini memberi dampak cepat dengan resistensi rendah.

Tahap 2: tambahkan validasi kualitas minimum

  • Type-check di CI.
  • Test cepat di pre-commit atau pre-push.
  • Commit message validation sederhana.

Fokus pada area yang sering menyebabkan rollback atau komentar review berulang.

Tahap 3: matangkan guardrail

  • Tambahkan full test suite di CI.
  • Perjelas checklist reviewer untuk keamanan, performa, dan observability.
  • Jadikan status CI tertentu sebagai required check.

Pada tahap ini, tim biasanya sudah melihat manfaat sehingga aturan tambahan lebih mudah diterima.

Jangan mulai dengan sepuluh rule lint baru, full test berat di setiap commit, dan template PR sepanjang satu halaman. Mulailah dari sumber friksi terbesar yang paling sering berulang.

Cara mengurangi false positive dan friksi

Tooling yang terlalu cerewet akan kehilangan legitimasi. Tujuannya bukan membuat pipeline paling ketat, melainkan pipeline yang dipercaya tim.

Batasi scope hook lokal

Jalankan formatter dan lint hanya pada file yang di-stage. Menjalankan seluruh repo pada setiap commit sering menjadi penyebab utama penolakan developer terhadap hook.

Bedakan rule wajib dan rule informatif

Tidak semua temuan harus memblokir commit atau merge. Misalnya, beberapa peringatan bisa dicatat sebagai warning di CI terlebih dahulu sebelum nantinya dipromosikan menjadi error.

Jaga determinisme

Hindari test flaky atau rule lint yang bergantung pada kondisi lingkungan. Jika hasil hook dan CI sering berbeda, developer akan menganggap pipeline tidak bisa dipercaya.

Dokumentasikan cara bypass yang bertanggung jawab

Ada kalanya tim perlu melewati hook untuk kondisi tertentu, misalnya debugging darurat. Jika itu dimungkinkan, beri panduan kapan boleh dilakukan dan pastikan CI tetap menjadi pengaman akhir.

Review rule secara berkala

Jika suatu rule sering menghasilkan alarm palsu dan jarang memberi nilai, lebih baik disesuaikan atau dihapus daripada dipertahankan demi kesan ketat.

Metrik DX yang layak dipantau

Jika ingin menganggap toolkit ini sebagai investasi engineering, ukur dampaknya. Tidak perlu rumit; beberapa metrik sederhana sudah cukup memberi sinyal.

  • Waktu feedback lokal: berapa lama pre-commit atau pre-push berjalan.
  • CI failure rate per kategori: format, lint, type-check, test.
  • Persentase kegagalan trivial: berapa banyak PR gagal hanya karena masalah mekanis.
  • Lead time ke merge: apakah waktu dari PR dibuka hingga merge membaik.
  • Jumlah komentar review berulang: misalnya soal formatting, naming, atau test yang hilang.
  • Retry rate CI: indikator test flaky atau pipeline tidak stabil.
  • Adopsi template PR: apakah bagian risiko dan verifikasi benar-benar terisi.

Anda tidak harus langsung punya dashboard canggih. Mulailah dari log CI, statistik PR, dan observasi reviewer selama beberapa sprint.

Kesalahan umum saat membangun toolkit tim

  • Semua rule dijalankan di pre-commit, sehingga commit menjadi lambat.
  • Mengandalkan hook tanpa CI, sehingga aturan mudah terlewati.
  • Template PR terlalu panjang, akhirnya diisi asal-asalan.
  • Checklist review duplikatif dengan lint, membuat reviewer membahas hal yang seharusnya otomatis.
  • Menambah tool tanpa ownership, sehingga konfigurasi usang dan sering salah alarm.
  • Tidak ada baseline sukses, jadi tim tidak tahu apakah workflow baru benar-benar membantu.

Contoh minimum viable toolkit untuk satu tim

Jika Anda ingin memulai minggu ini tanpa proyek besar, kombinasi minimal berikut biasanya cukup kuat:

  1. Pre-commit: format + lint untuk file yang di-stage.
  2. Commit-msg hook: validasi prefix commit sederhana.
  3. CI: full lint, full type-check, full test.
  4. PR template: ringkasan perubahan, cara verifikasi, risiko.
  5. Checklist review: keamanan, error handling, observability, performa dasar.

Dengan paket sekecil itu pun, tim biasanya sudah bisa mengurangi noise review dan mencegah banyak kegagalan yang seharusnya tertangkap lebih awal.

Penutup

Membangun thinking engineer toolkit untuk Git hook dan CI bukan soal menumpuk tool, tetapi soal mendesain alur kerja yang menempatkan validasi otomatis di tempat yang tepat. Hook lokal dipakai untuk feedback cepat, CI dipakai untuk penegakan aturan yang konsisten, dan checklist manusia dipusatkan pada keputusan yang memang butuh penilaian engineering.

Jika diterapkan bertahap, dijaga tetap cepat, dan dievaluasi dengan metrik DX yang masuk akal, toolkit ini dapat membuat review lebih fokus, pipeline lebih dipercaya, dan kualitas perubahan lebih stabil tanpa menambah birokrasi yang tidak perlu.