หลักการและวิธีการเขียน AGENTS.md สำหรับ AI Agents
หลักการออกแบบและเขียน AGENTS.md เพื่อใช้เป็นคำสั่งกลางสำหรับ AI Agents หลายระบบ เช่น Claude Code, Codex, thClaws และ AI Agent CLI อื่น ๆ ที่รองรับ project instruction file
1. AGENTS.md คืออะไร
AGENTS.md คือเอกสารคำสั่งประจำโปรเจกต์สำหรับ AI Agent
หน้าที่หลักคือบอก agent ว่า:
- โปรเจกต์นี้คืออะไร
- ใช้เทคโนโลยีอะไร
- ต้องติดตั้งและรันอย่างไร
- ต้องทดสอบอย่างไร
- โครงสร้างไฟล์สำคัญอยู่ตรงไหน
- มีกฎการเขียนโค้ดอย่างไร
- มีข้อห้ามหรือข้อควรระวังอะไร
- หลังทำงานเสร็จควรรายงานผลแบบไหน
พูดให้สั้นที่สุด:
README.mdใช้สำหรับมนุษย์อ่านAGENTS.mdใช้สำหรับ AI Agent อ่านก่อนทำงานในโปรเจกต์
2. เป้าหมายของ AGENTS.md
เป้าหมายของ AGENTS.md ไม่ใช่การอธิบายทุกอย่างของโปรเจกต์ แต่คือการให้ instruction ที่ agent ต้องใช้ซ้ำทุกครั้ง
ควรทำให้ agent เข้าใจได้ทันทีว่า:
- ต้องเริ่มจากตรงไหน
- ควรแก้ไฟล์แบบไหน
- ห้ามแก้อะไร
- ต้องรันคำสั่งอะไรหลังแก้ไข
- ต้องรายงานผลอย่างไร
- ถ้างานซับซ้อนต้องใช้ workflow อะไร
- ถ้ามี skill เฉพาะทาง ต้องเลือกใช้ skill ใด
3. หลักการเขียน AGENTS.md ที่ดี
3.1 เขียนให้สั้น ชัด และสั่งได้จริง
AI Agent ทำงานได้ดีเมื่อ instruction มีความชัดเจน ไม่คลุมเครือ และตรวจสอบได้
ไม่ควรเขียนแบบนี้:
Please write good code and be careful.
ควรเขียนแบบนี้:
After modifying TypeScript files, run:
- pnpm lint
- pnpm typecheck
- pnpm test
ไม่ควรเขียนแบบนี้:
Be careful with database files.
ควรเขียนแบบนี้:
Do not edit existing migration files. Create a new migration instead.
3.2 ใช้คำสั่งแบบ Do / Do not
AGENTS.md ควรเขียนเป็น rule ที่ agent ทำตามได้ทันที
ตัวอย่าง:
## Working Rules
- Do inspect existing code before editing.
- Do make minimal, focused changes.
- Do follow existing naming conventions.
- Do not reformat unrelated files.
- Do not add new dependencies without approval.
- Do not commit changes unless explicitly asked.
3.3 แยก instruction ถาวรออกจาก workflow เฉพาะงาน
สิ่งที่ควรอยู่ใน AGENTS.md:
- Project overview
- Tech stack
- Folder structure
- Setup command
- Development command
- Test command
- Coding convention
- Safety rules
- Git/change policy
- Final response format
- Skill selection rules
สิ่งที่ไม่ควรอยู่ใน AGENTS.md:
- prompt เฉพาะงานที่ยาวมาก
- workflow เฉพาะทาง เช่น เขียน blog, ตรวจ KYC, สร้าง image prompt
- business document ขนาดใหญ่
- reference ยาว ๆ
- policy หรือ rule ที่ใช้เฉพาะบาง task
- script logic ที่ควรอยู่ในไฟล์ script
สิ่งเหล่านี้ควรแยกไปไว้ใน:
skills/<skill-name>/SKILL.md
skills/<skill-name>/references/
skills/<skill-name>/scripts/
docs/
3.4 AGENTS.md ควรเป็น Project Operating Manual
ให้คิดว่า AGENTS.md คือคู่มือปฏิบัติงานของ agent สำหรับ repo นี้
Agent ควรอ่านแล้วรู้ว่า:
- ต้อง setup อย่างไร
- ใช้ command อะไร
- test อะไร
- code style เป็นแบบไหน
- ห้ามทำอะไร
- ต้องรายงานอะไรกลับมา
ไม่ควรทำให้ AGENTS.md กลายเป็นบทความยาวหรือเอกสาร marketing
3.5 ใช้ command ที่รันได้จริง
ควรใส่ command ที่ copy ไป run ได้ทันที
ตัวอย่าง:
## Commands
Install dependencies:
```bash
pnpm install
Run development server:
pnpm dev
Run checks:
pnpm lint
pnpm typecheck
pnpm test
หากมี script ที่ปลอดภัยกว่า raw command ให้ระบุชัดเจน
ตัวอย่าง:
```md
Do not run long-lived commands directly.
Use the safe scripts instead:
```bash
./skills/testing-safe-runner/scripts/test-safe.sh
./skills/testing-safe-runner/scripts/test-e2e.sh
./skills/testing-safe-runner/scripts/kill-dev.sh
4. AGENTS.md กับระบบต่าง ๆ
4.1 Codex
Codex รองรับ AGENTS.md โดยตรง
แนวทางที่เหมาะสมสำหรับ Codex:
~/.codex/AGENTS.md # global user preferences
project/AGENTS.md # project rules
project/apps/web/AGENTS.md # frontend-specific rules
project/apps/api/AGENTS.md # backend-specific rules
หลักการ:
- ใช้ root
AGENTS.mdสำหรับ rule กลางของ project - ใช้
AGENTS.mdย่อยใน folder เฉพาะ เมื่อ frontend/backend มี rule ต่างกัน - ไฟล์ที่อยู่ใกล้ working directory มากกว่าควรมี rule เฉพาะกว่า
- หลีกเลี่ยงการทำไฟล์ยาวเกินจำเป็น
- แยก workflow ยาวไปเป็น Skills
4.2 Claude Code
Claude Code ใช้ไฟล์หลักชื่อ CLAUDE.md แต่สามารถใช้ AGENTS.md เป็น instruction กลางของ repo ได้ โดยออกแบบให้ CLAUDE.md อ้างอิงหรือสรุปจาก AGENTS.md
โครงสร้างที่แนะนำ:
project-root/
├── AGENTS.md
├── CLAUDE.md
├── .claude/
│ └── rules/
├── skills/
│ └── <skill-name>/
│ └── SKILL.md
└── src/
แนวทาง:
- ให้
AGENTS.mdเป็น source of truth กลาง - ให้
CLAUDE.mdเป็น compatibility layer สำหรับ Claude Code - ใช้
.claude/rules/สำหรับ rule เฉพาะ path หรือ file type - ใช้ Skills สำหรับ workflow เฉพาะทาง
ตัวอย่าง CLAUDE.md แบบสั้น:
# CLAUDE.md
Follow the project instructions in `AGENTS.md`.
Additional Claude Code rules:
- Prefer reading relevant files before editing.
- Use existing project scripts where possible.
- Do not run destructive commands without explicit approval.
4.3 thClaws
thClaws สามารถใช้ AGENTS.md, SKILL.md, MCP, Plugins และ local project context ร่วมกันได้
สำหรับ thClaws ควรออกแบบ AGENTS.md ให้เป็น:
- root instruction ของโปรเจกต์
- กฎกลางสำหรับ agent workspace
- ตัวกำหนดว่าเมื่อเจองานประเภทใดต้องใช้ skill ใด
- ตัวกำหนด safe command และ local workflow
- ตัวเชื่อมระหว่าง project, skills, scripts, references และ MCP tools
โครงสร้างที่แนะนำสำหรับ thClaws:
project-root/
├── AGENTS.md
├── README.md
├── docs/
├── skills/
│ ├── testing-safe-runner/
│ │ ├── SKILL.md
│ │ └── scripts/
│ ├── source-capture/
│ │ ├── SKILL.md
│ │ ├── scripts/
│ │ └── references/
│ └── blog-writer/
│ ├── SKILL.md
│ └── references/
└── src/
แนวคิดสำคัญ:
AGENTS.mdบอก agent ว่าใน project นี้ต้องทำงานอย่างไรSKILL.mdบอก agent ว่าเมื่องานเฉพาะประเภทนี้ ให้ทำตาม workflow ใด
Comments ()