DESIGN.md คืออะไร และทำไมต้องใช้คู่กับ AGENTS.md

DESIGN.md คืออะไร และสิ่งที่ AGENTS.md ไม่ได้ครอบคลุมถึง

DESIGN.md เป็นไฟล์ markdown ที่อยู่ใน root ของ repository ซึ่งทำหน้าที่อธิบายให้ AI coding agent ทราบว่าเหตุใดโค้ดจึงมีโครงสร้างเช่นนั้น ส่วน AGENTS.md จะตอบคำถามในอีกแง่มุมหนึ่ง คือวิธีการทำงานในโปรเจกต์นี้ ซึ่งรวมถึงคำสั่ง build, คำสั่งทดสอบ, การ lint ที่ต้องผ่าน และ path ที่ห้ามเข้าไปยุ่ง DESIGN.md จะบันทึกการตัดสินใจที่ได้ข้อสรุปแล้ว รวมถึงผลกระทบที่จะเกิดขึ้นหากมีการยกเลิกการตัดสินใจเหล่านั้น

Coding agent ซึ่งหมายถึงเครื่องมืออย่าง Claude Code หรือ Cursor ที่สามารถอ่านและแก้ไข repository ได้ด้วยตนเองนั้น โดยปกติจะมีความมั่นใจสูง หากมันพบรูปแบบที่ดูไม่คุ้นเคย มันจะพยายามปรับปรุงรูปแบบนั้น ตัวอย่างเช่น มันอาจเปลี่ยน cache ที่เขียนขึ้นเองให้กลายเป็น Redis (data store ในหน่วยความจำ) เพราะนั่นคือสิ่งที่ cache มักจะเป็นในโค้ดส่วนใหญ่ที่โมเดลเคยอ่านมา AGENTS.md ไม่สามารถหยุดยั้งสิ่งนี้ได้ เพราะ make test ยังคงผ่านการทดสอบไม่ว่าจะใช้วิธีใด กฎที่ถูกละเมิดนั้นไม่เคยถูกเขียนไว้ในที่ที่ agent สามารถอ่านได้

หากคุณยังไม่ได้เขียนไฟล์แรก ให้เริ่มจากตรงนั้น AGENTS.md และ HUMAN.md ที่อยู่คู่กัน จะครอบคลุมถึงรูปแบบและตำแหน่งที่เครื่องมือแต่ละตัวใช้ค้นหาไฟล์ดังกล่าว เนื้อหาถัดจากนี้คือบทที่ต่อจากบทนั้น

เนื้อหาที่แท้จริงภายในไฟล์ DESIGN.md ที่เผยแพร่

วิธีที่เร็วที่สุดในการเรียนรู้รูปแบบนี้คือการอ่านไฟล์ที่บริษัทต่างๆ เผยแพร่เกี่ยวกับตนเอง โดย repository official-design-md จะรวบรวมเฉพาะไฟล์เหล่านั้นไว้ กฎการรวมไฟล์มีเพียงบรรทัดเดียว และบรรทัดนั้นคือหัวใจสำคัญของคอลเลกชันนี้:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

ณ เดือนตุลาคม 2026 มีรายการทั้งหมด 11 รายการ ได้แก่ Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel และ VoltAgent ไฟล์แต่ละไฟล์ตั้งอยู่ที่ URL สาธารณะ ส่วนใหญ่อยู่บนโดเมนของผู้เผยแพร่เอง และที่เหลืออยู่ใน GitHub repository แบบสาธารณะ คุณจึงสามารถอ่านไฟล์เหล่านี้ผ่าน terminal ได้ทันที

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

ทั้งสองไฟล์เป็นเอกสารระบบการออกแบบ (design system) ซึ่งอธิบายว่าผลิตภัณฑ์ควรมีหน้าตาอย่างไร ทั้งสี แบบอักษร ระยะห่าง และการเคลื่อนไหว ให้มองข้ามเนื้อหาเฉพาะทางไป เพราะส่วนที่มีประโยชน์คือรูปแบบการเขียน ไม่ใช่หัวข้อที่กล่าวถึง

