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

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

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

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

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

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

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

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

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

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

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

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 พยายามเริ่มต้นระบบใหม่

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

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

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

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

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

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

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

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

บันทึกจากต้นทางระบุว่า "ณ เวลาที่เขียนบทความนี้ 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 ไม่ควรอยู่ในไฟล์เหล่านี้เลย