# Rules và Workflows trong Antigravity: dạy AI làm theo quy trình của bạn

URL: https://opcaios.org/blog/rules-va-workflows-trong-antigravity
Ngày: 2026-11-03
Cập nhật: 2026-11-03
Tác giả: Lê Quốc Nghĩa
Chuyên mục: Hướng dẫn

Rules trong Antigravity là các chỉ dẫn lâu dài (quy ước code, ràng buộc kiến trúc, điều cấm) mà Google Antigravity tự tìm trong thư mục rồi đưa vào ngữ cảnh của tác tử ở mọi lượt, thay vì bạn phải nhắc lại trong từng câu lệnh. Workflow là chuỗi bước viết bằng Markdown, gọi bằng dấu "/". Điều quan trọng nhất, theo tài liệu chính thức đọc ngày 03/11/2026: workflow kiểu cũ đã ngừng hoạt động từ ngày 19/10/2026 và Google khuyên chuyển sang skill. Bài này không hứa rule làm AI tuân thủ tuyệt đối; mô hình vẫn có thể bỏ sót, và chúng tôi chưa đo mức tuân thủ. Nếu chưa biết Antigravity, đọc [Antigravity là gì?](/blog/antigravity-la-gi) trước. Bài đi qua rule và skill, GEMINI.md và AGENTS.md, phạm vi rule, chế độ kích hoạt, giới hạn, chuyển workflow sang skill, thứ tự tìm file và cách OPCAIOS dùng.