ไฟล์ของ Nuxt มีความยาวประมาณ 2,000 คำ ณ วันที่ 27 ตุลาคม 2026 โดยเนื้อหาส่วนใหญ่เป็นกฎเกณฑ์พร้อมเหตุผลประกอบ ไฟล์เริ่มต้นด้วยการระบุว่า dark mode คือธีมเริ่มต้น มีการระบุสีแบรนด์ #00DC82 พร้อมหมายเหตุว่าสีแบรนด์นั้น "สำหรับโลโก้ ภาพโซเชียล และงานพิมพ์ ห้ามนำไปใช้เป็นค่าสีดิบในโค้ด UI" ใกล้ส่วนท้ายของไฟล์ มีหัวข้อที่ชื่อว่า Reject these ซึ่งประกอบด้วย:

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

ไฟล์ของ Vercel มีความยาวมากกว่า คือประมาณ 6,000 คำ ณ เดือนตุลาคม 2026 และก้าวไปอีกขั้นหนึ่ง โดยหนึ่งในหัวข้อของไฟล์คือ Reject generated-design reflexes ภายใต้หัวข้อนี้มีรายการสิ่งที่ตัวสร้าง (generator) ที่มีความสามารถจะเลือกใช้เมื่อไม่มีใครสั่งห้ามไว้:

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

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

เหตุใดบริษัทต่างๆ จึงเผยแพร่ DESIGN.md ของตนเอง

ชุมชนเป็นผู้ริเริ่มเรื่องนี้ก่อน awesome-design-md รวบรวมไฟล์ไว้ 84 ไฟล์ที่คัดลอกมาจากเว็บไซต์สาธารณะ ตามจำนวนที่ระบุใน README ณ วันที่ 27 ตุลาคม 2026 โดยแต่ละไฟล์เขียนขึ้นตามรูปแบบ 9 ส่วนที่เหมือนกัน เพื่อให้เอเจนต์สามารถอ่านไฟล์เหล่านี้และสร้างผลลัพธ์ที่มีลักษณะใกล้เคียงกันได้ ไฟล์เหล่านั้นมีประโยชน์แต่ยังคงเป็นเพียงการคาดเดา เนื่องจากไม่มีใครในบริษัทเหล่านั้นเป็นผู้ตรวจสอบ

ไฟล์ที่เป็นของบริษัทโดยตรง (first-party) นั้นแตกต่างออกไป เพราะเป็นแหล่งข้อมูลต้นฉบับไม่ใช่การตีความจากผลลัพธ์ เมื่อ Vercel เปลี่ยนแปลงขนาดตัวอักษร (type scale) ไฟล์ vercel.com/design.md จะเปลี่ยนแปลงตามไปด้วย ในขณะที่สำเนาที่คัดลอกมาเมื่อเดือนมีนาคมจะยังคงสอนเอเจนต์ของคุณด้วยขนาดตัวอักษรแบบเก่า และไม่มีสิ่งใดใน repository ของคุณที่จะแจ้งเตือนว่าสำเนานั้นล้าสมัยแล้ว

