Làm app cùng AI agent

Giao diện

Thông tin kiểm chứng ngày 2026-10-24T00:00:00.000Z

CLAUDE.md / AGENTS.md ​

CLAUDE.md là file hướng dẫn dự án: Claude Code tự đọc nó ở đầu mỗi phiên. AGENTS.md là file hướng dẫn dùng chung theo chuẩn mở, Codex đọc trực tiếp.

Giải quyết vấn đề gì ​

Mỗi phiên agent bắt đầu từ con số 0. Nó không nhớ hôm qua bạn dặn "dùng bun, không dùng npm", "tiền là số nguyên", "test đặt cạnh file". Không có file hướng dẫn, bạn phải nhắc lại mỗi lần, hoặc agent tự đoán và đoán sai.

File hướng dẫn trả lời ba câu agent cần biết trước khi động tay:

  • Stack và lệnh: chạy, test, kiểm tra kiểu bằng lệnh gì.
  • Quy tắc: những điều dự án này làm khác thói quen chung.
  • Thế nào là "xong": điều kiện kiểm tra được, để agent không dừng ở chỗ "trông có vẻ xong".

Khi nào cần ​

  • Luôn luôn, từ ngày đầu dự án. Đây là khối rẻ nhất và lợi nhất.
  • Viết ngắn. Chỉ ghi những gì agent không tự suy ra được từ code. Thấy agent lặp lại một lỗi lần thứ hai thì thêm một dòng.
  • Dùng cả Claude Code lẫn Codex trong cùng repo: viết quy ước vào AGENTS.md, để CLAUDE.md chỉ nạp nó và thêm phần riêng.

Ví dụ tối thiểu ​

Starter dùng đúng mẫu "một nguồn, hai tool". Dòng đầu của practice/starter/CLAUDE.md là @AGENTS.md, cú pháp import của Claude Code: nội dung AGENTS.md được nạp vào như thể viết ngay tại đó.

markdown
@AGENTS.md

## Riêng cho Claude Code
- Hook `Stop` tự chạy typecheck + test trước khi bạn kết thúc lượt. Nếu nó báo lỗi, sửa tiếp, đừng báo "xong".
- Hook `PreToolUse` chặn đưa file bí mật vào git. Bị chặn thì đọc lý do và sửa lệnh.
- Tính năng mới: đi theo quy trình brainstorming → spec → plan → thực thi (plugin Superpowers).
- Cần tài liệu thư viện mới nhất: dùng Context7 thay vì đoán API.

Quy ước thật nằm ở practice/starter/AGENTS.md, Codex đọc trực tiếp file này. Phần đáng học nhất là định nghĩa "xong":

markdown
## Quy tắc
- Logic nghiệp vụ (tính toán, quy tắc) viết thành hàm thuần trong `packages/api/src/`, có test `*.test.ts` bên cạnh.
- Viết test trước, thấy test fail rồi mới viết code.
- Tiền tệ là số nguyên đồng (VND), không dùng số thực.

## Thế nào là "xong"
1. `bun run check-types` và `bun test` đều pass.
2. Đã chạy app và tự kiểm tra tính năng trên trình duyệt (skill `verify-app`).
3. Đã commit.

## Khi bí
- Yêu cầu mơ hồ: hỏi lại người dùng, đừng đoán.
- Thử 2 cách vẫn hỏng: dừng lại, tóm tắt đã thử gì, hỏi hướng đi.

Để ý: file hướng dẫn là lời dặn, agent có thể quên. Thứ nào bắt buộc phải xảy ra (chạy test trước khi dừng, không commit .env) thì starter đặt thêm thành hook, vì hook là cổng tất định.

Bên Codex ​

Codex đọc AGENTS.md trực tiếp, không cần import:

  • File global: ~/.codex/AGENTS.md (hoặc AGENTS.override.md).
  • Trong dự án: Codex đi từ gốc repo xuống thư mục đang làm việc, nối các AGENTS.md gặp trên đường; file gần thư mục làm việc hơn ghi đè.
  • Giới hạn mặc định project_doc_max_bytes = 32 KiB. Thêm một lý do để viết ngắn.

Vì vậy mẫu của starter (quy ước ở AGENTS.md, CLAUDE.md chỉ @AGENTS.md + phần riêng) cho cả hai tool cùng một bộ quy tắc mà không phải chép hai nơi.

Nguồn ​