AGENTS.md สำหรับ Codex และ Claude Code ควรเขียนอะไรและย้ายอะไรไปไว้ใน Skills

เอเจนต์เขียนโค้ด AI อาจอ่านโค้ดจนเข้าใจโครงสร้างโปรเจกต์ได้ค่อนข้างดี แต่ยังเสนอวิธีแก้ปัญหาที่ไม่เหมาะกับโปรเจกต์นั้นอยู่ดี

สมมติว่าเราต้องแก้อินเทอร์เฟซของไลบรารีภายในองค์กร แทนที่จะแก้เพียงเล็กน้อย เอเจนต์ กลับเพิ่มเมธอดที่ติด deprecated สร้างชั้นสำหรับรักษาความเข้ากันได้ และวางแผนย้ายระบบ (migration) ทั้งชุด ทั้งที่ไลบรารีนี้มีแอปใช้อยู่ไม่กี่ตัว และสามารถอัปเดตพร้อมกันได้ทั้งหมด

ในทางกลับกัน เอเจนต์ อาจแก้ API สาธารณะ โดยไม่รู้ว่ามีนักพัฒนาภายนอกใช้งานอยู่

ปัญหาแบบนี้ไม่ได้หมายความว่าโมเดลเขียนโค้ดไม่เก่งเสมอไป ข้อจำกัดบางอย่างของโปรเจกต์มองไม่เห็นจาก ซอร์สโค้ด โดยตรง นี่จึงเป็นเหตุผลที่ AGENTS.md น่าสนใจ เราอยากบอกสิ่งสำคัญเกี่ยวกับ รีโพซิทอรี ให้ เอเจนต์ รู้ล่วงหน้า แต่ก็ไม่อยากสร้างเอกสารอีกชุดที่ต้องคอยดูแลตลอดเวลา

AGENTS.md ทำงานอย่างไร

ตัว AGENTS.md เองเป็นเพียงไฟล์ Markdown ธรรมดา เราสามารถเขียนว่าโปรเจกต์นี้ทำอะไร มีข้อจำกัดอะไร และมีข้อตกลงใดที่ เอเจนต์ ควรคำนึงถึงเวลาแก้โค้ด

สิ่งที่ทำให้ไฟล์นี้มีประโยชน์คือเครื่องมืออย่าง Codex และ Claude Code สามารถค้นหาไฟล์และนำเนื้อหาไปใช้เป็นคำสั่งเพิ่มเติมให้โมเดลได้ เราจึงไม่ต้องพิมพ์กฎของโปรเจกต์ซ้ำในทุกคำขอ

โดยทั่วไปจะวาง AGENTS.md ไว้ที่ระดับบนสุดของรีโพซิทอรี และอาจเพิ่มไฟล์ในโมดูลที่มีข้อกำหนดเฉพาะ

ตัวอย่างโครงสร้างโปรเจกต์

MyApp/
├── AGENTS.md
├── Sources/
├── Features/
└── MyAppUI/
    └── AGENTS.md

ไฟล์ระดับบนสุด อธิบายข้อจำกัดโดยรวมของแอป ส่วนไฟล์ที่อยู่ใน MyAppUI อธิบายกฎของไลบรารี UI นี้โดยเฉพาะ

ทั้ง Codex และ Claude Code รองรับ AGENTS.md แล้ว แต่รายละเอียดการโหลดคำสั่งไม่เหมือนกัน Codex พิจารณาลำดับชั้นของไฟล์ตามไดเรกทอรีที่ทำงานอยู่ ส่วน Claude Code รองรับ AGENTS.md พร้อมกับยังมีรูปแบบ CLAUDE.md ของตัวเอง

ถ้า รีโพซิทอรี มีทั้งสองไฟล์ ควรตรวจสอบการตั้งค่าและลำดับความสำคัญของคำสั่ง โดยเฉพาะเมื่อคนในทีมใช้ เอเจนต์เขียนโค้ด AI คนละตัว

อย่างไรก็ตาม AGENTS.md ไม่ใช่ตัวตรวจโค้ดอัตโนมัติ (linter) โมเดลได้รับคำสั่งก็จริง แต่ไม่ได้รับประกันว่าจะทำตามทุกข้อ อีกทั้งเนื้อหาในไฟล์ยังใช้พื้นที่บริบท และอาจทำให้ใช้โทเคนมากขึ้น

หลักการจึงไม่ซับซ้อน เราให้ข้อมูลบางอย่างเกี่ยวกับโปรเจกต์ไว้ก่อน แล้ว เอเจนต์ นำไปใช้ร่วมกับงานที่ได้รับและโค้ดที่ค้นพบ

