AI Project Context Files: AGENTS.md, CLAUDE.md และ Markdown อื่น ๆ ควรใช้เมื่อไร

ช่วงหลังเครื่องมือ AI coding assistant เก่งขึ้นมากครับ แต่ปัญหาที่ผมเจอบ่อยคือทีมเริ่มมีไฟล์ Markdown หลายแบบเต็ม repository แล้วไม่ชัดว่าแต่ละไฟล์มีหน้าที่อะไร บางโปรเจกต์มี README.md, AGENTS.md, CLAUDE.md, architecture note, runbook, prompt note และ checklist กระจายกันอยู่หลายที่

ตอนแรกดูเหมือนยิ่งใส่ context ให้ AI เยอะยิ่งดี แต่ในทางปฏิบัติ ถ้า context ปนกันเกินไป AI จะอ่านเจอข้อมูลที่เก่า ซ้ำ ขัดกัน หรือเฉพาะเครื่องมือมากเกินไป แล้วเสนอวิธีแก้ที่ดูมั่นใจแต่ไม่ตรงกับ workflow จริงของทีม

สำหรับผม โจทย์ไม่ใช่ว่าควรมีไฟล์พวกนี้หรือไม่ แต่คือควรแยกหน้าที่ให้ชัดว่าอะไรเป็นกติกาถาวรของโปรเจกต์ อะไรเป็นคู่มือสำหรับคน อะไรเป็น runbook สำหรับ incident หรือ deployment และอะไรเป็น note ชั่วคราวที่ไม่ควรกลายเป็นความจริงระยะยาวของ repo

สาระตั้งต้นจากแหล่งข้อมูล

ก่อนเขียนเป็นแนวทาง ผมสรุปแก่นที่ใช้เป็นฐานของบทความนี้ไว้ก่อน:

1. OpenAI Codex ใช้ AGENTS.md เป็นไฟล์ guidance ของ repository หรือ subdirectory เพื่อบอก convention, command, test, style และข้อควรระวังที่ Codex ควรรู้เมื่อทำงานใน codebase
2. Anthropic Claude Code รองรับ CLAUDE.md เป็น project memory หรือ instruction file ที่ช่วยให้ Claude เข้าใจบริบทของโปรเจกต์ เช่น command สำคัญ coding style และ architecture note
3. GitHub Copilot รองรับ repository custom instructions ผ่านไฟล์ Markdown ภายใต้ .github/ เพื่อกำหนดแนวทางเฉพาะของ repository
4. สิ่งที่เหมือนกันคือไฟล์เหล่านี้ควรบอกพฤติกรรมและบริบทที่ stable พอสมควร ไม่ใช่ dump ทุกอย่างที่ทีมอยากให้ AI รู้
5. ถ้า context มีข้อมูลลับ token secret หรือรายละเอียดลูกค้าที่ไม่ควรถูกอ่านโดย automation กว้าง ๆ ไฟล์นั้นไม่ควรถูกใส่ไว้ใน repo context แบบไม่คิด

อย่าเริ่มจากชื่อไฟล์ ให้เริ่มจากหน้าที่

ชื่อไฟล์อาจต่างกันตามเครื่องมือครับ Codex มักพูดถึง AGENTS.md ส่วน Claude Code ใช้ CLAUDE.md บางทีมอาจมี COPILOT_INSTRUCTIONS.md, .github/copilot-instructions.md, README.md, ARCHITECTURE.md หรือ RUNBOOK.md

แต่สิ่งที่ควรถามก่อนคือไฟล์นี้มีหน้าที่อะไร ถ้าแบ่งแบบ practical ผมมักแยกเป็น 5 กลุ่ม:

1. Agent instructions: กติกาที่ AI assistant ควรทำตามเวลาแก้ repo นี้
2. Human onboarding: ข้อมูลให้คนใหม่เข้าใจว่าโปรเจกต์นี้คืออะไรและเริ่มรันอย่างไร
3. Architecture context: เหตุผลการออกแบบ ขอบเขตระบบ และ decision สำคัญ
4. Operational runbook: ขั้นตอนทำงานซ้ำ เช่น deploy, rollback, rotate key หรือเก็บ log
5. Task-local note: ข้อมูลเฉพาะงานปัจจุบัน เช่น bug investigation หรือ migration plan รอบนี้

