SSD Nodes Learn Hosting plans →
คู่มือ Matt Connorโดย Matt Connor · อัปเดตเมื่อ 2026-10-30

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

การใช้ไฟล์ AGENTS.md ขนาดใหญ่ที่ root ทำให้ข้อมูลล้าสมัยและสิ้นเปลือง context เรียนรู้วิธีจัดโครงสร้างแบบแยกไฟล์ตามไดเรกทอรีเพื่อเพิ่มประสิทธิภาพให้ AI agent ของคุณ

ความหมายของ 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 ซึ่งเก็บทั้ง web app, background worker และ directory ของ Terraform จะล้มเหลวใน 4 รูปแบบที่แตกต่างกัน

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

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

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

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

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

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

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

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

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

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

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

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

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

FAQ

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

มองหาพาธที่ไม่มีอยู่จริงแล้ว เอกสารมักจะเสื่อมสภาพในรูปแบบที่เฉพาะเจาะจงมาก คือการอธิบายโค้ดที่ถูกลบไปแล้ว พาธทุกพาธในไฟล์เหล่านี้ถูกเขียนไว้ในเครื่องหมาย 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 และไม่ใช่ไฟล์บนดิสก์ ใน Claude Code v2.1.283 หรือใหม่กว่า /doctor prompt-audit จะทำการตรวจสอบในลักษณะเดียวกันให้คุณ โดยจะมองหา "การอ้างอิงถึงไฟล์หรือคำสั่งที่ไม่มีอยู่จริง" และไฟล์ที่ขัดแย้งกันเอง โดยจะครอบคลุมไฟล์ AGENTS.md ของคุณโดยค่าเริ่มต้น และจะไม่เปลี่ยนแปลงสิ่งใดจนกว่าคุณจะสั่งให้ใช้การแก้ไขที่เสนอ

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

No such file or directory

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

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

อ่าน ตั้งแต่ Claude Code v2.1.277 เป็นต้นไป โดยกฎที่แน่นอนมีความสำคัญเนื่องจากโครงสร้างแบบซ้อนทับขึ้นอยู่กับกฎดังกล่าว ข้อมูล ณ วันที่ 27 ตุลาคม 2026 ระบุว่า: "Claude Code สามารถอ่าน AGENTS.md เพื่อใช้เป็นคำสั่งสำหรับโปรเจกต์ของคุณได้ ดังนั้น repository ที่ตั้งค่าไว้สำหรับ coding agent ตัวอื่นอยู่แล้วจึงใช้งานได้ทันทีโดยไม่ต้องเพิ่ม CLAUDE.md, การ import หรือการตั้งค่าใดๆ" ค่าเริ่มต้นของ Project instructions คือ claude-md-or-agents-md ซึ่งจะอ่าน "ไฟล์ AGENTS.md ของคุณเมื่อคุณไม่มี CLAUDE.md หรือ CLAUDE.local.md ใน working directory หรือใน directory ที่อยู่เหนือขึ้นไป" ไฟล์ที่ซ้อนอยู่ก็ครอบคลุมเช่นกัน: Claude จะอ่านไฟล์ AGENTS.md ใน subdirectory "เมื่อ Claude เปิดไฟล์ในนั้นด้วยเครื่องมือ Read" ตราบใดที่ "subdirectory นั้นไม่มีไฟล์ CLAUDE.md ทั้งสามประเภทของตัวเอง" ไฟล์ทั้งสามนั้นคือ CLAUDE.md, .claude/CLAUDE.md และ CLAUDE.local.md ดังนั้นการมีไฟล์ CLAUDE.local.md ส่วนตัวใน apps/web ก็เพียงพอที่จะหยุดการโหลด apps/web/AGENTS.md ได้

