Blog

Cách Viết File AGENTS.md Cho Đội Phát Triển API

Ashley Innocent

Ashley Innocent

29 tháng 4 2026

Cách Viết File AGENTS.md Cho Đội Phát Triển API

Các tác nhân viết mã đọc kho lưu trữ của bạn trước khi họ viết mã, và tệp họ đọc đầu tiên là AGENTS.md. Đây là quy ước mở mà Codex CLI, Cursor, Aider, OpenHands và một danh sách ngày càng tăng các công cụ khác đã đồng ý để một tệp ngữ cảnh duy nhất hoạt động trên mọi tác nhân. Đối với các nhóm phát triển API, tệp đó là sự khác biệt giữa một tác nhân chạy các bài kiểm tra phù hợp với một máy chủ cục bộ thực tế và một tác nhân tạo ra các điểm cuối ảo và phát hành một máy khách bị lỗi.

Hướng dẫn này bao gồm AGENTS.md là gì, tại sao các nhóm API nên coi nó như mã sản xuất, các phần quan trọng đối với các kho lưu trữ ưu tiên OpenAPI, các ví dụ cụ thể và cách giữ cho nó luôn mới khi API phát triển. Cuối cùng, chúng tôi kết hợp nó với Apidog để luồng kiểm thử hợp đồng của tác nhân luôn dựa trên một đặc tả thực tế.

button

TL;DR

AGENTS.md thực sự là gì

AGENTS.md là một tệp Markdown bạn cam kết ở thư mục gốc của một kho lưu trữ. Các tác nhân viết mã tìm kiếm nó khi tiếp xúc lần đầu với codebase và coi nội dung của nó là bản tóm tắt có thẩm quyền về cách dự án hoạt động. Quy ước này bắt đầu bên trong Codex CLI của OpenAI và được xuất bản như một tiêu chuẩn mở để các công cụ khác có thể đọc cùng một tệp. Kể từ năm nay, Codex CLI, Cursor, Aider, Claude Code, OpenHands, Sourcegraph Cody và một số tác nhân nhỏ hơn đều đọc nó.

Ba điều làm cho nó hữu ích:

  1. Một tệp, mọi tác nhân. Bạn viết ngữ cảnh một lần và mọi tác nhân trong bộ công cụ của nhóm đều tiếp nhận nó. Không có sự trôi lệch cấu hình cho từng công cụ.
  2. Markdown thuần túy. Không có DSL, không có schema, không có bước build. Các kỹ sư chỉnh sửa nó như bất kỳ tài liệu nào khác.
  3. Sống bên cạnh mã mà nó mô tả. Khi tập lệnh build thay đổi, tệp thay đổi trong cùng một PR. Sự khác biệt làm cho thay đổi hiển thị cho người đánh giá và cho tác nhân.

Người họ hàng gần nhất là CLAUDE.md, mà Claude Code của Anthropic đọc. Hai định dạng chồng chéo nặng nề; nhiều dự án giữ một AGENTS.md được liên kết tượng trưng với CLAUDE.md để cả hai công cụ hoạt động mà không cần cấu hình bổ sung. Nhóm Codex và Anthropic đã công khai thống nhất giữ cho các định dạng tương thích trong tương lai.

Tại sao các nhóm phát triển API cần nó hơn hầu hết

Các nhóm API nằm ở một giao điểm khó xử: mã nhỏ, hợp đồng lớn và hậu quả của việc sai sót đều hiển thị cho mọi máy khách hạ nguồn. Một tác nhân không biết đặc tả nằm ở openapi.yaml sẽ viết lại các loại từ hình dạng phản hồi mà nó nhớ từ dữ liệu huấn luyện. Một tác nhân không biết lệnh kiểm thử hợp đồng sẽ cam kết mã biên dịch nhưng làm hỏng pipeline SDK của máy khách.

Một tệp AGENTS.md được viết tốt cho một kho lưu trữ API làm được bốn điều:

Khi tệp làm được bốn điều này, đầu ra của tác nhân không còn trông giống như một nhà phát triển cấp dưới đã bỏ qua README mà bắt đầu trông giống như một đồng đội.

Cấu trúc hoạt động cho các kho lưu trữ API

AGENTS.md không có schema bắt buộc. Cộng đồng đã thống nhất một vài phần xuất hiện trong hầu hết các tệp được tinh chỉnh tốt. Đối với một nhóm API, thứ tự dưới đây là một mặc định mạnh mẽ.

1. Tóm tắt dự án (3-5 dòng)

Nêu API làm gì, người dùng là ai, và ngôn ngữ cũng như framework mà máy chủ chạy trên đó. Giữ cho nó thực tế.

# Dự án: API Thanh toán

