ทำไม repository ต้องเป็น "แหล่งความจริงเดียว" ของ AI agent และทำไมไฟล์คำสั่งยักษ์ไฟล์เดียวถึงพัง

โดย Nokka (นก-กา) | 23 สิงหาคม 2026

บทความนี้เขียนโดย AI (deepseek-v4-pro via ollama-cloud) ผ่าน Hermes Agent ภายใต้การควบคุมและตรวจสอบคุณภาพโดยมนุษย์, Nokka (นก-กา)

ก่อนอื่น, ทำความเข้าใจศัพท์

ก่อนเข้าเรื่อง ขอปูศัพท์ 3 คำที่คนอ่านบทความนี้ต้องรู้ก่อน:

• System of Record (แหล่งความจริงเดียว): แหล่งข้อมูลเดียวที่ "มีอำนาจสูงสุด" ในการตัดสินใจ, สำหรับ agent นั่นคือ repository
• Knowledge Visibility Gap (ช่องว่างการมองเห็นความรู้): สัดส่วนของความรู้โปรเจกต์ที่ "ไม่อยู่ใน repo", ยิ่งช่องว่างใหญ่ agent ยิ่งพังบ่อย
• Lost in the Middle: ปรากฏการณ์ที่ LLM ใช้ข้อมูล "ตรงกลาง" ของข้อความยาวๆ ได้แย่กว่าต้นและท้าย

ถ้าให้อุปมา: repository คือ "แผนที่" ที่ agent ใช้เดินทาง, ถ้าแผนที่ว่างเปล่า agent ก็ต้องเดา, และการเดาผิดกลายเป็น bug

ปัญหา: ความรู้กระจัดกระจายไปทั่ว

การตัดสินใจทางสถาปัตยกรรมของทีมคุณ กระจัดกระจายอยู่ตาม Confluence, Slack, Jira และหัวของวิศวกรอาวุโสไม่กี่คน

สำหรับมนุษย์ มันพอไปได้, คุณถามเพื่อนได้, ค้น chat log ได้, ขุดเอกสารได้, และถ้าไม่ได้จริงๆ ก็ไปดักถามคนที่ห้องพัก

แต่สำหรับ AI agent ข้อมูลที่ไม่อยู่ใน repository ไม่มีอยู่จริง

Agent มองเห็นแค่ 3 อย่าง

Agent มีแหล่งข้อมูลแค่ 3 ทาง: system prompt + task description, เนื้อหาไฟล์ใน repository, และผลลัพธ์จาก tool

ประวัติ Slack, Jira ticket, หน้า Confluence, และการตัดสินใจที่คุณคุยกับเพื่อนเมื่อบ่ายวันศุกร์, agent มองไม่เห็นทั้งหมด มัน "ไปถามใคร" ไม่ได้, "ค้น chat log" ไม่ได้ โลกการทำงานทั้งหมดของมันคือ repository เอง

OpenAI พูดตรงๆ: ข้อมูลที่ไม่อยู่ใน repo, ไม่มีอยู่สำหรับ agent, เรียกว่า "repo as spec" หลักการที่ repository คือเอกสาร specification ที่มีอำนาจสูงสุด [1]

ทดสอบว่าแผนที่คุณดีพอไหม: Fresh Session Test

เปิด agent session ใหม่เอี่ยม, ให้แค่เนื้อหา repository, แล้วดูว่ามันตอบ 5 คำถามนี้ได้ไหม:

5 คำถามของ Fresh Session Test

คำถาม	ควรมีคำตอบที่ไฟล์
ระบบนี้คืออะไร?	AGENTS.md / README
จัดระเบียบยังไง?	ARCHITECTURE.md / module docs
รันยังไง?	Makefile / init.sh
ตรวจสอบยังไง?	test / lint / check commands
ตอนนี้อยู่ตรงไหน?	PROGRESS.md / feature list / git

ถ้าตอบไม่ได้ แผนที่มีจุดว่าง, ตรงที่ว่าง agent ต้องเดา, เดาผิดกลายเป็น bug, เดามากเปลือง context และทุก session ใหม่ก็ต้องเดาใหม่ทั้งหมด

หลักการวาดแผนที่ที่ดี (4 ข้อ)

1. ความรู้อยู่ข้างโค้ด, กฎเรื่อง API authentication ควรอยู่ข้างโค้ด API ไม่ใช่ฝังในเอกสารยักษ์ ใส่ doc สั้นๆ ในแต่ละ module directory
2. ใช้ไฟล์ entry มาตรฐาน, AGENTS.md คือ "หน้าแรก" ของ agent, 50-100 บรรทัดพอ, ต้องตอบ 3 คำถาม: "โปรเจกต์นี้คืออะไร", "รันยังไง", "ตรวจยังไง"
3. น้อยแต่ครบ, ทุกความรู้ต้องมี use case ชัด, ถ้าลบกฎแล้วไม่กระทบการตัดสินใจของ agent กฎนั้นไม่ควรมี
4. อัปเดตพร้อมโค้ด, ผูกการอัปเดตความรู้เข้ากับการเปลี่ยนโค้ด, ใส่ doc ไว้ใน module directory พอแก้โค้ดก็เห็น doc

ตัวอย่างโครงสร้าง repo ที่ดี

project/
├── AGENTS.md              # Entry: overview, run commands, hard constraints
├── src/
│   ├── api/
│   │   ├── ARCHITECTURE.md  # API layer architecture decisions
│   │   └── ...
│   ├── db/
│   │   ├── CONSTRAINTS.md   # Database operation hard constraints
│   │   └── ...
├── PROGRESS.md             # Current progress: done, in-progress, blocked
└── Makefile                # Standardized commands: setup, test, lint, check

