// thỏa thuận
AGENTS.md
Codex nên hành xử thế nào trên repo này.
Dành cho người dùng Codex CLI
AGENTS.md cho Codex biết cách làm việc.
Không cho biết có gì ở đó.
AGENTS.md thiết lập thỏa thuận làm việc. MCP cho phép Codex vươn tới các công cụ. Maguyva là MCP server cho Codex một bản đồ có thể truy vấn của repo bạn, để lần chỉnh sửa đầu tiên không phải là một phỏng đoán về cấu trúc tệp.
Gói Free: 3 repository, Tối đa 50K dòng repo đã index, không cần thẻ.
AGENTS.md là thỏa thuận. MCP là kênh truyền tải. Maguyva là bản đồ.Chồng lớp
Bốn ý tưởng. Mỗi ý tưởng làm một việc.
// kênh truyền tải
MCP
Cách Codex vươn tới các công cụ và ngữ cảnh bên ngoài.
// codebase
Maguyva
MCP server trả về các dữ kiện repo có căn cứ.
// ai trả tiền
Workspace, không phải theo ghế
Tác nhân không phải trả tiền theo ghế. Xem bảng giá
AGENTS.md là một thỏa thuận làm việc. Cứ dùng nó.
Các chỉ dẫn lâu dài nên nằm trong AGENTS.md. Đây là nơi đúng cho:
- Các lệnh build, test, và lint mà Codex nên chạy.
- Các rào chắn “luôn làm X / không bao giờ làm Y” giới hạn trong một thư mục.
- Quy ước đặt tên và các ưu tiên khi tái cấu trúc.
- Con trỏ tới nhật ký quyết định chuẩn và ghi chú kiến trúc.
Giữ nó ngắn gọn. Giới hạn phạm vi. Commit nó.
Nhưng AGENTS.md chưa bao giờ được thiết kế để trở thành một chỉ mục có thể truy vấn của mọi ký hiệu, tệp, và call site trong repo của bạn.
Nơi AGENTS.md một mình trở nên tĩnh khi mở rộng quy mô
Bốn kiểu thất bại, mỗi kiểu một thẻ.
// thỏa thuận không phải là chỉ mục
Cho Codex biết cách làm việc không cho nó biết những gì đang tồn tại. Lần chỉnh sửa đầu tiên trên một package xa lạ là một phỏng đoán về đường dẫn tệp và tên hàm. AGENTS.md không thể liệt kê mọi ký hiệu, và bạn cũng không muốn nó làm vậy.
// tài liệu trôi khỏi mã
Một đoạn AGENTS.md mô tả cấu trúc hàng đợi của bạn đúng cho đến khi ai đó thêm một consumer mới. Mã nguồn giờ là nguồn sự thật và tài liệu đã lỗi thời một cách tự tin. Codex đọc nhầm cái sai.
// đổi tên là một bài toán đồ thị
“Cái gì tham chiếu tới class này?” không thể trả lời được từ một tệp markdown. Codex hoặc grep-rồi-cầu-may trên toàn monorepo, hoặc yêu cầu bạn dán call site vào chat.
// cửa sổ ngữ cảnh không miễn phí
Nhồi nhét AGENTS.md cho đến khi Codex “biết đủ” ngốn hết token lẽ ra dành cho suy luận. Qua vài KB, bạn đánh đổi chất lượng câu trả lời để lấy khối lượng ngữ cảnh tĩnh.
Ba lớp này khớp với nhau như thế nào
Người dùng Codex đã suy nghĩ theo hình mẫu này rồi. Trang này chỉ cần làm nó rõ ràng.
AGENTS.md
thỏa thuận
cách Codex hành xử
MCP
kênh truyền tải
cách nó vươn tới
Maguyva
dữ kiện codebase
những gì nó thấy
- AGENTS.md cách Codex hành xử trên repo này.
- MCP cách Codex vươn tới các công cụ và ngữ cảnh. (spec)
- Maguyva những gì Codex thấy khi nó đặt một câu hỏi cho codebase. Tìm kiếm ngữ nghĩa, AST, đồ thị, và văn bản trả về kèm đường dẫn tệp và số dòng.
AGENTS.md cho Codex biết cách làm việc.
Maguyva cho Codex thứ gì đó để làm việc dựa vào.
Ba quy trình làm việc
Riêng cho Codex. Có căn cứ vào đồ thị lệnh gọi thực tế, không phải grep của Codex.
// workflow 01
Đổi tên một class dùng chung, tìm mọi phần phụ thuộc trước
codex> đổi tên PaymentClient → BillingClient graph::callers(PaymentClient) 12 tham chiếu trên 7 package graph::importers(src/payments/client.ts) 9 importer graph::extends(PaymentClient) 2 lớp con (RetryClient, MockClient) → Codex đề xuất một migration gồm 21 chỉnh sửa kèm danh sách tệp ngay trong dòng kết quả. [exit 0]
Codex hỏi Maguyva về các phần phụ thuộc trước khi nó bắt đầu chỉnh sửa. Danh sách migration trả về có căn cứ vào đồ thị thực tế, không phải trí nhớ của Codex.
// workflow 02
Tìm cài đặt thực sự, chứ không phải test stub
codex> normalizePhoneNumber xử lý E.164 như thế nào? semantic::query("normalize phone E.164") src/util/phone.ts:88 normalizePhoneNumber() ← cài đặt thực test/util/phone.spec.ts:14 jest.mock(...) ← stub [exit 0]
Tên gọi có thể lừa dối. Mock che khuất mã thực. Maguyva xếp hạng cài đặt thực cao hơn test mock.
// workflow 03
Kiểm tra phạm vi ảnh hưởng trước khi tái cấu trúc
codex> điều gì gọi QueueDispatcher.publish? graph::callers(QueueDispatcher.publish) 3 in src/billing/* 1 in src/audit/* 1 in src/notifications/* [exit 0]
Call-site xuyên package hiện ra ngay trong dòng kết quả. Diff có căn cứ vào các importer thực tế, không phải grep của Codex.
Cài đặt trong Codex CLI
Ba bước. Gói Free: 3 repository, Tối đa 50K dòng repo đã index, không cần thẻ.
// step 01
Lập chỉ mục một repo tại maguyva.ai
Chọn một repo bạn biết rõ, để bạn có thể xác minh các câu trả lời.
// step 02
Thêm Maguyva làm MCP server trong cấu hình Codex của bạn
$ export MAGUYVA_API_KEY=mgv_xxxx $ codex mcp add maguyva --url https://maguyva.tools/mcp \ --bearer-token-env-var MAGUYVA_API_KEY # equivalent ~/.codex/config.toml [mcp_servers.maguyva] url = "https://maguyva.tools/mcp" bearer_token_env_var = "MAGUYVA_API_KEY"// step 03
Đặt một câu hỏi mà bạn đã biết câu trả lời
Đừng bắt đầu với toàn bộ công ty của bạn. Hãy bắt đầu với một repo và một câu hỏi có thể kiểm chứng.