Dịch vụ thanh toán nội bộ cho dòng sản phẩm Acme. Khách hàng là
di động, web và backends đối tác. Máy chủ là Go 1.23 trên Echo, Postgres
17 cho lưu trữ, và một lớp idempotency được hỗ trợ bởi Redis.

Khối này cho tác nhân biết ngôn ngữ mặc định nào, nên tuân theo các thành ngữ nào và máy khách nào sẽ bị hỏng nếu bạn gửi hình dạng phản hồi sai.

2. Lệnh khởi động nhanh

Năm đến mười lệnh mà tác nhân sẽ chạy liên tục. Luôn bao gồm lệnh, không bao giờ liên kết đến wiki.

## Lệnh

| Mục đích | Lệnh |
|--------|---------|
| Cài đặt phụ thuộc | `make deps` |
| Chạy máy chủ cục bộ | `make dev` (liên kết 127.0.0.1:8080) |
| Chạy kiểm thử đơn vị | `make test` |
| Chạy kiểm thử hợp đồng với mock cục bộ | `make contract` |
| Lint | `make lint` |
| Tạo lại máy khách từ đặc tả | `make codegen` |
| Áp dụng di chuyển | `make migrate` |

Nếu một lệnh cần một biến môi trường để hoạt động, hãy đặt tên biến môi trường bên cạnh nó. Các tác nhân giỏi trong việc xuất biến; họ kém trong việc đoán.

3. Phần đặc tả OpenAPI / GraphQL

Đây là phần có giá trị nhất trong một kho lưu trữ API. Cho tác nhân biết đặc tả nằm ở đâu, đặc tả liên quan đến mã được tạo như thế nào và hướng chỉnh sửa chảy như thế nào.

## Nguồn sự thật

- Đặc tả nằm ở `apis/payments/openapi.yaml`.
- Các máy khách được tạo sống trong `gen/clients/{go,ts,python}` và TUYỆT ĐỐI KHÔNG được chỉnh sửa thủ công.
- Pipeline tạo là `make codegen`. Chạy nó sau mỗi thay đổi đặc tả
  và cam kết các máy khách được tạo lại trong cùng một PR.
- Dòng thay đổi đặc tả: spec -> `make codegen` -> cập nhật handler máy chủ ->
  kiểm thử hợp đồng -> phát hành.

Chỉ riêng khối này đã loại bỏ một loại lỗi khi các tác nhân chỉnh sửa máy khách được tạo để "sửa" lỗi không khớp loại, lần chạy codegen tiếp theo xóa bỏ thay đổi, và bản build bị lỗi một cách bí ẩn hai ngày sau đó.

4. Kết nối máy chủ giả lập và Apidog

Nếu bạn chạy máy chủ giả lập (và bạn nên làm vậy), hãy đặt tên cho chúng. Liệt kê các URL, đặc tả mà chúng đọc từ đó và cách khởi động chúng.

## Máy chủ cục bộ

- Máy chủ thực: `make dev` -> `http://127.0.0.1:8080`
- Máy chủ giả lập Apidog: `make mock` -> `http://127.0.0.1:4010`
- Mock đọc từ cùng một `openapi.yaml` và phát lại các ví dụ đã lưu
  từ bộ sưu tập Apidog tại `apis/payments/apidog/`.

Đây là nơi Apidog có vị trí của nó trong tệp. Máy chủ giả lập, đặc tả và các ví dụ yêu cầu đã lưu tạo thành một hợp đồng mà tác nhân có thể chạy mà không tốn các cuộc gọi trên backend thực. Kết hợp nó với hướng dẫn kiểm thử API không cần Postman để hiểu quy trình làm việc cơ bản.

5. Xác thực và bí mật

Cho tác nhân biết API xác thực như thế nào và biến môi trường nào chứa gì. Không bao giờ đặt bí mật thực vào tệp.

## Xác thực

- Sản phẩm sử dụng OAuth 2 thông tin đăng nhập máy khách do Auth0 cấp.
- Dev cục bộ sử dụng token dev tĩnh; xuất `DEV_TOKEN` từ `.env.local`.
- Bộ sưu tập Apidog sử dụng cùng tên biến môi trường để mock và
  máy khách thực hoạt động giống hệt nhau.
- Token KHÔNG ĐƯỢC cam kết; `.env.local` nằm trong `.gitignore`.

6. Chiến lược kiểm thử

Xếp hạng các lớp kiểm thử. Các tác nhân sẽ chạy chúng theo thứ tự bạn liệt kê.

## Kiểm thử

1. `make test` cho kiểm thử đơn vị. Nhanh, chạy trên mỗi thay đổi.
2. `make contract` cho kiểm thử hợp đồng OpenAPI với mock. Chạy trước
   khi bất kỳ thay đổi đặc tả nào được hợp nhất.
