วิธีอัปเดตไฟล์ AGENTS.md ให้เป็นปัจจุบันอัตโนมัติด้วย dox

เหตุผลที่ไฟล์ AGENTS.md ของคุณล้าสมัยภายในสามสัปดาห์

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

ตัว agent จะอ่านและเชื่อถือข้อมูลในไฟล์นั้น ซึ่งเป็นจุดที่สร้างปัญหาให้คุณ repository ที่ไม่มีไฟล์ AGENTS.md จะทำให้ coding agent ต้องตรวจสอบสภาพแวดล้อมก่อนลงมือทำ แต่ repository ที่มีไฟล์ AGENTS.md ที่ผิดพลาดจะทำให้ agent หยุดตรวจสอบ เพราะมันคิดว่าได้คำตอบที่ถูกต้องแล้ว มันจะรันคำสั่งที่ระบุไว้ในไฟล์ของคุณ เมื่อ shell ตอบกลับมาว่า Missing script: "test" ตัว agent ก็จะเริ่มคาดเดาเอง บ่อยครั้งที่มันจะแก้ไขไฟล์ package.json เพื่อเพิ่มสคริปต์ตามที่เอกสารของคุณระบุไว้ ไฟล์ที่ล้าสมัยจึงไม่ได้แค่ล้มเหลวอย่างเงียบๆ แต่ยังทำให้เกิดการแก้ไขที่คุณไม่ต้องการอีกด้วย

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

dox คืออะไร และไม่ใช่สิ่งใด

dox เป็นไฟล์ Markdown เพียงไฟล์เดียว ตัว repository คือ agent0ai/dox และอยู่ภายใต้สัญญาอนุญาต MIT โดย ณ วันที่ 11 สิงหาคม 2026 โครงการทั้งหมดประกอบด้วย AGENTS.md ขนาด 3906 ไบต์, ไฟล์ README, ไฟล์ LICENSE และรูปภาพอีกสองรูป ไม่มีแพ็กเกจให้ติดตั้งและไม่มี runtime ใดๆ

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

ไฟล์นี้มีสิบส่วนและมีสองส่วนที่ทำหน้าที่หลัก ส่วน "Read Before Editing" สั่งให้ agent เดินทางจาก root ของ repository ไปยังทุก path ที่ตั้งใจจะแก้ไข และอ่านไฟล์ AGENTS.md ทุกไฟล์ที่พบระหว่างทางใน session ปัจจุบัน โดยไม่พึ่งพาหน่วยความจำ ส่วน "Update After Editing" สั่งให้ agent ทราบว่าการเปลี่ยนแปลงที่มีนัยสำคัญทุกครั้งต้องผ่านขั้นตอน DOX ซึ่งหมายถึงขั้นตอนการอัปเดตเอกสารที่ต้องทำก่อนที่จะถือว่างานนั้นเสร็จสมบูรณ์ ขั้นตอนนี้จะอัปเดตเอกสารที่เกี่ยวข้องใกล้ที่สุดเมื่อมีการเปลี่ยนแปลงวัตถุประสงค์ โครงสร้าง เวิร์กโฟลว์ สิทธิ์ หรือการตั้งค่าของผู้ใช้

ส่วนที่เหลือคือรูปแบบ ไฟล์ AGENTS.md ย่อยมีลำดับส่วนเริ่มต้นดังนี้: วัตถุประสงค์ (Purpose), ความเป็นเจ้าของ (Ownership), สัญญาในระดับท้องถิ่น (Local Contracts), คำแนะนำในการทำงาน (Work Guidance), การตรวจสอบ (Verification) และดัชนี DOX ย่อย (Child DOX Index) ไฟล์ระดับ root จะเก็บกฎของทั้งโครงการรวมถึงดัชนี DOX ย่อยระดับบนสุด ซึ่งเป็นวิธีที่ agent ใช้ค้นหาเอกสารย่อยต่างๆ ส่วน "Closeout" คือรายการตรวจสอบที่ agent จะทำเมื่อสิ้นสุดงาน: ตรวจสอบ path ที่เปลี่ยนแปลงเทียบกับสายงานอีกครั้ง อัปเดตเอกสารที่เกี่ยวข้องใกล้ที่สุด รีเฟรชดัชนีทุกรายการที่ได้รับผลกระทบ ลบข้อมูลที่ขัดแย้งกัน ดำเนินการตรวจสอบที่มีอยู่ และรายงานว่าเอกสารใดบ้างที่เลือกจะปล่อยไว้โดยไม่แก้ไข

