Best practices Claude Code: 21 nguyên tắc cần nắm

Nếu bạn đang dùng Claude Code như một chatbot để hỏi đáp linh tinh, bạn đang lãng phí một nửa sức mạnh của nó. Claude Code không phải là chatbot; nó là một môi trường lập trình tác nhân (agentic coding environment) vận hành theo chu kỳ tự chủ. Để thực sự làm chủ công cụ này, bạn phải nắm vững các best practices Claude Code nhằm điều phối tác nhân thay vì chỉ yêu cầu nó viết code hộ. Đừng bao giờ quên: Context là tài nguyên đắt đỏ nhất và sự can thiệp của con người thường là mắt xích yếu nhất trong chu trình an toàn.

Muốn Claude Code cho ra kết quả tử tế, bạn phải đổi tư duy: từ "cầm tay chỉ việc" sang thiết lập ràng buộc và tiêu chuẩn để tác nhân tự thực thi. Kỹ sư kỳ cựu không ngồi xem agent gõ từng dòng lệnh. Họ dựng một hệ thống tự kiểm chứng, canh ngân sách chú ý của mô hình và biết chính xác lúc nào nên reset để khỏi đốt token. 21 nguyên tắc dưới đây rút ra từ tài liệu chính thức, từ khoảng 400.000 phiên làm việc mà Anthropic đã phân tích, và từ ghi chép của những người dùng công cụ này hằng ngày, chứ không phải mẹo vặt truyền miệng.

Bạn quyết định làm gì, Claude quyết định làm thế nào

Một phiên làm việc thành hay bại nằm ở chỗ phân chia lao động theo đúng chuyên môn. Dữ liệu thực nghiệm của Anthropic chỉ ra con người nên giữ 70% quyền quyết định lập kế hoạch (planning), tức xác định "cái gì" cần giải quyết, còn Claude đảm nhận 80% quyết định thực thi (execution), tức "làm thế nào". Ý nghĩa của tỷ lệ đó: chuyên môn nghiệp vụ (domain expertise) của bạn mới là đòn bẩy, không phải tốc độ gõ phím. Bạn hiểu vấn đề càng sâu, Claude làm được càng nhiều trên mỗi câu lệnh.

Có một "hệ số nhân chuyên gia" rất rõ khi điều khiển agent. Trong một phiên làm việc, người dùng trình độ chuyên gia kích hoạt trung bình 12 hành động và 3.200 từ đầu ra trên mỗi prompt, so với 5 hành động và 600 từ của người mới. Cùng một mô hình, cùng một khung chat. Khác nhau ở chỗ chỉ dẫn sắc sảo và tiêu chuẩn nghiệm thu chính xác cho phép Claude tự chủ đi sâu hơn: chạm tới nhiều file hơn và xử lý được tác vụ phức tạp hơn mà không cần bạn can thiệp từng bước.

Đừng sa đà vào chuyện chỉ cho Claude viết hàm nào, đặt tên biến ra sao. Hãy định nghĩa ràng buộc hệ thống và trạng thái đích, rồi để agent gánh phần thực thi nặng nhọc. Tôi cho rằng kỹ năng đáng giá nhất bây giờ không nằm ở tốc độ gõ code, mà ở khả năng mô tả chính xác thế nào là "hoàn thành" của một tính năng, đủ rõ để agent tự đi tới đích.

Context là tài nguyên hữu hạn, và cách quản lý nó

Context (ngữ cảnh) là tài nguyên quý và hữu hạn nhất trong lập trình tác nhân. Lý do nằm ở kiến trúc: Transformer tính quan hệ cặp (pairwise relationship) n² cho n token. Cửa sổ ngữ cảnh (context window) càng đầy, khả năng chú ý của mô hình càng bị kéo căng, và bạn gặp hiện tượng "mục nát ngữ cảnh" (context rot). Agent quên chỉ dẫn quan trọng ở đầu hội thoại, nhầm logic, đẻ ra code rác. Ngân sách chú ý (attention budget) cạn rồi.

Nên phải quản lý context thật quyết liệt. Xong một tác vụ thì gõ /clear ngay, cắt sạch những gì không còn liên quan cho tác vụ kế tiếp. Nếu công việc bắt buộc phải kéo dài, dùng lệnh /compact để tóm tắt lịch sử, chỉ giữ trạng thái file hiện tại và các quyết định kiến trúc quan trọng. Bạn đang giải phóng chỗ cho Transformer lo logic mới, thay vì bắt nó xử lý n² mối quan hệ với đống log debug cũ kỹ từ một tiếng trước.