จำนวนผู้เผยแพร่ 11 รายยังถือว่าน้อย และ repository ก็ระบุไว้เช่นนั้นว่ามาตรฐานนี้ยังใหม่และการยอมรับอย่างเป็นทางการกำลังเติบโต ทั้งสองคอลเลกชันดูแลโดย VoltAgent ซึ่งเป็นเฟรมเวิร์กเอเจนต์แบบโอเพนซอร์สที่เผยแพร่ไฟล์ของตนเองเช่นกัน ดังนั้นโปรดอ่านรายการนี้ในฐานะเครื่องมือติดตามไม่ใช่การสำรวจที่เป็นกลาง อย่างไรก็ตาม รายการนี้ยังคงน่าติดตามเนื่องจากรายชื่อบริษัทที่ปรากฏอยู่ หลายแห่งเป็นบริษัทที่นักพัฒนาคนอื่นมักคัดลอกโค้ดส่วนหน้า (front-end) ไปใช้ และรายการใหม่ๆ อย่าง Ant Design, Microsoft FAST, Juspay และ Oxide Computer ก็เป็นระบบการออกแบบ (design systems) ที่ทีมอื่นนำไปสร้างต่อ ไฟล์ของบริษัทเหล่านี้กำลังกลายเป็นตัวอย่างที่ชัดเจนว่า DESIGN.md ควรเป็นอย่างไร ลองเปรียบเทียบกับเส้นทางที่ AGENTS.md เคยผ่านมา: agents.md ปัจจุบันมีโครงการโอเพนซอร์สกว่า 60,000 โครงการที่ใช้รูปแบบนี้ และการดูแลรักษาอยู่ภายใต้ Agentic AI Foundation ภายใต้ Linux Foundation ส่วน DESIGN.md ก็กำลังเดินไปบนเส้นทางเดียวกัน เมื่อวันที่ 21 เมษายน 2026 Google ได้เปิดเผยร่างข้อกำหนดสำหรับรูปแบบนี้ในรูปแบบโอเพนซอร์ส โดยเผยแพร่เป็น google-labs-code/design.md พร้อมด้วย token schema และ CLI ภายใต้สัญญาอนุญาต Apache-2.0 ณ เดือนตุลาคม 2026 รูปแบบนี้อยู่ในเวอร์ชัน alpha และยังอยู่ระหว่างการพัฒนาอย่างต่อเนื่อง โดยดูแลโดย Google Labs แทนที่จะเป็นมูลนิธิที่เป็นกลาง และเนื่องจากมันอธิบายถึงอัตลักษณ์ทางภาพ (visual identity) จึงไม่ได้กล่าวถึงค่าคงที่ (invariants) ที่ไฟล์สำหรับส่วนหลัง (backend) จำเป็นต้องมี ข้อกำหนดสำหรับไฟล์ที่เอเจนต์อ่านได้กำลังเริ่มมีความชัดเจนขึ้นอย่างรวดเร็ว และกำลังถูกกำหนดโดยผู้เล่นระดับแนวหน้าของอุตสาหกรรม

สิ่งที่ควรระบุใน DESIGN.md เมื่อโปรเจกต์ไม่มีส่วนติดต่อผู้ใช้ (User Interface)

ซอฟต์แวร์ส่วนใหญ่ที่รันบน VPS ไม่มีภาษาภาพ (visual language) ให้กำหนด แต่ไฟล์นี้ยังคงมีความสำคัญ เพราะกลไกการทำงานไม่ได้เกี่ยวข้องกับสีสัน แต่เกี่ยวข้องกับการบันทึกข้อจำกัดที่ผู้แก้ไขงานที่มีความมั่นใจอาจละเมิดโดยไม่รู้ตัว

Invariants (ค่าคงตัว): เขียนประโยคละหนึ่งข้อ โดยระบุสิ่งที่ต้องเป็นจริงเสมอหลังจากการแก้ไขใดๆ เช่น "การเขียนข้อมูลทุกครั้งต้องผ่าน queue.enqueue()" หรือ "การเขียนลงฐานข้อมูลโดยตรงจะข้ามการบันทึก audit log ซึ่ง audit log คือสิ่งที่ compliance export ใช้อ่าน" ค่าคงตัวที่ระบุเหตุผลกำกับไว้จะช่วยให้รอดพ้นจากการทำงานที่คุณไม่ได้คาดคิดมาก่อน หากระบุเพียงค่าคงตัวโดยไม่มีเหตุผล จะถูกมองว่าเป็นเพียงความชอบส่วนบุคคล ซึ่งความชอบมักจะถูกปรับเปลี่ยนออกไปได้ง่าย