ตรึง dox ไว้ที่ commit เดียว ไม่ใช่ที่ main

repository นี้ไม่มี tags และไม่มี releases จึงไม่มีหมายเลขเวอร์ชันให้ตรึง ให้ตรึงที่ commit แทน AGENTS.md ปัจจุบันคือ commit f34ec7ad1055d3393887e5a2670e8cb7320c9165 ลงวันที่ 1 สิงหาคม 2026

mkdir -p .agent
curl -fsSL -o .agent/dox-f34ec7a.md \
  https://raw.githubusercontent.com/agent0ai/dox/f34ec7ad1055d3393887e5a2670e8cb7320c9165/AGENTS.md
wc -c .agent/dox-f34ec7a.md

wc -c ควรแสดงผลเป็น 3906 หากได้ตัวเลขอื่น แสดงว่าคุณไม่ได้ดึงไฟล์ตามที่คู่มือนี้ระบุ ดังนั้นให้อ่านคู่มือก่อนที่จะเชื่อถือไฟล์นั้น หากคุณพิมพ์ commit hash ผิด -f จะทำให้ curl หยุดทำงานพร้อมกับ curl: (22) The requested URL returned error: 404 และไม่เขียนเนื้อหาใดๆ จากนั้น wc -c จะแสดงผลเป็น 0 ไฟล์ที่ถูกตัดทอนนั้นแย่ยิ่งกว่าการไม่มีไฟล์ เพราะ agent จะปฏิบัติตามสัญญาเพียงครึ่งเดียวโดยไม่รู้ตัว

cp .agent/dox-f34ec7a.md AGENTS.md
git add AGENTS.md .agent/dox-f34ec7a.md
git commit -m "Add DOX rules (agent0ai/dox @ f34ec7a)"

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

จากนั้นให้ถาม agent ของคุณภายใน repository เพื่อทำการตรวจสอบรอบแรก README ได้ระบุถ้อยคำที่ถูกต้องไว้ดังนี้:

Initialize DOX tree for this project now.

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

git status --short
find . -name AGENTS.md -not -path './.git/*' | sort

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

สิ่งที่ dox มองเห็นและสิ่งที่ไม่สามารถรับรู้ได้

เอเจนต์ที่สร้างโครงสร้างของคุณจะอ่าน repository ดังนั้นทุกสิ่งที่อยู่ใน repository สามารถนำไปใส่ใน inventory ได้ ไม่ว่าจะเป็นโครงสร้างไดเรกทอรี, package manifest และ lockfile, สคริปต์ใน package.json หรือ Makefile หรือ pyproject.toml, ไฟล์ CI workflow, Dockerfile, entry point และ CODEOWNERS หากคุณมีไฟล์ดังกล่าว inventory ที่สร้างจากข้อมูลเหล่านี้จะสามารถดูแลตัวเองได้อย่างแท้จริง เมื่อมีการย้ายแพ็กเกจ การประมวลผลในรอบถัดไปจะย้ายบรรทัดที่อธิบายแพ็กเกจนั้นตามไปด้วย

ทุกสิ่งที่อยู่ด้านล่างนี้เป็นหน้าที่ของคุณในการระบุ เนื่องจากข้อมูลเหล่านี้ไม่ได้อยู่ใน repository ให้เอเจนต์อ่านได้:

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

