# AGENTS.md cho Codex biết cách làm việc. Không cho biết có gì ở đó.

Canonical source: https://maguyva.ai/vi/for-codex

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

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.

> 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.

### AGENTS.md

Codex nên hành xử thế nào trên repo này.

### MCP

Cách Codex vươn tới các công cụ và ngữ cảnh bên ngoài.

### Maguyva

MCP server trả về các dữ kiện repo có căn cứ.

### Theo workspace, không theo người dùng

Không tính phí riêng cho từng agent. [Xem bảng giá](https://maguyva.ai/vi/pricing)

## 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`](https://developers.openai.com/codex/guides/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)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **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 *cơ sở để làm việc*.

## 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.

### 01. Đổi tên một class dùng chung, tìm trước mọi thành phần phụ thuộc vào nó

```text
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 thành phần phụ thuộc vào class đó *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.

### 02. Tìm cài đặt thực sự, chứ không phải test stub

```text
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.

### 03. Kiểm tra phạm vi ảnh hưởng trước khi tái cấu trúc

```text
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ẻ tín dụng.

### 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.

### 02. Thêm Maguyva làm MCP server trong cấu hình Codex của bạn

`~/.codex/config.toml`

```text
export MAGUYVA_API_KEY=mgv_xxxx
codex mcp add maguyva --url https://maguyva.tools/mcp --bearer-token-env-var MAGUYVA_API_KEY
```

```toml
[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"
bearer_token_env_var = "MAGUYVA_API_KEY"
```

### 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.

## Lập chỉ mục một repo mà bạn đã biết rõ.

Kết nối Codex qua MCP. Đặt một câu hỏi mà bạn có thể xác minh câu trả lời.