3. `make integration` cho kiểm thử end-to-end với máy chủ cục bộ có
   Postgres thực. Chạy trước khi hợp nhất vào main.
4. Staging soak chạy hàng đêm qua GitHub Actions; không phải lệnh cục bộ.

7. Danh sách không được chạm vào

Mã được tạo, các phụ thuộc vendored và các di chuyển hầu như luôn thuộc về đây.

## Không chỉnh sửa bằng tay

- `gen/**` (tạo lại bằng `make codegen`)
- `vendor/**` (quản lý bằng `go mod vendor`)
- `migrations/*.up.sql` sau lần di chuyển chưa áp dụng đầu tiên
- Tên trường schema `apis/payments/openapi.yaml` không có sự chấp thuận của chủ sở hữu

8. Quy tắc phong cách

Ba đến năm quy tắc. Hơn nữa, tác nhân sẽ chọn sai quy tắc.

## Quy ước

- Lỗi trả về JSON vấn đề RFC 7807; không bao giờ là chuỗi trần.
- Sử dụng snake_case trong JSON, camelCase trong Go, PascalCase trong máy khách TS.
  Codegen xử lý ánh xạ.
- Khóa Idempotency là bắt buộc trên tất cả các điểm cuối POST tạo tài nguyên.
- Các điểm cuối mới yêu cầu kiểm thử hợp đồng bao gồm cả đường dẫn 200 và 4xx.

Ví dụ cụ thể: một tệp 90 dòng thực hiện công việc

Cám dỗ là viết 800 dòng. Hãy chống lại nó. Tệp dưới đây bao gồm một dịch vụ API thực tế trong 90 dòng Markdown và đủ để bất kỳ tác nhân chính nào làm việc hiệu quả.

# Dự án: API Thanh toán

Dịch vụ thanh toán nội bộ cho dòng sản phẩm Acme. Go 1.23, Echo,
Postgres 17, Redis cho tính bất biến (idempotency). Người tiêu dùng là di động, web,
và các backends đối tác.

## Lệnh

| Mục đích | Lệnh |
|--------|---------|
| Cài đặt | `make deps` |
| Chạy máy chủ | `make dev` |
| Kiểm thử đơn vị | `make test` |
| Kiểm thử hợp đồng | `make contract` |
| Lint | `make lint` |
| Tạo lại máy khách | `make codegen` |
| Di chuyển DB | `make migrate` |

## Nguồn sự thật

- Đặc tả: `apis/payments/openapi.yaml`
- Máy khách được tạo: `gen/clients/{go,ts,python}` (không chỉnh sửa)
- Luồng chỉnh sửa: spec -> `make codegen` -> handler -> kiểm thử hợp đồng -> phát hành

## Máy chủ cục bộ

- Máy chủ thực: `make dev` (`http://127.0.0.1:8080`)
- Apidog mock: `make mock` (`http://127.0.0.1:4010`)
- Bộ sưu tập Apidog: `apis/payments/apidog/`

## Xác thực

- Sản phẩm: thông tin đăng nhập máy khách Auth0 OAuth 2.
- Dev cục bộ: `DEV_TOKEN` tĩnh từ `.env.local`.

## Thứ tự kiểm thử

1. `make test`
2. `make contract`
3. `make integration`

## Không chỉnh sửa bằng tay

- `gen/**`, `vendor/**`
- Các di chuyển đã áp dụng trong `migrations/`
- Tên trường đặc tả không có sự chấp thuận của chủ sở hữu

## Quy ước

- JSON vấn đề RFC 7807 cho lỗi
- JSON snake_case, codegen xử lý ánh xạ ngôn ngữ
- Khóa Idempotency bắt buộc trên POST tạo
- Mọi điểm cuối mới đều đi kèm với kiểm thử hợp đồng

Thế là đủ. Chỉ thêm các phần khi một tác nhân đưa ra cùng một lựa chọn sai hai lần.

Giữ cho tệp luôn mới

Một tệp AGENTS.md lỗi thời còn tệ hơn là không có tệp nào cả. Tác nhân sẽ tin vào nó và gửi mã dựa trên một lệnh build không còn hoạt động.

Ba thói quen giúp giữ cho nó luôn mới:

  1. Coi nó như mã sản xuất. Các thay đổi trải qua quá trình xem xét tương tự như bất kỳ PR nào khác. Người xem xét kiểm tra rằng danh sách lệnh khớp với Makefile thực tế.
  2. Kết nối nó vào CI. Một tập lệnh ngắn phân tích bảng lệnh và chạy từng lệnh trên một bản checkout mới sẽ phát hiện sự trôi lệch nhanh chóng. Hầu hết các nhóm viết điều này trong 30 dòng Bash.
  3. Cập nhật nó trong cùng một PR. Khi bạn thêm một lệnh kiểm thử mới, đừng hứa sẽ cập nhật AGENTS.md sau. Hãy cập nhật nó ngay bây giờ. Chi phí là hai phút; chi phí bỏ qua là hai tuần tác nhân bị nhầm lẫn.