dox ทราบข้อมูลนี้เกี่ยวกับตัวมันเอง กฎของมันระบุว่า Work Guidance ต้องสะท้อนถึงมาตรฐานปัจจุบันของโปรเจกต์หรือคำแนะนำของผู้ใช้ และหากยังไม่มีมาตรฐานใดๆ ให้เว้นส่วนนั้นว่างไว้ Verification ต้องสะท้อนถึงการตรวจสอบที่มีอยู่จริง ดังนั้นหากไม่มี test framework ใน repo ส่วนนั้นจะยังคงว่างอยู่จนกว่าจะมี การสร้างไฟล์ขึ้นมาโดยกำหนดมาตรฐานขึ้นเองนั้นแย่ยิ่งกว่าการเว้นว่างไว้ เพราะเอเจนต์จะบังคับใช้มาตรฐานที่ถูกสร้างขึ้นนั้นทันที

แยกเจตจำนงที่เขียนด้วยมือออกจากรายการที่สร้างขึ้นโดยอัตโนมัติ

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

คุณต้องการกลไกสองอย่างเพื่อจัดการเรื่องนี้

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

ประการที่สอง กั้นเขตเจตจำนงที่จำเป็นต้องอยู่ใน AGENTS.md ให้ล้อมรอบด้วยเครื่องหมายและถือว่าบล็อกนั้นเป็นส่วนที่มนุษย์เป็นเจ้าของ:

## User Preferences

<!-- dox:keep start -->
The jobs queue stays single consumer. Ordering is the reason this service exists.
Deploys ship on Tuesday. A Friday deploy is a human decision, not an agent decision.
<!-- dox:keep end -->

Markdown comment จะไม่แสดงผลบนหน้าเว็บ แต่ agent ยังคงอ่านได้ ตอนนี้ให้ตรวจสอบความคงอยู่ของบล็อกดังกล่าว เพื่อให้กระบวนการที่ลบข้อมูลนี้แจ้งเตือนความผิดพลาดออกมาอย่างชัดเจน ให้รันคำสั่งนี้ใน CI (continuous integration) ทุกครั้งที่มีการทำ pull request:

git fetch -q origin main
sed -n '/dox:keep start/,/dox:keep end/p' AGENTS.md > /tmp/keep.head
git show origin/main:AGENTS.md | sed -n '/dox:keep start/,/dox:keep end/p' > /tmp/keep.base
diff -u /tmp/keep.base /tmp/keep.head

diff จะไม่แสดงผลลัพธ์ใดๆ และ exit 0 เมื่อบล็อกดังกล่าวไม่ถูกแก้ไข หากมีผลลัพธ์แสดงออกมา หมายความว่ากระบวนการได้เขียนทับข้อความที่มนุษย์เป็นเจ้าของ ดังนั้นต้องมีคนตรวจสอบหรือย้อนกลับการเปลี่ยนแปลงนั้น การตรวจสอบนี้จะคงอยู่โดยที่ไม่มีใครต้องคอยจดจำด้วยตนเอง

สร้างใหม่ใน pull request แทนการใช้ตัวตั้งเวลา

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

การตรวจสอบแบบ blocking ที่บังคับใช้กฎนี้:

#!/usr/bin/env bash
set -euo pipefail
git fetch -q origin main
base=$(git merge-base origin/main HEAD)
changed=$(git diff --name-only "$base" HEAD)
if grep -qE '^(src|apps|packages)/' <<<"$changed" && ! grep -q 'AGENTS\.md$' <<<"$changed"; then
  echo "Code changed but no AGENTS.md was touched. Run a DOX pass, or say why not."
  exit 1
fi

ปรับเปลี่ยน path ให้ตรงกับ repository ของคุณ ประโยชน์ของวิธีนี้คือมันจะแจ้งเตือนความผิดพลาดตั้งแต่บน branch ซึ่งแก้ไขได้ง่าย และแจ้งเตือนด้วยเหตุผลที่ผู้ตรวจสอบ (reviewer) สามารถดำเนินการแก้ไขได้

