Menyiapkan Lingkungan Pengembangan Claude Code yang Aman dan Dapat Diulang

Laptop baru atau repositori yang baru di-clone seharusnya tidak menghabiskan setengah hari sebelum commit pertama yang berguna. Polanya sering sama: versi Node.js berbeda, npm dan pnpm tercampur, .env sudah usang, volume Docker masih membawa skema lama, dan langkah lokal tidak tertulis. Claude Code bisa mempercepat pekerjaan ini, tetapi hanya aman jika batasnya dibuat sejak awal.

Tujuannya bukan meminta agen melakukan semua hal tanpa kontrol. Tujuannya adalah lingkungan yang bisa diulang: setiap pengembang dan setiap sesi Claude Code membaca instruksi yang sama, memakai pengelola paket yang sama, mengikuti aturan rahasia yang sama, dan menjalankan perintah verifikasi yang sama.

Gunakan dokumentasi resmi sebagai acuan: setup Claude Code, settings, permissions, dan hooks. Di ClaudeCodeLab, lanjutkan dengan panduan mulai, praktik terbaik CLAUDE.md, dan panduan hooks.

flowchart TD
  A["Cek alat lokal"] --> B["Kunci Node dan pengelola paket"]
  B --> C["Buat dependency dan .env.example"]
  C --> D["Simpan aturan di CLAUDE.md"]
  D --> E["Batasi permission di settings.json"]
  E --> F["Blokir command berbahaya dengan hooks"]
  F --> G["Jalankan doctor, env check, dan test"]

Kebijakan awal

Perlakukan lingkungan pengembangan seperti kode produksi. Jika aturan penting, simpan di repositori. Jika rahasia penting, jangan masukkan ke konteks agen. Jika perintah bisa menghapus data atau memublikasikan kode, minta persetujuan manusia.