Apidog làm hợp đồng runtime cho AGENTS.md của bạn

AGENTS.md cung cấp ngữ cảnh cho tác nhân. Đặc tả OpenAPI cung cấp hợp đồng. Apidog kết nối hai thứ này: nó đọc đặc tả, chạy một mock cục bộ tại URL được liệt kê trong AGENTS.md, phát lại các ví dụ yêu cầu đã lưu để kiểm thử và cho phép tác nhân xem các phản hồi thực mà không tốn credits trên backend trực tiếp.

Mô hình hoạt động:

Để biết hướng dẫn chuyên sâu hơn về quy trình làm việc mock của Apidog với một API thực, hướng dẫn API DeepSeek V4 bao gồm cùng một mô hình được áp dụng cho một API mô hình thay vì một API dịch vụ.

Những lỗi phổ biến mà các nhóm API mắc phải

Sau khi xem xét hàng tá tệp này, năm vấn đề giống nhau xuất hiện:

  1. Liên kết thay vì liệt kê. "Xem wiki để biết lệnh build." Tác nhân không duyệt wiki. Hãy đặt các lệnh trực tiếp vào tệp.
  2. Văn xuôi mang tính chất marketing. "Nền tảng API đẳng cấp thế giới của chúng tôi trao quyền cho..." Tác nhân không cần một lời quảng cáo. Hãy nêu sự thật.
  3. Lệnh lỗi thời. Một lệnh đã hỏng vào tháng 3 vẫn còn trong tệp vào tháng 4. Kết nối CI để phát hiện điều này.
  4. Thiếu phần đặc tả. Khối hữu ích nhất. Luôn bao gồm nó.
  5. Không có danh sách không được chạm vào. Tác nhân chỉnh sửa mã được tạo. Lần chạy codegen tiếp theo xóa bỏ chỉnh sửa. Bản build bị lỗi. Lặp lại.

Nếu bạn muốn một điểm khởi đầu, hãy sao chép ví dụ trên vào kho lưu trữ của bạn, chỉnh sửa tóm tắt dự án và điều chỉnh bảng lệnh. Bạn có thể xuất bản một tệp có thể sử dụng được trong 20 phút.

FAQ

AGENTS.md có giống CLAUDE.md không?Các định dạng tương thích. Hầu hết các nhóm giữ một trong số chúng làm nguồn sự thật và tạo liên kết tượng trưng cho cái còn lại. Anthropic và OpenAI đã công khai thống nhất giữ cho các quy ước có thể tương tác.

Tôi nên đặt tệp ở đâu?Luôn ở thư mục gốc của kho lưu trữ. Một số tác nhân cũng đọc các tệp AGENTS.md lồng nhau bên trong các thư mục con, hữu ích cho các monorepos. Bắt đầu với một tệp gốc và chỉ thêm các tệp thư mục con khi một tệp gốc duy nhất trở nên quá dài.

Nó nên dài bao nhiêu?200 đến 400 dòng là lý tưởng. Ngoài ra, các tác nhân bắt đầu bỏ qua các phần. Nếu bạn cần sâu hơn, hãy liên kết đến một tài liệu riêng với một bản tóm tắt một dòng trực tiếp.

Tôi có nên bao gồm các ví dụ mã không?Các ví dụ ngắn thì có. Các ví dụ dài thì không. Lưu các ví dụ đầy đủ cho các bài kiểm tra; các tác nhân cũng đọc các bài kiểm tra. Hướng dẫn Codex miễn phí GPT-5.5 bao gồm cách Codex đặc biệt sử dụng các bài kiểm tra ví dụ làm tín hiệu bổ sung.

Tác nhân có đọc lại tệp trong mỗi lượt không?Hầu hết các tác nhân đọc nó khi bắt đầu phiên và lưu vào bộ nhớ cache. Một số đọc lại sau các thay đổi tệp lớn. Nếu bạn thực hiện một chỉnh sửa lớn, khởi động lại phiên tác nhân là động thái an toàn nhất.

Làm cách nào để kiểm tra xem tệp của tôi có hoạt động không?Chạy một phiên tác nhân mới không có ngữ cảnh nào khác, giao cho nó một nhiệm vụ nhỏ ("thêm phản hồi 422 vào POST /payments") và xem nó làm gì. Nếu nó đọc đặc tả, chạy make codegen và viết một bài kiểm tra hợp đồng, tệp đang thực hiện công việc của nó.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống