Claude Code cho monorepo và codebase lớn: 6 thiết lập nên làm

Claude Code chạy tốt ở mọi kích cỡ codebase, nhưng các mặc định vốn hợp với dự án nhỏ sẽ bắt đầu "phản tác dụng" khi repo lớn lên: một CLAUDE.md gốc phình ra cho mọi hệ con, Claude đọc cả code sinh tự động, worktree mới mất cả phút để checkout. Kết quả là tốn token và chất lượng giảm. Tài liệu chính thức có hẳn một hướng dẫn cho monorepo; đây là các thiết lập đáng làm nhất.

Bắt đầu từ đâu?

Việc chỉ trong một package thì mở Claude từ package đó: ít ngữ cảnh thừa nhất.

Sáu thiết lập chính

1. CLAUDE.md theo tầng: file gốc chứa quy tắc chung (chuẩn commit, cách chạy script), mỗi package một file riêng cho stack của nó. Chủ của từng thư mục duy trì file của mình.
2. claudeMdExcludes: bỏ qua CLAUDE.md của package bạn không bao giờ đụng tới, ví dụ "**/packages/legacy-*/**".
3. Chặn đọc code sinh tự động và vendor:

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

4. Plugin code intelligence: cho Claude tra định nghĩa và nơi gọi qua language server thay vì grep cả cây, ví dụ /plugin install typescript-lsp@claude-plugins-official.
5. worktree.sparsePaths: worktree chỉ checkout các thư mục cần (kèm file ở gốc); thêm symlinkDirectories: ["node_modules"] để khỏi nhân bản thư viện.
6. Skill theo package: mỗi package có .claude/skills/ riêng (cách test, quy ước component), chỉ nạp khi liên quan.

Làm việc qua nhiều package

• additionalDirectories trong settings hoặc claude --add-dir ../shared cho phép đọc/sửa package anh em.
• Thư mục thêm qua additionalDirectories không nạp CLAUDE.md và skill; qua --add-dir thì nạp skill, còn CLAUDE.md cần biến CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1.
• Thay đổi lan qua nhiều package: giao trọn trong một phiên và làm plan mode trước; kế hoạch được nạp lại sau mỗi lần compact.

Rủi ro và lưu ý

• Settings không kế thừa như CLAUDE.md: .claude/settings.json của thư mục cha không áp cho phiên mở từ thư mục con; mỗi package cần file tự đủ.
• Deny rule không chặn mọi đường đọc: grep -r trong Bash vẫn có thể in nội dung file bị chặn.
• Quá nhiều skill: khi danh sách dài, một số skill bị cắt mô tả; viết mô tả ngắn, bắt đầu bằng từ khoá người dùng hay gõ.
• Rà lại sau mỗi model mới: quy tắc lách giới hạn model cũ có thể thành thừa.

Áp dụng thế nào?

• Dev: Mở Claude từ package đang làm; chạy /context xem mục Memory files để chắc chỉ nạp đúng file.
• Tech Lead: Commit deny rule cho dist/build/vendor và cấu hình sparsePaths; review CLAUDE.md trong PR như tài liệu.
• PM: Khi quy ước bắt đầu trôi giữa các team, cân nhắc gom chúng thành plugin nội bộ có version.