![Sơ đồ rules và workflows trong Antigravity: rule toàn cục và rule theo dự án được gộp vào ngữ cảnh, bốn chế độ kích hoạt always_on, model_decision, glob, manual; workflow cũ chuyển sang skill bằng /migrate-workflows; thứ tự tìm file từ workspace lên gốc repo](https://opcaios.org/images/blog/rules-va-workflows-trong-antigravity/so-do.webp)
*Rule là ràng buộc luôn đi theo tác tử, skill là quy trình nhiều bước gọi khi cần. Sơ đồ: OPCAIOS.*

## Rules trong Antigravity khác skill thế nào?

Rules trong Antigravity là ràng buộc và bất biến, còn skill là quy trình nhiều bước, theo trang /docs/rules (đọc ngày 03/11/2026). Tài liệu đưa ví dụ: "luôn dùng zod để kiểm tra dữ liệu" là rule, còn "cách chạy migration cơ sở dữ liệu" là skill. Khác biệt nằm ở cách nạp. Rule được Antigravity tự phát hiện và đưa vào ngữ cảnh theo chế độ kích hoạt. Skill chỉ đưa tên và mô tả vào ngữ cảnh; tác tử đọc toàn bộ hướng dẫn khi việc đang làm khớp mô tả. Rule cũng có tính cộng dồn: Antigravity gộp mọi rule tìm thấy, không để file này thay file kia. Cách chia thực dụng cho người làm một mình:

1. Điều cần đúng ở mọi việc (ngôn ngữ trả lời, thư mục cấm sửa, quy ước đặt tên): viết thành rule.
2. Điều chỉ cần khi làm một việc cụ thể (deploy, viết bài, sao lưu): viết thành skill.

Khái niệm skill nói chung có trong [skill là gì](/blog/skill-la-gi-cach-dung-skill).

## GEMINI.md và AGENTS.md đặt ở đâu trong dự án?

GEMINI.md và AGENTS.md là hai tên file rule mà Antigravity đọc như Markdown thuần, không cần frontmatter và luôn bật. Theo /docs/rules, ở thư mục workspace và mỗi thư mục cha lên tới gốc repo, Antigravity nạp rule ở ba vị trí:

1. `AGENTS.md` hoặc `GEMINI.md` ngay trong thư mục đó.
2. `.agents/AGENTS.md` hoặc `.agents/GEMINI.md`.
3. Các file `.agents/rules/*.md` (vẫn nhận thư mục cũ `.agent/rules/`).

Antigravity không đọc rule trong thư mục con nằm dưới workspace, kể cả khi tác tử đọc hay sửa file ở đó. Vì AGENTS.md là quy ước dùng chung giữa nhiều tác tử, một file có thể phục vụ cả Antigravity lẫn công cụ khác; xem [AGENTS.md là gì](/blog/agents-md-la-gi) và [CLAUDE.md là gì](/blog/claude-md-la-gi) để so sánh với Claude Code.

## Rules toàn cục khác rules theo dự án thế nào?

Rules toàn cục áp dụng cho mọi dự án trên máy, còn rules theo dự án chỉ áp dụng trong một workspace và nên commit vào kho mã để cả nhóm dùng chung. Theo /docs/rules (đọc ngày 03/11/2026):

| Loại | Vị trí theo tài liệu | Frontmatter |
|---|---|---|
| Toàn cục, file đơn | `~/.gemini/AGENTS.md`, `~/.gemini/GEMINI.md`, `~/.gemini/config/AGENTS.md`, `~/.gemini/config/GEMINI.md` | Không cần, luôn bật |
| Toàn cục, dạng module | `~/.gemini/config/rules/*.md` | Bắt buộc |
| Theo dự án | `AGENTS.md`, `GEMINI.md`, `.agents/rules/*.md` từ workspace lên gốc repo | Bắt buộc với file trong `rules/` |

Có khác biệt nhỏ giữa các bề mặt: danh sách toàn cục của Antigravity IDE trong tài liệu chỉ ghi `~/.gemini/AGENTS.md`, `~/.gemini/GEMINI.md` và `~/.gemini/config/rules/*.md`. Trong ứng dụng và IDE, tạo rule qua bảng Customizations, thẻ Rules, nút + Global hoặc + Workspace. Nên để rule toàn cục thật ngắn.

## Bốn chế độ kích hoạt rule hoạt động ra sao?

Chế độ kích hoạt là khoá `trigger` trong frontmatter YAML, quyết định khi nào một file trong `rules/` được nạp vào ngữ cảnh. Theo /docs/rules, có bốn giá trị:

1. `always_on`: nạp toàn bộ nội dung vào system prompt mọi lượt. Nếu không cần frontmatter, đặt thẳng vào AGENTS.md.
2. `model_decision`: chỉ nạp đường dẫn và mô tả; tác tử đọc toàn văn khi việc khớp mô tả. Bắt buộc có `description`.
3. `glob`: tự bật khi tác tử làm việc với file khớp mẫu trong `globs`, ví dụ `"*.ts, *.tsx"`.
4. `manual`: không bao giờ tự nạp, chỉ thêm khi bạn @-nhắc tên rule. Antigravity CLI không hỗ trợ nhắc rule.

Cạm bẫy đáng nhớ: file trong `.agents/rules/` thiếu frontmatter, hoặc ghi trigger sai kiểu như `alwaysOn` hay `modelDecision`, sẽ bị bỏ qua mà không báo lỗi. Ví dụ một rule theo mẫu file (giả định, minh hoạ):

```markdown
---
trigger: glob
globs: "*.sql"
description: "Quy tắc khi viết migration cơ sở dữ liệu."
---
# Migration
1. Không xoá hay đổi tên cột trong một lần deploy.
2. Mỗi migration phải có cách hoàn tác.
```

Antigravity chỉ quét file `.md` nằm ngay trong `rules/`; file trong thư mục con bị bỏ qua trừ khi khai báo trong `.agents/rules.json`.

## Rule dài quá thì Antigravity xử lý thế nào?

Antigravity đặt hai giới hạn để rule không ăn hết cửa sổ ngữ cảnh, theo /docs/rules đọc ngày 03/11/2026. Thứ nhất, mỗi file rule tối đa 24.000 byte, tính sau khi đã chèn các file được include; phần vượt bị cắt. Thứ hai, toàn bộ rule toàn cục và rule `always_on` dùng chung ngân sách 20.000 token, tách riêng với ngân sách cho skill và MCP. Khi tổng vượt 20.000 token, Antigravity tự hạ các file lớn nhất từ toàn văn xuống thành một dòng con trỏ gồm đường dẫn và mô tả, để tác tử đọc khi cần. Vì vậy mô tả của rule quan trọng ngay cả với rule luôn bật: đó là phần còn lại khi rule bị hạ cấp. Rule cũng hỗ trợ hai cú pháp tham chiếu. Cú pháp `@[nhãn](đường-dẫn)` chèn nguyên nội dung file đích vào rule. Cú pháp `@tên-file` chỉ đổi thành đường dẫn tuyệt đối trong workspace để tác tử biết chính xác file nào. Nên tách rule dài thành nhiều file `model_decision`.

## Workflow trong Antigravity là gì và vì sao chuyển sang skill?

Workflow trong Antigravity là file Markdown chứa tiêu đề, mô tả và chuỗi bước, gọi bằng lệnh `/tên-workflow`, theo trang /docs/ide/workflows (đọc ngày 03/11/2026). Một workflow có thể gọi workflow khác, và mỗi file tối đa 12.000 ký tự. Tuy nhiên cả trang workflow lẫn trang /docs/migration/workflows-to-skills đều ghi: workflow hiện tại ngừng hoạt động từ ngày 19/10/2026, Google sẽ có hệ thống workflow mới và hướng dẫn chuyển đổi sau. Sau mốc đó, thư mục workflow cũ không còn được lập chỉ mục hay gọi được bằng lệnh gạch chéo. Chúng tôi chưa tự kiểm chứng hành vi này trên máy.

| Tiêu chí | Workflow cũ | Skill |
|---|---|---|
| Chuẩn | Định dạng riêng của Antigravity | Chuẩn mở Agent Skills |
| Cấu trúc | Một file `.md` | Thư mục có `SKILL.md` và tệp kèm |
| Vị trí dự án | `.agents/workflows/<tên>.md` | `.agents/skills/<tên>/SKILL.md` |
| Vị trí toàn cục | `~/.gemini/config/workflows/<tên>.md` | `~/.gemini/config/skills/<tên>/SKILL.md` |
| Nạp ngữ cảnh | Cả file | Tên và mô tả trước, nội dung khi cần |
| Gọi bằng "/" | Có | Có, `/<tên-skill>` |

Lệnh `/migrate-workflows` trong ứng dụng Antigravity quét cả hai thư mục workflow, tạo skill tương ứng, đổi file gốc thành đuôi `.bak` và kích hoạt skill mới. Nếu workflow và skill trùng tên, skill được ưu tiên.

## Antigravity tìm rule và skill theo thứ tự nào?

Antigravity tìm tuỳ biến ở hai phạm vi: workspace (thư mục `.agents/` cùng AGENTS.md, GEMINI.md) và cá nhân (`~/.gemini/config/` cùng `~/.gemini/AGENTS.md`, `~/.gemini/GEMINI.md`), theo /docs/customization-discovery (đọc ngày 03/11/2026). Quy tắc chính:

1. Kiểm tra thư mục workspace và từng thư mục cha, dừng ở gốc repo (thư mục chứa `.git`); ngoài repo thì chỉ xét workspace.
2. Không tìm xuống thư mục con dưới workspace.
3. Quét mỗi thư mục tuỳ biến đúng một cấp: skill phải nằm ngay trong `skills/`, rule ngay trong `rules/`; muốn sâu hơn thì khai báo trong file manifest như `skills.json`, `rules.json`.
4. Skill trùng tên: thư mục cá nhân trong repo (nếu repo cấu hình) thắng workspace, workspace thắng `~/.gemini/config/`, cuối cùng là skill có sẵn.
5. Rule không thay nhau: mọi rule tìm thấy đều được nạp.

Antigravity đọc lại rule và skill trước mỗi lượt, nên file mới có hiệu lực ngay tin nhắn sau. Trong CLI, chạy `/skills reload` để cập nhật danh sách lệnh. Phần skill và MCP đi sâu hơn ở [MCP và skill trong Antigravity](/blog/mcp-va-skill-trong-antigravity).

## Kinh nghiệm của OPCAIOS

Kiểm tra ngày 03/11/2026 trên máy Mac chính (ứng dụng Antigravity 2.28.x, IDE 2.5.x, CLI `agy` 1.4.12):

1. File GEMINI.md cấp người dùng chỉ có một dòng: luôn trả lời tiếng Việt.
2. Quy trình dùng chung nằm trong AGENTS.md, đặt ở thư mục gốc người dùng và trong kho ghi chú Obsidian: thứ tự đọc tài liệu đầu phiên, ghi nhật ký cuối phiên, đồng bộ qua một file trạng thái chung.
3. Có đúng một file workflow toàn cục nhưng là mẫu trống, chưa có mô tả, chưa dùng thật. Vì vậy mốc 19/10/2026 không ảnh hưởng gì tới chúng tôi.

Điều rút ra khi đối chiếu tài liệu: AGENTS.md ở thư mục gốc người dùng không nằm trong danh sách rule toàn cục, nên chỉ được nạp khi thư mục đó nằm trên đường từ workspace lên gốc repo. Chúng tôi chưa kiểm chứng file này có được nạp trong mọi dự án hay không.

## Câu hỏi thường gặp

### Nên dùng GEMINI.md hay AGENTS.md trong Antigravity?

Theo tài liệu /docs/rules, Antigravity đọc cả hai với cùng cách xử lý: Markdown thuần, không frontmatter, luôn bật, và nội dung được cộng dồn. Nếu bạn chỉ dùng Antigravity, tên nào cũng được. Nếu dùng nhiều tác tử như Claude Code, Codex, Cursor, AGENTS.md tiện hơn vì là quy ước chung nhiều công cụ cùng hiểu, nhờ đó bạn chỉ duy trì một bộ quy tắc. Đừng chép cùng nội dung vào cả hai file, vì rule cộng dồn sẽ tốn token gấp đôi.

### Vì sao rule tôi viết không có tác dụng?

Kiểm tra theo thứ tự trong /docs/customization-discovery. Một, file có nằm đúng chỗ không: workspace hoặc thư mục cha lên tới gốc repo, không phải thư mục con. Hai, file có nằm ngay trong `rules/` không, vì thư mục con bị bỏ qua. Ba, file trong `rules/` có frontmatter với `trigger` hợp lệ viết thường có gạch dưới không, như `always_on`. Bốn, rule có bị hạ thành con trỏ vì vượt ngân sách 20.000 token không. Cuối cùng, nhớ rằng mô hình vẫn có thể bỏ sót rule.

### Workflow cũ của tôi còn chạy được không?

Theo tài liệu đọc ngày 03/11/2026, workflow kiểu cũ ngừng hoạt động từ ngày 19/10/2026; sau mốc này thư mục workflow không còn được lập chỉ mục hay gọi bằng lệnh gạch chéo. Google cho biết sẽ có hệ thống workflow mới và hướng dẫn chuyển đổi sau. Cách xử lý hiện tại là chạy `/migrate-workflows` trong ứng dụng Antigravity, hoặc tự tạo thư mục skill rồi chuyển nội dung vào `SKILL.md` với frontmatter `name` và `description`. File gốc được giữ lại với đuôi `.bak`.

### Skill có gọi bằng dấu "/" như workflow không?

Có. Theo trang chuyển đổi workflow sang skill, mọi skill trong `.agents/skills/<tên>/` hoặc `~/.gemini/config/skills/<tên>/` gọi được bằng `/<tên>`, giống workflow cũ. Khác biệt là tác tử còn tự chọn skill khi việc khớp mô tả, nên mô tả phải viết rõ skill làm gì và dùng khi nào. Trong CLI, thêm skill khi đang chạy thì gõ `/skills reload` hoặc mở hội thoại mới. So sánh các cơ chế mở rộng có trong [slash command, skill, plugin hay MCP](/blog/slash-command-skill-plugin-hay-mcp).

### Người không biết code có tự viết rule được không?

Được, vì rule chỉ là file Markdown viết bằng lời thường. Bắt đầu bằng một AGENTS.md ngắn: ngôn ngữ trả lời, thư mục không được sửa, việc phải làm trước khi xoá hay deploy, cách báo cáo khi xong. Sau vài phiên, dùng lệnh `/learn` để Antigravity đề xuất rule từ những lần bạn sửa nó, rồi duyệt từng đề xuất. Muốn học cách dạy tác tử AI làm theo quy trình của mình, xem [khoá đào tạo ứng dụng AI](/services/dao-tao-ung-dung-ai) của OPCAIOS.

*Nguồn: tài liệu Google Antigravity tại antigravity.google: /docs/rules, /docs/ide/workflows, /docs/migration/workflows-to-skills, /docs/skills, /docs/slash-commands, /docs/customization-discovery (đọc ngày 03/11/2026); chưa tự kiểm chứng việc workflow cũ ngừng chạy sau 19/10/2026, chưa kiểm chứng file AGENTS.md ở thư mục gốc người dùng được nạp trong mọi dự án, chưa đo mức tuân thủ rule. Kinh nghiệm là của OPCAIOS.*