Bật cấu hình dòng trạng thái (status line) để nhìn token tiêu hao theo thời gian thực. Đừng chờ agent "ngáo" rồi mới cuống cuồng reset. Dọn context như cách bạn refactor code: đều đặn, không tiếc tay. Một phiên sạch sẽ với 2.000 token chất lượng luôn cho kết quả tốt hơn một hội thoại "lẩu thập cẩm" 50.000 token đầy lỗi build và các vòng sửa sai.

Cái giá phải trả là bạn mất thói quen "hỏi thêm cho tiện". Reset nghĩa là gõ lại bối cảnh từ đầu, và lần nào cũng thấy phiền.

Giữ cửa sổ ngữ cảnh gọn trong phiên dài

/clear và /compact là hai cái búa. Việc khó hơn là biết mình đang ở đâu trước khi chất lượng tụt, và cái đó thì không có phím tắt. Theo dõi mức tiêu thụ bằng /usage hoặc một status line tự cấu hình, rồi can thiệp quanh ngưỡng 70% thay vì đợi output tự tố cáo. Triệu chứng của một context đã suy giảm khá dễ nhận: đề xuất lặp lại, ràng buộc bạn đặt ra một tiếng trước bị lờ đi, và những phương án bạn đã bác bỏ quay lại như ý tưởng mới tinh.

Nén cũng không phải cái hộp đen mà bạn chỉ biết đứng nhìn. /compact <chỉ dẫn> lái bản tóm tắt, nên bạn ép được nó giữ danh sách file đã sửa hoặc đúng câu lệnh test. Nén được cả một đầu hội thoại chứ không nhất thiết cả cuộc: trong menu tua lại, "Summarize from here" gói lại mọi thứ sau một checkpoint và giữ nguyên phần trước đó, còn "Summarize up to here" làm ngược lại. Tắt nén tự động thì bạn nắm quyền chọn thời điểm, và nó đáng làm khi bạn biết một bản tóm tắt sắp rơi đúng vào giữa đoạn đang rối.

Phần còn lại là dọn dẹp vặt, và nó trả công theo giờ. Giữ danh sách công cụ kết nối gọn, chỉ nạp định nghĩa tool khi cần, vì mỗi MCP server nằm không vẫn ăn context ở mọi lượt. Lệnh chạy lâu thì đẩy xuống nền bằng Ctrl+B, đừng ngồi nhìn nó cuộn. Và khi buộc phải chờ một job chậm, hãy hỏi trạng thái theo khoảng giãn dần thay vì bám liên tục: kiểm tra mỗi phút trong hai mươi phút không cho bạn thêm gì so với ba lần hỏi, mà lại nhét đầy cửa sổ bằng thứ vô nghĩa. Bám riết một tiến trình không làm nó chạy nhanh hơn.

Explore, plan, code: tách nghiên cứu khỏi thực thi

Sai lầm nghiệp dư nhất: để Claude nhảy vào edit code ngay khi vừa nhận prompt. Kết quả thường là những diff (so sánh mã cũ và mới) sai hướng, cấu trúc project bị bẻ gãy, token bay vô ích. Quy trình chuẩn của một senior phải là Explore (Khám phá) -> Plan (Lập kế hoạch) -> Implement (Thực thi) -> Commit (chốt thay đổi). Tách nghiên cứu khỏi thực thi cho bạn phê duyệt thiết kế tổng thể trước khi agent chạm vào mã nguồn, và mọi thay đổi vẫn nằm trong tầm kiểm soát.

Chế độ lập kế hoạch (plan mode) là chốt chặn rẻ nhất bạn có. Ở chế độ này Claude phân tích codebase, đọc các file liên quan và đề xuất kế hoạch hành động, không chạy bất kỳ lệnh write nào. Bạn soi kế hoạch, sửa danh sách file mục tiêu, rồi chỉ chuyển sang giai đoạn gõ code khi đã đồng ý hẳn với hướng tiếp cận. Thời gian tiết kiệm được nằm ở chỗ bạn không phải debug những sai lầm logic cơ bản.

