วิธีจัดการไฟล์ AGENTS.md แบบซ้อนกันใน monorepo

ความหมายของ AGENTS.md แบบซ้อนกันใน monorepo

การมีไฟล์ AGENTS.md ซ้อนกันใน monorepo หมายถึงการมีไฟล์ขนาดเล็กหนึ่งไฟล์ที่ root ของ repository และมีอีกไฟล์หนึ่งอยู่ภายในไดเรกทอรีของแต่ละบริการ ไฟล์ที่ root จะเก็บกฎเพียงไม่กี่ข้อที่ใช้ร่วมกันได้ทุกที่ รวมถึงแผนผังที่ระบุตำแหน่งของไฟล์อื่นๆ ส่วนไฟล์ของแต่ละบริการจะเก็บคำสั่งและข้อกำหนดเฉพาะสำหรับไดเรกทอรีนั้นๆ เท่านั้น เมื่อ agent ทำการแก้ไข services/worker/queue.py มันจะอ่านไฟล์ที่ root และไฟล์ของ worker นั้นๆ โดยไม่ต้องเสีย context ไปกับส่วน front end ที่มันจะไม่มีวันเข้าไปยุ่ง

ไม่มีสิ่งใดที่ต้องติดตั้ง AGENTS.md เป็นเพียงข้อตกลงร่วมกัน และโครงการต้นทางได้ระบุไว้อย่างชัดเจนว่า:

AGENTS.md เป็นเพียง Markdown มาตรฐาน คุณสามารถใช้หัวข้อใดก็ได้ตามต้องการ agent จะทำการอ่านข้อความที่คุณระบุให้โดยตรง

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

เหตุใดไฟล์ AGENTS.md ขนาดใหญ่ที่ root ถึงหยุดทำงาน

ไฟล์ AGENTS.md ขนาด 600 บรรทัดเพียงไฟล์เดียวที่วางไว้ที่ root ของ repository ซึ่งเก็บทั้งเว็บแอป, background worker และไดเรกทอรี Terraform จะล้มเหลวใน 4 รูปแบบที่แตกต่างกัน

ข้อมูลล้าสมัยเพราะไม่มีใครเป็นเจ้าของ วิศวกรที่เปลี่ยนชื่อสคริปต์ทดสอบใน apps/web กำลังแก้ไขไฟล์ภายใต้ apps/web ไฟล์ AGENTS.md ที่ root ไม่ได้อยู่ใน diff นั้น จึงไม่มีผู้ตรวจสอบคนใดเห็นความไม่สอดคล้องกัน หกสัปดาห์ต่อมา ไฟล์ดังกล่าวกลับอธิบายขั้นตอนการ build ที่ไม่มีอยู่จริงแล้ว และคนที่ทำพังก็ลืมการเปลี่ยนแปลงนั้นไปแล้ว

สิ้นเปลือง context ในทุกงาน ไฟล์เหล่านี้จะถูกโหลดตั้งแต่เริ่ม session ก่อนที่ agent จะทราบว่าคุณกำลังจะถามอะไร เอกสารของ Claude Code ระบุตัวเลขไว้ชัดเจนว่า "ควรตั้งเป้าหมายไว้ที่ต่ำกว่า 200 บรรทัดต่อไฟล์ CLAUDE.md ไฟล์ที่ยาวกว่าจะใช้ context มากขึ้นและลดความแม่นยำในการปฏิบัติตาม" Codex จะหยุดรวมไฟล์คำสั่งเมื่อขนาดรวมกันถึง 32 KiB ซึ่งเป็นค่าเริ่มต้นของ project_doc_max_bytes ไฟล์ที่ root ซึ่งอธิบายบริการทั้ง 4 รายการจะใช้โควตา context ของบริการ 3 รายการที่เหลือไปโดยเปล่าประโยชน์ในทุกงาน

