Claude Code Harness Foundations
What loads into context
จัดกลุ่มไฟล์ config ของโปรเจกต์ตามจังหวะที่มันเข้า context — อะไรโหลดเต็มตอนเปิด session อะไรโหลดเมื่อถูกแตะ และอะไรไม่เข้า context เลย พร้อม lab ที่ให้ engine ตัดสิน verdict ของคุณ
1) จุดที่ต้องตัดสินใจ: ไฟล์ไหนจะอยู่ใน context ของ session นี้
คุณเพิ่งเขียน convention ของทีมไว้ใน `src/app/CLAUDE.md` แล้วเปิด session ใหม่ที่รากโปรเจกต์ ถาม Claude เรื่องรูปแบบ response ของ API ปรากฏว่ามันตอบเหมือนไม่เคยเห็นข้อความนั้น ทั้งที่ไฟล์อยู่ใน repo และเพิ่งเขียนเมื่อวาน อีกด้านหนึ่ง โปรเจกต์มี `.claude/settings.json` ที่กำหนด permission ไว้ละเอียด คุณไม่แน่ใจว่ามันกินพื้นที่ context ของทุก session หรือเปล่า สองคำถามนี้มีคำตอบเดียวกัน: harness เป็นคนตัดสินว่าไฟล์ไหนกลายเป็นข้อความใน context และตัดสินตอนไหน ไม่ใช่ตัวไฟล์ และไม่ใช่ความจำของคุณจาก session ก่อน
บทนี้จึงไม่สอนให้จำรายชื่อไฟล์เป็นตัว ๆ แต่สอนกฎการโหลดที่ตัดสินทุกไฟล์ด้วยกลไกเดียวกัน: ไฟล์นี้เข้า context ตอนเริ่ม session, ตอนมีคนเปิดไฟล์ที่เกี่ยวข้อง, หรือไม่เข้าเลย เมื่อเข้าใจกฎนี้ คุณจะวางไฟล์ผิดที่ได้น้อยลง และอ่าน setup ของคนอื่นออกเมื่อมันไม่ทำงาน
2) surface นี้คืออะไร: ไฟล์ที่ harness อ่านตอนประกอบ session
ก่อนจะจำชื่อไฟล์ใด ๆ ให้เห็นภาพก่อนว่าเกิดอะไรขึ้นตอนเปิด session: harness เริ่มจาก context ว่าง แล้วอ่านชุดไฟล์ที่โปรเจกต์และเครื่องของคุณมีอยู่ เพื่อตัดสินว่าอะไรควรกลายเป็นข้อความให้โมเดลอ่าน ไฟล์เหล่านั้นแบ่งเป็นสามตระกูลตามเจ้าของและหน้าที่ - ไฟล์หน่วยความจำและกฎ (`CLAUDE.md`, `.claude/rules/*.md`) — เนื้อหาถูกส่งเข้า context ให้โมเดลอ่านโดยตรง - ไฟล์ประกาศความสามารถ (`SKILL.md`, `.claude/agents/*.md`) — harness ส่งเฉพาะ description เพื่อให้โมเดลรู้ว่ามีอะไรให้เรียกใช้ ส่วนเนื้อหาข้างในรอจังหวะถูกเรียกจริง - ไฟล์ตั้งค่า (`settings.json`, hook config, `.mcp.json`) — harness อ่านเพื่อตั้งค่าตัวเอง ไม่ได้ส่งให้โมเดล ความต่างของสามตระกูลนี้คือเหตุผลที่คำถาม "ไฟล์นี้อยู่ใน context ไหม" ตอบด้วยชื่อไฟล์อย่างเดียวไม่ได้ ต้องรู้ว่ามันถูกใช้ทำอะไร
ตำแหน่งที่กำหนดว่า context จะประกอบจากอะไร
ตัวอย่างโครงไฟล์ของ shop-api เมื่อ setup เริ่มมีครบใน phase ถัดไป — fixture ของบทนี้จำลองโครงเดียวกันในขนาดเล็ก เพื่อให้ checks ตัดสินได้โดยไม่ต้องมีไฟล์เกินจำเป็น
- shop-api/
- CLAUDE.mdหน่วยความจำโปรเจกต์ที่ราก
- .claude/
- settings.jsonตั้งค่า ไม่เข้า context
- rules/
- api.mdประกาศ paths ได้
- testing.mdประกาศ paths ได้
- skills/
- release-notes/
- SKILL.mddescription เข้า context
- agents/
- order-reviewer.mddescription เข้า context
3) จัดกลุ่มตามจังหวะ: session-start, on-demand และ never
harness ตัดสินจังหวะของแต่ละไฟล์จากสองอย่างเท่านั้น: ชนิดของไฟล์พร้อมตำแหน่งที่มันอยู่ และ frontmatter ที่ไฟล์นั้นประกาศไว้ ผลลัพธ์มีสามแบบ
สามจังหวะของ context-load
session-start — โหลดเต็มก่อนคุณพิมพ์คำแรก
ไฟล์หน่วยความจำที่อยู่รากโปรเจกต์ และ rule ที่ไม่มี paths: ถูกอ่านเข้า context ทั้งไฟล์ทุกครั้งที่ session เริ่ม กฎถาวรของทีมจึงควรอยู่ที่นี่
on-demand — โหลดเมื่อมีเหตุให้โหลด
CLAUDE.md ที่อยู่ในโฟลเดอร์ย่อยเข้าตอน Claude อ่านไฟล์ในโฟลเดอร์นั้น rule ที่ประกาศ paths: เข้าตอนเปิดไฟล์ที่ตรงเงื่อนไข และ body ของ skill เข้าตอน skill ถูกเรียกใช้ ส่วน description ของ skill และ subagent เข้าตั้งแต่เริ่ม session แต่ body รอ
never — อ่านโดย harness แต่ไม่เข้า context
settings.json, hook config และ .mcp.json เป็นการตั้งค่าของ harness เอง มันมีผลต่อ session แต่ไม่เป็นข้อความที่โมเดลเห็น การซ่อนข้อมูลในไฟล์เหล่านี้จึงต่างจากการซ่อนในไฟล์หน่วยความจำ
จุดที่คนพลาดบ่อยคือคิดว่า "อยู่ใน repo" เท่ากับ "โมเดลเห็น" — ความจริงคือไฟล์เดียวกันย้ายตำแหน่งแล้วเปลี่ยนจังหวะได้ และไฟล์ที่ harness อ่านเพื่อตั้งค่าก็ไม่เคยกลายเป็นข้อความใน context เลย
4) contrast: ถูก syntax แต่ผิดที่
config สองชิ้นด้านล่าง parse ผ่านทั้งคู่ ไม่มี syntax error ให้จับผิด ต่างกันแค่ตำแหน่งของไฟล์ — และนั่นพอที่จะทำให้เจตนาของผู้เขียนไม่เกิดผล
วาง convention ผิดที่: ถูก syntax แต่ไม่เข้า context
สองไฟล์นี้เนื้อหาเหมือนกันและ parse ผ่านทั้งคู่ ต่างกันแค่ตำแหน่ง — และตำแหน่งคือสิ่งที่ตัดสินว่า session อื่นจะเห็นมันหรือไม่
เจตนาคือให้ทุก session รู้ convention แต่การวางไว้ในโฟลเดอร์ย่อยทำให้มันเป็น on-demand — session ที่ไม่ได้แตะไฟล์ใน src/app/ จะไม่เห็นข้อความนี้เลย
วางที่ราก ไฟล์หน่วยความจำนี้โหลดเต็มทุกครั้งที่ session เริ่ม จึงตรงกับเจตนาของ convention ที่ต้องใช้ทุก session
5) ฝึก: อ่าน verdict จาก engine แล้วแก้ config ให้ตรงเป้า
สอง labs นี้รัน config จริงผ่าน engine ตัวเดียวกับที่ใช้ในทุกบทของ track — verdict ที่คุณเห็นคือผลของกฎที่คุณเพิ่งอ่าน ไม่ใช่คำอธิบาย Lab แรกให้คุณทำตามทีละขั้นพร้อมอ่านเหตุผลของทุก verdict ส่วน Lab ที่สองมีแค่เป้าหมาย ให้คุณหาจุดที่ config ไม่ตรงเป้าเอง
6) ตาราง volatile: ตรวจสอบล่าสุดเมื่อไร
กลไกการโหลด (session-start / on-demand / never) เป็นส่วนที่นิ่ง แต่ชื่อไฟล์ ฟิลด์ และรายละเอียดปลีกย่อยของแต่ละ surface เปลี่ยนได้ตามการพัฒนาผลิตภัณฑ์ ตารางนี้จึงรวมข้อเท็จจริงเหล่านั้นไว้ที่เดียว พร้อมวันที่ตรวจสอบและหน้าอ้างอิง — ก่อนเชื่อรายชื่อหรือรายละเอียดใด ให้เปิดหน้าอ้างอิงตรวจก่อน
| ไฟล์ / เงื่อนไข | จังหวะที่เข้า context | เอกสารเจ้าของ |
|---|---|---|
| `CLAUDE.md` ที่รากโปรเจกต์, user และ managed | session-start — โหลดเต็ม | https://code.claude.com/docs/en/memory |
| `CLAUDE.md` ในโฟลเดอร์ย่อย | on-demand — เมื่ออ่านไฟล์ในโฟลเดอร์นั้น | https://code.claude.com/docs/en/memory |
| `.claude/rules/*.md` ที่ไม่มี `paths:` | session-start — โหลดเต็ม | https://code.claude.com/docs/en/memory |
| `.claude/rules/*.md` ที่มี `paths:` | on-demand — เมื่อเปิดไฟล์ที่ตรงเงื่อนไข | https://code.claude.com/docs/en/memory |
| `SKILL.md` — description | session-start | https://code.claude.com/docs/en/skills |
| `SKILL.md` — body | on-demand — เมื่อ skill ถูกเรียกใช้ | https://code.claude.com/docs/en/skills |
| `SKILL.md` ที่มี `disable-model-invocation: true` | ไม่แม้แต่ description | https://code.claude.com/docs/en/skills |
| `.claude/agents/*.md` — description / body | session-start / on-demand | https://code.claude.com/docs/en/sub-agents |
| `.claude/settings.json`, hook config, `.mcp.json` | never — ไม่เข้า context | https://code.claude.com/docs/en/settings |
| ตรวจสอบล่าสุด: 2026-09-22 · https://code.claude.com/docs/en/memory |
7) ตรวจความเข้าใจและก้าวต่อไป
ทดสอบความเข้าใจ: อะไรเข้า context และเมื่อไร
เช็กว่าคุณแยกสามจังหวะของ context-load ออก และเลือกตำแหน่งไฟล์ตามเจตนาได้
ไฟล์ใดที่ harness อ่านเพื่อตั้งค่าตัวเอง แต่ไม่มีทางกลายเป็นข้อความใน context ของโมเดล
ต้องให้ convention ของทีมถูกเห็นในทุก session ตั้งแต่ก่อนพิมพ์คำแรก ควรวางไว้ที่ใด
rule ที่ประกาศ `paths:` จะมี verdict เป็น ______ เมื่อเปิดไฟล์ที่ตรงเงื่อนไข (ตอบเป็นคำภาษาอังกฤษแบบที่ engine แสดง)
verdict มีสามค่า: session-start, on-demand และ never
- สามจังหวะคือ session-start, on-demand และ never — ไฟล์หนึ่ง ๆ ถูกตัดสินจากชนิด ตำแหน่ง และ frontmatter ของมัน
- ไฟล์ตั้งค่าอยู่ใน repo แต่ไม่เคยเข้า context — อย่าเก็บข้อมูลที่ไม่อยากให้โมเดลเห็นลงในไฟล์หน่วยความจำ
- skill และ subagent ประกาศตัวด้วย description ตั้งแต่เริ่ม session ส่วน body รอจังหวะถูกเรียกใช้
- ก้าวต่อไป: บทถัดไปคือ Sessions and transcripts ซึ่งต่อจากคำถามว่า 'อะไรเข้า context' ไปสู่คำถามว่า 'session เก็บอะไรไว้บนดิสก์ และย้อนกลับไปดูได้อย่างไร'