DESIGN.md คืออะไร? วิธีเขียนไฟล์อธิบายโครงสร้างโค้ดให้ AI

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 (ซึ่งเป็น in-memory 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 มีรายการทั้งหมด 7 แห่ง ได้แก่ Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel และ VoltAgent ไฟล์แต่ละไฟล์ตั้งอยู่ที่ URL สาธารณะที่เสถียร คุณจึงสามารถอ่านไฟล์เหล่านี้ผ่าน terminal ได้ทันที

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

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

ไฟล์ของ Nuxt มีความยาวประมาณ 2,100 คำ โดยเนื้อหาส่วนใหญ่เป็นกฎเกณฑ์ที่มาพร้อมกับเหตุผลประกอบ:

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

ไฟล์ของ Vercel มีความยาวมากกว่า โดยอยู่ที่ประมาณ 6,500 คำ ณ เดือนสิงหาคม 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.

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

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

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

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

จำนวนผู้เผยแพร่ 7 รายถือเป็นตัวเลขที่น้อย และ repository ก็ระบุไว้เช่นนั้นว่ามาตรฐานนี้ยังใหม่และการยอมรับอย่างเป็นทางการกำลังเติบโต ทั้งสองคอลเลกชันได้รับการดูแลโดย VoltAgent ซึ่งเป็นเฟรมเวิร์กเอเจนต์แบบโอเพนซอร์สที่เผยแพร่ไฟล์ของตนเองด้วยเช่นกัน ดังนั้นโปรดอ่านรายการนี้ในฐานะเครื่องมือติดตาม ไม่ใช่การสำรวจที่เป็นกลาง อย่างไรก็ตาม รายการนี้ยังคงน่าติดตามเนื่องจากตัวตนของผู้เผยแพร่ทั้ง 7 ราย พวกเขาคือบริษัทที่นักพัฒนาคนอื่นๆ มักคัดลอกโค้ดส่วนหน้า (front-end) ไปใช้มากที่สุด และไฟล์ของพวกเขากำลังกลายเป็นตัวอย่างที่ชัดเจนว่า DESIGN.md ควรเป็นอย่างไร ลองเปรียบเทียบกับเส้นทางที่ AGENTS.md เคยผ่านมา: agents.md ในปัจจุบันมีโครงการโอเพนซอร์สกว่า 60,000 โครงการที่ใช้รูปแบบนี้ และการดูแลรักษาอยู่ภายใต้ Agentic AI Foundation ภายใต้ Linux Foundation ข้อกำหนดสำหรับไฟล์ที่เอเจนต์สามารถอ่านได้กำลังถูกกำหนดขึ้นอย่างรวดเร็ว และกำลังถูกกำหนดโดยกลุ่มผู้นำในอุตสาหกรรม

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

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

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

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

Boundaries (ขอบเขต): จุดที่การแก้ไขเพียงเล็กน้อยอาจส่งผลกระทบเป็นวงกว้าง เช่น schema ของฐานข้อมูล, prefix ของ public route ที่ลูกค้าเขียนสคริปต์เชื่อมต่อไว้, ไฟล์ config ที่แอปพลิเคชันอ่านก่อนเริ่มทำงาน หรือ cron entry ที่กำหนดให้รันได้เพียงสำเนาเดียว ให้ระบุชื่อจุดเหล่านี้และบอกถึงต้นทุนหากมีการเปลี่ยนแปลง หากเอเจนต์สามารถเข้าถึงเว็บสาธารณะได้ เช่น ผ่าน a self-hosted SearXNG instance ที่เชื่อมต่อเป็น 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 สิ่งที่เหลืออยู่ควรเป็นส่วนที่คุณจะพูดออกมาในระหว่างการทำ code review ซึ่งเป็นส่วนที่ขึ้นต้นด้วยคำว่า "เราเคยลองทำแบบนั้นไปแล้ว"

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

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

ให้งานแก่ agent ที่นำไปสู่เงื่อนไขที่ต้องปฏิบัติตามอย่างเคร่งครัด (invariant) เช่น "เพิ่ม background job ที่ทำหน้าที่ระบุแถวข้อมูลที่ล้าสมัยให้เป็น expired" ไฟล์ที่ทำหน้าที่ของมันอย่างถูกต้องจะปรากฏให้เห็นในคำตอบก่อนที่จะมีโค้ดใดๆ เกิดขึ้น: 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 ณ เดือนสิงหาคม 2026 ยังไม่มีหน่วยงานกำกับดูแลและไม่มีข้อกำหนดที่เผยแพร่อย่างเป็นทางการ สิ่งที่มีคือการนำไปใช้งานโดยบริษัทต้นทาง ได้แก่ Vercel, Nuxt, Atlassian และ Resend ซึ่งเผยแพร่ไฟล์นี้ไว้ที่ URL สาธารณะ และมีคอลเลกชันของชุมชนที่รวบรวมไว้อีก 73 รายการซึ่งทำวิศวกรรมย้อนกลับมาจากเว็บไซต์สาธารณะ ให้ถือว่านี่เป็นธรรมเนียมปฏิบัติที่คุณสามารถนำไปใช้และขยายผลได้อย่างอิสระ เนื่องจากไม่มีสิ่งใดมาตรวจสอบความถูกต้องของชื่อหัวข้อของคุณได้

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

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

DESIGN.md แตกต่างจาก architecture decision record อย่างไร

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

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

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