การตั้งเวลาเป็นเพียงแผนสำรอง ไม่ใช่กลไกหลัก งานที่รันรายสัปดาห์จะช่วยตรวจจับสิ่งที่ไม่มีใครสังเกตเห็นบน branch เช่น ไฟล์ที่ถูกย้ายจากการ rebase, แพ็กเกจที่ถูกลบจากการ merge หรือเอกสารที่อ้างถึงไดเรกทอรีที่ไม่มีอยู่แล้ว ให้รันงานนี้บนเครื่องขนาดเล็ก เครื่องเดียวกับที่คุณอาจใช้เพื่อ รัน coding agent บน VPS และให้มันเปิด pull request แทนการ push เข้า main โดยตรง

#!/usr/bin/env bash
set -euo pipefail
cd /srv/src/myapp
git fetch -q origin
git switch -c "dox/refresh-$(date +%Y%m%d)" origin/main
# Your agent CLI goes on the next line, in whatever non-interactive mode it offers.
# Prompt: "Run a DOX pass over this repository. Change AGENTS.md files only."
git add '*AGENTS.md'
git commit -m "dox: refresh AGENTS.md tree" || { echo "nothing to refresh"; exit 0; }
git push -q -u origin HEAD
gh pr create --fill

คอมเมนต์นั้นเป็นเพียงตัวยึดตำแหน่ง (placeholder) โดยเจตนา Agent แต่ละตัวมี CLI (command line interface) และ flag สำหรับการทำงานแบบ non-interactive ของตัวเอง หากคัดลอกคำสั่งจากหน้าเว็บที่ไม่ตรงกับเวอร์ชันที่คุณใช้ คำสั่งนั้นจะล้มเหลวภายใน cron ซึ่งไม่มีใครเห็นข้อผิดพลาด ให้กรอกข้อมูลให้ครบถ้วนและรันสคริปต์ด้วยตนเองหนึ่งครั้งก่อนตั้งเวลา ค่า || exit 0 ก็มีความสำคัญเช่นกัน เพราะ git commit จะส่งค่า exit code ที่ไม่ใช่ศูนย์พร้อมกับ nothing to commit, working tree clean ในกรณีที่โครงสร้างไฟล์เป็นปัจจุบันอยู่แล้ว และภายใต้ set -e นั่นจะทำให้การรันที่ปกติถูกรายงานว่าเป็นความล้มเหลว

ทุกขั้นตอนมีค่าใช้จ่ายเป็น token เพราะหลักการ "อ่านก่อนแก้ไข" (Read Before Editing) ทำให้ agent ต้องอ่านทั้ง chain ในทุกงาน นี่คือสิ่งแลกเปลี่ยน และคุ้มค่าที่จะเฝ้าสังเกตหากคุณกำลัง คำนวณต้นทุนการรันงานของ agent อยู่แล้ว

Monorepos: หลายสัญญา, หนึ่งดัชนี

ไฟล์ AGENTS.md หลักเพียงไฟล์เดียวใน repository ที่มี 40 แพ็กเกจ จะทำให้เกิด diff ของการสร้างเอกสารใหม่ที่ไม่มีใครอ่าน และได้เอกสารที่ส่วนใหญ่ไม่เกี่ยวข้องกับสิ่งที่ agent กำลังทำอยู่ในขณะนั้น คำตอบของ dox คือ Child DOX Index: ไฟล์หลักจะเก็บกฎระดับ repository และชี้ไปยังไฟล์ลูก โดยที่ขอบเขตที่ชัดเจนแต่ละส่วนจะรับผิดชอบไฟล์ของตนเอง วิธีการวางโครงสร้าง tree นี้ และเครื่องมือใดบ้างที่สามารถอ่านไฟล์แบบซ้อนกันได้ จะครอบคลุมอยู่ใน ไฟล์ AGENTS.md แบบซ้อนกันสำหรับ monorepos

