Sự cố lúc 2 giờ sáng: Khi AI Agent của bạn “nổi loạn”
Đã 2:14 sáng, và terminal của tôi đang cuộn nhanh hơn tốc độ tôi có thể đọc. Tôi yêu cầu Claude Code “sửa logic xác thực trong login controller”, nhưng nó lại đang tái cấu trúc (refactoring) toàn bộ schema cơ sở dữ liệu và đã xóa sạch 12 tệp .env.example. Nó đánh dấu chúng là “dư thừa” và quyết định rằng chúng không thuộc về repo này.
Nếu bạn đã bắt đầu sử dụng công cụ CLI mới của Anthropic là Claude Code, chắc hẳn bạn đã cảm nhận được sự pha trộn giữa kinh ngạc và kinh hoàng. Nó cực kỳ nhanh. Tuy nhiên, nếu không có “dây xích”, nó hoạt động giống như một lập trình viên thực tập vừa uống sáu ly espresso và quyết định viết lại toàn bộ codebase cũ của công ty ngay trong ngày đầu tiên đi làm.
Sau khi dọn dẹp đống lộn xộn đó, tôi nhận ra vấn đề không phải ở AI. Mà là do tôi chưa đưa cho nó một bản đồ. Bản đồ đó nằm trong thư mục .claude/. Nếu bạn không định nghĩa thư mục này, bạn đang để một AI agent chạy tự do trong repository production mà không có chút kiến thức nào về các tiêu chuẩn của nhóm bạn.
Tại sao Claude Code bị ảo giác về cấu trúc dự án của bạn
Hãy nghĩ theo cách này: khi bạn khởi chạy claude trong terminal, về cơ bản đó là một thực tập sinh tốc độ cao đang bước vào một căn phòng tối. Nó thực hiện quét sơ bộ cây thư mục và đọc package.json để đoán cách bạn làm việc.
Hầu hết các thất bại của Claude Code đều bắt nguồn từ ba lỗ hổng cụ thể:
- Thiếu hụt ngữ cảnh: Nó không biết bạn thích sử dụng functional components hơn class, hoặc bạn đang sử dụng các mô hình kiến trúc cụ thể như Clean Architecture.
- Vấn đề ranh giới: Nó cố gắng “tối ưu hóa” mã nguồn của thư viện bên thứ ba trong
node_moduleshoặc can thiệp vào các tệp build trong/dist. - Mơ hồ về quyền hạn: Nó không chắc liệu mình có được phép chạy các lệnh có tính hủy diệt như
rm -rfhoặcdocker-compose downmà không cần hỏi trước hay không.
Nếu không có cấu hình theo cấu trúc, agent sẽ mặc định sử dụng dữ liệu huấn luyện chung của nó. Dữ liệu này thường khác xa 180 độ so với các yêu cầu cụ thể của dự án của bạn.
Ba cách để kiểm soát Agent
Các lập trình viên thường cố gắng xử lý hành vi của Claude Code theo một trong ba cách. Hai trong số đó thường thất bại khi mọi thứ trở nên phức tạp.
1. Phương pháp “Prompt thủ công”
Bạn cố gắng giải thích các quy tắc trong mỗi prompt: “Sửa lỗi nhưng đừng thay đổi CSS và sử dụng thụt đầu dòng bằng Tab.” Điều này rất mệt mỏi. Nó tiêu tốn thêm khoảng 200–500 token mỗi lượt, và agent cuối cùng sẽ quên các hướng dẫn khi lịch sử trò chuyện dài lên.
2. Cấu hình toàn cục (Global Configuration)
Bạn thiết lập các alias toàn cục hoặc biến môi trường trên máy của mình. Cách này có hiệu quả với bạn, nhưng ngay khi đồng nghiệp clone repo về, sự nhất quán sẽ bị phá vỡ. Trợ lý AI của bạn sẽ hành xử khác nhau trên mỗi chiếc laptop trong văn phòng.
3. Thư mục .claude/ (Cách tiếp cận chuyên nghiệp)
Bằng cách tạo một thư mục .claude/ tại gốc của dự án, bạn thiết lập một “Nguồn chân lý” (Source of Truth) vĩnh viễn. Thư mục này nằm trong lịch sử Git của bạn. Mọi lập trình viên—và chính AI—đều tuân theo các quy tắc giống hệt nhau. Tôi đã áp dụng điều này trong các microservices production, và nó đã giảm bớt các lỗi “tái cấu trúc ảo giác” gần 90%.
Cấu trúc .claude/ lý tưởng
Để giữ cho dự án của bạn sạch sẽ và AI agent hoạt động ổn định, bạn cần một bộ tệp cụ thể. Đây là cấu trúc tôi đề xuất cho bất kỳ dự án TypeScript hoặc Python nghiêm túc nào.
my-project/
├── .claude/
│ ├── config.json
│ ├── custom_instructions.md
│ └── project_context.md
├── src/
└── ...1. Tệp config.json
Tệp này quy định hành vi kỹ thuật của CLI. Nó xác định những công cụ nào agent có thể chạm vào. Đây là cấu hình cơ bản cho một môi trường an sau:
{
"auto_execute_commands": false,
"allowed_tools": ["read_file", "write_file", "list_files", "grep_search"],
"theme": "dark",
"model": "claude-3-7-sonnet-latest"
}Đặt auto_execute_commands thành false là bước kiểm tra an toàn bắt buộc của tôi. Nó buộc Claude phải xin phép trước khi chạy bất kỳ lệnh nào có thể xóa sạch cơ sở dữ liệu hoặc push lên một nhánh (branch) được bảo vệ.
2. custom_instructions.md (Sách quy tắc)
Đây là tệp quan trọng nhất. Claude Code tự động tìm kiếm các hướng dẫn ở đây để xác định phong cách lập trình. Đừng quá lịch sự; hãy quyết liệt với các yêu cầu của bạn.
# Tiêu chuẩn lập trình của dự án
- Sử dụng TypeScript cho tất cả các tệp mới. Không cho phép kiểu `any`.
- Chúng tôi sử dụng Tailwind CSS để định dạng. Không tạo các tệp .css.
- Sử dụng `pnpm` thay vì `npm`. Không bao giờ chạy `npm install`.
- Khi sửa lỗi, luôn viết một test case Vitest trước.
- KHÔNG BAO GIỜ chỉnh sửa các tệp trong thư mục `/legacy`.3. project_context.md (Bản đồ)
Các mô hình AI thường gặp khó khăn với kiến trúc quy mô lớn. Chúng thấy các tệp riêng lẻ nhưng bỏ lỡ “Bức tranh toàn cảnh”. Hãy sử dụng tệp này để giải thích cách các phần trong dự án của bạn kết nối với nhau. Điều này tiết kiệm hàng nghìn token vì Claude không phải “tìm kiếm” kiến trúc nữa.
# Ngữ cảnh dự án
Đây là ứng dụng Next.js 14 sử dụng App Router.
## Các thư mục chính:
- `/src/lib/api`: Chứa tất cả các wrapper fetch cho backend.
- `/src/store`: Quản lý qua Zustand cho global state.
## Ghi chú kiến trúc:
Chúng tôi sử dụng kiến trúc lục giác (hexagonal architecture). Giữ logic nghiệp vụ trong `/src/core`
và mã nguồn đặc thù của framework trong `/src/infrastructure`.Thêm các biện pháp bảo vệ với .claudeignore
Giống như .gitignore, bạn phải cho Claude biết những gì nó không được phép xem. Nếu bạn có các tệp log dung lượng 500MB hoặc thông tin đăng nhập nhạy cảm, đừng để Claude quét chúng. Việc đó vừa lãng phí tiền bạc vừa tạo ra rủi ro bảo mật.
Mặc dù Claude Code tuân thủ tệp .gitignore tiêu chuẩn của bạn, tôi khuyên bạn nên thực hiện rõ ràng hơn. Nếu bạn có thư mục /temp_data không bị Git bỏ qua nhưng AI không nên đọc, hãy thêm nó vào custom_instructions.md hoặc một tệp .claudeignore riêng biệt nếu phiên bản CLI của bạn hỗ trợ.
Quy trình làm việc: Từ “trông trẻ” đến giám sát
Khi thư mục .claude/ của bạn đi vào hoạt động, quy trình làm việc hàng ngày của bạn sẽ thay đổi. Bạn ngừng sửa những lỗi cơ bản và bắt đầu quản lý kết quả đầu ra.
- Khởi tạo: Chạy
claude. Agent sẽ đọccustom_instructions.mdngay lập tức. - Giao việc: Đưa ra một lệnh cấp cao: “Thêm một trang hồ sơ người dùng mới.”
- Thực thi: Claude kiểm tra
project_context.md, thấy bạn sử dụng App Router và chọn đúng thư mục mà không cần hỏi. - Xem xét: Vì
auto_execute_commandsđang tắt, bạn xem xét kế hoạch trước khi nó tác động đến ổ đĩa của mình.
Lời kết
Thiết lập thư mục .claude/ chỉ mất khoảng 10 phút. Nó giúp bạn tiết kiệm hàng giờ gỡ lỗi cho những ảo giác do AI tạo ra sau này. Thiết lập này chuyển dịch sự “thông minh” từ một mô hình đám mây chung chung thành một trợ lý chuyên biệt thực sự hiểu rõ codebase của bạn.
Hãy commit thư mục .claude/ của bạn ngay hôm nay. Đồng nghiệp của bạn—và chính bạn lúc 2 giờ sáng trong tương lai—sẽ cảm ơn bạn khi agent tuân thủ các quy tắc thay vì cố gắng “phát minh lại bánh xe” trong khi đang sửa lỗi khẩn cấp trên production.