Với một công việc phức tạp, hãy ép agent vào tư duy lập kế hoạch ngay từ lệnh CLI:

claude --permission-mode plan

Trong trạng thái đó, bạn tha hồ hỏi thăm dò kiểu "Flow auth này đang dính chặt với DB nào?" mà không sợ agent tự ý refactor lung tung. Phê duyệt kế hoạch trước khi đổ mồ hôi gõ code là cách duy nhất giữ cho hệ thống nhất quán khi làm việc với agent.

Viết prompt tự mang đủ ngữ cảnh

Chính xác ngay từ câu lệnh là cách sửa rẻ nhất bạn có. Khoanh tác vụ vào đúng file, đúng tình huống, và nói rõ bạn muốn gì ở phần test: "viết test cho foo.py phủ trường hợp người dùng đã đăng xuất, không dùng mock" đưa bạn tới chỗ mà "thêm test cho foo.py" không bao giờ tới được.

Khi câu hỏi là vì sao code lại thành ra thế này, đừng bắt Claude suy đoán. Trỏ nó tới thứ đang giữ câu trả lời: bảo nó đọc lịch sử git của một class rồi tóm tắt xem API đó hình thành ra sao, thế là câu trả lời được neo vào chuyện đã thực sự xảy ra. Còn muốn code mới đồng nhất với code cũ thì chỉ thẳng mẫu cần chép, trỏ vào một widget đã có và bảo nó làm theo, thay vì mô tả quy ước bằng trí nhớ.

Báo lỗi hiệu quả nhất khi gồm triệu chứng, vị trí khả nghi và định nghĩa thế nào là đã sửa xong. "Người dùng báo login hỏng sau khi session hết hạn, kiểm tra phần refresh token trong src/auth/, viết một test tái hiện được lỗi rồi mới sửa" chứa một giả thuyết, một phạm vi tìm kiếm và một tiêu chí nghiệm thu. "Sửa lỗi login" không chứa cái nào cả, và phần thiếu đó bạn trả bằng một vòng hỏi đáp.

Cách nạp nội dung vào cũng quan trọng ngang chữ nghĩa. Dùng @ để tham chiếu file thay vì mô tả code nằm đâu. Dán hoặc kéo thẳng ảnh vào prompt cho mọi việc liên quan tới giao diện. Đưa URL tài liệu, và cho phép sẵn những tên miền bạn dùng liên tục qua /permissions để thôi phải bấm duyệt mãi một thao tác fetch. Dữ liệu nằm sẵn trên đĩa thì đẩy thẳng vào: cat error.log | claude hơn hẳn việc dán log bằng tay.

Bạn cũng hoàn toàn có thể bảo Claude tự đi lấy thứ nó cần bằng lệnh Bash hay công cụ MCP, và tôi thấy cách này gần như luôn tốt hơn ngồi đoán trước xem nó sẽ cần gì. Prompt mơ hồ thì vẫn có chỗ đứng chứ không phải lúc nào cũng dở: "file này có gì đáng cải thiện?" là một chuyến thăm dò, và nó lôi ra những thứ bạn không biết để mà hỏi.

Luôn cho Claude một cách tự kiểm chứng kết quả

Muốn "rời mắt khỏi màn hình", bạn phải cho Claude một cơ chế tự xác nhận (verify) kết quả. Không có tiêu chí xác nhận, Claude dừng lại ở mức "trông có vẻ ổn", và bạn là người đi nhặt sạn. Vòng lặp khép kín đúng phải là: Claude làm việc -> Claude chạy test/build -> Claude đọc mã lỗi và tự sửa cho đến khi đạt yêu cầu. Bạn rời vị trí người kiểm thử, chuyển sang ghế người duyệt kết quả cuối cùng.

Xác nhận có thể là chạy test suite, kiểm tra mã lỗi build (exit code), hoặc so sánh ảnh chụp màn hình UI nếu bạn làm front-end. Ép agent "show bằng chứng" thay vì chỉ khẳng định thành công loại được phần lớn các lỗi ngớ ngẩn. Hãy tập thói quen nhét tiêu chí xác nhận vào ngay prompt đầu tiên, để agent biết phải chạy lệnh gì mà tự chấm bài của mình.

Khác biệt giữa prompt của một newbie và một senior nằm gọn trong bảng này: