BEST PRACTICES CHO CLAUDE CODE (PHẦN I)

Lời người dịch: Những best practices này hoàn toàn có thể áp dụng cho các công cụ khác như Codex (ChatGPT), GitHub Copilot, Cursor,…

Claude Code là một agentic coding environment (môi trường lập trình sử dụng AI agent). Nó có thể đọc mã nguồn, chạy các câu lệnh, chỉnh sửa file và tự động giải quyết các vấn đề. Bạn chỉ cần mô tả điều mình muốn, Claude sẽ tự tìm cách làm.

Claude sẽ tự động Explore (Nghiên cứu), Plan (Lập kế hoạch) và Implement (Triển khai) để hoàn thành công việc.

#1 Hãy cung cấp các tiêu chí đánh giá để Claude tự kiểm chứng kết quả

Tiêu chí đánh giá là những thứ mà Claude có thể đọc và đánh giá. Ví dụ: test suite (pass hết các test cases), build exit code (kết quả build), linter (kiểm tra lỗi cú pháp và định dạng), script so sánh kết quả với dữ liệu mẫu (fixture), hoặc screenshot (ảnh chụp giao diện) để so sánh với bản thiết kế.

Claude sẽ thực thi công việc, so sánh kết quả công việc với tiêu chí đánh giá, đọc kết quả đánh giá rồi tiếp tục lặp lại quá trình này cho đến khi tất cả mọi thứ đều đạt yêu cầu.

Một số cách áp dụng:

1. Cung cấp tiêu chí kiểm chứng
   • Trước: Implement a function that validates email addresses.
   • Sau: Write a validateEmail function. Example test cases: user@example.com is true, invalid is false, user@.com is false. Run the tests after implementing.
2. Kiểm chứng bằng hình ảnh
   • Trước: Make the dashboard look better.
   • Sau: [Paste screenshot] Implement this design. Take a screenshot of the result and compare it to the original. List differences and fix them.
3. Giải quyết nguyên nhân gốc rễ thay vì chỉ xử lý phần ngọn của vấn đề
   • Trước: The build is failing.
   • Sau: The build fails with this error: [paste error]. Fix it and verify the build succeeds. Address the root cause, don't suppress the error.

#2 Explore (Nghiên cứu) trước, sau đó Plan (Lập kế hoạch) rồi mới Implement (Triển khai)

Nếu để Claude bắt đầu code ngay, bạn có thể nhận về một kết quả không mong muốn. Thay vào đó, hãy sử dụng “plan mode” để yêu cầu Claude phân tích mã nguồn và tạo ra một kế hoạch triển khai chi tiết theo từng bước cụ thể trước khi triển khai.

Workflow được khuyến nghị gồm bốn bước:

1. Explore (Nghiên cứu):

   • Yêu cầu Claude đọc code để hiểu nghiệp vụ mà không thay đổi bất cứ thứ gì.
   • Ví dụ: Read /src/auth and understand how we handle sessions and login. Also look at how we manage environment variables for secrets.

2. Plan (Lập kế hoạch):

   • Yêu cầu Claude xây dựng một kế hoạch triển khai chi tiết.
   • Ví dụ: I want to add Google OAuth. What files need to change? What's the session flow? Create a plan.

3. Implement (Triển khai):

   • Thoát khỏi Plan Mode, yêu cầu Claude triển khai theo kế hoạch đã thống nhất, và đánh giá dựa trên kế hoạch đó.
   • Ví dụ: Implement the OAuth flow from your plan. Write tests for the callback handler, run the test suite and fix any failures.

4. Commit: Sau khi mọi thứ đều đạt yêu cầu, yêu cầu Claude tạo commit với nội dung rõ ràng và mở Pull Request.

   • Ví dụ: Commit with a descriptive message and open a PR.

Lưu ý:

• Plan Mode rất hữu ích, nhưng cũng làm tăng thời gian và chi phí.
• Đối với những thay đổi nhỏ, phạm vi rõ ràng như sửa lỗi chính tả, thêm một dòng log hoặc đổi tên biến thì hãy để Claude thực hiện ngay mà không cần lập kế hoạch.
• Việc lập kế hoạch đặc biệt hữu ích khi:
  • Chưa rõ nên tiếp cận bài toán theo hướng nào.
  • Thay đổi liên quan đến nhiều file.
  • Bạn chưa nắm rõ phần code cần chỉnh sửa.
• Nếu toàn bộ thay đổi có thể mô tả gói gọn trong một câu prompt thì thường không cần dùng Plan Mode.

#3 Cung cấp context (ngữ cảnh) cụ thể trong prompt

Claude có thể suy luận được rất nhiều thứ, nhưng không thể đọc được suy nghĩ của bạn. Vì vậy, hãy chỉ rõ các file liên quan, các constraints (ràng buộc cần tuân thủ) và các pattern (đoạn code mẫu) đã có trong codebase. Prompt càng cụ thể thì bạn càng ít phải chỉnh sửa kết quả sau đó.

1. Giới hạn phạm vi công việc: Hãy chỉ rõ file, scenario (tình huống cần xử lý) và testing (yêu cầu về kiểm thử).

   • Trước: Add tests for foo.py.
   • Sau: Write a test for foo.py covering the edge case where the user is logged out. Avoid mocks.

2. Chỉ ra nguồn thông tin: Hướng Claude đến đúng nơi có thể tìm được câu trả lời.

   • Trước: Why does ExecutionFactory have such a weird API?
   • Sau: Look through ExecutionFactory's git history and summarize how its API came to be.

3. Tham chiếu các pattern hiện có: Chỉ cho Claude những phần code mà bạn muốn nó học theo để tạo sự nhất quán với codebase.

   • Trước: Add a calendar widget.
   • Sau: Look at how existing widgets are implemented on the home page to understand the patterns. HotDogWidget.php is a good example. Follow the pattern to implement a new calendar widget that lets the user select a month and paginate forwards/backwards to pick a year. Build from scratch without libraries other than the ones already used in the codebase.

4. Mô tả biểu hiện của lỗi: Nêu rõ biểu hiện của lỗi, vị trí nghi ngờ và tiêu chí để xác nhận rằng lỗi đã được khắc phục.

   • Trước: Fix the login bug.
   • Sau: Users report that login fails after session timeout. Check the auth flow in src/auth/, especially token refresh. Write a failing test that reproduces the issue, then fix it.

Nguồn: https://code.claude.com/docs/en/best-practices