Thiết Kế AI_CONTEXT.md — Nghệ Thuật Giao Tiếp Với AI Qua Tài Liệu

Khi AI chỉ là một lữ khách không có ký ức, thì tài liệu chính là tấm bản đồ ta trao cho nó — và cách ta vẽ bản đồ sẽ quyết định nơi nó có thể đưa ta đến.

Mở Đầu: Vấn Đề Của Bộ Nhớ Ngắn Hạn

Có một sự thật mỉa mai: những Mô hình Ngôn ngữ Lớn (LLM) được huấn luyện trên hàng nghìn tỷ token, có thể “biết” về lịch sử, triết học, lập trình — nhưng khi bước vào một dự án cụ thể, chúng không khác gì một người mới bắt đầu ngày đầu tiên đi làm.

Mỗi cuộc hội thoại, AI quên sạch mọi thứ.

Đây không phải lỗi của AI. Đó là bản chất của nó — stateless, không có trạng thái, không có ký ức bền vững. Và vì thế, gánh nặng thuộc về người thiết kế: làm sao để trong một cuộc trò chuyện ngắn ngủi, AI có thể hiểu đủ sâu để làm việc hiệu quả?

Câu trả lời nằm ở một file đơn giản: AI_CONTEXT.md.

AI_CONTEXT.md Là Gì?

AI_CONTEXT.md là một tài liệu ngữ cảnh dành riêng cho AI — tương tự như README.md dành cho developer, nhưng được tối ưu hóa để AI đọc và hiểu.

Nếu README.md trả lời câu hỏi “Dự án này là gì?”, thì AI_CONTEXT.md trả lời câu hỏi “AI cần biết gì để làm việc trong dự án này?”

Mục Đích Cốt Lõi

Nguyên Tắc Thiết Kế: Nghệ Thuật Của Sự Cô Đọng

“Ta không thể kể cho lữ khách cả đời ta trong một đêm bên lửa. Ta chỉ kể điều cần thiết cho hành trình ngày mai.”

Một file AI_CONTEXT.md hiệu quả tuân theo những nguyên tắc sau:

1. Comprehensive Yet Concise — Toàn diện nhưng Cô đọng

Đây là nghịch lý trung tâm: bạn cần đưa đủ thông tin để AI hiểu, nhưng không quá nhiều đến mức làm loãng sự chú ý.

• Điều nên có: Tổng quan dự án, kiến trúc, quy ước code, glossary
• Điều KHÔNG nên có: Chi tiết implementation, toàn bộ API docs, lịch sử commit

Quy tắc ngón tay cái: Nếu một mục cần hơn 5 dòng để giải thích, hãy tóm tắt và liên kết đến tài liệu chi tiết hơn.

2. Structure Over Prose — Cấu trúc quan trọng hơn Văn xuôi

AI đọc tốt hơn khi nội dung được tổ chức rõ ràng:

## Section Header (Ngắn gọn, mô tả)

- **Key concept:** Giải thích một dòng
- **File path:** `path/to/relevant/file.md`
- **Example:** Ví dụ ngắn nếu cần

Tránh: Đoạn văn dài, giải thích lan man, thông tin lặp lại.

3. Hierarchy of Information — Phân cấp Thông tin

Thông tin quan trọng nhất phải ở đầu file. AI (và con người) có xu hướng chú ý nhiều hơn vào những gì xuất hiện trước.

Thứ tự đề xuất:

1. Project Overview (Dự án làm gì?)
2. Core Architecture (Cấu trúc chính)
3. Key Conventions (Quy ước quan trọng)
4. Interaction Rules (Cách AI nên hành xử)
5. Current State (Trạng thái hiện tại)

4. Actionable Aliases — Lệnh Có Thể Thực Thi

Một trong những pattern mạnh mẽ nhất là định nghĩa aliases — những lệnh tắt mà user có thể gọi để AI thực hiện một quy trình cụ thể.

## Interaction Rules

- **`@build`**: Run the full build pipeline
  - *Loads:* `scripts/build.md`
  - *Usage:* `@build production`

- **`@test [module]`**: Run tests for specific module
  - *Loads:* `scripts/test.md`
  - *Usage:* `@test auth`

Điều này biến AI từ một “chatbot” thành một agent có thể hành động trong ngữ cảnh dự án.

Cấu Trúc Gợi Ý: Template AI_CONTEXT.md

Dựa trên thực tiễn từ nhiều dự án, đây là cấu trúc gợi ý:

# AI_CONTEXT: [Project Name]

## 1. Project Overview
[2-3 câu mô tả dự án và mục tiêu chính]

## 2. Architecture
[Sơ đồ ASCII hoặc mô tả ngắn gọn về cấu trúc thư mục/module]

## 3. Key Conventions
- **Language:** [Ngôn ngữ chính]
- **Style Guide:** [Link hoặc tóm tắt]
- **Testing:** [Framework và triết lý test]

## 4. Glossary
| Term | Definition |
|------|------------|
| [Term 1] | [Giải thích] |

## 5. Interaction Rules (Aliases)
- **`@command`**: [Mô tả]
  - *Loads:* [File(s) được load]
  - *Usage:* [Ví dụ]

## 6. Current State
- **Version:** [x.x.x]
- **Status:** [Active/Maintenance/etc.]
- **Focus:** [What the team is currently working on]

## 7. Constraints & Rules
- [Rule 1]
- [Rule 2]

Những Sai Lầm Thường Gặp

Quá Chi Tiết

## API Endpoints
- GET /users - Returns a JSON array of user objects with fields id, name, email...
[...200 dòng tiếp theo]

Vấn đề: Tốn token, dễ outdated, AI không cần biết tất cả chi tiết này.

Giải pháp: Tóm tắt và dẫn link: “Xem API docs tại docs/api.md“.

Quá Mơ Hồ

## Architecture
The project uses a modular architecture.

Vấn đề: Không có thông tin hữu ích. “Modular” có nghĩa gì trong ngữ cảnh này?

Giải pháp: Cụ thể hóa: “The project uses a 3-layer architecture: API → Service → Repository.”

Không Cập Nhật

Một AI_CONTEXT.md được viết 6 tháng trước và không bao giờ update sẽ gây hại hơn là có ích — AI sẽ đưa ra quyết định dựa trên thông tin cũ.

Giải pháp: Đưa việc update AI_CONTEXT vào workflow — mỗi khi kiến trúc thay đổi, file này cũng phải thay đổi.

Triết Lý Sâu Hơn: Tài Liệu Như Giao Tiếp

“Khi ta viết cho AI, ta đang viết cho một tâm trí không có quá khứ và không có tương lai — chỉ có khoảnh khắc hiện tại của những gì ta cung cấp.”

AI_CONTEXT.md không chỉ là một file kỹ thuật. Nó là một hình thức giao tiếp bất đồng bộ giữa bạn và một thực thể thông minh nhưng không có ngữ cảnh.

Cách bạn viết file này phản ánh:

• Sự rõ ràng trong tư duy: Bạn có thực sự hiểu dự án không?
• Sự đồng cảm với AI: Bạn có biết AI cần gì không?
• Kỷ luật trong documentation: Bạn có duy trì được không?

Theo nghĩa này, thiết kế AI_CONTEXT.md là một bài tập về sự tự hiểu — để giải thích cho AI, trước tiên bạn phải giải thích được cho chính mình.

Kết Luận: Tấm Bản Đồ Cho Lữ Khách Không Ký Ức

Hơn 40% dự án AI thất bại vì ngữ cảnh kém. Một file AI_CONTEXT.md được thiết kế tốt có thể là sự khác biệt giữa một AI assistant hữu ích và một chatbot gây hoang mang.

Hãy nhớ:

• Cô đọng nhưng đầy đủ — như một bức thư gửi cho chính mình trong tương lai
• Cấu trúc rõ ràng — AI đọc structure tốt hơn prose
• Aliases như API — biến AI thành agent có thể hành động
• Cập nhật thường xuyên — tài liệu lỗi thời còn nguy hiểm hơn không có tài liệu

Như một lữ khách đứng trước ngã ba đường, AI chỉ có thể đi đúng hướng nếu tấm bản đồ ta trao cho nó được vẽ đúng cách.

Written by chuotfx

Hãy ngồi xuống, uống miếng bánh và ăn miếng trà. Chúng ta cùng nhau đàm đạo về đời, về code nhóe!