ทำไมไฟล์คำสั่งยักษ์ไฟล์เดียวถึงพัง

คุณเริ่มจริงจังกับ harness, สร้าง AGENTS.md แล้วยัดทุกกฎเข้าไป 1 เดือนผ่านไปไฟล์พองเป็น 300 บรรทัด, 2 เดือน 450, 3 เดือน 600 แล้วคุณสังเกตว่า agent กลับแย่ลง:

• แก้ bug ง่ายๆ แต่ agent เผา context ไปกับการอ่านคำสั่ง deploy ที่ไม่เกี่ยวข้อง
• ข้อจำกัด security สำคัญที่ฝังอยู่บรรทัด 300 ถูกมองข้าม
• กฎ style 3 ข้อขัดแย้งกัน agent เลือกสุ่มทุกครั้ง

นี่คือกับดัก "ไฟล์คำสั่งยักษ์", ทุกอย่างดูมีประโยชน์เลยยัดหมด แต่การหากฎเฉพาะข้อต้องรื้อทั้งไฟล์

4 ปัญหาของไฟล์ยักษ์

ปัญหา	ผล
Context budget ถูกกิน	ไฟล์ 600 บรรทัดกิน 10-20K token = 8-15% ของ window
Lost in the Middle	กฎสำคัญตรงกลางถูกมองข้าม (งานวิจัย Liu et al. 2023 [2])
Priority conflicts	กฎ hard constraint กับ soft guideline ดูเหมือนกันหมด
Maintenance decay	ไฟล์มีแต่โต ไม่เคยหด, signal-to-noise ลดลงเรื่อยๆ

วิธีแก้: แยกไฟล์ตามหัวข้อ

หลักการ: เก็บข้อมูลที่ใช้บ่อยไว้ใกล้มือ, เก็บข้อมูลที่ใช้นานๆ ครั้งไว้ไกลๆ, และไม่แบกสิ่งที่ไม่มีวันใช้

ไฟล์ entry AGENTS.md อยู่ที่ 50-200 บรรทัด มีแค่: project overview (1-2 ประโยค), first-run commands, hard constraints (ไม่เกิน 15 ข้อ), และลิงก์ไป topic documents

# AGENTS.md

## Project Overview
Python 3.11 FastAPI backend, PostgreSQL 15 database.

## Quick Start
- Install: `make setup`
- Test: `make test`

## Hard Constraints
- All APIs must use OAuth 2.0 authentication
- All database queries must use SQLAlchemy 2.0 syntax

## Topic Docs
- API Design Patterns (`docs/api-patterns.md`), Required when adding endpoints
- Database Rules (`docs/database-rules.md`), Required when modifying DB

แต่ละ topic document 50-150 บรรทัด จัดตามหัวข้อใน docs/, agent อ่านเฉพาะเมื่อจำเป็น เหมือน packing cube: ชุดชั้นในกล่องหนึ่ง, ของใช้ห้องน้ำอีกกล่อง, ที่ชาร์จอีกกล่อง หาของไม่ต้องเทกระเป๋าทั้งใบ

เรื่องจริง: 45% → 72% ด้วยการแยกไฟล์

ทีม SaaS หนึ่ง AGENTS.md พองจาก 50 เป็น 600 บรรทัด, agent เริ่มแย่ลง: แก้ bug ง่ายๆ แต่เผา context กับคำสั่ง deploy, กฎ security "ทุก query ต้อง parameterized" ฝังอยู่บรรทัด 300 ถูกมองข้ามบ่อย, กฎ style 3 ข้อขัดแย้ง [3]

ทีมทำ refactoring: AGENTS.md ตัดเหลือ 80 บรรทัด, สร้าง topic docs 3 ไฟล์, ย้าย historical notes ไปเป็น test case หรือลบทิ้ง

ผลลัพธ์: อัตราสำเร็จจาก 45% → 72%, การปฏิบัติตามกฎ security จาก 60% → 95% เพราะกฎย้ายจากกลางไฟล์ไปอยู่บนสุดของ entry file, ไม่ "lost in the middle" อีกต่อไป

สรุปมุมมองของผม

ผมมองว่า 2 บทเรียนนี้คือ "รากฐาน" ของ harness engineering ทั้งหมด: (1) ความรู้ต้องอยู่ใน repo เพราะ agent มองไม่เห็นที่อื่น, (2) ไฟล์คำสั่งต้องสั้นและแยกตามหัวข้อ เพราะไฟล์ยักษ์ทำให้ agent หลงทาง

ถ้าคุณทำได้แค่ 2 อย่างนี้ก่อน, เอา AGENTS.md มาทำให้สั้น + ย้ายความรู้ลง repo, คุณจะเห็นความต่างทันทีโดยไม่ต้องเปลี่ยนโมเดล

AGENTS.md ของคุณตอนนี้ยาวกี่บรรทัดครับ? แล้วความรู้สำคัญของทีมคุณ อยู่ใน repo กี่เปอร์เซ็นต์? คอมเมนต์เล่าให้ฟังได้ครับ

แหล่งอ้างอิง

[1] OpenAI. "Harness Engineering: leveraging Codex in an agent-first world". 2026. https://openai.com/index/harness-engineering/

[2] Liu et al. "Lost in the Middle: How Language Models Use Long Contexts". 2023. https://arxiv.org/abs/2307.03172

[3] Learn Harness Engineering, Lecture 03-04. 2026. https://github.com/walkinglabs/learn-harness-engineering

---

บทความนี้วิเคราะห์จาก OpenAI, arXiv และ walkinglabs/learn-harness-engineering ข้อมูล ณ 23 สิงหาคม 2026 Nokka