คำถามที่ยากกว่าคือควรใส่ข้อมูลอะไรลงไป

ควรเขียนอะไรใน AGENTS.md

เอเจนต์เขียนโค้ด AI สมัยนี้สำรวจ รีโพซิทอรี ได้เองแล้ว มันเปิด Package.swift ค้นหาเทสต์ ดูไลบรารีที่พึ่งพา และไล่ความสัมพันธ์ระหว่างคอมโพเนนต์ ได้

ผมจึงไม่คิดว่าควรนำโครงสร้างโปรเจกต์ทั้งหมดมาเขียนซ้ำใน AGENTS.md โดยเฉพาะข้อมูลที่หาได้ง่ายจากโค้ด

ข้อมูลที่น่าสนใจกว่าคือสิ่งที่อาจไม่มีอยู่ใน ซอร์สโค้ด เลย

ลองนึกถึง รีโพซิทอรี แยกชื่อ MySDK ซึ่งเป็นไลบรารี Swift แบบสาธารณะ แจกจ่ายให้ผู้พัฒนาภายนอกผ่าน Swift Package Manager

AGENTS.md ของโปรเจกต์นี้อาจเริ่มด้วยข้อความสั้น ๆ ดังนี้

# Project

MySDK is a public Swift SDK distributed
through Swift Package Manager.

Third-party applications depend on its public API.

## Constraints

- Preserve public API compatibility.
- Do not introduce breaking changes without approval.
- Keep the SDK independent of application-specific code.

ไม่มีอะไรซับซ้อน แต่เมื่อ เอเจนต์ จะแก้ เมธอดสาธารณะ มันมีเหตุผลที่จะต้องคำนึงถึงความเข้ากันได้

ถ้า MySDK เป็นไลบรารีภายในองค์กร กฎอาจต่างออกไป

สมมติว่าทีมควบคุมแอปทั้งหมดที่ใช้ SDK และสามารถประสานการปล่อยเวอร์ชันได้ บางครั้งการแก้อินเทอร์เฟซแล้วอัปเดตทุกแอปก็ง่ายกว่าการรักษา API เก่าไว้

แน่นอนว่าไลบรารีภายในไม่ได้เป็นแบบนี้ทั้งหมด ถ้ามีแอปหลายสิบตัวที่ปล่อยเวอร์ชันแยกกัน ข้อกำหนดด้านความเข้ากันได้ อาจเข้มงวดเกือบเท่า SDK สาธารณะ

ความแตกต่างลักษณะนี้ต่างหากที่ควรบันทึกไว้

เอเจนต์ มองเห็นได้ว่าเมธอดเขียนอย่างไร แต่จะรู้เองได้ยากว่าเมธอดนั้นเปลี่ยนได้มากแค่ไหน

เรื่องสถาปัตยกรรมก็คล้ายกัน หากมีข้อจำกัดที่ค่อนข้างคงที่และดูจากโค้ดไม่ชัด ก็ควรเขียนไว้ ส่วนรายชื่อคลาส หน้าจอ และการพึ่งพาปัจจุบันทั้งหมดอาจไม่ได้ช่วยมากนัก

และปัญหาไม่ได้มีแค่ความยาวของไฟล์

ทำไมคำสั่งที่ยาวเกินไปอาจเป็นปัญหา

AGENTS.md สามารถกลายเป็นเอกสารโปรเจกต์ที่พองขึ้นเรื่อย ๆ ได้ง่าย

ตอนแรกมีเพียงกฎไม่กี่ข้อ ต่อมา เอเจนต์ ทำผิด เราก็เพิ่มคำสั่ง อีกสัปดาห์มันสร้างชั้นนามธรรม (abstraction) ที่ไม่จำเป็น ก็เพิ่มอีกข้อ ไม่นานก็มีทั้งเรื่องเทสต์ การจัดการข้อผิดพลาด การตั้งชื่อ และการรีแฟกเตอร์

สุดท้ายไฟล์อาจยาวหลายร้อยบรรทัด

ปัญหาคือ เอเจนต์ อาจได้รับคำสั่งส่วนใหญ่เหล่านี้ แม้งานตรงหน้าจะไม่เกี่ยวข้องเลย

มีงานวิจัยที่น่าสนใจเกี่ยวกับเรื่องนี้

เดือนกุมภาพันธ์ 2026 นักวิจัยจาก ETH Zürich เผยแพร่งาน Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?

