Tệp hướng dẫn dự án cho AI là một tệp văn bản đặt trong kho mã, nơi bạn viết sẵn những điều mà trợ lý cần biết trước khi động tay: dự án dùng công nghệ gì, phiên bản nào, chạy kiểm thử bằng lệnh gì, đặt tên theo quy ước nào và những chỗ nào không được sửa. Trợ lý đọc tệp này ở đầu mỗi phiên làm việc, nhờ vậy bạn không phải nhắc lại cùng một điều mỗi lần mở chat.
Hầu hết trợ lý viết mã và tác tử hiện nay đều hỗ trợ một dạng tệp như vậy, chỉ khác tên tệp và vị trí đặt. Bài này tập trung vào nội dung: nên viết gì, không nên viết gì, viết dài bao nhiêu và cách kiểm xem trợ lý có thật sự làm theo không. Tên tệp cụ thể của từng công cụ bạn tra trong tài liệu chính thức của bản đang dùng, vì quy ước này còn đang thay đổi.
Vì sao trợ lý cứ lặp lại những lỗi giống nhau
Nếu đã dùng trợ lý AI một thời gian trong cùng một dự án, bạn sẽ gặp cảnh quen thuộc: nó dùng thư viện gọi mạng khác với thư viện cả dự án đang dùng, đặt tên biến theo kiểu khác quy ước, viết kiểm thử bằng khuôn khổ mà dự án không cài, hoặc chạy lệnh cài gói bằng trình quản lý gói sai. Mỗi lần bạn nhắc, nó sửa ngay, nhưng sang cuộc trò chuyện mới lại mắc đúng lỗi cũ.
Nguyên nhân là trợ lý không có trí nhớ giữa các phiên, trừ những gì được đưa vào ngữ cảnh. Nó đoán quy ước từ những tệp nó tình cờ đọc được, và với dự án lớn, phần đọc được thường không đủ để đoán đúng. Tệp hướng dẫn dự án giải quyết đúng chỗ này: biến những điều bạn hay phải nhắc thành văn bản cố định mà trợ lý luôn đọc.
Một lợi ích phụ ít người để ý: tệp viết cho AI đọc cũng là tệp người mới vào nhóm đọc rất có ích. Lệnh chạy dự án, quy ước đặt tên, vùng không được đụng là đúng những gì một lập trình viên mới cần trong tuần đầu. Nhiều nhóm sau khi viết tệp cho AI mới nhận ra trước giờ họ chưa từng ghi những điều đó ra cho người.
Tên tệp và vị trí theo từng loại công cụ
Mỗi công cụ quy ước tên tệp riêng. Bảng dưới liệt kê một số tên đang được dùng phổ biến tại thời điểm viết bài để bạn nhận ra; trước khi tạo, hãy kiểm lại tài liệu của bản bạn đang dùng.
| Kiểu công cụ | Tên tệp hay gặp | Ghi chú |
|---|---|---|
| Tác tử dòng lệnh của một số hãng | CLAUDE.md, GEMINI.md đặt ở thư mục gốc | Thường đọc thêm tệp cùng tên ở thư mục con khi làm việc trong thư mục đó |
| Quy ước dùng chung giữa nhiều tác tử | AGENTS.md ở thư mục gốc | Được nhiều công cụ khác nhau chấp nhận, hợp khi nhóm dùng lẫn nhiều công cụ |
| Tiện ích trong trình soạn thảo | Tệp hướng dẫn trong thư mục cấu hình của kho, ví dụ thư mục .github | Một số tiện ích cho thêm tệp theo từng loại tệp hoặc thư mục |
| Trình soạn thảo tích hợp AI | Thư mục quy tắc riêng trong thư mục cấu hình của dự án | Thường cho chia quy tắc thành nhiều tệp nhỏ, gắn theo đường dẫn |
Nếu nhóm dùng nhiều công cụ, đừng viết bốn tệp với nội dung khác nhau. Viết một tệp chính, các tệp còn lại chỉ ghi một dòng trỏ về tệp chính hoặc là bản sao được sinh tự động. Hai bản hướng dẫn mâu thuẫn còn tệ hơn không có.
Tám mục nên có trong tệp hướng dẫn
Không cần viết hết ngay lần đầu. Bắt đầu với những mục dưới đây, mỗi mục vài dòng, bổ sung dần khi gặp lỗi lặp lại:
- Dự án là gì: một hai câu mô tả sản phẩm và người dùng, để trợ lý hiểu bối cảnh khi đặt tên hay viết thông báo lỗi.
- Công nghệ và phiên bản: ngôn ngữ, khuôn khổ, cơ sở dữ liệu, phiên bản chính. Ghi rõ phiên bản giúp trợ lý không dùng cú pháp chỉ có ở bản mới hơn môi trường chạy thật.
- Lệnh thường dùng: cài phụ thuộc, chạy dự án, chạy kiểm thử, chạy kiểm tra định dạng. Ghi đúng lệnh như bạn gõ trong cửa sổ dòng lệnh.
- Cấu trúc thư mục: thư mục nào chứa gì, đặt tệp mới ở đâu.
- Quy ước viết mã: đặt tên, xử lý lỗi, ghi nhật ký, cách viết truy vấn cơ sở dữ liệu, thư viện dùng cho từng việc.
- Vùng cấm sửa: thư mục sinh tự động, tệp di chuyển dữ liệu đã chạy, tệp cấu hình môi trường, mã của bên thứ ba được chép vào.
- Cách kiểm trước khi báo xong: chạy lệnh kiểm thử nào, lệnh kiểm định dạng nào, kết quả thế nào mới coi là đạt.
- Cách trả lời: ví dụ trả lời bằng tiếng Việt, chú thích trong mã bằng tiếng Anh, giải thích ngắn trước khi sửa.
Mục vùng cấm sửa thường được viết sau cùng nhưng lại cứu nhiều nhất. Một tác tử tự ý sửa tệp di chuyển dữ liệu đã chạy trên máy chủ thật có thể làm hỏng lần triển khai kế tiếp mà kiểm thử ở máy không phát hiện được.
Khung mẫu cho một dự án web nhỏ
Dưới đây là khung tệp hướng dẫn cho một dự án web giả định viết bằng PHP và MySQL, mỗi gạch đầu dòng tương ứng với một hai dòng trong tệp thật. Bạn thay nội dung theo dự án của mình, giữ nguyên cách viết ngắn và kiểm được.
- Dự án: trang đặt lịch cho tiệm sửa xe nhỏ, người dùng chủ yếu xem trên điện thoại (ví dụ giả định).
- Công nghệ: PHP 8.2, MySQL 8, không dùng khuôn khổ; mã chạy trên máy chủ PHP 8.2 nên không dùng cú pháp của bản mới hơn.
- Lệnh: cài phụ thuộc bằng composer install; chạy kiểm thử bằng vendor/bin/phpunit; kiểm cú pháp một tệp bằng php -l kèm đường dẫn tệp.
- Thư mục: mã xử lý nằm trong src, giao diện trong views, tệp tĩnh trong public; tệp mới đặt đúng thư mục theo loại.
- Quy ước: truy vấn luôn dùng câu lệnh chuẩn bị sẵn có tham số; lỗi ghi bằng error_log, không in ra màn hình; tên hàm viết kiểu camelCase.
- Không sửa: thư mục vendor, thư mục migrations đã chạy, tệp .env và mọi tệp trong thư mục uploads.
- Trước khi báo xong: chạy toàn bộ kiểm thử và kiểm cú pháp các tệp đã sửa; báo rõ lệnh đã chạy và kết quả.
- Trả lời: tiếng Việt, giải thích ngắn kế hoạch trước khi sửa, hỏi lại khi yêu cầu chưa rõ.
Để ý khung mẫu không có câu nào chung chung. Mỗi dòng hoặc là một sự thật về dự án, hoặc là một việc làm được và kiểm được. Nếu một dòng bạn định viết không thuộc hai loại đó, nhiều khả năng nó không cần có trong tệp.
Viết thế nào để trợ lý làm theo
Ngắn và cụ thể hơn là dài và đầy đủ. Tệp hướng dẫn được đưa vào ngữ cảnh mỗi lần, nên tệp quá dài vừa tốn phần ngữ cảnh dành cho mã, vừa làm các chỉ dẫn quan trọng chìm giữa chữ. Phần lớn dự án vừa và nhỏ chỉ cần một đến hai trăm dòng. Chi tiết dài như toàn bộ quy trình triển khai nên để ở tệp khác và chỉ ghi đường dẫn tới đó.
Viết thành mệnh lệnh có thể kiểm được. Câu "viết mã sạch, dễ đọc" không giúp gì vì trợ lý nào cũng nghĩ mình đang làm vậy. Câu "mọi truy vấn cơ sở dữ liệu dùng tham số ràng buộc, không ghép chuỗi" thì rõ và kiểm được. Mỗi dòng nên trả lời được câu hỏi: làm sao biết trợ lý đã làm đúng.
Nêu cả lý do với những quy định lạ. Nếu dự án có quy định trái với thói quen chung, ví dụ không dùng một thư viện phổ biến vì lý do tương thích, ghi kèm lý do ngắn. Trợ lý gặp tình huống ranh giới sẽ suy luận đúng hơn khi biết vì sao.
Không bao giờ ghi bí mật vào tệp. Tệp hướng dẫn nằm trong kho mã và được gửi tới máy chủ của hãng mỗi phiên. Không ghi mật khẩu, khoá API, địa chỉ máy chủ nội bộ nhạy cảm hay tên khách hàng. Nếu cần nói về cấu hình, ghi tên biến môi trường, không ghi giá trị.
Dùng ví dụ ngắn thay cho mô tả dài. Một dòng ví dụ tên hàm đúng quy ước, hoặc đường dẫn tới một tệp mẫu mà nhóm coi là chuẩn, thường hiệu quả hơn một đoạn văn mô tả quy ước.
Kiểm xem trợ lý có đọc và làm theo không
Viết xong mà không kiểm thì bạn không biết tệp có tác dụng hay không. Cách kiểm nhanh trong mười phút:
- Mở một phiên mới, hỏi trợ lý: theo hướng dẫn của dự án, lệnh chạy kiểm thử là gì và thư mục nào không được sửa. Câu trả lời phải khớp với tệp.
- Giao một việc nhỏ có dính tới quy ước, ví dụ thêm một hàm truy vấn dữ liệu, rồi xem nó có dùng đúng thư viện và đúng cách đặt tên không.
- Giao một việc cố tình chạm vùng cấm, ví dụ nhờ sửa một tệp trong thư mục sinh tự động, xem trợ lý có từ chối hoặc cảnh báo không.
- Nếu trợ lý làm sai, đọc lại dòng hướng dẫn liên quan, viết lại cho cụ thể hơn, rồi thử lại trong phiên mới.
- Ghi lại các câu kiểm này vào một tệp nhỏ để chạy lại mỗi khi sửa tệp hướng dẫn hoặc đổi công cụ.
Cần nhớ tệp hướng dẫn là lời dặn chứ không phải hàng rào. Trợ lý có thể bỏ qua chỉ dẫn khi ngữ cảnh quá dài hoặc khi yêu cầu của bạn mâu thuẫn với nó. Những gì bắt buộc phải đúng, như không đẩy mã chưa qua kiểm thử, cần được chặn bằng công cụ thật: kiểm tra tự động trong quy trình tích hợp và quyền trên kho mã.
Giữ tệp hướng dẫn sống cùng kho mã
Tệp hướng dẫn viết một lần rồi bỏ đó sẽ lỗi thời sau vài tháng: dự án nâng phiên bản khuôn khổ, đổi thư viện kiểm thử, thêm thư mục mới, còn tệp vẫn ghi cái cũ. Lúc đó nó còn hại hơn không có, vì trợ lý tin vào tệp và làm sai một cách tự tin.
Cách giữ tệp sống là coi nó như mã. Đưa vào git, sửa qua yêu cầu gộp mã như mọi thay đổi khác, và thêm một dòng vào danh sách kiểm khi rà soát: thay đổi này có làm tệp hướng dẫn lỗi thời không. Khi ai đó trong nhóm phải nhắc trợ lý cùng một điều lần thứ hai, đó là tín hiệu nên thêm một dòng vào tệp.
Định kỳ vài tháng một lần, đọc lại toàn bộ tệp và xoá những dòng không còn cần. Tệp dài dần theo thời gian là xu hướng tự nhiên, và cắt bớt cũng quan trọng như thêm vào. Ví dụ giả định: một nhóm năm người ghi trong tệp quy tắc tạm về một lỗi của thư viện cũ; nửa năm sau thư viện đã sửa lỗi nhưng quy tắc vẫn nằm đó, khiến trợ lý tiếp tục viết đoạn mã vòng tránh không còn cần thiết.
Câu hỏi thường gặp
Tệp hướng dẫn dự án cho AI nên dài bao nhiêu?
Phần lớn dự án vừa và nhỏ chỉ cần khoảng một đến hai trăm dòng. Tệp quá dài tốn phần ngữ cảnh dành cho mã và làm chỉ dẫn quan trọng bị chìm. Chi tiết dài nên tách ra tệp khác, trong tệp hướng dẫn chỉ ghi đường dẫn tới đó.
Nhóm dùng nhiều công cụ AI khác nhau thì viết mấy tệp?
Viết một tệp chính chứa toàn bộ nội dung. Các tệp theo tên riêng của từng công cụ chỉ trỏ về tệp chính hoặc là bản sao được sinh tự động. Duy trì nhiều bản với nội dung khác nhau sớm muộn sẽ mâu thuẫn và làm trợ lý lúng túng.
Có nên viết tệp hướng dẫn bằng tiếng Việt không?
Được, các mô hình lớn hiện nay đọc tiếng Việt tốt. Nhiều nhóm viết phần mô tả bằng tiếng Việt cho cả nhóm dễ đọc, còn tên lệnh, tên thư mục, tên thư viện giữ nguyên như trong mã. Điều quan trọng là viết cụ thể và kiểm được, không phải ngôn ngữ.
Tệp hướng dẫn có đảm bảo AI không sửa những chỗ bị cấm không?
Không. Tệp hướng dẫn là lời dặn, trợ lý vẫn có thể bỏ qua khi ngữ cảnh dài hoặc yêu cầu mâu thuẫn. Những điều bắt buộc cần được chặn bằng công cụ thật như quyền trên kho mã, kiểm tra tự động trước khi gộp và quyền hạn của tác tử trên máy.
Có được ghi địa chỉ máy chủ và mật khẩu vào tệp hướng dẫn cho tiện không?
Không nên. Tệp nằm trong kho mã và được gửi tới máy chủ của hãng mỗi phiên làm việc. Chỉ ghi tên biến môi trường cần có, không ghi giá trị; giá trị thật để trong tệp cấu hình môi trường đã được loại khỏi git.
Bao lâu nên rà lại tệp hướng dẫn một lần?
Sửa ngay khi dự án đổi công nghệ, đổi lệnh hay đổi quy ước, và rà toàn bộ vài tháng một lần để xoá dòng không còn cần. Mỗi khi phải nhắc trợ lý cùng một điều lần thứ hai cũng là lúc nên thêm một dòng vào tệp.