ตั้งค่า Claude Code ใน Monorepo หรือ Codebase ขนาดใหญ่

กำหนดค่า Claude Code สำหรับ monorepos และ codebases ขนาดใหญ่ด้วยไฟล์ CLAUDE.md แบบซ้อนกัน, sparse worktrees, code intelligence และ skills แต่ละ package เพื่อให้ Claude โฟกัสกับโค้ดที่คุณกำลังทำงานอยู่

Codebase ขนาดใหญ่อาจเป็น repository เดียวที่มีโค้ดหลายล้านบรรทัด หรือ monorepo ที่มีหลาย packages Claude Code ทำงานได้ทุกขนาด แต่เมื่อ codebase โตขึ้น การตั้งค่าเริ่มต้นที่ออกแบบมาสำหรับโปรเจกต์เล็กๆ อาจเติมคำสั่งและการอ่านไฟล์ที่ไม่เกี่ยวข้องใน context window ทำให้เสีย tokens และลดประสิทธิภาพของ Claude

สิ่งที่คู่มือนี้ครอบคลุม

ต้องการทำอะไร	ใช้
โหลดเฉพาะ conventions สำหรับโค้ดที่แตะต้อง	ไฟล์ CLAUDE.md แต่ละ directory
ยกเว้นไฟล์ CLAUDE.md สำหรับ packages ที่ไม่ได้ทำงาน	claudeMdExcludes
บล็อก Claude ไม่ให้เปิด build output, generated code, และ dependencies	Read deny rules ใน permissions.deny
ค้นหา definition หรือ callers ผ่าน language server แทนการสแกนไฟล์	Code intelligence plugin
Checkout เฉพาะ directories ที่งานต้องการเมื่อ Claude สร้าง worktree	worktree.sparsePaths
อ่านและแก้ไข sibling package หรือ repository อื่นจาก session เดียวกัน	--add-dir หรือ additionalDirectories
ให้ Claude มีขั้นตอนเฉพาะสำหรับพื้นที่หนึ่งที่โหลดเมื่อเกี่ยวข้อง	Skills แต่ละ directory

ตัวอย่าง Monorepo

monorepo/
  CLAUDE.md                     # คำสั่ง root
  packages/
    api/
      CLAUDE.md                 # คำสั่งเฉพาะ API
      .claude/skills/
      src/
    web/
      CLAUDE.md                 # คำสั่งเฉพาะ frontend
      .claude/skills/
      src/
    shared/
      CLAUDE.md                 # คำสั่ง shared library
      src/

เลือกจุดเริ่มต้น Claude

ที่ที่คุณเปิด claude กำหนดว่าไฟล์ใดที่ Claude อ่านได้และ CLAUDE.md ใดที่โหลดเมื่อเริ่ม:

เริ่มจาก	การเข้าถึงไฟล์	CLAUDE.md ที่โหลดเมื่อเริ่ม	เหมาะสำหรับ
Repository root	ทุกไฟล์	Root เท่านั้น	งานที่ครอบคลุมหลาย packages
Subdirectory	ต้นไม้ย่อยนั้นเท่านั้น	ของ directory นั้นและทุก ancestor	งานที่อยู่ใน package เดียว

จัดชั้น CLAUDE.md ตาม Directory

ใน codebase ขนาดใหญ่ CLAUDE.md เดียวที่ root มักจะโตขึ้นเรื่อยๆ เพื่อครอบคลุม conventions ทุก subsystem ซึ่งเสีย context กับคำสั่งที่ไม่เกี่ยวข้อง การแบ่งคำสั่งตาม directory หมายความว่า Claude โหลดกฎทั้ง repository บวกกับ conventions เฉพาะโค้ดที่กำลังทำ

Root CLAUDE.md ควรมีข้อมูลเกี่ยวกับโครงสร้าง repository:

This is a monorepo with three packages under packages/:

- packages/api: Node.js REST API with Express, TypeScript, and PostgreSQL
- packages/web: React frontend with Vite, TypeScript, and TailwindCSS
- packages/shared: shared TypeScript utilities used by both api and web

Run commands from the package directory, not the monorepo root.

packages/api/CLAUDE.md เพิ่มบริบทเฉพาะ stack ของพื้นที่นั้น:

This package is the REST API server.

- Run tests: `npm test` (uses Vitest)
- Run dev server: `npm run dev` (port 3001)
- Database migrations: `npm run migrate`
- Environment variables: copy `.env.example` to `.env`

ยกเว้นไฟล์ CLAUDE.md ที่ไม่เกี่ยวข้อง

การตั้งค่า claudeMdExcludes ข้ามไฟล์เฉพาะตาม path หรือ glob pattern:

{
  "claudeMdExcludes": [
    "**/packages/admin-dashboard/**",
    "**/packages/legacy-*/**"
  ]
}

บล็อกการอ่าน Generated และ Vendored Code

สำหรับ paths ที่ checked in เช่น vendored SDK หรือ generated code:

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**)",
      "Read(./**/build/**)",
      "Read(./**/*.generated.*)",
      "Read(./vendor/**)"
    ]
  }
}

ลดการอ่านไฟล์ด้วย Code Intelligence

ใน codebase ขนาดใหญ่ การหา definition หรือการใช้ symbol อาจเสียการอ่านไฟล์จำนวนมาก Code intelligence plugins เชื่อมต่อ Claude กับ language server เพื่อ jump ไป definitions, หา references โดยตรง:

/plugin install typescript-lsp@claude-plugins-official

ตรวจสอบ Worktrees และการเข้าถึงไฟล์

Checkout เฉพาะ Directories ที่ต้องการ

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  }
}

ให้สิทธิ์เข้าถึงข้าม Packages

{
  "permissions": {
    "additionalDirectories": [
      "../shared",
      "../web"
    ]
  }
}

หรือใช้ --add-dir เมื่อเริ่ม Claude:

claude --add-dir ../shared

เพิ่ม Skills แต่ละ Directory

Skills ใน directory ย่อยโหลดตามความต้องการ สร้าง skill directory ภายใน subdirectory:

mkdir -p packages/api/.claude/skills/api-testing

จากนั้นเขียน SKILL.md:

---
name: api-testing
description: Testing patterns for the API package. Use when writing or modifying tests in packages/api/.
---

## Test structure

Tests are in `src/__tests__/` mirroring the `src/` directory structure.

## Running tests

- All tests: `npm test`
- Single file: `npm test -- src/__tests__/routes/users.test.ts`

การกำหนดค่ารวม

ตัวอย่าง packages/api/.claude/settings.json ที่รวมทุกอย่าง:

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  },
  "permissions": {
    "additionalDirectories": [
      "../shared"
    ],
    "deny": [
      "Read(./**/dist/**)",
      "Read(./**/build/**)"
    ]
  }
}

ด้วยการตั้งค่านี้ การเริ่ม Claude จาก packages/api/:

• โหลด root CLAUDE.md และ packages/api/CLAUDE.md ข้าม packages/web/CLAUDE.md
• สามารถอ่านและแก้ไขไฟล์ใน packages/api/ และ packages/shared/
• ข้ามการอ่าน build output ใต้ dist/ และ build/
• มี api-testing skill พร้อมใช้ตามความต้องการ