Claude Architect · Pelajaran

Cakupan Proyek vs Pengguna

.mcp.json yang dibagikan di VCS vs ~/.claude.json pribadi.

Pelajaran 2 dari 413 langkah

Cakupan Proyek vs Pengguna adalah pelajaran Claude Architect gratis di CoddyKit. Ini adalah pelajaran 2 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar Claude Architect, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus Claude Architect mencakup 4 pelajaran total.

Dua Tempat untuk Konfigurasi MCP

Ketika Anda menghubungkan server MCP ke Claude Code, definisi server tersebut harus berada di suatu tempat. Ada dua lingkup, dan memilih yang salah merupakan kesalahan arsitektur yang umum.

Lingkup proyek — .mcp.json di akar repositori, di-commit ke sistem kendali versi. Dibagikan kepada seluruh tim.
Lingkup pengguna — ~/.claude.json di direktori rumah Anda. Bersifat pribadi, tidak pernah dibagikan melalui VCS.

Aturan keputusannya sederhana: apakah semua orang yang mengerjakan repositori ini membutuhkan server tersebut? Jika ya, server itu termasuk lingkup proyek.

Yang Disediakan Server MCP

Sebelum menentukan lingkup, ingat kembali apa yang sebenarnya Anda bagikan. Server MCP mengekspos tiga jenis primitif:

Alat — tindakan yang dapat dipanggil model (menjalankan kueri ke basis data, membuka tiket).
Sumber daya — data dan konteks hanya-baca, seperti skema atau katalog.
Instruksi — templat yang dapat digunakan kembali.

Ketika Anda meng-commit server ke .mcp.json, setiap rekan tim langsung mendapatkan Alat, Sumber daya, dan Instruksi yang sama — permukaan kapabilitas yang dibagikan dan dapat direproduksi.

Lingkup Proyek: .mcp.json dalam VCS

Lingkup proyek adalah tempat yang tepat untuk server yang diandalkan oleh seluruh tim: server GitHub perusahaan, gerbang basis data internal, atau server sumber daya sistem desain bersama.

Karena .mcp.json di-commit, rekan tim baru cukup mengkloning repositori dan semua alat sudah tersedia — tanpa penyiapan manual dan tanpa perbedaan akibat masalah "berfungsi di mesin saya".

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Rahasia Tidak Pernah Di-commit

Berbagi konfigurasi server tidak masalah. Berbagi token adalah pelanggaran keamanan. Aturannya: rujuk rahasia melalui variabel lingkungan — jangan pernah meng-commit nilai mentahnya.

Di .mcp.json Anda menulis ${GITHUB_TOKEN}, yang diperluas dari lingkungan milik setiap pengembang saat runtime. Berkas bersama tersebut menjelaskan cara terhubung; setiap mesin menyediakan kredensialnya sendiri.

# Each developer exports their own token locally
export GITHUB_TOKEN="ghp_yourPersonalTokenHere"

# .mcp.json references it as ${GITHUB_TOKEN} — the
# literal token value is NEVER written into the repo

Lingkup Pengguna: ~/.claude.json

Lingkup pengguna berada di ~/.claude.json dan bersifat pribadi untuk Anda. Ini adalah tempat yang tepat untuk server yang milik Anda dan hanya akan mengganggu rekan tim jika dibagikan:

Server catatan pribadi / otak kedua.
Server eksperimental yang sedang Anda evaluasi.
Alat alur kerja yang terhubung ke akun pribadi Anda.

Yang terpenting, lingkup pengguna tidak dibagikan melalui VCS — rekan tim baru tidak akan pernah menerimanya.

{
  "mcpServers": {
    "my-notes": {
      "command": "node",
      "args": ["/Users/me/tools/notes-mcp/server.js"]
    }
  }
}

Model Mental: Cerminan CLAUDE.md

Pemisahan lingkup ini sama persis dengan hierarki CLAUDE.md — prinsipnya sama, berkasnya berbeda:

Tingkat proyek (./CLAUDE.md, .mcp.json) — dibagikan melalui VCS, semua orang mendapatkannya.
Tingkat pengguna (~/.claude/CLAUDE.md, ~/.claude.json) — pribadi, TIDAK dibagikan, sehingga rekan tim baru tidak memilikinya.

Logika yang sama berlaku untuk .claude/skills/ dan .claude/commands/: lingkup proyek dibagikan melalui VCS, sedangkan salinan ~/.claude/ bersifat pribadi.

Uji Orientasi

Cara paling jelas untuk menentukan lingkup adalah bertanya: "Ketika rekan tim baru mengkloning repositori ini, apakah semua ini harus langsung berfungsi?"

Ya → lingkup proyek (.mcp.json). Mereka mengkloning repositori, server sudah dikonfigurasi, dan mereka dapat produktif sejak hari pertama.
Tidak, ini milik saya → lingkup pengguna (~/.claude.json).

Tempatkan server yang penting bagi tim dalam lingkup pengguna dan Anda telah menciptakan dependensi tak terlihat: server berfungsi untuk Anda, gagal diam-diam bagi orang lain, dan tidak ada yang tahu alasannya.

Utamakan Server Komunitas daripada Server Khusus

