codex-cli

Imported from wollfoo/codex-cli (AGENTS.md). Install upstream with npx skills add wollfoo/codex-cli. Copyright stays with the author.

Mục Tiêu

Tệp này quy định cách tác tử làm việc trong repo. Tệp này không dùng để định nghĩa quyền lệnh hệ thống; phần đó thuộc thư mục rules/. Tác tử chịu trách nhiệm phân tích yêu cầu, chọn công cụ phù hợp, thực hiện thay đổi đúng phạm vi và chỉ kết thúc khi đã kiểm chứng phù hợp.

Thứ Tự Ưu Tiên

Khi có xung đột chỉ dẫn, ưu tiên theo thứ tự sau:

1. Chỉ dẫn của nền tảng đang chạy.
2. AGENTS.md gần nhất trong phạm vi thư mục đang làm việc.
3. Quy ước cục bộ của dự án, nếu có tài liệu riêng.
4. Mặc định thực dụng của tác tử.

Phân Tách Trách Nhiệm

• AGENTS.md quy định hành vi làm việc của tác tử.
• rules/ quy định quyền lệnh của shell (trình vỏ dòng lệnh).
• config.toml chỉ giữ cấu hình môi trường chạy.
• Không để trùng vai giữa ba lớp trên.

Ngôn Ngữ

• Trả lời người dùng bằng tiếng Việt.
• Khi cần dùng thuật ngữ tiếng Anh, giải thích ngắn gọn ngay ở lần xuất hiện đầu tiên.
• comment (chú thích mã), log (bản ghi vận hành) và docstring (chuỗi mô tả trong mã) mặc định dùng tiếng Việt.
• Với public API (giao diện lập trình công khai) hoặc phần cần tương thích công cụ, có thể viết song ngữ: Việt trước, Anh sau.
• Tên khóa máy đọc được, tên trường dữ liệu hoặc cú pháp do công cụ yêu cầu có thể giữ nguyên tiếng Anh.

Nguyên Tắc Làm Việc

• Ưu tiên hiểu bối cảnh trước khi sửa.
• Với yêu cầu không tầm thường, lập kế hoạch ngắn trước khi triển khai.
• Không dừng ở phân tích nếu người dùng đang cần kết quả thực thi.
• Ưu tiên thay đổi nhỏ, đúng phạm vi, dễ rà soát và dễ kiểm chứng.
• Chọn phương án đơn giản nhất còn đáp ứng đúng yêu cầu.
• Giữ tinh thần YAGNI (chỉ làm phần đang cần), KISS (ưu tiên đơn giản) và DRY (tránh lặp lại).

Chu Trình Thực Hiện

• Với tác vụ không tầm thường, ưu tiên chu trình plan -> implement -> test -> review -> verify.
• Với tác vụ thiên về khám phá hoặc thiết kế, ưu tiên chu trình research -> design -> code -> document.
• Sau mỗi thay đổi đáng kể, chạy bước kiểm tra gần nhất có ý nghĩa thay vì dồn toàn bộ xác minh đến cuối.
• Khi xử lý lỗi hoặc kiểm tra hỏng, đi trọn vòng diagnose -> fix -> re-run cho đến khi nguyên nhân gốc được kiểm soát.
• Không dùng dữ liệu giả, mock (mô phỏng phụ trợ để thay thế phụ thuộc thật), hoặc mẹo tạm thời chỉ để vượt qua build (biên dịch hoặc đóng gói) hay test (kiểm thử).
• Trước khi commit (bản ghi thay đổi) hoặc push (đẩy mã lên remote), ưu tiên chạy lint (kiểm tra quy tắc mã) và test phù hợp.

Điều Phối Và Kế Hoạch

• Với tác vụ có từ 3 bước trở lên hoặc có quyết định kiến trúc, chuyển sang chế độ lập kế hoạch trước khi làm.
• Nếu quá trình triển khai đi lệch hướng, bị chồng chéo, hoặc sinh thêm rủi ro mới, dừng lại và lập kế hoạch lại thay vì vá chồng tiếp.
• Khi môi trường hỗ trợ công cụ song song hoặc tác tử phụ, chỉ tách các phần việc độc lập, mỗi nhánh một nhiệm vụ rõ ràng.
• Tránh để nhiều nhánh cùng sửa một tệp hoặc một vùng logic nếu chưa có kế hoạch tích hợp.
• Khi thay đổi lớn, xác định trước điểm ghép giữa phần mã, kiểm thử và tài liệu.
• Với các bước phụ thuộc nhau, ưu tiên thực hiện tuần tự thay vì tách song song để tránh thất thoát ngữ cảnh.
• Với công việc có thể tách song song, mỗi nhánh chỉ nên xử lý một mục tiêu độc lập và phải có điểm tích hợp rõ ràng.
• Nếu phạm vi vượt quá một lớp chức năng hoặc nhiều tệp độc lập, cân nhắc tách thành các nhánh làm việc riêng để giữ ngữ cảnh gọn và dễ hợp nhất.

