# AGENTS.md cho OpenCode biết quy tắc của bạn. Maguyva cho nó thấy mã.

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

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

OpenCode đọc AGENTS.md để biết cách làm việc và gọi MCP server cho mọi thứ khác. Maguyva là một MCP server từ xa cho OpenCode một bản đồ có thể truy vấn của repo, kèm đường dẫn tệp và số dòng.

> Một mục từ xa dưới mcp. Không có gì chạy cục bộ.

## Những điều cần biết về OpenCode

Bốn điều riêng của OpenCode.

### opencode.json

Thêm server dưới `mcp` trong `opencode.json` của dự án, hoặc trong `~/.config/opencode/opencode.json` cho mọi dự án.

### type: remote

OpenCode kết nối tới endpoint của Maguyva qua HTTP. Không có gì chạy cục bộ và không cần Node.js.

### Tham chiếu biến môi trường

OpenCode thay thế biến môi trường trong cấu hình, nên header là `Bearer {env:MAGUYVA_API_KEY}` và khóa không nằm trong tệp bạn commit.

### Giới hạn theo từng agent

Mỗi MCP server thêm định nghĩa công cụ vào ngữ cảnh. OpenCode có thể tắt công cụ của một server trên toàn cục bằng glob như `"maguyva*": false` và bật lại cho những agent cần chúng.

## AGENTS.md là một thỏa thuận làm việc. Cứ dùng nó.

```text
> /init
# quét repo và viết AGENTS.md
```

OpenCode đọc `AGENTS.md` ở thư mục gốc dự án và `~/.config/opencode/AGENTS.md` cho quy tắc cá nhân. Nếu không có `AGENTS.md`, nó dùng `CLAUDE.md`. Hãy dùng nó cho:

- Lệnh build, test và lint.
- Quy ước và ranh giới agent cần tôn trọng.
- Chỉ dẫn tới các tài liệu quan trọng.

Bản quét lúc `/init` là một bản tóm tắt, không phải chỉ mục. Nó không cho OpenCode biết ai gọi hàm được thêm vào hôm qua.

## Khi AGENTS.md không còn đủ

Ba khoảng trống OpenCode lấp bằng grep và sự kiên nhẫn.

### // bản tóm tắt không phải chỉ mục

AGENTS.md có thể nêu tên các package quan trọng. Nó không thể liệt kê mọi ký hiệu và nơi gọi, và cũng không nên thử.

### // grep tìm chuỗi, không tìm nơi gọi

Một kết quả khớp văn bản không thể phân biệt lời gọi thật với comment, mock hay method trùng tên ở class khác.

### // tệp bị lệch dần

AGENTS.md đúng vào ngày nó được viết. Mã tiếp tục thay đổi; tệp chỉ đổi khi có người nhớ cập nhật.

## Maguyva làm MCP server từ xa trong OpenCode

Một mục dưới mcp mang lại cho OpenCode:

- **11 công cụ trên repo đã lập chỉ mục của bạn**: tìm kiếm ngữ nghĩa, cấu trúc (AST), đồ thị và văn bản, cùng tra cứu ký hiệu, thành phần phụ thuộc và truy xuất tệp.
- **Câu trả lời kèm đường dẫn tệp và số dòng**: trên 285+ ngôn ngữ.
- **Cùng câu trả lời cho mọi mô hình**: OpenCode làm việc với nhiều nhà cung cấp mô hình. Maguyva trả về cùng một bản đồ dù mô hình nào hỏi.

> AGENTS.md cho OpenCode biết *cách làm việc*.
> Maguyva cho OpenCode *cơ sở để làm việc*.

## Hai quy trình làm việc

Hỏi bản đồ ngay từ cùng một terminal.

### 01. Đổi tên một type dùng chung giữa các package

```text
opencode> đổi tên OrderStatus thành FulfillmentStatus

dependency_search("OrderStatus", dependents)
  23 tham chiếu trên 8 package
structural_search(switch_statement, "OrderStatus")
  4 switch vét cạn

→ OpenCode sửa toàn bộ danh sách, kể cả các switch.
[exit 0]
```

Các switch vét cạn chính là chỗ tìm kiếm văn bản bỏ sót và trình biên dịch phát hiện muộn.

### 02. Phân biệt mã với tài liệu

```text
opencode> FEATURE_BULK_EXPORT được đọc ở đâu?

text_pattern_search("FEATURE_BULK_EXPORT")
  src/config/flags.ts:17
  src/export/bulk.ts:5
  docs/flags.md:40   ← chỉ là tài liệu

→ Hai đường dẫn mã, một tài liệu đã cũ.
[exit 0]
```

Kết quả khớp chính xác trả về kèm đường dẫn, nên OpenCode phân biệt được mã với tài liệu trước khi sửa bên nào.

## Cài đặt trong OpenCode

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, để bạn có thể đánh giá các câu trả lời.

### 02. Thêm Maguyva dưới mcp trong opencode.json

`opencode.json`

```json
{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

### 03. Export khóa của bạn và kiểm tra kết nối

Đặt `MAGUYVA_API_KEY` trong shell khởi chạy OpenCode. `opencode mcp list` hiển thị từng server đã cấu hình; sau đó đặt một câu hỏi mà bạn đã biết câu trả lời.

[Tài liệu MCP](https://opencode.ai/docs/mcp-servers/) của OpenCode nói về timeout, OAuth và quyền truy cập công cụ theo từng agent.

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

Kết nối OpenCode qua MCP, rồi đặt một câu hỏi bạn có thể kiểm tra.