คำสั่งเริ่มขัดแย้งกันเอง ไดเรกทอรีเว็บต้องการ pnpm test ในขณะที่ worker ต้องการ pytest -q เมื่อเขียนรวมไว้ในไฟล์เดียว แต่ละกฎจะถูกต้องเพียงบางเวลาเท่านั้น ทำให้ agent ต้องเดาว่ากฎใดที่ควรนำมาใช้ เอกสารของ Claude Code อธิบายผลลัพธ์ไว้ว่า "หากกฎสองข้อขัดแย้งกัน Claude อาจเลือกข้อใดข้อหนึ่งโดยพลการ" การใช้ไฟล์แยกตามไดเรกทอรีจะขจัดปัญหาการเดา เพราะจะมีกฎเพียงข้อเดียวที่อยู่ใน context เมื่อกฎที่คุณมั่นใจว่าเขียนไว้อย่างชัดเจนถูกข้ามไป การตรวจสอบผ่าน เหตุผลที่คำสั่งไม่ถูกนำไปใช้ จะได้ผลดีกว่าการเขียนคำสั่งใหม่เป็นครั้งที่สี่

เต็มไปด้วยข้อเท็จจริงที่ agent สามารถอ่านได้จากโค้ด เช่น โครงสร้างไดเรกทอรี, รายการ dependency หรือสรุปการทำงานของแต่ละแพ็กเกจ การตรวจสอบ /doctor ของ Claude Code มีไว้เพื่อตัดข้อมูลเหล่านี้ออกโดยเฉพาะ โดยจะ "ตัดเนื้อหาที่ Claude สามารถอนุมานได้จาก codebase เช่น โครงสร้างไดเรกทอรี, รายการ dependency และภาพรวมสถาปัตยกรรม" และเก็บไว้เพียง "ข้อควรระวัง, เหตุผลเบื้องหลัง และข้อตกลงที่แตกต่างจากค่าเริ่มต้นของเครื่องมือ" ประโยคนั้นคือบททดสอบที่ดีที่สุดที่ผมรู้จักในการตัดสินว่าบรรทัดใดควรอยู่ในไฟล์หรือไม่

เอเจนต์อ่านไฟล์ที่ root หรืออ่านเฉพาะไฟล์ที่ใกล้ที่สุด?

นี่คือจุดที่คนส่วนใหญ่เข้าใจโมเดลการทำงานผิด จึงควรยกข้อกำหนดตามมาตรฐานของผู้พัฒนามาอ้างอิงโดยตรงแทนการสรุปความ:

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

และในกรณีที่เกิดความขัดแย้ง:

ไฟล์ AGENTS.md ที่อยู่ใกล้กับไฟล์ที่กำลังแก้ไขมากที่สุดจะเป็นฝ่ายชนะ; อย่างไรก็ตาม คำสั่งที่ผู้ใช้พิมพ์ในแชทโดยตรงจะมีลำดับความสำคัญสูงสุดเหนือทุกสิ่ง

คำว่า "ลำดับความสำคัญสูงสุด" (takes precedence) ทำให้หลายคนเข้าใจผิดว่า "ไฟล์ที่ root จะถูกเพิกเฉย" ซึ่งไม่เป็นความจริง ในเครื่องมือที่นำมาตรฐานนี้ไปใช้งาน ไฟล์ทุกไฟล์บนเส้นทางจาก root ของ repository ลงมาจนถึงไดเรกทอรีที่กำลังทำงานอยู่จะถูกอ่านและนำมารวมกัน ไฟล์ที่ใกล้ที่สุดจะชนะก็ต่อเมื่อมีไฟล์สองไฟล์ระบุข้อมูลที่ขัดแย้งกันในหัวข้อเดียวกันเท่านั้น

Codex ระบุกลไกนี้ไว้อย่างชัดเจนว่า: "Codex จะเชื่อมต่อไฟล์จาก root ลงมา โดยคั่นด้วยบรรทัดว่าง ไฟล์ที่อยู่ใกล้กับไดเรกทอรีปัจจุบันของคุณจะเขียนทับคำแนะนำก่อนหน้า" Claude Code ใช้วิธีการเดียวกันสำหรับไฟล์ชื่อเดียวกัน ไฟล์ที่อยู่ในลำดับชั้นของไดเรกทอรีเหนือไดเรกทอรีที่กำลังทำงานอยู่ "จะถูกโหลดทั้งหมดเมื่อเริ่มโปรแกรม" และ "ไฟล์ทั้งหมดที่พบจะถูกนำมาเชื่อมต่อกันในบริบทแทนที่จะเขียนทับกัน" ส่วนไดเรกทอรีที่อยู่ ต่ำกว่า ไดเรกทอรีที่กำลังทำงานอยู่จะมีพฤติกรรมต่างออกไป โดย Claude Code จะโหลดไฟล์เหล่านั้นตามความจำเป็น "เมื่อ Claude อ่านไฟล์ในไดเรกทอรีเหล่านั้น"

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