Rejected alternatives (ทางเลือกที่ถูกปฏิเสธ): ระบุตัวเลือกที่ชัดเจนและเหตุผลที่เลือกไม่ใช้ เช่น "เราไม่ใช้ Redis สำหรับการทำ caching เนื่องจากบริการรันบน VPS เครื่องเดียว การใช้ in-process map จึงเร็วกว่าและลดจำนวน daemon ที่ต้องดูแลรักษาลงหนึ่งตัว หากมีการเพิ่ม application server เครื่องที่สองค่อยพิจารณาเรื่องนี้ใหม่" หากไม่มีข้อความนี้ ตัวแทน (agent) ที่ได้รับมอบหมายให้เพิ่มความเร็วของ cache อาจเลือกใช้ Redis ซึ่งถือว่าถูกต้องตามตรรกะเพราะคุณไม่ได้ระบุข้อจำกัดไว้ นี่คือส่วนที่คุ้มค่าที่สุดของไฟล์นี้

Boundaries (ขอบเขต): จุดที่การแก้ไขเพียงเล็กน้อยอาจส่งผลกระทบเป็นวงกว้าง เช่น schema ของฐานข้อมูล, prefix ของ public route ที่ลูกค้าเขียนสคริปต์เรียกใช้งานอยู่แล้ว, ไฟล์ config ที่ deploy อ่านก่อนที่แอปพลิเคชันจะเริ่มทำงาน หรือ cron entry ที่สมมติว่ารันได้เพียงสำเนาเดียว ให้ระบุชื่อจุดเหล่านี้และบอกว่าการเปลี่ยนแปลงแต่ละจุดมีต้นทุนอย่างไร หากตัวแทนสามารถเข้าถึงเว็บสาธารณะได้ เช่น ผ่าน อินสแตนซ์ SearXNG ที่โฮสต์เองและเชื่อมต่อเป็น search backend นั่นคือขอบเขตที่ควรบันทึกไว้เช่นกัน เพราะไฟล์ควรระบุว่าข้อความที่ดึงมาส่วนใดได้รับอนุญาตให้ส่งผลต่อโค้ด และส่วนใดที่ทำได้เพียงแค่นำมาอ้างอิงกลับหาคุณเท่านั้น

Vocabulary (คำศัพท์): หากในโค้ดใช้คำว่า tenant แต่ทีมงานใช้คำว่า customer ให้เขียนการจับคู่คำศัพท์เหล่านี้ไว้ ตัวแทนที่เดาผิดในส่วนนี้จะสร้างโค้ดที่อ่านดูดีแต่จำลองโมเดลผิดพลาด ซึ่งเป็นข้อผิดพลาดที่ตรวจพบได้ยากที่สุดในระหว่างการรีวิวโค้ด

การออกแบบ DESIGN.md ที่คุณสามารถคัดลอกไปใช้ได้วันนี้

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

ให้กรอกข้อมูลในสองส่วนที่คุณสามารถเขียนได้จากความจำในวันนี้ ได้แก่ ส่วนของสิ่งที่ต้องคงไว้ (invariants) และทางเลือกที่ถูกปฏิเสธ (rejected alternatives) ส่วนหัวข้อที่เหลือให้คงไว้ตามเดิม ไฟล์ที่มีเนื้อหาจริงเพียงสี่บรรทัดย่อมดีกว่าไฟล์ที่มีเนื้อหาคาดเดาถึงสี่สิบบรรทัด หาก repository ของคุณประกอบด้วยหลายแพ็กเกจ ไฟล์เดียวที่ root อาจไม่ครอบคลุมทั้งหมด คุณควรใช้วิธีการแยกไฟล์ตามไดเรกทอรีเช่นเดียวกับ ไฟล์ AGENTS.md แบบซ้อนกันใน monorepo โดยใช้ไฟล์สั้นๆ ที่ root สำหรับการตัดสินใจที่ใช้ร่วมกันทั้งหมด และใช้ไฟล์ขนาดเล็กกว่าไว้ข้างๆ แต่ละแพ็กเกจที่มีการตัดสินใจเฉพาะของตนเอง