งานนี้ศึกษาผลของคำสั่งระดับรีโพซิทอรี ต่อ เอเจนต์เขียนโค้ด ภายใต้เงื่อนไขการทดลอง ไฟล์ที่สร้างโดยอัตโนมัติทำให้อัตราความสำเร็จลดลงเล็กน้อย ส่วนไฟล์ที่นักพัฒนาเขียนเองช่วยได้เพียงเล็กน้อย ขณะเดียวกันต้นทุนการประมวลผลของโมเดล (inference) เพิ่มขึ้นประมาณ 20% หรือมากกว่า

เอเจนต์ ทำตามคำสั่งจริง มันสำรวจ รีโพซิทอรี มากขึ้น ทำงานเพิ่มเติม และรันการตรวจสอบเพิ่ม แต่กิจกรรมเหล่านั้นไม่ได้ทำให้ผลลัพธ์ดีขึ้นเสมอไป

อีกงานหนึ่งชื่อ On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents ซึ่งเผยแพร่ในเดือนมกราคม 2026 รายงานว่าเวลามัธยฐานในการทำงานลดลง 28.64%

งานทั้งสองใช้วิธีทดลองต่างกัน จึงไม่ควรนำตัวเลขมาเทียบกันตรง ๆ แต่ก็ชี้ว่าการมี AGENTS.md ไม่ได้ทำให้ เอเจนต์ ทำงานดีขึ้นโดยอัตโนมัติ

ในเดือนมกราคม 2026 Matt Pocock ก็เสนอให้ทบทวน AGENTS.md และ CLAUDE.md โดยตัดคำสั่งที่ขัดแย้งกัน คำแนะนำที่รู้อยู่แล้ว และกฎที่ไม่จำเป็นต้องโหลดทุกครั้ง

ลองดูตัวอย่างนี้

## Guidelines

- Write clean code.
- Follow SOLID principles.
- Use meaningful names.
- Avoid bugs.

ทุกข้อฟังดูถูกต้อง แต่แทบไม่ได้บอกอะไรเกี่ยวกับโปรเจกต์นี้โดยเฉพาะ

ถึงอย่างนั้นผมก็ไม่คิดว่าควรลบบริบทของโปรเจกต์ทั้งหมด ข้อความไม่กี่บรรทัดเกี่ยวกับหน้าที่ของ รีโพซิทอรี และข้อจำกัดของ API สาธารณะ อาจมีประโยชน์กว่าคำแนะนำทั่วไปหลายหน้า

อีกเหตุผลที่ไม่ควรเขียนละเอียดเกินไปคือข้อมูลล้าสมัยได้

สมมติว่าเราอธิบายสถาปัตยกรรมของแอป ระบบนำทาง หน้าจอหลัก และตำแหน่งเซอร์วิสต่าง ๆ ลงใน AGENTS.md

ผ่านไปไม่กี่เดือน บางโมดูลถูกเขียนใหม่ การนำทางเปลี่ยนไป และคอมโพเนนต์บางส่วนถูกย้ายออกเป็น Swift Package

โค้ดเปลี่ยนแล้ว แต่ไฟล์คำสั่งยังเหมือนเดิม

เอเจนต์ จึงอาจเชื่อคำอธิบายที่ล้าสมัย แทนที่จะตรวจสอบโค้ดปัจจุบัน

เรื่องนี้ยิ่งยุ่งยากในแอปขนาดใหญ่ที่ใช้หลายรูปแบบสถาปัตยกรรม บางโมดูลใช้ SwiftUI บางส่วนใช้ UIKit และอีกส่วนมีวิธีจัดการการนำทาง ของตัวเอง

การประกาศกฎสถาปัตยกรรมเดียวสำหรับทั้งแอปใน AGENTS.md ระดับบนสุด อาจสร้างปัญหามากกว่าช่วยแก้

ผมจึงอยากเก็บคำสั่งให้สั้นและคงทนพอที่จะไม่ต้องแก้ทุกครั้งที่รีแฟกเตอร์

แยกคำสั่งตามโมดูล

กลับมาที่ MyApp กัน

สมมติว่าแอปมีขนาดใหญ่พอที่จะมีไลบรารีคอมโพเนนต์ UI ของตัวเองชื่อ MyAppUI

MyApp/
├── AGENTS.md
├── App/
├── Features/
│   ├── Checkout/
│   └── Vouchers/
└── Packages/
    ├── MyAppUI/
    │   └── AGENTS.md
    └── MyAnalytics/
        └── AGENTS.md

AGENTS.md ระดับบนสุด อธิบายแอปและข้อจำกัดร่วมกัน

ส่วนภายใน MyAppUI เราอาจระบุว่าคอมโพเนนต์ต้องนำกลับมาใช้ซ้ำได้ และไม่ควรผูกกับหน้าจอใดหน้าจอหนึ่งของแอป

