โครงสร้างโปรเจกต์ Claude Code: ไฟล์ไหนทำหน้าที่อะไร

ป้ายกำกับที่ใช้ในหน้านี้: จากภาพ คือสิ่งที่เห็นในภาพโดยตรง, ตีความ คือข้อสรุปของเราเอง, ความรู้ทั่วไป คือข้อมูลที่ภาพไม่ได้ให้, ยังไม่ทดสอบ คือสิ่งที่ยังไม่ได้ลองใช้จริง ข้อความที่อ่านไม่ออกจะระบุไว้ตรงจุด

🎯 แก่นของเรื่อง

ความคิดหลักคือแยกความรู้ของโปรเจกต์ออกเป็นไฟล์ตามหน้าที่ ได้แก่ context, การตั้งค่า, กฎ, งานซ้ำ, ความสามารถเฉพาะทาง, ผู้ช่วยเฉพาะทาง และการตรวจอัตโนมัติ Claude Code จะอ่านไฟล์เหล่านี้เองทุกครั้ง คุณไม่ต้องอธิบายซ้ำทุกแชต

ทำไมถึงได้ผล (ตีความ)

• ไฟล์ที่อยู่ใน repo ถูกโหลดอัตโนมัติ ทุกครั้งที่เริ่มงานโมเดลจึงเริ่มจากความรู้ชุดเดียวกัน ผลลัพธ์จึงคาดเดาได้มากขึ้น
• ไฟล์ที่ commit เข้า repo ทุกคนในทีมได้ชุดเดียวกัน ส่วนไฟล์ .local ที่ git ไม่ติดตามเก็บความชอบส่วนตัวไว้โดยไม่กระทบคนอื่น
• Hooks เป็นสคริปต์ ผลของมันจึงแน่นอน ส่วนกฎในไฟล์ markdown เป็นคำแนะนำที่โมเดลอ่านแล้วทำตาม (ตีความ)

20% ที่สำคัญที่สุด

📈 ช่วยให้ดีขึ้นอย่างไร

ภาพไม่มีตัวเลขวัดผล มีเพียงข้อความสรุปว่าได้ผลลัพธ์ "better, safer and faster" ซึ่งเป็นข้อความอ้าง ไม่ใช่ผลวัด ทุกแถวด้านล่างจึงยังไม่ใช่ค่าที่วัดแล้ว

🧪 ลองใช้

ตัวอย่างประกอบ (ตัวเลขเป็นของเราเอง ไม่ได้มาจากภาพ)

สมมติทีมเขียน API 5 คน และใน review แต่ละ PR มีคอมเมนต์เรื่องสไตล์ เฉลี่ย 6 ข้อ

1. เขียน rules/code-style.md ที่ระบุการตั้งชื่อและรูปแบบ
2. วัด 10 PR ถัดไป สมมติได้เฉลี่ย 3 ข้อ
3. การลดลง = (6 − 3) ÷ 6 = 50%
4. เงื่อนไขผ่านที่ตั้งก่อนวัด: ลดลงอย่างน้อย 30% ผลสมมตินี้จึงผ่าน

เมื่อไรควรใช้

ก้าวแรกที่เล็กที่สุด

สร้าง CLAUDE.md ที่รากโปรเจกต์ ใส่ 3 เรื่อง: โปรเจกต์ทำอะไร คำสั่ง build/test คืออะไร และกฎโค้ด 3 ข้อที่ผิดบ่อยที่สุด

เช็กลิสต์ติดตั้งทีละชั้น

วิธีเช็กว่าดีขึ้นจริง

• ตัวชี้วัด: จำนวนคอมเมนต์สไตล์ต่อ PR หรือเวลาที่ใช้ต่อ task ซ้ำ
• baseline: เก็บ 10 งานก่อนติดตั้ง
• เงื่อนไขผ่าน: ตั้งก่อนวัด เช่น ลดลงอย่างน้อย 30% เมื่อวัด 10 งานหลังติดตั้ง

🧠 ทดสอบความเข้าใจ

🗂️ แผนผังโครงสร้าง

ภาพวาดโครงสร้างโดยมี project/ เป็นรากของ repo ตามตารางด้านล่าง

project/                    # repo root
├── CLAUDE.md               # project overview and coding guidelines
├── CLAUDE.local.md         # personal overrides (git-ignored)
├── .mcp.json               # MCP server configuration
└── .claude/                # Claude-specific config
    ├── settings.json       # team settings
    ├── settings.local.json # personal settings
    ├── rules/
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    ├── commands/
    │   ├── review.md
    │   └── fix-issue.md
    ├── skills/
    │   └── deploy/
    │       ├── SKILL.md
    │       └── deploy-step-by-step.md
    ├── agents/
    │   ├── code-reviewer.md
    │   └── security-auditor.md
    └── hooks/
        └── validate-bash.sh

Note จุดที่ภาพกำกวม: เส้นเชื่อมของ rules/, commands/, skills/, agents/ และ hooks/ ในภาพอาจอ่านได้ว่าอยู่ใต้ .claude/ หรือเป็นพี่น้องกับมัน แผนผังข้างบนวางไว้ใต้ .claude/ ซึ่งเป็นการตีความ และตรงกับข้อความ "Claude specific config (keep here)" ที่ภาพเขียนไว้ข้าง .claude/ ควรตรวจกับเอกสารทางการของ Anthropic ก่อนใช้จริง

📄 รายละเอียดแต่ละส่วน

ไฟล์ที่รากโปรเจกต์ (Project config)

Settings

• settings.json: การตั้งค่าของทีม อยู่ใน .claude/ (จากภาพ)
• settings.local.json: การตั้งค่าส่วนตัวที่ override ได้ (จากภาพ)
• รูปแบบเดียวกับไฟล์ที่รากโปรเจกต์: ไฟล์ร่วมเข้า repo ไฟล์ .local เก็บเฉพาะตัว (ตีความ)

Rules

Custom commands

เหตุผลที่ใช้ (จากภาพ): นิยามคำสั่ง slash ที่ใช้ซ้ำได้ เร่งเวิร์กโฟลว์ที่ทำบ่อย และให้ทีมทำงานแบบเดียวกัน

Skills

• skills/deploy/ เป็นตัวอย่างสกิลสำหรับ deploy (จากภาพ)
• SKILL.md อธิบายว่าสกิลทำอะไร และ deploy-step-by-step.md เก็บขั้นตอนทีละข้อ (จากภาพ)
• สกิลถูกโหลดอัตโนมัติ และแต่ละสกิลมีคำสั่งที่ชัดเจน (จากภาพ ส่วนท้ายของข้อความถูกปุ่มของแอปบังจนอ่านไม่ครบ)

Sub-agents

หลักการที่ภาพให้: ใช้ agent ที่เหมาะกับงาน เช่น code review และ security

Hooks

• hooks/validate-bash.sh ทำ pre-commit และ pre-run checks (จากภาพ)
• ใช้รันสคริปต์ก่อนหรือหลังการกระทำ ตรวจ lint เทสต์ หรือ deploy และช่วยให้โค้ดปลอดภัย (จากภาพ ข้อความท้ายบางคำอ่านไม่ครบ)
• ความรู้ทั่วไป: การผูกสคริปต์เข้ากับเหตุการณ์ตามปกติตั้งค่าในไฟล์ settings ไม่ใช่เพียงวางสคริปต์ในโฟลเดอร์ hooks/ รายละเอียดให้ตรวจกับเอกสารทางการ (ยังไม่ทดสอบ)

🔄 ลำดับการทำงานทั้งสาย (How it all works)

หกขั้นตอนตามภาพ ซ้ายไปขวา

flowchart LR
    A[1 อ่าน CLAUDE.md] --> B[2 โหลด settings, rules, skills]
    B --> C[3 ใช้ commands และ sub-agents]
    C --> D[4 ต่อเครื่องมือผ่าน MCP]
    D --> E[5 รัน hooks และ validations]
    E --> F[6 ได้ผลลัพธ์ดีขึ้น ปลอดภัยขึ้น เร็วขึ้น]

⚠️ Risks

Warning อย่า commit ไฟล์ส่วนตัวหรือความลับ ใน CLAUDE.local.md และ settings.local.json ต้องอยู่ใน .gitignore ตั้งแต่แรก และอย่าใส่ API key ในไฟล์ที่ commit รวมถึง .mcp.json

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

✅ Decision / next steps

Recommendation เริ่มจาก CLAUDE.md ก่อน แล้วเพิ่มทีละชั้นเมื่อพบปัญหาจริง: กฎซ้ำ → rules/, prompt ซ้ำ → commands/, ต้องบังคับ → hooks

1. สร้าง CLAUDE.md และใส่ไฟล์ .local ใน .gitignore
2. วัด baseline 10 งาน
3. เพิ่ม rules/ และ commands/ แล้ววัดซ้ำ
4. ตรวจรายละเอียดรูปแบบไฟล์กับเอกสารทางการของ Anthropic ก่อนใช้ hooks และ skills จริง

📖 ศัพท์เฉพาะ

🔤 ตัวย่อที่ใช้ในหน้านี้

หมายเหตุ: ชื่อเต็มของทุกแถวเป็นความรู้ทั่วไป ภาพไม่ได้ให้ชื่อเต็มไว้ ส่วนชื่อไฟล์ CLAUDE.md และ SKILL.md เป็นชื่อไฟล์ ไม่ใช่ตัวย่อ

📌 Summary

• โครงสร้างแยกหน้าที่เป็นเจ็ดกลุ่ม: project config, settings, rules, commands, skills, agents, hooks (จากภาพ)
• ไฟล์ร่วมเข้า repo ไฟล์ .local เก็บเฉพาะตัวและต้องถูก git ละเว้น (จากภาพ)
• ลำดับการทำงานมีหกขั้น ตั้งแต่อ่าน CLAUDE.md จนถึงรัน hooks (จากภาพ)
• ผลลัพธ์ที่ดีขึ้นยังเป็นข้อความอ้าง ไม่มีตัวเลขวัด จึงต้องวัดเองด้วย baseline
• ตำแหน่งโฟลเดอร์ย่อยและวิธีผูก hooks ต้องตรวจกับเอกสารทางการก่อนใช้