เครื่องมือบางตัวจะโหลดไฟล์ markdown ทุกไฟล์ใน root ของ repository ในขณะที่บางตัวจะโหลดเฉพาะไฟล์ที่ระบุไว้เท่านั้น ดังนั้นอย่าเพิ่งด่วนสรุป ให้เพิ่มตัวชี้ไปยัง AGENTS.md:

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

รูปแบบที่ผิด: การมี DESIGN.md ที่ซ้ำซ้อนกับ README

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

สิ่งนี้ทำให้คุณต้องสูญเสียทรัพยากรสองต่อ ต่อแรกคือเรื่องบริบท (context) ไฟล์ที่ AI agent อ่านทุกครั้งที่เริ่มงานใหม่จะถูกนับรวมเป็นต้นทุนในทุกงาน การมีส่วนการติดตั้งที่ซ้ำซ้อนจึงเป็นภาระส่วนเกินที่กินพื้นที่หน้าต่างบริบท (context window) ซึ่งมีจำกัด การบริหารจัดการพื้นที่นี้เป็นทักษะเฉพาะตัว ซึ่งได้อธิบายไว้ใน การจัดการ context window ใน Claude Code สรุปสั้นๆ คือ สิ่งใดก็ตามที่ถูกโหลดโดยอัตโนมัติควรเป็นข้อความที่มีมูลค่าสูงสุดใน repository

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

วิธีทดสอบทำได้ง่าย หากย่อหน้าใดสามารถนำไปวางใน README ได้อย่างเหมาะสม ให้ตัดออกจาก DESIGN.md สิ่งที่ควรเหลืออยู่คือส่วนที่คุณจะพูดออกมาในระหว่างการรีวิวโค้ด ซึ่งเป็นส่วนที่ขึ้นต้นด้วยประโยคว่า "เราเคยลองทำแบบนั้นไปแล้ว"

คุณจะทราบได้อย่างไรว่าไฟล์ทำงานได้ตามปกติ?

ไม่มีเครื่องมือ linter สำหรับตรวจสอบเรื่องนี้ แต่คุณสามารถทำการทดสอบที่ใช้เวลาเพียงหนึ่งนาทีได้

ให้งานแก่ agent ที่นำไปสู่เงื่อนไขที่ต้องปฏิบัติตามอย่างเคร่งครัด (invariant) เช่น "เพิ่ม background job เพื่อทำเครื่องหมายแถวข้อมูลที่เก่าแล้วว่าหมดอายุ" ไฟล์ที่ทำงานได้ถูกต้องจะปรากฏอยู่ในคำตอบก่อนที่จะมีโค้ดใดๆ: agent ควรแจ้งคุณว่า job ดังกล่าวจะเขียนข้อมูลผ่าน queue.enqueue() เพราะการเขียนโดยตรงจะทำให้ข้ามขั้นตอนการบันทึก audit log ไป หาก agent เปิดการเชื่อมต่อฐานข้อมูลแล้วเขียนข้อมูลโดยตรง แสดงว่ามีสองกรณีที่เป็นไปได้ คือไฟล์นั้นไม่ได้ถูกอ่านเลย หรือเงื่อนไขที่กำหนดไว้หลวมเกินไปจนสามารถโต้แย้งได้

ให้คอยสังเกตจำนวน token ด้วย เนื่องจากไฟล์นี้จะถูกโหลดในทุกรอบการทำงาน หากการใช้ context เพิ่มขึ้นหลังจากที่คุณเพิ่ม DESIGN.md แล้วคำตอบไม่ได้ดีขึ้น แสดงว่าไฟล์นั้นมีเนื้อหาที่เป็นคำอธิบายซึ่ง agent รู้อยู่แล้ว การอ่านตัวนับ token ใน Claude Code จะแสดงให้เห็นว่า budget ส่วนนั้นถูกใช้ไปที่ใด