นั่นทำให้คำแนะนำเดิมที่ให้วางไฟล์ CLAUDE.md ไว้ข้างๆ AGENTS.md แต่ละไฟล์กลายเป็นกับดัก หากคุณมี AGENTS.md และมี CLAUDE.md หรือ CLAUDE.local.md อยู่ใน working directory หรือเหนือขึ้นไป เอกสารระบุว่า Claude จะอ่าน "ไฟล์ CLAUDE.md ของคุณเท่านั้น" ไฟล์ .claude/CLAUDE.md ก็ถูกนับในลักษณะเดียวกัน การมีไฟล์คู่หูที่ root เพียงไฟล์เดียวที่มีบรรทัดเฉพาะของ Claude จะทำให้ไฟล์ AGENTS.md ทุกไฟล์ใน path นั้นถูกซ่อนไว้ และไฟล์ CLAUDE.local.md ส่วนตัวก็ส่งผลเช่นเดียวกัน หากคุณต้องการเก็บไฟล์ไว้ ให้พิมพ์ /config และตั้งค่า Project instructions เป็น claude-md-and-agents-md ซึ่งจะอ่านทั้งสองไฟล์ โดยอ่านไฟล์ CLAUDE.md ของแต่ละ directory ก่อน แล้วตามด้วย AGENTS.md

เลขเวอร์ชันเพียงอย่างเดียวไม่สามารถยืนยันได้ว่าใช้งานได้จริง คุณต้องใช้ v2.1.277 ขึ้นไป แต่ก่อนเวอร์ชัน v2.1.281 บาง session เช่น บน Amazon Bedrock หรือเมื่อปิดการใช้งาน telemetry จะอ่านเฉพาะไฟล์ CLAUDE.md เท่านั้น และในบางกรณี session แรกหลังจากอัปเกรดจาก v2.1.276 หรือเก่ากว่าจะข้าม AGENTS.md ไปด้วย: เอกสารระบุว่า "Claude จะอ่าน AGENTS.md ตั้งแต่ session ถัดไปของคุณเป็นต้นไป" ดังนั้นให้ตรวจสอบที่ตัว session เอง ใน session แบบโต้ตอบ Claude Code จะพิมพ์บรรทัดเช่น no CLAUDE.md found; AGENTS.md loaded: ตามด้วย path และในเวอร์ชันปัจจุบัน /memory จะแสดงรายการไฟล์นั้น ก่อนเวอร์ชัน v2.1.280 คำสั่ง /memory และ /context ไม่แสดงรายการ AGENTS.md ที่ Claude อ่านโดยตรง ดังนั้นในเวอร์ชันเหล่านั้นให้ถาม Claude ว่าคำสั่งโปรเจกต์ของมันคืออะไร

รูปแบบการ import ยังคงถูกต้องในกรณีที่ Claude ไม่สามารถอ่าน AGENTS.md ได้โดยตรง เช่น เวอร์ชันเก่า, session ก่อน v2.1.281 บน Amazon Bedrock หรือเมื่อปิด telemetry, session ที่ปลั๊กอินอ่านไฟล์ถูกปิดใช้งาน หรือโปรเจกต์ที่เก็บไฟล์ CLAUDE.md โดยตั้งค่า Project instructions เป็น claude-md ให้ใส่สิ่งนี้ใน 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 จากนั้นเริ่ม session และรัน /context ซึ่งไฟล์ที่โหลดจะปรากฏภายใต้ Memory files บน Windows การทำ symlink ต้องใช้สิทธิ์ Administrator หรือ Developer Mode และ Git จะ checkout symlink ที่ commit ไว้ให้เป็นไฟล์ข้อความธรรมดา เว้นแต่จะเปิดใช้งาน core.symlinks ซึ่งจะทำให้ clone นั้นเหลือเพียง CLAUDE.md บรรทัดเดียวแทนที่คำสั่งของคุณ หากใครก็ตามที่ clone repository นี้ทำงานบน Windows ให้ใช้การ import แบบ @AGENTS.md แทน หากคุณตั้งค่า workaround ใดๆ ก่อนที่ Claude Code จะอ่าน AGENTS.md ได้เอง คุณสามารถปล่อยไว้ได้: เอกสารระบุว่าการคงการ import ไว้ "ไม่เคยทำให้ Claude อ่าน AGENTS.md ซ้ำสองครั้ง" และไฟล์ CLAUDE.md ที่เป็น symlink จะถูกอ่านเพียงครั้งเดียว