Area	File atau command	Alasan
Runtime	.nvmrc, packageManager, Corepack	Mencegah drift Node dan pnpm
Rahasia	.env.example, .gitignore, permissions.deny	Menjaga kredensial asli keluar dari prompt dan commit
Memori proyek	CLAUDE.md	Memuat aturan yang sama di setiap sesi
Izin	.claude/settings.json	Mengontrol baca, Bash, dan mode default
Hooks	.claude/hooks/*	Menjalankan guardrail deterministik
Verifikasi	doctor, check:env, test	Mengganti dugaan dengan output perintah

Bootstrap siap pakai

Skrip ini untuk Git Bash, WSL, macOS, atau Linux. Ia membuat proyek TypeScript minimal, memvalidasi variabel lingkungan, mengunci pnpm, menolak pembacaan rahasia, dan menambahkan hook PreToolUse.

#!/usr/bin/env bash
set -euo pipefail

APP_DIR="${1:-claude-dev-lab}"
mkdir -p "$APP_DIR"
cd "$APP_DIR"

command -v node >/dev/null || { echo "Node.js diperlukan"; exit 1; }
command -v claude >/dev/null || { echo "Claude Code CLI diperlukan"; exit 1; }

corepack enable
corepack prepare [email protected] --activate

cat > package.json <<'JSON'
{
  "name": "claude-dev-lab",
  "private": true,
  "type": "module",
  "packageManager": "[email protected]",
  "scripts": {
    "doctor": "node --version && pnpm --version && claude --version",
    "check:env": "tsx src/env.ts",
    "test": "vitest run --passWithNoTests"
  },
  "dependencies": {
    "dotenv": "latest",
    "zod": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "tsx": "latest",
    "typescript": "latest",
    "vitest": "latest"
  }
}
JSON

mkdir -p src .claude/hooks .vscode
printf "22\n" > .nvmrc
cat > .gitignore <<'EOF'
node_modules
.env
.env.*
!.env.example
dist
coverage
EOF

cat > .env.example <<'EOF'
NODE_ENV=development
DATABASE_URL=postgresql://app:app@localhost:5432/app
REDIS_URL=redis://localhost:6379
EOF

cat > src/env.ts <<'TS'
import { config } from "dotenv";
import { z } from "zod";

config();

const Env = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url().optional()
});

const parsed = Env.safeParse(process.env);
if (!parsed.success) {
  console.error(parsed.error.flatten().fieldErrors);
  process.exit(1);
}

console.log("env ok", {
  nodeEnv: parsed.data.NODE_ENV,
  hasRedis: Boolean(parsed.data.REDIS_URL)
});
TS

cat > CLAUDE.md <<'EOF'
# Instruksi proyek

## Setup lingkungan
- Gunakan versi Node dari `.nvmrc`.
- Gunakan pnpm melalui Corepack. Jangan pindah ke npm atau yarn.
- Salin `.env.example` menjadi `.env` di lokal, lalu isi nilainya secara manual.
- Jangan pernah membaca, mencetak, atau commit `.env` dan file rahasia.
- Sebelum mengubah kode, jalankan `pnpm run doctor` dan `pnpm run check:env`.
- Setelah mengubah kode, jalankan test paling sempit yang relevan dan catat hasilnya.

## Aturan kerja
- Mulai dengan eksplorasi dan rencana singkat.
- Jangan jalankan perintah destruktif atau deploy tanpa persetujuan manusia yang jelas.
- Simpan perubahan setup di file yang dapat diulang, bukan hanya di riwayat terminal.
EOF

cat > .claude/hooks/block-dangerous.mjs <<'JS'
import { readFileSync } from "node:fs";

const input = JSON.parse(readFileSync(0, "utf8") || "{}");
const command = String(input.tool_input?.command ?? "");

const blockedPatterns = [
  /rm\s+-rf\s+(\/|~|\$HOME)/,
  /git\s+push\b/,
  /curl\b.+\|\s*(bash|sh)/,
  /Invoke-WebRequest\b.+\|\s*iex/i
];

if (blockedPatterns.some((pattern) => pattern.test(command))) {
  console.log(JSON.stringify({
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Perintah berbahaya diblokir. Tujuan dan dampaknya harus dicek manusia."
    }
  }));
} else {
  console.log("{}");
}
JS

cat > .claude/settings.json <<'JSON'
{
  "defaultMode": "plan",
  "permissions": {
    "allow": [
      "Read",
      "Bash(pnpm install)",
      "Bash(pnpm run *)",
      "Bash(git status *)",
      "Bash(claude --version)",
      "Bash(claude doctor)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push *)",
      "Bash(rm -rf *)"
    ]
  },
  "env": {
    "CLAUDE_CODE_SUBPROCESS_ENV_SCRUB": "1"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/block-dangerous.mjs"
          }
        ]
      }
    ]
  }
}
JSON

pnpm install
cp .env.example .env
pnpm run doctor
pnpm run check:env
pnpm test

Di Windows native, cek rangkaian alat lebih dulu:

winget install Anthropic.ClaudeCode
claude --version
claude doctor
node --version
corepack enable
pnpm --version

Jika pnpm --version gagal, benahi Node dan Corepack sebelum menyentuh proyek. Jika claude doctor melaporkan proxy, sertifikat, atau login, simpan error persisnya dan minta Claude Code mendiagnosis dengan batasan itu.

Prompt yang lebih aman

claude -p "
Audit dan lengkapi setup lingkungan pengembangan untuk repositori ini.

Aturan:
- Jangan baca .env, .env.*, atau file di bawah secrets/
- Ikuti packageManager; jangan ganti pnpm ke npm atau yarn
- Jangan hapus Docker volume dan jangan jalankan git push

Boleh:
- Baca README, package.json, CLAUDE.md, dan .claude/settings.json
- Jalankan pnpm install, pnpm run doctor, pnpm run check:env, dan pnpm test

Kembalikan laporan singkat berisi perintah yang dijalankan, file yang diubah, kegagalan, dan langkah manual tersisa.
"

Use case konkret

Kasus penggunaan	Cara memakai
Prototipe SaaS baru	Tambahkan PostgreSQL dan Redis lewat Docker Compose tanpa kehilangan kemampuan pengulangan
Onboarding repository tim	Claude Code membaca dokumen, menjalankan check yang diizinkan, dan melengkapi langkah yang hilang
Situs konten atau produk	Lindungi CTA, event analytics, OGP, dan halaman sensitif untuk AdSense
Alat internal	Standarkan seed database, queue, mock, dan perintah test

Untuk proyek yang banyak memakai Docker, lanjutkan ke Docker Compose. Untuk kerja tim, baca kolaborasi Claude Code. Untuk CI, sambungkan perintah ini ke setup CI/CD.

Kegagalan umum

Jangan campur pengelola paket. Jika ada pnpm-lock.yaml, jangan biarkan agen menjalankan npm install. Tulis aturan itu di CLAUDE.md dan pertahankan packageManager di package.json.

Jangan biarkan Claude Code membaca .env. File yang boleh ditinjau adalah .env.example; nilai asli tetap lokal. Gunakan .gitignore dan permissions.deny bersama.

Volume Docker juga berisiko. Volume lama bisa membuat migration yang benar terlihat gagal. Sebelum menghapus, minta penjelasan target, risiko, dan alternatifnya.

Hindari bypassPermissions di mesin utama. Gunakan hanya di container atau VM yang terisolasi. Untuk repositori yang tidak tepercaya, baca hooks sebelum memulai sesi.

Checklist kemampuan pengulangan

• claude --version dan claude doctor berhasil
• Ada .nvmrc atau .node-version
• package.json berisi packageManager
• Hanya ada satu lockfile
• .env.example terbaru dan .env diabaikan
• CLAUDE.md menjelaskan setup, larangan, dan command verifikasi
• .claude/settings.json memblokir rahasia, git push, dan perintah destruktif
• Laporan akhir berisi perintah dan hasil

CTA dan hasil

Lingkungan lokal yang tidak stabil bisa merusak tautan pembelian, formulir, analytics, atau halaman iklan. Untuk menjadikan alur ini sistem yang bisa diulang, mulai dari cheat sheet gratis, lihat produk, atau bawa ke tim melalui training.

Saya mencoba alur ini dengan membuat proyek minimal, menginstal dependensi, menyalin .env.example, lalu menjalankan pnpm run doctor, pnpm run check:env, dan pnpm test. Guardrail yang paling berguna adalah larangan membaca .env serta hook yang memblokir git push atau perintah destruktif. Dalam praktik Masa, kegagalan setup lebih sering berasal dari asumsi yang tidak ditulis daripada perintah yang sulit.