เรื่องนี้มีความสำคัญที่สุดเมื่อ agent ทำงานอยู่บนเซิร์ฟเวอร์แทนที่จะเป็นบนแล็ปท็อปของคุณ agent ที่ทำงานในเซสชันที่เปิดค้างไว้นานๆ เช่น การตั้งค่าใน Claude Code workspace บน VPS ด้วย tmux จะไม่มีความจำของการสนทนาในวันก่อนหน้า repository คือความจำเพียงอย่างเดียว ทุกสิ่งที่คุณอธิบายในแชทแต่ไม่ได้ commit ไว้จะหายไปเมื่อเริ่มเซสชันถัดไป และ DESIGN.md คือที่สำหรับเก็บคำอธิบายเหล่านั้นเพื่อให้ยังคงอยู่ต่อไปได้

เริ่มต้นด้วยการตัดสินใจที่คุณโต้แย้ง

เวอร์ชันแรกใช้เวลาดำเนินการยี่สิบนาที ให้เปิดดู pull request ล่าสุดหลายรายการที่มีผู้ตรวจสอบเขียนว่า "ไม่ เราทำวิธีอื่นที่นี่" ความเห็นแต่ละรายการคือข้อกำหนดที่ไม่เคยถูกบันทึกไว้เป็นลายลักษณ์อักษร และแต่ละจุดคือตำแหน่งที่เอเจนต์จะทำผิดพลาดแบบเดียวกัน โดยทำได้รวดเร็วและบ่อยครั้งกว่ามนุษย์ ให้เพิ่มข้อมูลลงในไฟล์เมื่อเกิดความล้มเหลว ไม่ใช่ทำตามกำหนดเวลา หากคุณยังคงหาจุดที่เอเจนต์จะเข้ามามีส่วนร่วมในกระบวนการพัฒนาซอฟต์แวร์ตามปกติ คู่มือปี 2026 สำหรับการเรียนรู้ AI agents เป็นจุดถัดไปที่เหมาะสมในการศึกษาต่อ

FAQ

DESIGN.md เป็นมาตรฐานอย่างเป็นทางการหรือไม่?

ไม่เป็นในลักษณะเดียวกับ AGENTS.md โดย AGENTS.md มีเว็บไซต์หลักที่ agents.md มีโครงการโอเพนซอร์สกว่า 60,000 โครงการใช้งาน และอยู่ภายใต้การดูแลของ Agentic AI Foundation ซึ่งเป็นส่วนหนึ่งของ Linux Foundation ส่วน DESIGN.md มีการเผยแพร่ข้อกำหนดแต่ไม่มีหน่วยงานกลางเป็นผู้ดูแล Google ได้เปิดซอร์สร่างข้อกำหนดเมื่อวันที่ 21 เมษายน 2026 โดยจัดเก็บไว้ใน repository google-labs-code/design.md ภายใต้สัญญาอนุญาต Apache-2.0 ณ เดือนตุลาคม 2026 ข้อกำหนดนี้ยังอยู่ในสถานะ alpha และอยู่ระหว่างการพัฒนาอย่างต่อเนื่อง โดยอธิบายถึงอัตลักษณ์ทางภาพ ได้แก่ สี ตัวอักษร เลย์เอาต์ และส่วนประกอบต่างๆ DESIGN.md มีการนำไปใช้จริงโดยบริษัทและโครงการต่างๆ 11 แห่ง เช่น Vercel, Nuxt, Atlassian และ Resend และยังมีคอลเลกชันของชุมชนที่รวบรวมไฟล์ดังกล่าวเพิ่มอีก 84 ไฟล์จากเว็บไซต์สาธารณะ ณ วันที่ 27 ตุลาคม 2026 สำหรับไฟล์ส่วน backend ที่ระบุถึงค่าคงที่และทางเลือกที่ถูกปฏิเสธ ให้ถือว่าเป็นข้อตกลงที่คุณสามารถนำไปใช้และขยายผลได้ตามต้องการ เนื่องจากยังไม่มีข้อกำหนดใดครอบคลุมชื่อส่วนเหล่านั้น