# MyAppUI

This package contains reusable UI components
used across multiple application features.

## Constraints

- Keep components independent of feature-specific logic.
- Avoid dependencies on application navigation.
- Preserve existing component APIs unless a change is approved.

สำหรับ MyAnalytics กฎย่อมต่างกัน เช่น ไม่ควรพึ่งพา UI หรือมีตรรกะทางธุรกิจของฟีเจอร์ใดฟีเจอร์หนึ่ง

ข้อดีคือคำสั่งแต่ละชุดอยู่ใกล้ส่วนของโปรเจกต์ที่เกี่ยวข้อง ถ้ากฎของ MyAppUI เปลี่ยน ก็ไม่จำเป็นต้องแก้ไฟล์หลักของแอป

แต่ผมจะไม่สร้าง AGENTS.md ทุกไดเรกทอรี ไฟล์แยกควรมีเมื่อมีข้อจำกัดเฉพาะที่สำคัญจริง ๆ ไม่อย่างนั้นเราจะเปลี่ยนจากเอกสารใหญ่หนึ่งไฟล์เป็นเอกสารเล็กสิบไฟล์ที่ต้องดูแลเหมือนกัน

ถ้าเป็นหลาย รีโพซิทอรี ก็ใช้แนวคิดเดียวกัน

สมมติว่า MyApp, MyAppUI และ MySDK อยู่คนละ รีโพซิทอรี แต่ละโปรเจกต์มีหน้าที่และข้อจำกัดต่างกัน การมี AGENTS.md ของตัวเองจึงสมเหตุสมผล

แต่ถ้าทั้งสามโปรเจกต์ใช้กฎการทดสอบหรือการรีแฟกเตอร์แบบเดียวกัน การคัดลอกคำสั่งชุดใหญ่ไปทุกที่คงไม่ใช่ทางเลือกที่ดี เพราะเนื้อหาจะค่อย ๆ แตกต่างกันเมื่อเวลาผ่านไป

ตรงนี้เองที่ Skills เข้ามาช่วยได้

ควรย้ายอะไรไปไว้ใน Skills

สมมติว่าโปรเจกต์ Swift ของทีมมีแนวทางเขียนยูนิตเทสต์ร่วมกัน ทั้งการจัดข้อมูลตั้งต้นสำหรับเทสต์ (fixture) การใช้อ็อบเจกต์จำลอง (mock) การทดสอบโค้ดแบบอะซิงโครนัส และการใช้ Swift Testing

เราสามารถเขียนรายละเอียดหลายหน้าลงใน AGENTS.md ได้

แต่ทำไม เอเจนต์ ต้องอ่านคำสั่งการทดสอบทั้งหมด ในเมื่อกำลังแก้คอมโพเนนต์ UI เล็ก ๆ อยู่?

เนื้อหาแบบนี้เหมาะกับ Skills มากกว่า

.agents/
└── skills/
    ├── swift-testing/
    │   └── SKILL.md
    ├── api-compatibility/
    │   └── SKILL.md
    └── code-quality/
        └── SKILL.md

Skill มี metadata ที่อธิบายว่าใช้เมื่อไร และมีคำสั่งรายละเอียดสำหรับงานนั้น เอเจนต์ สามารถดูคำอธิบายเพื่อเลือก Skill ที่เกี่ยวข้อง แล้วค่อยโหลดเนื้อหาเมื่อจำเป็น

จึงไม่ต้องเก็บทุกขั้นตอนเอาไว้ในบริบท ตลอดเวลา

ตัวอย่างเช่น swift-testing เก็บแนวทางการทดสอบของทีม code-quality อธิบายเรื่องความอ่านง่าย การจัดการข้อผิดพลาด และการรีแฟกเตอร์ ส่วน api-compatibility เก็บขั้นตอนตรวจสอบ อินเทอร์เฟซสาธารณะ

Skill เดียวกันอาจนำไปใช้กับหลาย รีโพซิทอรี ได้ ขึ้นอยู่กับเครื่องมือและวิธีติดตั้ง

แต่ต้องแยกหน้าที่ของ AGENTS.md กับ Skills ให้ชัด

ถ้า รีโพซิทอรี เป็น SDK สาธารณะ เอเจนต์ ควรรู้ตั้งแต่แรกว่าต้องรักษา ความเข้ากันได้ของ API ไม่ว่าจะเลือกโหลด Skill ที่เกี่ยวข้องหรือไม่