ถ้าทุกอย่างไปรวมอยู่ในไฟล์เดียว AI อาจได้ context เยอะขึ้น แต่คุณภาพของ context แย่ลง เพราะมันแยกไม่ออกว่าอะไรเป็นกติกาถาวร อะไรเป็น historical note และอะไรเป็นแค่ความคิดชั่วคราว

AGENTS.md ควรเล็ก ชัด และใช้ได้จริง

ถ้า repo ใช้ Codex ผมจะมอง AGENTS.md เป็น instruction file สำหรับพฤติกรรมการทำงานใน repo มากกว่าเป็น encyclopedia ของระบบ สิ่งที่ควรอยู่ในไฟล์นี้คือเรื่องที่ AI ต้องรู้แทบทุกครั้งที่แตะ code เช่น:

1. command สำหรับ install, lint, test, build และ typecheck
2. โครงสร้าง repository แบบย่อ เช่น frontend อยู่ไหน backend อยู่ไหน shared package อยู่ไหน
3. coding convention ที่สำคัญและต่างจากค่า default
4. test expectation เช่นแก้ API ต้องรันชุดไหน แก้ UI ต้องเช็กอะไร
5. security หรือ privacy constraint ที่ห้ามละเลย
6. workflow ของทีม เช่นห้ามแก้ generated file โดยตรง หรือห้ามเปลี่ยน schema โดยไม่มี migration

สิ่งที่ไม่ควรใส่คือรายละเอียดทุก endpoint ทุก component ทุก decision ในอดีต หรือบันทึกประชุมยาว ๆ เพราะ AI จะต้องอ่านของเยอะเกินจำเป็น และทีมจะดูแลไฟล์นี้ยากขึ้นเรื่อย ๆ

กติกาที่ดีควรสั้นพอให้คนในทีมอ่านแล้วเห็นด้วย ถ้าคนยังไม่อ่านเพราะยาวเกินไป AI ก็มีโอกาสได้ context ที่ไม่มีใครตรวจเหมือนกัน

CLAUDE.md หรือไฟล์เฉพาะเครื่องมือควรมีเท่าที่ต่างจริง

บางทีมใช้หลาย assistant พร้อมกัน เช่น Codex, Claude Code, GitHub Copilot หรือเครื่องมือใน IDE จุดที่ต้องระวังคืออย่าทำให้ไฟล์ instruction ของแต่ละเครื่องมือกลายเป็นสำเนาที่เริ่มต่างกันทีละนิด

ถ้าใช้ AGENTS.md และ CLAUDE.md พร้อมกัน ผมแนะนำให้แยกแบบนี้:

1. กติกากลางของ repo ควรอยู่ในไฟล์ที่ทีมถือเป็น source of truth เช่น AGENTS.md หรือ docs/ai-context.md
2. ไฟล์เฉพาะเครื่องมือควรใส่เฉพาะ syntax, workflow หรือข้อจํากัดที่เครื่องมือนั้นต้องรู้เป็นพิเศษ
3. ถ้าข้อมูลเดียวกันต้องมีหลายที่ ให้เขียนสั้นและชี้กลับไปที่ source หลัก แทนการคัดลอกทั้งก้อน
4. review ไฟล์เหล่านี้พร้อมกับการเปลี่ยน command, framework, directory หรือ test workflow

ปัญหาที่เจอบ่อยคือ README.md บอกให้รัน npm test, AGENTS.md บอกให้รัน npm run check, แต่ CLAUDE.md ยังบอกคำสั่งเก่าจากปีที่แล้ว พอ AI ทำงานตามไฟล์ที่เก่า ทีมก็เสียเวลาตามแก้ output ที่ผิดตั้งแต่ต้น

README ยังสำคัญ เพราะคนต้องเข้าใจก่อน AI

ผมไม่คิดว่าไฟล์ AI context ควรมาแทน README.md ครับ README ยังควรเป็นหน้าประตูหลักของโปรเจกต์สำหรับคน โดยเฉพาะคนที่เพิ่ง clone repo หรือกลับมาแตะงานหลังหายไปนาน

README ที่ดีควรตอบคำถามพื้นฐาน:

1. โปรเจกต์นี้ทำอะไร
2. ต้องใช้ runtime หรือ dependency อะไร
3. setup อย่างไร
4. run local อย่างไร
5. test และ build อย่างไร
6. link ไปเอกสารสำคัญอยู่ไหน