DESIGN.md ควรเป็นเพียงส่วนหนึ่งของ AGENTS.md หรือไม่?

สำหรับ repository ขนาดเล็ก คำตอบคือใช่ การมีไฟล์เดียวที่ agent อ่านอย่างแน่นอนนั้นดีกว่าการมีสองไฟล์ที่อาจถูกละเลยไปไฟล์หนึ่ง ให้แยกไฟล์เมื่อ AGENTS.md เริ่มอ่านยาก หรือเมื่อคุณสังเกตเห็นว่าเนื้อหาทั้งสองส่วนมีการเปลี่ยนแปลงด้วยความถี่ที่ต่างกัน AGENTS.md จะเปลี่ยนแปลงเมื่อมีการเปลี่ยนแปลงการ build ส่วน DESIGN.md จะเปลี่ยนแปลงเมื่อมีการตัดสินใจใหม่ ซึ่งเกิดขึ้นได้ยากกว่าและมีความสำคัญมากกว่า เมื่อคุณแยกไฟล์ ให้เพิ่มบรรทัดหนึ่งใน AGENTS.md เพื่อสั่งให้ agent อ่าน DESIGN.md ก่อนเริ่มแก้ไขโค้ด เนื่องจากเครื่องมือบางตัวอาจไม่ได้โหลดไฟล์ markdown ทุกไฟล์ใน root directory

DESIGN.md แตกต่างจากบันทึกการตัดสินใจทางสถาปัตยกรรม (ADR) อย่างไร?

ADR (architecture decision record) คือบันทึกที่มีการลงวันที่ของการตัดสินใจแต่ละครั้ง ซึ่งโครงการที่มีสุขภาพดีจะสะสมบันทึกเหล่านี้ไว้หลายสิบฉบับในโฟลเดอร์ นี่คือประวัติศาสตร์ และประวัติศาสตร์เป็นสิ่งที่สิ้นเปลืองทรัพยากรในการโหลด เนื่องจาก agent จะต้องอ่านบันทึกทั้งหมดเพื่อวิเคราะห์ว่าข้อใดที่ยังคงมีผลอยู่ ส่วน DESIGN.md คือสถานะปัจจุบันที่เขียนขึ้นเพื่อให้ agent อ่านทั้งหมดในทุกงาน หากคุณเขียน ADR อยู่แล้ว ให้เก็บไว้ทั้งสองอย่าง ADR จะบอกว่ามีการตัดสินใจอะไรและเมื่อใด ส่วน DESIGN.md จะบอกว่าสิ่งใดที่เป็นจริงในปัจจุบัน และเป็นไฟล์ที่คุณควรระบุให้ agent อ่าน

DESIGN.md ควรมีความยาวเท่าใด?

ควรสั้นพอที่จะโหลดได้ในทุกรอบการทำงานโดยไม่ส่งผลกระทบ ตัวอย่างที่เผยแพร่มีความยาวมากเนื่องจากเป็นการระบุภาษาทางภาพทั้งหมด เช่น ไฟล์ของ Nuxt มีความยาวประมาณ 2,000 คำ และไฟล์ของ Vercel มีความยาวประมาณ 6,000 คำ ณ เดือนตุลาคม 2026 สำหรับบริการ backend มักต้องการเนื้อหาน้อยกว่านั้นมาก ให้เริ่มที่ความยาวหนึ่งหน้าและเพิ่มเนื้อหาเฉพาะเมื่อ agent ทำงานผิดพลาดในสิ่งที่ประโยคเดียวสามารถป้องกันได้ ความยาวไม่ใช่ตัวชี้วัด ทุกบรรทัดควรเป็นสิ่งที่ agent อาจทำผิดพลาดหากไม่มีข้อมูลนั้นระบุไว้