Hãy ngừng dùng lệnh /init để tạo file CLAUDE.md, nếu bạn không muốn tự tay làm hỏng hiệu suất của AI agent. Sinh file cấu hình tự động là một kiểu "cargo culting" (bắt chước mù quáng): nó ngốn tài nguyên, làm nhiễu ngữ cảnh, và ở những tác vụ phức tạp thì kéo luôn độ chính xác của agent đi xuống.
File CLAUDE.md tạo tự động thường chứa đầy thông tin trùng lặp mà agent vốn đã có thể tự tìm thấy
qua package.json hoặc cấu hình hệ thống.
Nạp đống thông tin thừa này vào, bạn ép agent tiêu "ngân sách chỉ dẫn" một cách vô ích: chi phí đội lên, còn sự tập trung dành cho việc viết code thì loãng đi.
Một kỹ sư phần mềm lành nghề coi CLAUDE.md là một "bản ghi lỗi" (corrections file) tinh gọn, chỉ giữ những dữ liệu không thể đọc ra từ mã nguồn. Hiệu quả của agent tỷ lệ nghịch với độ dài của file cấu hình tĩnh.
/init thực sự tạo ra những gì — và vì sao phần lớn là thừa
Lệnh /init thường tạo ra ba thành phần: danh sách lệnh (scripts), cấu trúc thư mục và mô tả tech stack. Với các mô hình ngôn ngữ lớn (LLM) hiện đại như Sonnet 4.5 hay GPT-5.2, đây hoàn toàn là "nhiễu" chứ không phải "tín hiệu".
Nghiên cứu từ ETH Zurich (2026) cho thấy 100% file do Sonnet 4.5 tự tạo đều chứa phần tổng quan codebase — thứ agent đã tự nắm được qua bước "Explore". Chép lại các script từ package.json vào CLAUDE.md chỉ nhân đôi nguồn sự thật (source of truth): agent phải tốn thêm token suy luận để đối chiếu file cấu hình thật với file Markdown tĩnh, đẩy lượng token đầu ra tăng 16.58% mà chẳng cho kết quả tốt hơn.
Cái giá này không nằm trên lý thuyết. Một dự án dùng Next.js hay Effect thì agent tự nhận ra qua bước khám phá; ghi lại điều đó trong một file toàn cục không thêm chút giá trị nào, chỉ làm token thêm nặng.
Cách Claude dùng context: ngân sách chỉ dẫn và việc nạp toàn cục
Ngữ cảnh của agent được phân tầng: Provider → System Prompt → Developer Message (CLAUDE.md) → User Prompt. CLAUDE.md nằm ở phần System Prompt cứng — phân vùng nạp ngay khi mở phiên và không đổi được trong suốt phiên làm việc.
Mọi mô hình ngôn ngữ lớn (LLM) đều có "ngân sách chỉ dẫn" (instruction budget), giới hạn trong khoảng 300–500 chỉ dẫn. Lấp đầy ngân sách đó bằng những thông tin hiển nhiên, bạn thu hẹp luôn không gian dành cho các giai đoạn cần linh hoạt như khám phá (Exploration) và thực thi (Implementation).
CLAUDE.md còn có một nết nguy hiểm: nó "luôn được nạp" (globally loaded). Một quy tắc về React vẫn nằm trong cửa sổ ngữ cảnh ngay cả khi agent đang sửa một script SQL ở backend. Chiếm dụng không gian System Prompt một cách bừa bãi, bạn bóp dư địa cho khâu thực thi logic và kiểm thử, để rồi agent dễ "ngộp" thông tin.
Cái giá thật sự: token tăng, chất lượng giảm, tài liệu lỗi thời
Theo dữ liệu của Lulla et al. (ICSE JAWs 2026), dùng file ngữ cảnh tự động khiến tỷ lệ thành công giảm 2–3% trong khi chi phí tăng hơn 20%. Ba cơ chế nằm sau con số đó:
- Hiệu ứng "voi hồng" (Pink Elephant). Hễ CLAUDE.md nhắc đến một công nghệ cũ (chẳng hạn tRPC) như một phần kiến trúc, agent sẽ bị neo (anchoring) vào đó. Dù bạn đang viết tính năng mới bằng công nghệ khác, agent vẫn có xu hướng đề xuất tRPC, chỉ vì nó nằm trong System Prompt "cứng".
- Tài liệu mục ruỗng (documentation rot). Một file tĩnh lỗi thời ngay khoảnh khắc bạn refactor code. Lúc đó CLAUDE.md thành nguồn tin sai, dẫn thẳng agent vào những hành động hỏng.
- Hiệu ứng "lạc giữa dòng" (Lost in the Middle). Thông tin quan trọng kẹt ở giữa một file CLAUDE.md quá dài thường bị LLM lướt qua. Những quy tắc thật sự đáng giá bị chôn dưới đống mô tả kiến trúc tầm thường.
Một file CLAUDE.md tốt nên chứa gì (và không nên chứa gì)
Tiêu chí duy nhất: chỉ đưa vào những thông tin không thể tìm ra bằng cách đọc code (non-discoverable).
Hãy bỏ hết danh sách lệnh trong package.json, mô tả thư mục và style guide chung chung. Dồn chỗ cho các "bẫy" (landmines) môi trường hoặc quy ước ngầm của team. Một file CLAUDE.md tối giản theo phong cách Matt Pocock trông như sau:
# Project Rules
- You are on WSL on Windows (careful with path resolution).
- Auth module uses custom middleware; do not refactor to standard Express middleware.
- Always run tests with --no-cache to avoid false positives.Những dòng này đáng giá vì chúng xử lý đúng các vấn đề agent không thể tự suy ra dù đọc hết codebase. Muốn nắm trọn những gì nên nằm trong file, hãy xem bài CLAUDE.md best practices.
Thay vì /init: nuôi CLAUDE.md lớn lên một cách tự nhiên
Hãy nuôi file theo lối "tăng trưởng hữu cơ" (organic growth): mở đầu bằng file trống, chỉ thêm quy tắc khi agent mắc đi mắc lại một lỗi mà bạn không sửa được bằng cách dọn cấu trúc code hay thêm linter.
Tư duy của một kỹ sư cấp cao gói gọn trong ba điểm:
- Coi CLAUDE.md là "nợ kỹ thuật" (technical debt). Một quy tắc nằm trong file quá sáu tháng là dấu hiệu kiến trúc codebase đã hỏng. Hãy sửa code cho nó tự giải thích (self-documenting), đừng viết thêm chỉ dẫn.
- Dùng "lời nói dối" có chủ đích. Để tăng tốc, bạn có thể khai báo: "Dự án này là greenfield, chưa có người dùng thực." Một câu thôi mà giúp agent bỏ qua đống logic backfill dữ liệu rắc rối và dồn sức tạo schema thật nhanh.
- Phân cấp file (hierarchy). Với repo lớn, một file CLAUDE.md duy nhất ở thư mục gốc là một "code smell". Hãy tách thành nhiều file context theo từng thư mục/module, để agent chỉ nạp đúng phần cần cho phạm vi đang làm.
Các câu hỏi thường gặp
Có nên dùng /init cho dự án mới tinh không? Không. Agent thừa sức đọc package.json và cấu hình framework. Cứ để nó tự khám phá, đừng nạp sẵn những thông tin hiển nhiên chỉ tổ gây nhiễu ngay từ đầu.
Không ghi vào file thì agent biết chạy test kiểu gì? Agent có bước "Explore": nó tự đọc scripts trong package.json hoặc tìm các file .test.ts để biết cách vận hành, chẳng cần bạn chép lại vào CLAUDE.md.
"Skills" khác CLAUDE.md ở chỗ nào? CLAUDE.md thì toàn cục và cứng nhắc (hardwired). "Skills" là các chỉ dẫn nạp theo nhu cầu (on-demand). Hãy đẩy các hướng dẫn logic cụ thể sang "Skills" để dành lại ngân sách chỉ dẫn.
Vì sao file do con người viết lại tốt hơn? Vì con người chỉ ghi lại những "bẫy" và lỗi đặc thù. Ngữ cảnh nhờ vậy mà tinh gọn, agent dồn được toàn bộ tài nguyên vào việc giải quyết vấn đề thay vì đọc lại kiến trúc.