ส่วน AGENTS.md หรือ CLAUDE.md ควรช่วย AI ทำงานให้ตรง convention ของ repo ไม่ใช่บังคับให้คนต้องอ่านไฟล์ AI ก่อนถึงจะเริ่มงานได้ ถ้า README อ่อน แต่ agent instruction ยาวมาก แปลว่า project knowledge เริ่มเอียงไปอยู่กับเครื่องมือแทนที่จะอยู่กับทีม

เรื่องนี้เชื่อมกับสิ่งที่ผมเคยเขียนใน เมื่อ AI กลายเป็นเพื่อนร่วมงาน: วิธีใช้ให้เพิ่มคุณภาพ ไม่ใช่แค่เพิ่มความเร็ว เพราะ AI จะช่วยงานได้ดีขึ้นเมื่อ workflow ของคนชัดก่อน แล้วค่อยให้ AI เข้ามาเร่งหรือช่วยตรวจ

Architecture note และ runbook ไม่ควรถูกยัดไว้ใน prompt

Architecture decision, constraint และ runbook มีอายุการใช้งานต่างจาก agent instruction

Architecture note ควรอธิบายเหตุผล เช่นทำไมเลือก database นี้ ทำไมแยก service แบบนี้ ทำไมตัดสินใจไม่ใช้ framework บางตัว และ trade-off สำคัญคืออะไร ข้อมูลแบบนี้ช่วยทั้งคนและ AI แต่ควรอยู่ในไฟล์ที่ review ได้ เช่น docs/architecture.md หรือ ADR

Runbook ควรเป็นขั้นตอนปฏิบัติ เช่น deploy, rollback, restore backup, rotate credential, respond to alert หรือ export log ตอน incident ไฟล์แบบนี้ต้องชัด ตรวจได้ และอัปเดตตามระบบจริง

ถ้าเอา architecture note และ runbook ไปซ่อนใน AGENTS.md ไฟล์เดียว จะเกิดปัญหา 2 อย่าง หนึ่งคือ agent instruction ยาวเกินไป สองคือทีมอาจลืมว่า runbook นั้นเป็นเอกสารปฏิบัติที่ต้องทดสอบและดูแล ไม่ใช่แค่ context ให้ AI อ่าน

ถ้าอยากต่อยอดเรื่อง runbook และการทำงานซ้ำให้น่าเชื่อถือ อ่าน ทำไม Log ถึงสำคัญตอนเกิด Incident มากกว่าที่หลายคนคิด

อย่าใส่ secret และข้อมูลลูกค้าใน context file

ไฟล์ context มักถูกอ่านโดย automation หรือ assistant มากกว่าที่เราคิด ดังนั้นไม่ควรใส่ข้อมูลที่ถ้าหลุดแล้วมีปัญหา เช่น:

1. API key, token, password, private key
2. รายละเอียดลูกค้าหรือข้อมูลส่วนบุคคล
3. vulnerability detail ที่ยังไม่เปิดเผย
4. production log ที่ยังไม่ได้ scrub
5. URL ภายในที่มี credential หรือ token ฝังอยู่
6. วิธี bypass control ที่ไม่ควรเผยแพร่กว้างใน repo

ถ้าต้องให้ AI รู้ข้อจำกัดด้านความปลอดภัย ให้เขียนเป็น rule เช่น "ห้าม hardcode secret", "ใช้ environment variable จาก vault", "อย่า log token หรือข้อมูลส่วนบุคคล" แทนการใส่ secret หรือข้อมูลจริงลงไป

มุมนี้ใกล้กับ AI Governance สำหรับทีมเล็ก: ไม่ต้องมีเอกสารร้อยหน้า แต่ต้องมีขอบเขต และ Shadow AI ในทีมเล็ก: Productivity เพิ่มขึ้น แต่ข้อมูลอาจไหลออกแบบเงียบ ๆ เพราะ context ที่ดีต้องช่วยลดความเสี่ยง ไม่ใช่เพิ่มช่องทางให้ข้อมูลสำคัญถูกอ่านโดยไม่จำเป็น

ตัวอย่างโครงสร้างที่ผมมองว่าใช้ได้จริง

สำหรับ repo ขนาดเล็กถึงกลาง ผมจะเริ่มแบบนี้:

README.md
AGENTS.md
CLAUDE.md
docs/
  architecture.md
  decisions/
    0001-use-postgres.md
  runbooks/
    deploy.md
    rollback.md
    rotate-secrets.md