สิ่งที่ dox เปลี่ยนแปลงคือขอบเขตของการตรวจสอบ pull request ที่แก้ไข packages/api ควรสร้าง diff ของเอกสารภายใน packages/api เท่านั้นและไม่ควรมีที่อื่น:

git diff --stat -- '*AGENTS.md'

หากคำสั่งดังกล่าวแสดงรายการไฟล์ 6 ไฟล์สำหรับการเปลี่ยนแปลงเพียงหนึ่งแพ็กเกจ แสดงว่าโครงสร้าง tree นั้นไม่ถูกต้อง อาจเป็นเพราะขอบเขตนั้นกว้างเกินไป หรือกฎที่ควรอยู่ในไฟล์หลักถูกคัดลอกไปยังไฟล์ลูกทุกไฟล์ dox ระบุวิธีแก้ไขไว้โดยตรง: กฎทั่วไปให้ใส่ไว้ในเอกสารของ parent ส่วนรายละเอียดเฉพาะเจาะจงให้ใส่ไว้ในเอกสารของ child การทำกฎซ้ำซ้อนคือสาเหตุที่ทำให้การแก้ไขตามปกติส่งผลให้ต้องเขียนใหม่ทั้งหมด หากกฎเดียวกันนั้นจำเป็นต้องใช้จริงในหลาย repository นั่นเป็นปัญหาคนละประเภท และ การแชร์ทักษะของ agent ข้าม repository เป็นเครื่องมือที่เหมาะสมกว่าสำหรับกรณีนี้

ตรวจสอบความแตกต่างของไฟล์เสมือนเป็นซอร์สโค้ด

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

• คำสั่งที่ระบุไว้ในไฟล์ ซึ่งคุณควรทดลองรันด้วยตนเองก่อนทำการ merge คำสั่งสร้างระบบ (build instructions) ที่ถูกเขียนขึ้นมาลอยๆ คือจุดที่มักเกิดความผิดพลาดบ่อยที่สุด
• บรรทัดที่ถูกลบออกซึ่งมีเจตนาแฝงอยู่ การเพิ่มเนื้อหาทำได้ง่าย แต่การสูญเสียข้อมูลมักเกิดขึ้นจากการลบ
• path แบบสัมบูรณ์ (absolute path), ชื่อโฮสต์ (hostname), URL ภายใน หรือสิ่งใดก็ตามที่มีลักษณะคล้ายข้อมูลรับรอง (credential)
• รายการในสารบัญสำหรับสิ่งที่ไม่มีอยู่แล้ว ซึ่ง ls จะจัดการได้ในทันที

จากนั้นให้ตรวจสอบขนาดของไฟล์ด้วย wc -l AGENTS.md หากไฟล์ระดับ root มีความยาวเกิน 200 บรรทัด นั่นเป็นสัญญาณว่าควรแยกไฟล์ออก เพราะหัวใจสำคัญของระบบนี้คือการที่ agent สามารถอ่านเฉพาะส่วนที่เกี่ยวข้องและมีขนาดเล็ก แทนที่จะต้องอ่านข้อมูลทั้งหมด

เมื่อเกิดข้อผิดพลาด

pass ลบ block ที่คุณต้องการทิ้ง การตรวจสอบด้วย diff ด้านบนจะแสดงบรรทัดที่ถูกลบออกไป ให้กู้คืนไฟล์จากจุด branch ด้วย git restore --source=origin/main AGENTS.md จากนั้นให้รัน pass อีกครั้งโดยระบุคำสั่งที่เจาะจงมากขึ้นเกี่ยวกับ section ที่อนุญาตให้แก้ไขได้