Untuk integrasi standar — GitHub, Slack, Postgres, sistem berkas — utamakan server MCP komunitas daripada membangun server sendiri. Lebih sedikit kode yang harus dipelihara, perilakunya telah teruji dengan baik, dan server tersebut dapat dimasukkan dengan rapi ke lingkup proyek.

Simpan server khusus untuk sistem yang benar-benar eksklusif dan tidak memiliki opsi komunitas. Apa pun pilihan Anda, keputusan lingkupnya tetap sama: seluruh tim → .mcp.json; pribadi → ~/.claude.json.

Sumber Daya Bersinar dalam Lingkup Proyek

Sumber daya MCP mengekspos konteks hanya-baca — skema basis data, katalog API, atau dokumen standar pengodean. Inilah hal-hal yang ingin dibuat identik oleh tim di setiap komputer pengembang.

Masukkan server yang mengekspos skema ke .mcp.json dan Claude milik setiap rekan tim akan melihat skema resmi yang sama. Tidak ada yang menjalankan kueri berdasarkan pemahaman mental yang sudah usang, dan jawaban tetap konsisten di seluruh tim.

{
  "mcpServers": {
    "db-schema": {
      "command": "npx",
      "args": ["-y", "@acme/mcp-schema-server"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Kesalahan Terstruktur Bertahan di Kedua Lingkup

Lingkup menentukan tempat server didefinisikan, bukan seberapa tangguh server tersebut. Server MCP yang dibangun dengan baik mengembalikan kesalahan terstruktur apa pun lingkupnya: penanda isError serta errorCategory (transient / validation / business / permission), isRetryable, pesan, kueri yang dicoba, dan hasil sebagian jika ada.

Kesalahan umum seperti "Operation failed" menghambat pemulihan yang cerdas; kesalahan terstruktur memungkinkan agen mengarahkan tindakan, mencoba lagi, atau melakukan eskalasi. Rancang ini ke dalam server — manfaatnya tetap terasa baik saat dibagikan maupun digunakan secara pribadi.

{
  "isError": true,
  "errorCategory": "transient",
  "isRetryable": true,
  "message": "Upstream timeout contacting issues API",
  "attempted_query": "list_issues(repo='acme/web')",
  "partial_results": []
}

Pembagian Praktis

Penyiapan nyata menggabungkan kedua lingkup dengan rapi:

Proyek (.mcp.json, di-commit): server GitHub, gerbang basis data internal, server sumber daya skema — semua yang dibutuhkan tim untuk membangun produk ini.
Pengguna (~/.claude.json, pribadi): server catatan pribadi Anda, alat eksperimental yang sedang Anda uji.

Kedua lapisan tersebut berpadu: Claude Code memuat keduanya, memberi Anda permukaan bersama tim sekaligus tambahan pribadi — tanpa mengotori repositori atau membocorkan alat pribadi Anda kepada rekan tim.

Pemeriksaan Singkat: Memilih Lingkup

Terapkan aturan keputusan pada skenario nyata.

Jawab di pelajaran interaktif

Rangkuman: Lingkup Proyek vs Pengguna

Hal-hal penting:

Lingkup proyek = .mcp.json, di-commit ke VCS, dibagikan kepada seluruh tim. Gunakan saat semua orang membutuhkan server tersebut setelah mengkloning repositori.
Lingkup pengguna = ~/.claude.json, pribadi, TIDAK dibagikan melalui VCS. Gunakan untuk server pribadi atau eksperimental Anda.
Mencerminkan hierarki CLAUDE.md: tingkat proyek dibagikan, sedangkan tingkat pengguna bersifat pribadi dan tidak dimiliki rekan tim baru.
Jangan pernah meng-commit rahasia — rujuk rahasia melalui variabel lingkungan seperti ${GITHUB_TOKEN}.
Utamakan server komunitas untuk integrasi standar; rancang kesalahan terstruktur apa pun lingkupnya.

Aturan keputusan yang perlu diingat: apakah rekan tim baru harus mendapatkannya setelah mengkloning repositori? Ya → proyek. Milik saya → pengguna.

Gratis untuk memulai

Belajar Python dengan tutor AI — gratis

Tulis dan jalankan kode asli di browser kamu, dapatkan bantuan instan dari tutor AI 24/7, dan lanjutkan di mana kamu tinggalkan di web atau aplikasi.

Kursus: 26
Pelajaran: 104

Mulai belajar gratis Lihat kursus lengkapnya

Pertanyaan yang Sering Diajukan

Apakah pelajaran “Cakupan Proyek vs Pengguna” gratis?

Ya — teks lengkap “Cakupan Proyek vs Pengguna” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus Claude Architect, upgrade ke CoddyKit PRO. Kursus Claude Architect mencakup 4 pelajaran total.

Apa yang akan aku pelajari di “Cakupan Proyek vs Pengguna”?

.mcp.json yang dibagikan di VCS vs ~/.claude.json pribadi. Kamu berlatih Claude Architect dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.

Apakah aku perlu pengalaman untuk memulai Claude Architect?

Tidak diperlukan pengalaman sebelumnya. Claude Architect di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 2 dari 4.

Berapa lama pelajaran “Cakupan Proyek vs Pengguna” memakan waktu?

Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.

Bisakah aku menulis dan menjalankan kode dalam pelajaran Claude Architect ini?

Ya. Setiap pelajaran Claude Architect menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.

Semua pelajaran dalam kursus ini

← Kembali ke Claude Architect