README.md เป็นทางเข้าของคน AGENTS.md เป็นกติกากลางสำหรับ AI ใน repo CLAUDE.md ใส่เฉพาะสิ่งที่ Claude Code ต้องรู้ต่างจากกติกากลาง docs/architecture.md อธิบายภาพระบบ และ docs/runbooks/ เก็บขั้นตอนปฏิบัติ

ถ้า repo เล็กมาก อาจไม่ต้องมีครบทั้งหมดก็ได้ เริ่มจาก README ที่ดี แล้วเพิ่ม AGENTS.md เมื่อเริ่มใช้ Codex จริง เพิ่ม CLAUDE.md เมื่อใช้ Claude Code จริง และค่อยแยก architecture หรือ runbook เมื่อข้อมูลเริ่มยาวหรือเริ่มมีผลต่อการปฏิบัติงานจริง

Checklist ก่อนเพิ่ม context file ใหม่

ก่อนสร้างไฟล์ใหม่ ผมจะถาม 8 ข้อนี้:

1. ไฟล์นี้มีผู้อ่านหลักเป็นคนหรือ AI
2. ข้อมูลในไฟล์นี้ stable แค่ไหน
3. มี source of truth ที่ซ้ำอยู่แล้วหรือไม่
4. ถ้าข้อมูลนี้เก่า จะทำให้ AI แนะนำผิดหรือไม่
5. ไฟล์นี้ควรอยู่ระดับ repo หรือเฉพาะ subdirectory
6. มีข้อมูลลับหรือข้อมูลลูกค้าปนอยู่หรือไม่
7. ใครเป็น owner ที่จะอัปเดตเมื่อ command หรือ architecture เปลี่ยน
8. ต้องเพิ่ม validation command อะไรให้ AI ทำตามหลังแก้ code

ถ้าตอบไม่ได้ว่าใครดูแลและจะอัปเดตเมื่อไร ไฟล์นั้นอาจกลายเป็น technical debt ในรูปแบบเอกสาร

อ่านต่อที่เกี่ยวข้อง

• ถ้าอยากวาง AI ไว้ใน workflow ที่มี judgement อ่าน เมื่อ AI กลายเป็นเพื่อนร่วมงาน: วิธีใช้ให้เพิ่มคุณภาพ ไม่ใช่แค่เพิ่มความเร็ว
• ถ้าต้องการขอบเขตการใช้ AI ในทีมเล็ก อ่าน AI Governance สำหรับทีมเล็ก: ไม่ต้องมีเอกสารร้อยหน้า แต่ต้องมีขอบเขต
• ถ้ากังวลเรื่องข้อมูลไหลออกจากการใช้ AI อ่าน Shadow AI ในทีมเล็ก: Productivity เพิ่มขึ้น แต่ข้อมูลอาจไหลออกแบบเงียบ ๆ

สรุป

AI project context files มีประโยชน์มาก แต่จะมีประโยชน์จริงเมื่อเราไม่ใช้มันเป็นที่ทิ้งข้อมูลทุกอย่างของโปรเจกต์ AGENTS.md หรือ CLAUDE.md ควรช่วยให้ assistant ทำงานตาม convention ของ repo ได้ดีขึ้น ส่วน README, architecture note และ runbook ควรยังมีหน้าที่ของตัวเอง

หลักง่าย ๆ คือให้ context สั้น ชัด stable และมี owner ถ้าเป็นกติกาถาวรของ repo ใส่ใน agent instruction ได้ ถ้าเป็นคู่มือคน ให้ README หรือ docs รับผิดชอบ ถ้าเป็นเหตุผลการออกแบบ ให้เก็บใน architecture note หรือ ADR ถ้าเป็นขั้นตอนปฏิบัติ ให้ทำ runbook และถ้าเป็นข้อมูลเฉพาะงานปัจจุบัน ให้เก็บเป็น task note ไม่ใช่ยัดเข้า context ถาวร

เมื่อไฟล์แต่ละประเภทมีหน้าที่ชัด AI จะช่วยงานได้แม่นขึ้น คนในทีมก็เข้าใจระบบดีขึ้น และ repository จะไม่กลายเป็นกอง Markdown ที่ทุกคนกลัวจะแก้เพราะไม่รู้ว่าไฟล์ไหนเป็นความจริงล่าสุด

แหล่งอ้างอิง

• OpenAI Codex: Customization and AGENTS.md
• Anthropic Claude Code: Manage Claude's memory
• GitHub Docs: Add repository custom instructions for Copilot
• AWS Well-Architected: Use runbooks to perform procedures