CCA · Foundations

แยก CLAUDE.md ให้เป็นโมดูล: @import และ .claude/rules/

แนวคิด

เมื่อ CLAUDE.md เริ่มยาว การยัดทุกอย่างไว้ไฟล์เดียวทำให้อ่านยากและกฎสำคัญหายไปในความรก มีสองกลไกที่ช่วยแตกมันออกเป็นโมดูล อย่างแรกคือ @import syntax ที่อ้างไฟล์ภายนอกเข้ามา เขียนเป็น @path/to/file ที่ตำแหน่งใดก็ได้ใน CLAUDE.md แล้ว Claude Code จะ expand เนื้อหาไฟล์นั้นเข้า context ตอน launch

@import รับได้ทั้ง relative path และ absolute path โดย relative path จะ resolve เทียบกับไฟล์ที่มี import นั้น ไม่ใช่ working directory ไฟล์ที่ถูก import ยัง import ต่อได้แบบ recursive ลึกได้สูงสุดสี่ hop และถ้าอยากอ้าง path เป็นข้อความเฉย ๆ โดยไม่ import ให้ครอบด้วย backtick เช่นเขียน @README ในเครื่องหมาย backtick จะไม่ถูกดึงเข้ามา

อย่างที่สองคือ directory .claude/rules/ ที่ให้เราแยกกฎเป็นไฟล์ตามหัวข้อ เช่น testing.md, api-conventions.md, deployment.md ทุกไฟล์ .md ในนั้นถูกค้นพบแบบ recursive และ rule ที่ไม่มี paths frontmatter จะถูกโหลดตอน launch ด้วยลำดับความสำคัญเท่ากับ .claude/CLAUDE.md

ทำไมสำคัญ

ประโยชน์ของ @import คือให้ maintainer แต่ละ package เลือก include เฉพาะไฟล์มาตรฐานที่เกี่ยวกับ domain ของตน เช่น package ฝั่ง frontend import แค่ standard ของ UI ส่วน package ฝั่ง data import standard ของ database ทำให้แต่ละ CLAUDE.md โฟกัสและดูแลง่าย แทนที่จะทำสำเนากฎเดียวกันหลายที่

แต่มีความเข้าใจผิดที่ต้องระวัง @import ช่วยเรื่อง "การจัดระเบียบ" ไม่ใช่ "การประหยัด context" เพราะไฟล์ที่ถูก import ยังโหลดเข้า context เต็ม ๆ ตอน launch เหมือนเขียนรวมไว้ในไฟล์เดียว ถ้าเป้าหมายคือลด token ที่กินทุก session สิ่งที่ตอบโจทย์กว่าคือ path-scoped rule ใน .claude/rules/ ที่โหลดเฉพาะตอนแตะไฟล์ที่ตรง pattern

สำหรับการแตก monolith .claude/rules/ คือทางเลือกที่สะอาดกว่าการมี CLAUDE.md ก้อนเดียวมหึมา เพราะแต่ละหัวข้อแยกไฟล์ ทีมช่วยกันดูแลเป็นส่วน ๆ ได้ และยังต่อยอดไปเป็น path-specific rule ในบทถัดไปได้ทันที

ตัวอย่าง

# CLAUDE.md — ใช้ @import ดึงมาตรฐานที่เกี่ยวข้อง
ดู @README.md สำหรับภาพรวม และ @package.json สำหรับคำสั่ง npm

# Additional Instructions
- git workflow @docs/git-instructions.md
- ความชอบส่วนตัวข้าม worktree @~/.claude/my-project-instructions.md

# หรือแตก monolith เป็นไฟล์ตามหัวข้อใน .claude/rules/
.claude/
├── CLAUDE.md
└── rules/
    ├── testing.md          # โหลดตอน launch (ไม่มี paths)
    ├── api-conventions.md
    └── deployment.md

เช็คความเข้าใจ

@import ช่วยเรื่องใด และไม่ช่วยเรื่องใด

rule ใน .claude/rules/ ที่ไม่มี paths frontmatter ถูกโหลดเมื่อใด

อ่านต่อ