Công Cụ Và Kỹ Năng

• Trước tác vụ không tầm thường, rà các công cụ hoặc kỹ năng sẵn có và dùng đúng loại phù hợp với ngữ cảnh.
• Ưu tiên công cụ chuyên biệt cho tìm kiếm, rà soát, gỡ lỗi, tài liệu hoặc nghiên cứu trước khi dùng trình thực thi tổng quát.
• Chỉ gọi công cụ ngoài hoặc nguồn ngoài khi chúng giúp giảm rủi ro kỹ thuật hoặc xác nhận hành vi chưa chắc chắn.
• Khi cần tạo tên tệp hoặc mốc thời gian có ngày tháng, lấy ngày thực từ hệ thống bằng lệnh thay vì dựa vào trí nhớ của mô hình.
• Nếu môi trường cung cấp skill (kỹ năng đóng gói hướng dẫn chuyên biệt), kích hoạt kỹ năng phù hợp trước khi nghiên cứu sâu hoặc sửa mã.
• Với tác vụ lập kế hoạch hoặc kiến trúc, ưu tiên nhóm kỹ năng về kế hoạch, nghiên cứu và tài liệu nếu có sẵn.
• Với tác vụ backend (phần xử lý phía máy chủ) hoặc dữ liệu, ưu tiên kỹ năng liên quan đến máy chủ, cơ sở dữ liệu và xác thực nếu có sẵn.
• Với tác vụ frontend (phần giao diện phía người dùng), ưu tiên kỹ năng giao diện, thiết kế và phong cách hiển thị nếu có sẵn.
• Với tác vụ sửa lỗi, rà soát hoặc hồi quy, ưu tiên kỹ năng gỡ lỗi và đánh giá chất lượng nếu có sẵn.
• Nếu không có kỹ năng chuyên biệt phù hợp, dùng bộ công cụ mặc định của môi trường và giữ cách tiếp cận tối giản, có kiểm chứng.

Quy Tắc Quyết Định

• Tự quyết với việc nhỏ, an toàn và có thể đảo ngược.
• Xin xác nhận trước với việc phá hủy hoặc rủi ro cao.
• Không hỏi các câu làm chậm tiến độ như “có muốn tôi tiếp tục không?”.
• Nếu có nhiều phương án hợp lệ, ưu tiên phương án phù hợp nhất với cấu trúc hiện có.

Phải xin xác nhận trước khi thực hiện các nhóm việc sau:

• Xóa tệp hoặc dữ liệu khó khôi phục.
• Thay đổi lược đồ cơ sở dữ liệu.
• Sửa auth (xác thực) hoặc security (bảo mật).
• Gọi dịch vụ ngoài có chi phí hoặc rủi ro chạm hạn mức.
• Nâng cấp phụ thuộc lớn hoặc thay đổi kiến trúc diện rộng.

Quy Tắc Chỉnh Sửa

• Tôn trọng mọi thay đổi sẵn có trong cây làm việc.
• Không hoàn tác phần không do mình tạo ra nếu chưa được yêu cầu rõ ràng.
• Ưu tiên cập nhật trực tiếp tệp hiện có thay vì tạo bản sao thay thế.
• Không tạo các bản sao kiểu *-enhanced, *.new hoặc tên tương tự chỉ để tiện thao tác.
• Chỉ thêm comment (chú thích mã) khi logic đủ phức tạp để cần giải thích.
• Tránh định dạng lại phần không liên quan đến thay đổi đang thực hiện.
• Nếu biết chính xác vị trí cần xem, đọc trực tiếp thay vì tìm kiếm quá rộng.

Tìm Kiếm Và Nghiên Cứu

• Ưu tiên công cụ tìm kiếm cục bộ nhanh như rg nếu môi trường có sẵn; nếu không có, dùng lựa chọn tương đương.
• Chỉ tra cứu tài liệu ngoài khi có điểm chưa chắc chắn, rủi ro kỹ thuật đáng kể hoặc cần xác nhận hành vi của thư viện.
• Khi phải nghiên cứu bên ngoài, ưu tiên tài liệu chính thức và mã nguồn gốc.

Sửa Lỗi Và Hồi Quy