ทั้งสอง branch สร้างเนื้อหาใหม่ขึ้นมาพร้อมกัน คุณจะพบ CONFLICT (content): Merge conflict in AGENTS.md และเครื่องหมายความขัดแย้ง <<<<<<< HEAD ภายในไฟล์ ห้ามแก้ไขเครื่องหมายเหล่านี้ด้วยตนเอง เนื่องจากไฟล์นี้ถูกสร้างขึ้นโดยอัตโนมัติ วิธีแก้ไขที่ถูกต้องคือการรัน pass ใหม่บน tree ที่รวมกันแล้ว

agent เพิกเฉยต่อไฟล์โดยสิ้นเชิง ให้ตรวจสอบว่าเครื่องมือของคุณอ่านไฟล์ชื่อใดอยู่ หากเครื่องมืออ่านไฟล์อื่น ให้ชี้ไปยังเนื้อหาเดียวกันด้วย ln -s AGENTS.md CLAUDE.md แล้ว commit symlink นั้น เพื่อให้คุณมีแหล่งข้อมูลเพียงแหล่งเดียว แทนที่จะมีเอกสารสองฉบับที่เนื้อหาไม่ตรงกัน หากชื่อไฟล์ถูกต้องแล้วแต่กฎยังคงถูกข้าม ให้รันการวินิจฉัยสำหรับ เหตุผลที่ coding agents เพิกเฉยต่อคำสั่งของคุณ ก่อนที่คุณจะเขียนเอกสารนั้นใหม่

tree มีลูกที่ไม่มีใครทำดัชนีไว้ ให้เปรียบเทียบผลลัพธ์จาก find . -name AGENTS.md กับรายการดัชนีในเอกสารหลัก ลูกที่ไม่มีดัชนีระบุถึงจะเป็นส่วนที่ agent มองข้ามไปโดยสิ้นเชิง

เมื่อการใช้ generator เป็นเรื่องเกินความจำเป็น

หากมีหนึ่งแพ็กเกจ หนึ่งคำสั่งทดสอบ และผู้ดูแลสองคนที่เข้าใจ repository เป็นอย่างดี ให้เขียนไฟล์ขนาด 20 บรรทัดด้วยมือ ไฟล์ AGENTS.md ที่มีความยาว 20 บรรทัดไม่มีการเสื่อมสภาพเร็วพอที่จะคุ้มค่ากับการสร้างโครงสร้างต้นไม้ (tree), ดัชนี (index), การตรวจสอบผ่าน CI และงานที่ต้องทำเป็นรายสัปดาห์ ให้กลับมาอ่านไฟล์นี้เมื่อคุณเปลี่ยนแปลงการ build ซึ่งนั่นคือต้นทุนการบำรุงรักษาทั้งหมด และมันน้อยกว่าต้นทุนของเครื่องมือที่ต้องใช้จัดการสิ่งเหล่านี้

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

FAQ

ฉันจำเป็นต้องติดตั้งอะไรเพื่อใช้งาน dox หรือไม่?

ไม่จำเป็น dox เป็นไฟล์ Markdown เพียงไฟล์เดียวภายใต้สัญญาอนุญาต MIT และ ณ วันที่ 11 สิงหาคม 2026 ตัว repository ไม่มีการจัดส่ง package หรือ releases ใดๆ คุณเพียงคัดลอกเนื้อหาไปไว้ในไฟล์ AGENTS.md ของโปรเจกต์ แล้ว coding agent ของคุณจะปฏิบัติตามกฎที่ระบุไว้ในนั้น ให้ทำการ pin commit ที่คุณคัดลอกมา ซึ่งคือ f34ec7ad1055d3393887e5a2670e8cb7320c9165 ในขณะที่เขียนบทความนี้ และระบุชื่อ commit นั้นไว้ในข้อความ commit ของคุณ เพื่อให้สามารถตรวจสอบได้ในภายหลังว่าโครงสร้างโปรเจกต์ของคุณถูกสร้างขึ้นภายใต้กฎเวอร์ชันใด

