# Claude bắt đầu mỗi phiên làm việc trong tình trạng mù tịt.

Canonical source: https://maguyva.ai/vi/for-claude-code

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

`CLAUDE.md` cho Claude biết cách hành xử. Nó không cho Claude biết trong repo của bạn có gì. Maguyva lập chỉ mục codebase và trả về qua MCP, để Claude chỉnh sửa như thể đã đọc mã từ trước.

> Dùng CLAUDE.md cho hành vi. Dùng Maguyva cho các dữ kiện codebase hiện tại.

## CLAUDE.md là một thực hành tốt. Cứ dùng nó.

```text
> cat CLAUDE.md
# quy ước dự án, các lệnh, rules giới hạn phạm vi
```

Các chỉ dẫn lâu dài nên nằm trong `CLAUDE.md`. Đây là nơi đúng cho:

- Các lệnh build, test, và lint mà agent nên chạy.
- Các quy tắc phong cách viết mã và quy ước đặt tên.
- 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.
- Con trỏ tới tài liệu chuẩn và nhật ký quyết định.

Tài liệu [bộ nhớ](https://code.claude.com/docs/en/memory) của Anthropic mô tả điều này rất rõ. Giữ nó ngắn gọn. Giới hạn phạm vi. Commit nó.

Nhưng `CLAUDE.md` chưa bao giờ được thiết kế để làm bản đồ cho codebase của bạn.

## Nơi CLAUDE.md không còn đủ nữa

Bốn kiểu thất bại mà markdown một mình không thể khắc phục.

### // tệp không phải là codebase

Cho Claude biết *cách hành xử* 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 repo xa lạ là một phỏng đoán về đường dẫn tệp, tên hàm, và call site. CLAUDE.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 lỗi thời, mã thì không

Một đoạn `CLAUDE.md` mô tả luồng auth của bạn đúng cho đến khi ai đó tái cấu trúc auth. Mã nguồn giờ là nguồn sự thật và tài liệu sai một cách tự tin. Claude đọc nhầm cái sai.

### // phụ thuộc không nằm trong markdown

“Cái gì sẽ hỏng nếu tôi thay đổi hàm này?” là một câu hỏi về đồ thị. Nó không thể được trả lời bởi một tệp tài liệu. Claude hoặc grep-rồi-cầu-may, hoặc yêu cầu bạn dán tệp vào chat.

### // cửa sổ ngữ cảnh có ngân sách

Nhồi nhét CLAUDE.md cho đến khi Claude “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.

## Maguyva là lớp mà CLAUDE.md không bao phủ

Một MCP server từ xa cho Claude Code:

- **Tìm kiếm ngữ nghĩa, AST, đồ thị, và văn bản**: trên repo đã lập chỉ mục của bạn, trả về kèm đường dẫn tệp và số dòng.
- **Tra cứu phụ thuộc, kiểu dữ liệu, và call-site**: những câu hỏi mà một đồ thị trả lời được còn một tệp tài liệu thì không.
- **Kết quả nhận biết nhánh**: để Claude thấy đúng phiên bản mã mà nó đang thực sự chỉnh sửa.
- **Định giá theo workspace**: không theo người dùng. Lập chỉ mục 1 repo hay 50; không tính phí riêng cho từng agent.

> CLAUDE.md cho Claude biết *cách hành xử*.
> Maguyva cho Claude *một bản đồ mã có thể truy vấn*.

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

Đánh số, nhiều khối mã. Những câu hỏi bạn đã từng hỏi Claude, giờ có căn cứ vào các dòng mã thực tế.

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

```text
Bạn: "Retry hoạt động thế nào trong payment client của chúng ta?"

Không có Maguyva → Claude grep retry, tìm thấy 14 kết quả, chọn một cái (thường là một test mock).
Có Maguyva    → Maguyva trả về định nghĩa ký hiệu, các call-site, và
                   file:line của cài đặt thực, đã được xếp hạng.
```

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

```text
Bạn: "Cái gì gọi normalizePhoneNumber?"

Maguyva trả về: 7 call-site trên 4 package, bao gồm một cái trong một dịch vụ Python
import nó qua gRPC stub. Claude đề xuất thay đổi kèm danh sách
migration ngay trong dòng kết quả, không phải sau khi CI báo đỏ.
```

### 03. Xác minh agent trước khi bạn chấp nhận diff

```text
Claude: "Tôi đã chỉnh sửa src/auth/session.ts:142 để sửa việc refresh token."

Hỏi Maguyva: "Cho tôi xem session.ts:130-160 và bất cứ thứ gì import session."

Maguyva trả về đoạn tệp trực tiếp + 3 importer. Diff giờ có căn cứ
vào các dòng mã thực tế, không phải trí nhớ của Claude từ token thứ 11.000.
```

## Cài đặt trong Claude Code

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 nắm rõ để có thể tự kiểm chứng câu trả lời. Gói Free bao gồm 3 repository, Tối đa 50K dòng repo đã index.

### 02. Cài đặt plugin Maguyva trong Claude Code

```text
/plugin marketplace add maguyva/agent-plugins
/plugin install maguyva@maguyva

# the plugin reads your key from the environment
export MAGUYVA_API_KEY=mgv_xxxx
```

### 03. Đặt một câu hỏi mà bạn đã biết câu trả lời

Hãy bắt đầu với một repo và một câu hỏi có thể kiểm chứng, không phải toàn bộ công ty của bạn. Nếu câu trả lời khớp với điều bạn sẽ nói, vậy là bạn đã sẵn sàng.

Hướng dẫn đầy đủ nằm trong [tài liệu của Maguyva](https://maguyva.ai/vi/docs).

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

Kiểm tra một câu hỏi mà bạn có thể xác minh câu trả lời. Đó là toàn bộ quá trình onboarding.