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 (data store ในหน่วยความจำ) เพราะนั่นคือสิ่งที่ cache มักจะเป็นในโค้ดส่วนใหญ่ที่โมเดลเคยอ่านมา AGENTS.md ไม่สามารถหยุดยั้งพฤติกรรมนี้ได้ เพราะ make test ยังคงผ่านการทดสอบไม่ว่าจะใช้วิธีใด กฎที่ถูกละเมิดนั้นไม่เคยถูกเขียนไว้ในที่ที่ agent สามารถอ่านได้

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

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

วิธีที่เร็วที่สุดในการเรียนรู้รูปแบบนี้คือการอ่านไฟล์ที่บริษัทต่างๆ เผยแพร่เกี่ยวกับตนเอง คลังเก็บข้อมูล 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 เมื่อโปรเจกต์ไม่มีส่วนติดต่อผู้ใช้งาน (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 เครื่องที่สอง" หากไม่มีส่วนนี้ ผู้ที่ได้รับมอบหมายให้เพิ่มความเร็ว cache อาจเลือกใช้ Redis ซึ่งเป็นการตัดสินใจที่ถูกต้องตามตรรกะ เพราะคุณไม่ได้ระบุข้อจำกัดนี้ไว้ ส่วนนี้คือส่วนที่คุ้มค่าที่สุดของไฟล์ทั้งหมด

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

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) ส่วนหัวข้อที่เหลือให้คงไว้ตามเดิม ไฟล์ที่มีเนื้อหาจริงเพียงสี่บรรทัดย่อมดีกว่าไฟล์ที่มีเนื้อหาคาดเดาถึงสี่สิบบรรทัด

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

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

สิ่งที่ต้องคงไว้ (Invariants)

ทางเลือกที่ถูกปฏิเสธ (Rejected alternatives)

การตัดสินใจ (Decisions)

ผลกระทบ (Consequences)

รูปแบบที่ไม่ควรทำ: ไฟล์ DESIGN.md ที่เนื้อหาซ้ำกับ README

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

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

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

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

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

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

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

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

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 คือสถานะปัจจุบันที่เขียนขึ้นเพื่อให้ถูกอ่านทั้งหมดในทุกงาน ให้เก็บไว้ทั้งสองอย่างหากคุณเขียน ADR อยู่แล้ว ADR จะบอกว่าอะไรถูกตัดสินใจและเมื่อใด ส่วน DESIGN.md จะบอกว่าอะไรคือความจริงในปัจจุบัน และเป็นไฟล์ที่คุณควรอ้างอิงให้ agent อ่าน

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

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