AGENTS.md | Cấu hình tác nhân

Codex đọc các tệp AGENTS.md trước khi thực hiện bất kỳ công việc nào. Bằng cách phân lớp hướng dẫn toàn cục với các ghi đè dành riêng cho dự án, bạn có thể bắt đầu mọi tác vụ với các kỳ vọng nhất quán, bất kể mở kho lưu trữ nào.

Cách Codex tìm hướng dẫn

Codex xây dựng một chuỗi hướng dẫn khi khởi động (một lần trong mỗi lượt chạy; trong TUI, điều này thường có nghĩa là một lần cho mỗi phiên được khởi chạy). Quá trình tìm kiếm tuân theo thứ tự ưu tiên sau:

Phạm vi toàn cục: Trong thư mục chính của Codex (mặc định là ~/.codex, trừ khi bạn đặt CODEX_HOME), Codex đọc AGENTS.override.md nếu tệp này tồn tại. Nếu không, Codex đọc AGENTS.md. Codex chỉ sử dụng tệp không trống đầu tiên ở cấp này.
Phạm vi dự án: Bắt đầu từ thư mục gốc của dự án (thường là thư mục gốc Git), Codex đi xuống đến thư mục làm việc hiện tại của bạn. Nếu Codex không thể tìm thấy thư mục gốc của dự án, Codex chỉ kiểm tra thư mục hiện tại. Trong mỗi thư mục trên đường dẫn, Codex lần lượt kiểm tra AGENTS.override.md, rồi AGENTS.md, sau đó là mọi tên dự phòng trong project_doc_fallback_filenames. Codex chỉ đưa vào tối đa một tệp trong mỗi thư mục.
Thứ tự hợp nhất: Codex nối các tệp từ thư mục gốc xuống dưới, phân tách chúng bằng dòng trống. Các tệp gần thư mục hiện tại của bạn hơn sẽ ghi đè hướng dẫn trước đó vì chúng xuất hiện sau trong prompt kết hợp.

Codex bỏ qua các tệp trống và ngừng thêm tệp khi tổng kích thước đạt giới hạn được xác định bởi project_doc_max_bytes (mặc định là 32 KiB). Để biết chi tiết về các tùy chọn này, hãy xem Cách tìm hướng dẫn dự án. Hãy tăng giới hạn hoặc chia hướng dẫn vào các thư mục lồng nhau khi chạm mức tối đa.

Tạo hướng dẫn toàn cục

Tạo các giá trị mặc định lâu dài trong thư mục chính của Codex để mọi kho lưu trữ đều kế thừa các quy ước làm việc của bạn.

Đảm bảo thư mục tồn tại:
```
mkdir -p ~/.codex
```

Tạo ~/.codex/AGENTS.md với các tùy chọn có thể tái sử dụng:

# ~/.codex/AGENTS.md

## Working agreements

- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.

Chạy Codex ở bất kỳ đâu để xác nhận tệp đã được tải:
```
codex --ask-for-approval never "Summarize the current instructions."
```
Kết quả mong đợi: Codex trích dẫn các mục trong ~/.codex/AGENTS.md trước khi đề xuất công việc.

Sử dụng ~/.codex/AGENTS.override.md khi bạn cần ghi đè toàn cục tạm thời mà không xóa tệp cơ sở. Xóa tệp ghi đè để khôi phục hướng dẫn dùng chung.

Phân lớp hướng dẫn dự án

Các tệp ở cấp kho lưu trữ giúp Codex nắm được quy ước của dự án trong khi vẫn kế thừa các giá trị mặc định toàn cục.

Trong thư mục gốc của kho lưu trữ, thêm một AGENTS.md bao gồm thiết lập cơ bản:

# AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.

Thêm ghi đè trong các thư mục lồng nhau khi một số nhóm cần quy tắc khác. Ví dụ: trong services/payments/, hãy tạo AGENTS.override.md:

# services/payments/AGENTS.override.md

## Payments service rules

- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.

Khởi động Codex từ thư mục payments:
```
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."
```
Kết quả mong đợi: Codex báo cáo tệp toàn cục trước, AGENTS.md ở thư mục gốc kho lưu trữ thứ hai và ghi đè của payments cuối cùng.

Codex ngừng tìm kiếm khi đến thư mục hiện tại của bạn, vì vậy hãy đặt các tệp ghi đè càng gần công việc chuyên biệt càng tốt.

Sau đây là kho lưu trữ mẫu sau khi bạn thêm tệp toàn cục và ghi đè dành riêng cho payments:

Thêm quy tắc đánh giá mã