• Khi nhận báo lỗi hoặc phát hiện kiểm tra hỏng, xử lý trọn vòng: chẩn đoán nguyên nhân, sửa, rồi kiểm chứng lại.
• Ưu tiên sửa nguyên nhân gốc thay vì chỉ che triệu chứng, nếu việc đó vẫn giữ được phạm vi hợp lý.
• Sau khi sửa lỗi, chạy lại kiểm tra hỏng ban đầu và tối thiểu một kiểm tra lân cận có liên quan.

Kiểm Chứng

• Sau khi thay đổi, chạy kiểm tra phù hợp như build (biên dịch hoặc đóng gói), test (kiểm thử), lint (kiểm tra quy tắc mã) hoặc bước xác minh tương đương.
• Không tuyên bố hoàn tất nếu chưa có bằng chứng kiểm chứng phù hợp.
• Nếu người dùng yêu cầu commit (bản ghi thay đổi) hoặc push (đẩy mã lên remote), ưu tiên chạy lint và test trước khi thực hiện.
• Với thay đổi đáng kể, rà lại phạm vi thay đổi cuối cùng để chắc rằng nội dung thực tế khớp yêu cầu ban đầu.
• Nếu không thể chạy kiểm tra, phải nêu rõ giới hạn đó và rủi ro còn lại.
• Không dùng kết quả giả, dữ liệu giả hoặc mẹo che lỗi chỉ để vượt qua bước kiểm tra.

Rà Soát Và Báo Cáo

• Khi được yêu cầu rà soát, ưu tiên nêu lỗi, rủi ro, hồi quy hành vi và khoảng trống kiểm thử.
• Chỉ tóm tắt tổng quan sau khi đã nêu các phát hiện chính.
• Với báo cáo nghiên cứu hoặc kế hoạch, viết ngắn gọn, ưu tiên thông tin hành động và đánh đổi kỹ thuật.
• Nếu còn câu hỏi mở hoặc giả định chưa xác nhận, liệt kê chúng ở cuối báo cáo.
• Khi báo cáo hoàn tất, nêu rõ đã thay đổi gì, đã kiểm chứng ra sao và còn giới hạn nào nếu có.
• Với báo cáo nghiên cứu, ưu tiên độ rõ và tính hành động hơn văn phong trau chuốt.
• Khi cần tên thư mục, tệp hoặc mốc có định dạng ngày như YYMMDD, lấy ngày thực từ lệnh hệ thống thay vì suy đoán.

Tài Liệu

• Cập nhật tài liệu khi thêm tính năng mới, sửa lỗi quan trọng, đổi quyết định kiến trúc hoặc tạo quy ước mới cần dùng lâu dài.
• Ghi rõ thay đổi phá vỡ tương thích, cập nhật bảo mật quan trọng hoặc thay đổi hành vi đáng chú ý khi chúng xuất hiện.
• Giữ tài liệu bám sát trạng thái triển khai thực tế.
• Không thêm tài liệu hình thức nếu thay đổi không tạo giá trị duy trì.
• Trước khi sửa tài liệu hiện có, đọc trạng thái hiện tại để tránh lặp hoặc mâu thuẫn.
• Sau khi cập nhật tài liệu, rà lại ngày tháng, liên kết và tham chiếu chéo nếu các mục này có mặt.

Tự Cải Thiện

• Nếu repo có tệp như tasks/lessons.md, đọc tệp đó ở đầu phiên trước khi bắt đầu thay đổi đáng kể.
• Khi người dùng sửa lỗi hoặc chỉ ra sai sót lặp lại, ghi nhận mẫu lỗi, nguyên nhân gốc và quy tắc phòng tránh vào nơi lưu bài học của dự án nếu có.
• Mục tiêu là không lặp lại cùng một lỗi trong cùng phiên hoặc trong các lần làm việc sau.

An Toàn Và Bảo Mật

• Không đưa bí mật như khóa truy cập, mật khẩu hoặc nội dung .env vào commit (bản ghi thay đổi) hoặc báo cáo cuối.
• Thận trọng khi đọc, in hoặc xử lý thông tin nhạy cảm.
• Tôn trọng các ranh giới lệnh đã được quy định trong thư mục rules/.

Không Đưa Vào Tệp Này

• Persona, nghi thức phản hồi hoặc câu mở đầu bắt buộc.
• Điểm thưởng, cơ chế trò chơi hóa hoặc nội dung tuyên ngôn.
• Quyền lệnh chi tiết của shell (trình vỏ dòng lệnh).
• Tham chiếu sống tới thư mục lưu trữ tạm hoặc công cụ cũ.
• Hướng dẫn chỉ đúng cho một nền tảng khác nhưng không áp dụng trực tiếp ở đây.