AGENTS.md: Thiết lập workspace rules cho agent — Từ hỗn loạn đến nhất quán

Tại sao agent của bạn hôm nay viết code TypeScript strict mode, nhưng ngày mai lại quên mất? Tại sao cùng một prompt, bạn chạy được nhưng đồng nghiệc lại không? Vấn đề nằm ở thiếu "luật lệ địa phương" — AGENTS.md chính là bộ quy tắc workspace giúp agent nhất quán trong từng dự án, bất kể ai chạy hay chạy bao nhiêu lần.

Vấn đề

Khi làm việc với AI agent qua nhiều ngày và nhiều người, bạn chạy vào ba vấn đề cốt lõi:

Context drift (trôi dạt ngữ cảnh): Agent hôm nay code theo chuẩn FastAPI repository pattern, nhưng ngày mai lại viết Django-style queries vì "quên" constraints. Không có vùng bịt kín nào ngăn agent lan man sang pattern khác khi context window bị nhiễu.

Team inconsistency: Bạn và đồng nghiệc cùng mở một repo, nhưng agent đối xử khác nhau vì mỗi người có "system prompt" riêng trong đầu. Bạn nhắc agent "viết test trước", đồng nghiệc lại quên — kết quả là codebase hỗn loạn.

Prompt bloat: Giải pháp tạm bợ là nhét toàn bộ tech stack vào SOUL.md global. Nhưng khi chuyển sang dự án khác dùng React thay vì FastAPI, agent vẫn áp dụng chuẩn backend cho code frontend vì SOUL.md quá generic và nặng nề.

Cách tiếp cận cũ — dùng chat prompt để "nhắc nhở" agent mỗi lần — thất bại vì prompt là ephemeral (biến mất khi tắt terminal), không thể review trong PR, và không chia sẻ được giữa team members.

Ý tưởng cốt lõi

AGENTS.md là file markdown đặt tại thư mục gốc project (hoặc .claude/AGENTS.md) đóng vai trò workspace constitution — bản hiến pháp địa phương cho agent.

File này sử dụng cấu trúc hai tầng quen thuộc: YAML frontmatter làm metadata routing, và Markdown body chứa quy tắc chi tiết. Nó tồn tại trong repo Git, được version control, và chỉ "active" khi agent làm việc trong directory đó.

Hierarchy của Context Engineering

Kiến trúc này tuân theo nguyên tắc separation of concerns — tách biệt mối quan tâm theo scope:

SOUL.md (Global Identity)
    ↓  "Tôi là lập trình viên chuyên nghiệp, thích code rõ ràng"
    
AGENTS.md (Workspace Rules)  
    ↓  "Dự án này dùng FastAPI + SQLAlchemy 2.0, không dùng Django"
    
MEMORY.md (Session History)
    ↓  "Hôm qua ta đang sửa bug authentication ở file users.py..."
    
SKILL.md (Task Capabilities)
    "Cách viết unit test theo Arrange-Act-Assert pattern"

Aha moment: AGENTS.md chính là .editorconfig hoặc .gitignore nhưng dành cho AI behavior — declarative, team-shared, và scoped theo project.

Cấu trúc file thực tế

---
name: Backend API Agent
description: Expert in FastAPI, PostgreSQL, domain-driven design
model: claude-3-5-sonnet
tools:
  allowed: [read_file, edit_file, bash, python]
  forbidden: [web_search]  # Chỉ dùng local docs, không search bên ngoài
---

# Workspace Rules

## Tech Stack Constraints
- **Framework**: FastAPI + SQLAlchemy 2.0, nghiêm cấm Django
- **Pattern**: Repository pattern bắt buộc, không truy vấn DB trực tiếp từ router
- **Type**: Pydantic strict mode, không dùng `\`{Any}\`` hoặc `\`{dict}\``

## File Conventions
- Domain models đặt trong `/domain/`
- API routes đặt trong `/api/v1/`
- Tests song song với source (`_test.py`), không dùng thư mục `/tests/` riêng

## Prohibited Actions (Hard Constraints)
- KHÔNG sửa đổi database schema qua migration tự động
- KHÔNG commit code chưa qua `ruff check` và `pytest`
- KHÔNG dùng `requests` library, chỉ dùng `httpx` cho async consistency

Điểm then chốt là mục Prohibited Actions — đây là "cấm kỵ" mang tính technical enforcement hơn là "đề nghị". Khi agent thấy forbidden: [web_search] trong frontmatter, nó biết chắc chắn không được gọi tool đó, thay vì phải "cân nhắc" qua prompt.

Tại sao nó hoạt động

File-based > Prompt-based: AGENTS.md sống trong repository như README.md hoặc pyproject.toml. Điều này mang lại ba tính chất quan trọng:

• Persistent: Survive reboot, không như chat history trong terminal
• Diffable: Team review thay đổi behavior qua Git PR (ví dụ: "Thêm cấm dùng Django ORM")
• Scoped: Chỉ load khi agent cd vào workspace đó, tránh làm phình to global context

Progressive disclosure: Agent không nạp AGENTS.md cho đến khi cần. Nếu bạn đang ở directory project React, agent chỉ đọc AGENTS.md của React project; nếu switch sang backend Python, nó đọc AGENTS.md khác. Điều này tránh "context pollution" — hiện tượng tech stack của dự án A leo sang dự án B.

Deterministic boundaries: Mục forbidden trong YAML frontmatter tạo compile-time constraints (kiểm soát lúc biên dịch) thay vì runtime suggestions. Thay vì nhờ agent "nhớ" không dùng web search, ta cắt quyền tool đó trong configuration. Đây là kiến trúc "permission model" — tách "muốn làm" khỏi "được phép làm".

Trade-off cần lưu ý: Modularization tạo ra fragmentation risk. Nếu team đổi từ FastAPI sang Django nhưng quên cập nhật AGENTS.md, agent sẽ ép buộc dùng pattern cũ. Cần discipline để maintain file này như maintain code style guide.

Ý nghĩa thực tế

Team consistency: 5 developers cùng clone một repo, cùng một AGENTS.md → agent hành xử đồng nhất cho dù người dùng là senior hay junior. Đây là "coding standard" cho AI assistant.

Onboarding zero-friction: Developer mới vào team chỉ cần clone repo; agent tự biết luật dự án mà không cần "training" bằng 20 phút giải thích tech stack.

Multi-project switching: Developer có thể nhảy giữa dự án Python (FastAPI) và dự án React (Next.js) trong cùng một session — agent tự điều chỉnh behavior theo AGENTS.md của từng directory.

Limitations:

• Hiện chỉ OpenClaw và Claude Code hỗ trợ native AGENTS.md discovery
• Không tự động sync nếu developer quên copy file vào repo (cần template)
• Dễ lỗi thời nếu team refactor tech stack nhưng quên update file config

Đào sâu hơn

Docs chính thức:

• Claude Code Documentation: Context Files — Giải thích chi tiết hierarchy giữa SOUL.md, AGENTS.md và MEMORY.md
• OpenClaw Workspace Configuration — Hướng dẫn setup AGENTS.md cho multi-agent teams

Bài liên quan TroiSinh:

Mở rộng:

• Claude Code Context Engineering Best Practices — GitHub repo với mẫu AGENTS.md cho các stack phổ biến (Python, TypeScript, Rust)
• Agent Identity Files Pattern — Phân tích sâu về "file-based personality" thay vì prompt-based