Đối với tính năng đánh giá mã của Codex trong GitHub, hãy thêm một phần ## Code Review Rules vào AGENTS.md gần nhất với mã mà các quy tắc chi phối. Đặt các bước kiểm tra áp dụng cho toàn kho lưu trữ ở thư mục gốc và các bước kiểm tra dành riêng cho dịch vụ trong một tệp lồng nhau.

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

Giữ các quy tắc ngắn gọn, giải thích hành vi cần gắn cờ cùng mọi phương án an toàn hoặc ngoại lệ, đồng thời dành các bước kiểm tra định dạng và lint cho CI. Xem Tùy chỉnh nội dung Codex đánh giá để biết hướng dẫn thiết lập và viết quy tắc.

Tùy chỉnh tên tệp dự phòng

Nếu kho lưu trữ của bạn đã sử dụng một tên tệp khác (ví dụ: TEAM_GUIDE.md), hãy thêm tên đó vào danh sách dự phòng để Codex coi tệp này như một tệp hướng dẫn.

Chỉnh sửa cấu hình Codex:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

Khởi động lại Codex hoặc chạy một lệnh mới để tải cấu hình đã cập nhật.

Giờ đây, Codex kiểm tra từng thư mục theo thứ tự sau: AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. Những tên tệp không có trong danh sách này sẽ bị bỏ qua khi tìm hướng dẫn. Giới hạn byte lớn hơn cho phép kết hợp nhiều hướng dẫn hơn trước khi bị cắt bớt.

Khi đã thiết lập danh sách dự phòng, Codex coi các tệp thay thế là hướng dẫn:

Đặt biến môi trường CODEX_HOME khi bạn muốn sử dụng một hồ sơ khác, chẳng hạn như người dùng tự động hóa dành riêng cho dự án:

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

Kết quả mong đợi: Đầu ra liệt kê các tệp theo đường dẫn tương đối với thư mục .codex tùy chỉnh.

Xác minh thiết lập

Chạy codex --ask-for-approval never "Summarize the current instructions." từ thư mục gốc của kho lưu trữ. Codex sẽ phản hồi hướng dẫn từ các tệp toàn cục và tệp dự án theo thứ tự ưu tiên.
Sử dụng codex --cd subdir --ask-for-approval never "Show which instruction files are active." để xác nhận các ghi đè lồng nhau thay thế những quy tắc rộng hơn.
Để kiểm tra những tệp hướng dẫn nào Codex đã tải, hãy bật nhật ký TUI dạng văn bản thuần bằng codex -c log_dir=./.codex-log và kiểm tra ./.codex-log/codex-tui.log, hoặc xem tệp session-*.jsonl gần đây nhất nếu bạn đã bật ghi nhật ký phiên.
Nếu hướng dẫn có vẻ lỗi thời, hãy khởi động lại Codex trong thư mục đích. Codex xây dựng lại chuỗi hướng dẫn trong mỗi lượt chạy (và khi bắt đầu mỗi phiên TUI), vì vậy không có bộ nhớ đệm nào cần xóa thủ công.

Khắc phục sự cố tìm hướng dẫn

Không tải được gì: Xác minh rằng bạn đang ở đúng kho lưu trữ và codex status báo cáo đúng thư mục gốc của không gian làm việc mà bạn mong đợi. Đảm bảo các tệp hướng dẫn có nội dung; Codex bỏ qua tệp trống.
Xuất hiện hướng dẫn không đúng: Tìm AGENTS.override.md ở cấp cao hơn trong cây thư mục hoặc trong thư mục chính của Codex. Đổi tên hoặc xóa tệp ghi đè để quay lại sử dụng tệp thông thường.
Codex bỏ qua tên dự phòng: Xác nhận rằng bạn đã liệt kê các tên trong project_doc_fallback_filenames mà không có lỗi chính tả, sau đó khởi động lại Codex để cấu hình cập nhật có hiệu lực.
Hướng dẫn bị cắt bớt: Tăng project_doc_max_bytes hoặc chia các tệp lớn vào các thư mục lồng nhau để giữ nguyên hướng dẫn quan trọng.
Nhầm lẫn hồ sơ: Chạy echo $CODEX_HOME trước khi khởi chạy Codex. Giá trị không phải mặc định sẽ trỏ Codex đến một thư mục chính khác với thư mục bạn đã chỉnh sửa.

Bước tiếp theo

Truy cập trang web AGENTS.md chính thức để biết thêm thông tin.
Xem Cách viết prompt cho Codex để tìm hiểu các mẫu hội thoại phối hợp hiệu quả với hướng dẫn lâu dài.

Tìm kiếm gần đây

Tìm kiếm đề xuất

Điều hướng tài liệu

Hướng dẫn tùy chỉnh bằng AGENTS.md