ฉันจะป้องกันไม่ให้การสร้างไฟล์ใหม่ (regeneration) ลบกฎที่ฉันเขียนไว้เองได้อย่างไร?

ให้แยกส่วนของเจตจำนง (intent) และรายการ (inventory) ออกจากกัน การให้เหตุผลที่ต้องการความคงทนควรอยู่ในเอกสารแยกต่างหาก และสิ่งใดที่จำเป็นต้องอยู่ใน AGENTS.md ให้ใส่ไว้ภายในบล็อกที่ทำเครื่องหมายไว้ จากนั้นให้ตรวจสอบบล็อกดังกล่าวใน CI โดยดึงข้อมูลออกมาจาก branch และจาก origin/main ด้วย sed แล้วเปรียบเทียบทั้งสองส่วนด้วย diff หากพบความแตกต่างให้สั่ง fail build ทันที เพื่อให้มีคนเข้ามาตรวจสอบและอนุมัติหรือย้อนกลับการเปลี่ยนแปลงนั้น แทนที่จะปล่อยให้การเปลี่ยนแปลงหลุดรอดไปโดยไม่สังเกตเห็นภายใน diff ขนาดใหญ่

ฉันควรสร้าง AGENTS.md ใหม่บ่อยแค่ไหน?

ควรทำใน pull request ที่ทำให้ไฟล์นั้นไม่ถูกต้อง การเปลี่ยนแปลงเชิงโครงสร้างและเอกสารประกอบควรอยู่ใน diff เดียวกัน เพราะนั่นเป็นช่วงเวลาเดียวที่ผู้ตรวจสอบจะมีบริบทเพียงพอในการพิจารณาทั้งสองส่วน การรันตามกำหนดการรายสัปดาห์เป็นเพียงการสำรองสำหรับกรณีที่เกิดความคลาดเคลื่อน (drift) ที่หลุดรอดไปจาก branch และควรเปิดเป็น pull request แทนที่จะ commit ลงใน main โดยตรง

คำสั่ง build ควรอยู่ใน AGENTS.md ที่ root หรือในไฟล์ย่อย?

ควรอยู่ในเอกสารที่ใกล้ที่สุดซึ่งรับผิดชอบคำสั่งนั้น กฎระดับ repository และดัชนีของไฟล์ย่อยจะอยู่ที่ root ส่วนคำสั่งที่ใช้กับ package ใด package หนึ่งโดยเฉพาะควรอยู่ใน AGENTS.md ของ package นั้น dox จะแก้ไขข้อขัดแย้งโดยพิจารณาจากระยะห่าง: เอกสารที่ใกล้กว่าจะเป็นตัวควบคุมรายละเอียดในระดับท้องถิ่น และไฟล์ย่อยไม่มีสิทธิ์ลดทอนความเข้มงวดของกฎจากไฟล์แม่ การคัดลอกคำสั่งเดียวกันลงในทุกไฟล์ย่อยคือสาเหตุที่ทำให้การรันตามปกติส่งผลให้ต้องเขียนทับทั้งโครงสร้าง

dox คุ้มค่าสำหรับ repository ขนาดเล็กหรือไม่?

โดยปกติแล้วไม่คุ้มค่า สำหรับ package เดียวที่มีคำสั่งทดสอบเดียวและไฟล์ AGENTS.md ความยาว 20 บรรทัด การเสื่อมสภาพของกฎจะเกิดขึ้นช้า และคุณสามารถแก้ไขได้ภายในหนึ่งนาทีหลังจากพบปัญหา dox จะคุ้มค่าเมื่อ repository มีขอบเขตการทำงานหลายส่วนที่มีกฎต่างกัน หรือมีผู้ร่วมพัฒนาที่ขาดพื้นฐานความเข้าใจ เพราะในกรณีนั้นชุดเอกสารจะทำหน้าที่แทนงานที่ไม่มีใครคนใดคนหนึ่งทำอยู่