ผมจึงจะเก็บข้อจำกัดนี้ไว้ใน AGENTS.md และย้ายขั้นตอนตรวจสอบอย่างละเอียดไปไว้ใน Skill

วิธีนี้ก็ไม่ได้สมบูรณ์แบบ เอเจนต์ อาจเลือก Skill ผิดหรือไม่เลือกเลย และแต่ละเครื่องมือก็มีวิธีค้นหาและโหลด Skills ต่างกัน แต่การแยกบริบทที่ต้องรู้อยู่เสมอออกจากขั้นตอนเฉพาะงานยังเป็นแนวทางที่สมเหตุสมผล

ใครควรเขียน AGENTS.md

แล้วควรให้ เอเจนต์ สร้าง AGENTS.md เองหรือไม่?

ฟังดูสะดวก เพราะมันอ่าน รีโพซิทอรี วิเคราะห์รูปแบบสถาปัตยกรรม และร่างไฟล์ได้ในไม่กี่นาที

แต่มีปัญหาอย่างหนึ่ง เอเจนต์ มองเห็นโค้ดที่มีอยู่ โดยไม่รู้เสมอไปว่าทีมยังเห็นด้วยกับแนวทางไหน และแนวทางไหนเป็นของเก่าที่กำลังพยายามเลิกใช้

สมมติว่าในโปรเจกต์มีคลาสจำนวนมากที่ลงท้ายด้วย Manager โมเดลอาจสรุปว่านี่คือ ข้อตกลงการตั้งชื่อ และเขียนเป็นกฎลงไป

ทั้งที่ทีมอาจพยายามเลิกใช้ชื่อแบบนี้มานานแล้ว

เรื่องเดียวกันเกิดได้กับซิงเกิลตัน รูปแบบสถาปัตยกรรม และการแบ่งโมดูล สิ่งที่มีอยู่ใน รีโพซิทอรี ไม่ได้แปลว่าควรนำไปใช้ซ้ำเสมอ

ผมไม่ติดที่จะใช้ AI ช่วยร่างไฟล์ เช่น ให้มันเสนอข้อจำกัดที่อาจสำคัญ พร้อมชี้ไปยังโค้ดหรือเอกสารที่ใช้เป็นหลักฐาน

แต่ข้อความสุดท้ายควรผ่านการตรวจและแก้ไขโดยนักพัฒนา

ผมก็จะไม่เพิ่มกฎใหม่ทุกครั้งที่ เอเจนต์ ทำงานพลาด ถ้ามันสร้างชั้นนามธรรมที่ไม่จำเป็น ควรหาสาเหตุก่อน บางทีการเขียนคำขอ ให้ชัดขึ้นหรือชี้ไปยังโค้ดที่มีอยู่ก็เพียงพอ

ควรเพิ่ม AGENTS.md เมื่อพบข้อผิดพลาดซ้ำ ๆ ที่เกิดจากข้อจำกัดของโปรเจกต์ซึ่ง เอเจนต์ จำเป็นต้องรู้ล่วงหน้า

สรุป

AGENTS.md ใช้ได้ดีที่สุดเมื่อสั้นและบอกเพียงหน้าที่ของรีโพซิทอรีกับข้อจำกัดที่มองไม่เห็นจากโค้ด ส่วนขั้นตอนละเอียดควรย้ายไปไว้ใน Skills และถ้าให้ AI ช่วยร่าง ก็ต้องให้คนตรวจทุกครั้ง

ควรลองพิสูจน์ด้วยว่าไฟล์นี้ช่วยได้จริงไหม แค่เปรียบเทียบงานตัวอย่างไม่กี่งานทั้งแบบมีและไม่มีคำสั่งก็พอ ถ้าไม่ต่างกัน ก็ไม่มีเหตุผลต้องดูแลไฟล์นี้

---

อ่านเพิ่มเติม

• AGENTS.md และ เอกสาร Codex เกี่ยวกับรูปแบบไฟล์และการโหลดคำสั่งของโปรเจกต์
• Claude Code Memory เกี่ยวกับ AGENTS.md, CLAUDE.md และคำสั่งระดับโปรเจกต์
• Matt Pocock, มกราคม 2026 เกี่ยวกับการลดคำสั่งที่ไม่จำเป็น
• Evaluating AGENTS.md, กุมภาพันธ์ 2026 งานวิจัยผลของคำสั่งระดับรีโพซิทอรี ต่อ เอเจนต์เขียนโค้ด
• On the Impact of AGENTS.md Files, มกราคม 2026 งานวิจัยด้านประสิทธิภาพของ AGENTS.md
• Anthropic Agent Skills แนวทางจัดคำสั่งเฉพาะงาน