วิธีอัปเดตไฟล์ 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 โครงการทั้งหมดประกอบด้วยไฟล์ขนาด 3906 ไบต์ AGENTS.md จำนวนหนึ่งไฟล์, ไฟล์ README, ไฟล์ LICENSE และรูปภาพอีกสองรูป ไม่มีแพ็กเกจให้ติดตั้งและไม่มี runtime ใดๆ

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

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

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

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

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

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

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

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

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

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

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

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

## 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 จะไม่แสดงผลบนหน้าเว็บ แต่ 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 มีขนาดเล็กพอที่จะอ่านได้จริง

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

#!/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 ซึ่งเป็นจุดที่แก้ไขได้ง่าย และล้มเหลวด้วยเหตุผลที่ผู้ตรวจสอบสามารถดำเนินการแก้ไขได้

ตารางเวลาเป็นเพียงการสำรองข้อมูล ไม่ใช่กลไกหลัก งานที่ตั้งไว้เป็นรายสัปดาห์จะช่วยตรวจจับสิ่งที่ไม่มีใครสังเกตเห็นบน 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

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

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

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

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

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

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

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

ตรวจสอบความแตกต่างของเอกสารเสมือนการตรวจสอบโค้ด

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

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

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

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

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

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

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

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

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

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

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

FAQ

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

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

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

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

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

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

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

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

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

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