มีกับดักหนึ่งประการที่เกี่ยวข้อง หลังจาก /compact ไฟล์ CLAUDE.md ที่ root ของโปรเจกต์จะถูกอ่านใหม่จากดิสก์ แต่ไฟล์ที่ซ้อนอยู่ใน subdirectory จะไม่ถูกฉีดเข้าไปใหม่ Claude Code จะโหลดไฟล์เหล่านั้นใหม่เมื่อจำเป็น ในครั้งถัดไปที่ agent ทำงานกับไฟล์ใน directory นั้น เอกสารระบุเรื่องนี้ไว้สำหรับไฟล์ CLAUDE.md และไม่ได้อธิบายการบีบอัดแยกต่างหากสำหรับไฟล์ AGENTS.md ที่อ่านโดยตรง ดังนั้นให้คาดการณ์ว่าไฟล์ที่ซ้อนอยู่ของทั้งสองชื่อจะมีพฤติกรรมเช่นนี้ หากกฎต่อ directory ดูเหมือนจะหยุดทำงานกลางคันระหว่าง session ที่ยาวนาน นั่นมักเป็นสาเหตุ และการอ่านไฟล์ใดๆ ใน directory นั้นจะทำให้กฎกลับมาทำงานอีกครั้ง

การตั้งค่าที่ชี้ agent อื่นไปยัง AGENTS.md

Codex อ่าน AGENTS.md โดยธรรมชาติ ในแต่ละระดับมันจะตรวจสอบ AGENTS.override.md ก่อน ซึ่งช่วยให้หนึ่ง directory มีการ override เฉพาะที่โดยไม่ต้องแก้ไขไฟล์ที่ใช้ร่วมกัน มันจะหยุดรวมไฟล์เมื่อขนาดรวมถึง 32 KiB ซึ่งเป็นค่าเริ่มต้นของ project_doc_max_bytes ซึ่งเป็นอีกเหตุผลหนึ่งที่ควรทำให้ไฟล์ที่ root มีขนาดเล็ก

Aider รับไฟล์ผ่าน .aider.conf.yml ด้วยบรรทัด read: AGENTS.md

Gemini CLI รับไฟล์ผ่าน .gemini/settings.json ด้วย { "context": { "fileName": "AGENTS.md" } }

เอกสารต้นทางระบุการเปลี่ยนชื่อที่รองรับย้อนหลังสำหรับ repository ที่ยังคงใช้ชื่อเอกพจน์แบบเก่า: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

ใน monorepo ขนาดใหญ่มาก การตั้งค่า claudeMdExcludes ของ Claude Code จะข้ามไฟล์บรรพบุรุษตาม path หรือ glob ซึ่งมีประโยชน์เมื่อ directory ของทีมอื่นอยู่เหนือ directory ของคุณ รูปแบบของมันยังใช้กับไฟล์ AGENTS.md ที่ Claude Code อ่านด้วยเช่นกัน

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

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

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 หรือไม่?

อ่าน ตั้งแต่เวอร์ชัน v2.1.277 เป็นต้นไป จากการตรวจสอบเอกสารเมื่อวันที่ 27 ตุลาคม 2026 Claude Code จะอ่าน AGENTS.md โดยค่าเริ่มต้นเมื่อคุณไม่มี CLAUDE.md หรือ CLAUDE.local.md ใน working directory ของคุณหรือเหนือขึ้นไป และมันจะอ่าน AGENTS.md ของไดเรกทอรีย่อยเมื่อเปิดไฟล์ในนั้นด้วยเครื่องมือ Read ในกรณีที่ไดเรกทอรีย่อยนั้นไม่มี CLAUDE.md, .claude/CLAUDE.md หรือ CLAUDE.local.md ของตัวเอง อย่าเพิ่ม CLAUDE.md ไว้ข้างๆ AGENTS.md แต่ละไฟล์: หากมีไฟล์อยู่ที่หรือเหนือ working directory ขึ้นไป Claude จะอ่านเพียง "ไฟล์ CLAUDE.md ของคุณ" เท่านั้น หากคุณต้องการ CLAUDE.md ด้วย ให้ตั้งค่า Project instructions เป็น claude-md-and-agents-md ใน /config หรือใส่ @AGENTS.md ไว้ที่บรรทัดแรกของไฟล์ ให้รัน /memory ในเซสชันและยืนยันว่า path ของ AGENTS.md ปรากฏอยู่ในรายการ

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

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

บทความนี้มีประโยชน์หรือไม่