พฤติกรรมนี้ได้รับการตรวจสอบกับเอกสารของ Codex และ Claude Code ในเดือนสิงหาคม 2026 เครื่องมือแต่ละตัวอาจนำมาตรฐานนี้ไปใช้แตกต่างกันเล็กน้อยและมีการเปลี่ยนแปลงอยู่เสมอ ดังนั้นโปรดตรวจสอบกฎการโหลดสำหรับเอเจนต์ที่ทีมของคุณใช้งานอยู่ให้แน่ชัด

โครงสร้างที่ใช้งานได้จริงสำหรับ repository ที่มี 3 บริการ

repo/
  AGENTS.md                   rules true everywhere, plus the map
  apps/web/AGENTS.md          TypeScript client, Vite, Vitest
  services/worker/AGENTS.md   Python queue consumer, pytest
  infra/AGENTS.md             Terraform and the deploy scripts

ไฟล์ระดับ root ถูกทำให้สั้นโดยเจตนา ไฟล์นี้ระบุตำแหน่งที่ต้องตรวจสอบและบรรจุเฉพาะกฎที่ใช้บังคับกับทุกไดเรกทอรีเท่านั้น

# AGENTS.md

This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.

- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts

## Rules for the whole repository

- The package manager is `pnpm`. `npm install` writes a second lockfile
  that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
  `schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
  in the same commit.

ไฟล์ระดับไดเรกทอรีคือที่ที่เก็บรายละเอียดต่าง ๆ ซึ่งสามารถมีความยาวได้ตามความเหมาะสมของไดเรกทอรีนั้น

# apps/web

Browser client. Vite and React, TypeScript with `strict` on.

## Commands

- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.

## Conventions

- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
  because the client attaches the auth header and retries on 429.

## Traps

- `pnpm build` does not type check. Vite strips the types instead of
  checking them, so a broken type still produces a green build.
  Run `pnpm typecheck` as a separate step.

ไฟล์ worker มีรูปแบบเดียวกันแต่เนื้อหาต่างออกไป ได้แก่ คำสั่งติดตั้ง, pytest -q, เหตุผลที่ consumer ต้องทำงานแบบ idempotent และการ migration ที่ต้องรันให้เสร็จก่อนที่การทดสอบจะผ่าน ส่วนไฟล์ infra คือที่ที่คุณเขียนกฎเพื่อป้องกันไม่ให้ agent สร้างความเสียหาย ห้ามรัน terraform apply โดยเด็ดขาด ให้รัน terraform plan แล้วหยุดเพียงแค่นั้น พร้อมระบุ state backend ที่กำหนดค่าไว้แล้ว เพื่อไม่ให้ agent พยายามเริ่มต้น backend ใหม่

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

ใครเป็นผู้ปรับปรุงไฟล์เมื่อมีการเปลี่ยนแปลงโค้ด?

มีกฎเพียงข้อเดียวและต้องระบุไว้ในไฟล์ระดับ root: ใครก็ตามที่เปลี่ยนแปลงโค้ดในไดเรกทอรีใด ต้องปรับปรุงไฟล์ AGENTS.md ของไดเรกทอรีนั้นใน commit เดียวกัน

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

ให้สนับสนุนกฎนี้ด้วยการตรวจสอบใน pull request โดยระบบจะค้นหาไฟล์ AGENTS.md ที่ใกล้ที่สุดเหนือไฟล์ที่มีการเปลี่ยนแปลงแต่ละไฟล์ จากนั้นจะรายงานเมื่อไฟล์ดังกล่าวไม่ได้รับการแก้ไข

#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)

nearest_doc() {
  d=$(dirname "$1")
  while [ "$d" != "." ]; do
    if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
    d=$(dirname "$d")
  done
  echo "AGENTS.md"
}

printf '%s\n' "$changed" | while read -r f; do
  [ -n "$f" ] || continue
  case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
  doc=$(nearest_doc "$f")
  printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
  echo "note: $f changed but $doc was not updated"
done

บน branch ที่มีการปรับปรุง API client ใหม่โดยไม่ได้แก้ไขเอกสารประกอบ ผลลัพธ์ที่ได้จะเป็นดังนี้:

note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updated

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

ฉันจะตรวจสอบได้อย่างไรว่า AGENTS.md ล้าสมัยไปแล้ว?

คุณสามารถตรวจสอบได้ 2 วิธีในปัจจุบัน และมีอาการหนึ่งอย่างที่คุณจะพบได้ในระหว่างเซสชัน

เปรียบเทียบอายุของไฟล์แต่ละไฟล์กับอายุของโค้ดที่ไฟล์นั้นอธิบายไว้ %cs จะแสดงวันที่คอมมิตออกมาเป็น YYYY-MM-DD

for f in $(git ls-files '*AGENTS.md'); do
  d=$(dirname "$f")
  printf '%s  doc:%s  code:%s\n' "$f" \
    "$(git log -1 --format=%cs -- "$f")" \
    "$(git log -1 --format=%cs -- "$d")"
done

apps/web/AGENTS.md          doc:2026-02-11  code:2026-08-07
services/worker/AGENTS.md   doc:2026-07-29  code:2026-08-09
infra/AGENTS.md             doc:2026-08-01  code:2026-08-01

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

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

grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
  [ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
done

ให้อ่านผลลัพธ์ที่ได้แทนการนำคำสั่งนี้ไปรวมไว้ใน CI นอกจากนี้มันยังแจ้งเตือน globs เช่น src/**/*.ts และ URL ใดก็ตามที่คุณอ้างถึง เนื่องจากทั้งสองอย่างมีเครื่องหมาย slash และไม่มีอย่างใดที่เป็นไฟล์อยู่บนดิสก์

อาการที่พบในเซสชัน เอเจนต์อ่านไฟล์ พยายามเปิด src/api/client.ts ตามที่ไฟล์ระบุไว้ และเครื่องมือจะส่งผลลัพธ์กลับมาว่า:

No such file or directory

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

Claude Code อ่านไฟล์ AGENTS.md หรือไม่

ไม่ และควรกล่าวให้ชัดเจนเนื่องจากโครงสร้างแบบซ้อนทับขึ้นอยู่กับเรื่องนี้ ณ เดือนสิงหาคม 2026 เอกสารระบุว่า: "Claude Code อ่าน CLAUDE.md ไม่ใช่ AGENTS.md" รูปแบบนี้ยังคงใช้งานได้ เพียงแต่คุณต้องมี CLAUDE.md ไว้ข้างๆ AGENTS.md แต่ละไฟล์

รูปแบบการ import เหมาะสมเมื่อคุณต้องการเพิ่มบรรทัดเฉพาะสำหรับเครื่องมือทับบนบรรทัดที่ใช้ร่วมกัน ให้ใส่สิ่งนี้ลงใน services/worker/CLAUDE.md:

@AGENTS.md

## Claude Code

Use plan mode for changes under `services/worker/migrations/`.

รูปแบบ symlink เหมาะสมเมื่อไม่มีเนื้อหาเฉพาะสำหรับเครื่องมือที่ต้องเพิ่ม

git ls-files '*AGENTS.md' | while read -r f; do
  ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.md

ln จะไม่แสดงผลลัพธ์ใดๆ เมื่อทำงานสำเร็จ ดังนั้นให้ตรวจสอบรายการด้วย: apps/web/CLAUDE.md -> AGENTS.md จากนั้นเริ่มเซสชันและรัน /context ซึ่งไฟล์ที่โหลดจะปรากฏภายใต้ Memory files บน Windows การสร้าง symlink จำเป็นต้องใช้สิทธิ์ Administrator หรือ Developer Mode ดังนั้นให้ใช้การ import แบบ @AGENTS.md แทน

มีข้อควรระวังหนึ่งประการ หลังจาก /compact ไฟล์ระดับ root จะถูกอ่านจากดิสก์ใหม่ แต่ไฟล์ที่ซ้อนอยู่ในไดเรกทอรีย่อยจะไม่ถูกฉีดเข้าไปใหม่ ไฟล์เหล่านั้นจะกลับมาเมื่อ agent อ่านไฟล์ในไดเรกทอรีนั้นอีกครั้ง หากกฎเฉพาะไดเรกทอรีดูเหมือนจะหยุดทำงานกลางคันระหว่างเซสชันที่ยาวนาน มักเป็นเพราะสาเหตุนี้ และการ touch ไฟล์ใดๆ ในไดเรกทอรีนั้นจะทำให้กฎกลับมาทำงานอีกครั้ง

สิ่งนี้แตกต่างจากหน่วยความจำของเอเจนต์หรือทักษะอย่างไร

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

AGENTS.md ถูกเขียนขึ้นโดยคุณ ถูก commit ลง git ผ่านการรีวิวใน pull request และเหมือนกันสำหรับทุกคนที่ clone repository นี้ไปใช้ ส่วนหน่วยความจำของเอเจนต์ (agent memory) ถูกเขียนขึ้นโดยตัวเอเจนต์เอง ถูกจัดเก็บไว้นอก repository และเป็นข้อมูลเฉพาะของเครื่องนั้นๆ เอกสารของ Claude Code ได้แบ่งขอบเขตไว้เช่นเดียวกัน: CLAUDE.md เก็บ "คำสั่งและกฎ" ที่คุณเป็นผู้เขียน ส่วน auto memory เก็บ "สิ่งที่เรียนรู้และรูปแบบ" ที่ Claude เป็นผู้เขียน และไดเรกทอรีหน่วยความจำจะไม่ถูกแชร์ข้ามเครื่องกัน วิธีทดสอบนั้นง่ายมาก หากข้อเท็จจริงนั้นจำเป็นต้องเป็นความจริงสำหรับเพื่อนร่วมงานที่เพิ่ง clone โปรเจกต์มาใหม่ ข้อมูลนั้นจะไม่สามารถอยู่ในหน่วยความจำได้ วิธีที่หน่วยความจำของเอเจนต์คงอยู่ระหว่างเซสชัน ครอบคลุมเนื้อหาในส่วนนี้

ทักษะ (skill) คือสิ่งที่เป็นลำดับที่สาม AGENTS.md คือบริบทที่โหลดขึ้นมาในทุกเซสชัน ส่วนทักษะคือขั้นตอนการทำงานที่โหลดขึ้นมาเมื่อจำเป็น เอกสารของ Claude Code ให้กฎที่ใช้งานได้จริงว่า: "หากรายการใดเป็นขั้นตอนการทำงานหลายขั้นตอน หรือมีความสำคัญเฉพาะส่วนใดส่วนหนึ่งของ codebase ให้ย้ายไปไว้ในทักษะหรือกฎที่กำหนดขอบเขตตาม path แทน" ครึ่งหลังของประโยคนั้นคือสิ่งที่ AGENTS.md แบบซ้อนกัน (nested) แก้ปัญหาได้ ส่วนครึ่งแรกคือสิ่งที่ ทักษะของเอเจนต์ มีไว้เพื่อรองรับ และเมื่อต้องการใช้ขั้นตอนการทำงานเดียวกันในมากกว่าหนึ่ง repository ให้ แชร์ทักษะข้าม repository แทนการคัดลอกย่อหน้าเดิมไปวางในไฟล์ AGENTS.md ถึงสิบไฟล์

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

FAQ

AGENTS.md แบบซ้อนกันจะเข้ามาแทนที่ไฟล์ที่ root หรือเพิ่มเข้าไป?

มันเป็นการเพิ่มเข้าไปครับ ทางต้นน้ำระบุว่า "ไฟล์ที่ใกล้ที่สุดจะมีลำดับความสำคัญสูงสุด" ซึ่งอธิบายถึงสิ่งที่เกิดขึ้นเมื่อเกิดความขัดแย้ง ไม่ใช่สิ่งที่ถูกโหลดเข้ามา Codex จะ "เชื่อมไฟล์จาก root ลงมาเรื่อยๆ โดยคั่นด้วยบรรทัดว่าง" ส่วน Claude Code จะเชื่อมทุกไฟล์ที่พบขณะไล่ลำดับขึ้นมาจาก working directory แทนที่จะเขียนทับ ไฟล์ที่ใกล้ที่สุดจะชนะเฉพาะในกรณีที่ไฟล์สองไฟล์ให้คำสั่งที่ต่างกันในหัวข้อเดียวกัน ให้เขียนกฎที่ใช้ร่วมกันไว้ที่ root เพียงครั้งเดียว และอย่าทำซ้ำในทุกไดเรกทอรี

ไฟล์ AGENTS.md ที่ root ควรมีขนาดเท่าใด?

ควรมีขนาดเล็กพอที่คุณจะไม่รู้สึกรำคาญหากมันถูกแปะไว้ที่ด้านบนของทุกคำขอที่คุณทำใน repository นั้น เพราะนั่นคือสิ่งที่เกิดขึ้นจริง เอกสารของ Claude Code แนะนำให้จำกัดความยาวไว้ไม่เกิน 200 บรรทัดต่อไฟล์ และเตือนว่าไฟล์ที่ยาวกว่านั้นจะ "ลดประสิทธิภาพในการปฏิบัติตามคำสั่ง" โดยปกติแล้ว Codex จะหยุดรวมไฟล์คำสั่งเมื่อมีขนาดรวมถึง 32 KiB หากไฟล์ root ของคุณอธิบายบริการไว้ 4 รายการ เนื้อหาส่วนใหญ่จะเป็นภาระที่ไม่จำเป็นสำหรับงานใดงานหนึ่ง ให้ย้ายรายละเอียดลงไปไว้ในไฟล์ประจำไดเรกทอรีและทิ้งแผนผังไว้ที่ root แทน

ฉันจะป้องกันไม่ให้ไฟล์เหล่านี้ล้าสมัยได้อย่างไร?

ให้ใส่กฎหนึ่งข้อไว้ในไฟล์ root: ใครก็ตามที่แก้ไขโค้ดในไดเรกทอรีใด ต้องอัปเดตไฟล์ AGENTS.md ของไดเรกทอรีนั้นใน commit เดียวกัน การวางไฟล์ไว้ข้างโค้ดคือสิ่งที่ทำให้กฎนี้ได้ผล เพราะการเปลี่ยนแปลงจะปรากฏอยู่ใน pull request diff เดียวกันกับที่มนุษย์กำลังอ่านอยู่ ให้เพิ่ม CI warning ที่จับคู่ path ที่มีการเปลี่ยนแปลงกับไฟล์ AGENTS.md ที่ใกล้ที่สุดที่อยู่เหนือขึ้นไป และตรวจสอบเปรียบเทียบ git log -1 --format=%cs ของแต่ละไฟล์กับคำสั่งเดียวกันที่รันบนไดเรกทอรีที่ไฟล์นั้นอธิบายอยู่เป็นระยะ

Claude Code อ่านไฟล์ AGENTS.md หรือไม่?

ไม่ครับ ณ เดือนสิงหาคม 2026 เอกสารระบุว่า "Claude Code อ่าน CLAUDE.md ไม่ใช่ AGENTS.md" ให้สร้าง CLAUDE.md ในไดเรกทอรีเดียวกันโดยมี @AGENTS.md อยู่ในบรรทัดแรก ซึ่งจะเป็นการโหลดไฟล์ที่ใช้ร่วมกันและช่วยให้คุณเพิ่มคำสั่งเฉพาะสำหรับ Claude ไว้ด้านล่างได้ การใช้ symlink ที่สร้างด้วย ln -s AGENTS.md CLAUDE.md สามารถใช้งานได้หากไม่มีอะไรต้องเพิ่มเป็นพิเศษ แม้ว่าบน Windows จะต้องใช้สิทธิ์ Administrator หรือ Developer Mode ก็ตาม ให้รัน /context ใน session และยืนยันว่าไฟล์ปรากฏอยู่ใน Memory files

ฉันควรวางกฎที่สำคัญเฉพาะบางครั้งไว้ที่ไหน?

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