Deep Dive: Claude Code .claude/ project setup

Claude Code และ AI coding agent หลายตัวเก่งขึ้นมากครับ แต่ปัญหาที่ผมเจอบ่อยเวลาเอามาใช้กับงานจริงไม่ใช่แค่เรื่องโมเดลตอบดีไหม

ปัญหาคือ agent ไม่รู้จักโปรเจกต์เราเท่ากันทุกครั้ง

วันนี้เราเปิด session ใหม่ ต้องบอก stack ใหม่ บอก test command ใหม่ บอก coding convention ใหม่ พรุ่งนี้คนในทีมอีกคนเปิด Claude Code ใน repo เดียวกัน แต่สั่งคนละแบบ กฎคนละชุด สุดท้าย output เลยไม่คงเส้นคงวา

นี่คือปัญหา repeatability ของ AI coding agent ครับ

Claude Code แก้ปัญหานี้ด้วยโครงสร้างไฟล์ที่ให้โปรเจกต์บอก agent ได้ว่าอะไรคือบริบททีม อะไรคือ permission อะไรคือ workflow และอะไรเป็น preference ส่วนตัวของแต่ละคน

จุดกลางของเรื่องนี้คือ .claude/ folder

โครงสร้างหลักของ .claude/ project

ตาม official docs ของ Claude Code โปรเจกต์หนึ่งสามารถมีไฟล์และโฟลเดอร์สำคัญประมาณนี้:

your-project/
├── CLAUDE.md
├── CLAUDE.local.md
└── .claude/
    ├── settings.json
    ├── settings.local.json
    ├── commands/
    ├── rules/
    ├── skills/
    └── agents/

ถ้าแปลเป็นภาษาคนทำงาน แต่ละส่วนมีหน้าที่แบบนี้ครับ

• CLAUDE.md คือคู่มือทีมที่ Claude อ่านทุก session เช่น build command, test command, stack, coding convention, architecture note ควร commit เข้า git
• CLAUDE.local.md คือ note ส่วนตัวของคุณในโปรเจกต์นี้ ไม่ควร commit เข้า git
• .claude/settings.json คือ project settings เช่น permissions, hooks, env หรือ config ที่ทีมควรแชร์ร่วมกัน ควร commit เข้า git
• .claude/settings.local.json คือ local override ของแต่ละคน เช่น permission หรือ experiment ส่วนตัว ไม่ควร commit เข้า git
• .claude/rules/ คือ instruction แยกไฟล์ตามหัวข้อหรือ path เช่น testing, API convention, code style
• .claude/skills/ คือ workflow ที่ agent โหลดเมื่อจำเป็น เช่น security review, deploy, run checklist
• .claude/agents/ คือ subagent persona เฉพาะทาง เช่น code reviewer หรือ security auditor

ผมชอบคิดว่า .claude/ คือ control center ของโปรเจกต์สำหรับ Claude Code

ไม่ใช่ทุกโปรเจกต์ต้องมีครบทุกโฟลเดอร์ แต่ถ้าเริ่มใช้ Claude Code กับทีมจริง การมีโครงสร้างนี้ช่วยลดการสั่งซ้ำและลดการเดาบริบทได้มาก

เริ่มจากอะไร ก่อนจะจัดเต็ม

Official docs ของ Claude Code เขียนไว้ค่อนข้างตรงว่า คนส่วนใหญ่แก้แค่ CLAUDE.md กับ settings.json ก็พอ ส่วน skills, rules, subagents เป็น optional

ผมเห็นด้วยครับ

อย่าเริ่มจากการสร้าง .claude/ ให้ครบทุกอย่างตั้งแต่วันแรกเพราะดูเป็นมืออาชีพ เริ่มจากของที่ช่วยงานจริงก่อน

ขั้นแรก: เขียน CLAUDE.md ให้ดี

ไฟล์นี้ควรตอบคำถามที่คุณไม่อยากพิมพ์ซ้ำทุก session เช่น

• โปรเจกต์นี้ใช้ stack อะไร
• build command คืออะไร
• test command คืออะไร
• lint command คืออะไร
• source code อยู่ folder ไหน
• API convention เป็นแบบไหน
• test ต้องเขียนไว้ตรงไหน
• rule ไหนห้ามพลาด เช่น named exports, response shape, migration policy

Docs เรื่อง memory ของ Claude Code แนะนำว่า CLAUDE.md ควรสั้นและชัด เป้าหมายประมาณไม่เกิน 200 บรรทัด ถ้าเริ่มยาวเกิน หรือเริ่มกลายเป็น procedure หลายขั้น ให้แยกไปเป็น skill หรือ path-scoped rule แทน

ขั้นที่สอง: ตั้ง .claude/settings.json สำหรับทีม

ส่วนนี้ใช้เก็บ configuration ที่เกี่ยวกับการทำงานของ Claude Code ใน project scope เช่น permissions, hooks, env หรือ setting ที่ควรแชร์กับทีม

ประเด็นสำคัญคือแยกให้ชัดว่าอะไรเป็นของทีม และอะไรเป็นของส่วนตัว

ของทีมควรอยู่ใน git เช่น CLAUDE.md และ .claude/settings.json

ของส่วนตัวควรอยู่ local เช่น CLAUDE.local.md และ .claude/settings.local.json

Settings มี scope ไม่เท่ากัน

Claude Code แบ่ง settings เป็นหลาย scope ได้แก่ managed, user, project และ local

ลำดับ priority ตาม docs คือ:

1. managed
2. command line args
3. local
4. project
5. user

แปลแบบง่าย ๆ คือ policy ขององค์กรชนะทุกอย่าง ส่วน local setting ของคุณชนะ project setting เฉพาะบนเครื่องคุณเอง และ user setting เป็นค่า default ทั่วไปถ้า scope อื่นไม่ได้กำหนดไว้

สำหรับทีมเล็ก จุดที่ควรรู้คือ:

• อยากให้ทั้งทีมใช้ร่วมกัน ใส่ .claude/settings.json
• อยากทดลองเอง ไม่อยากกระทบทีม ใส่ .claude/settings.local.json
• อยากใช้ทุกโปรเจกต์ของตัวเอง ใส่ ~/.claude/settings.json

ตรงนี้ดูเหมือนรายละเอียดเล็ก ๆ แต่ช่วยลดปัญหา config ตีกันในทีมได้มาก

เรื่องที่หลายคนสับสน: commands กับ skills

ในภาพอ้างอิงจะมี .claude/commands/ เช่น review.md, fix-issue.md, deploy.md แล้วกลายเป็น slash command แบบ /project:review หรือ /project:deploy

แต่ docs ปัจจุบันของ Claude Code มี nuance สำคัญครับ

custom commands ถูก merge เข้าไปเป็นส่วนหนึ่งของ skills แล้ว

พูดง่าย ๆ คือไฟล์แบบ .claude/commands/deploy.md และ skill แบบ .claude/skills/deploy/SKILL.md สามารถสร้าง /deploy ได้คล้ายกัน และ existing commands เดิมยังใช้งานได้

ดังนั้นถ้าโปรเจกต์คุณมี .claude/commands/ อยู่แล้ว ไม่ต้อง panic และไม่ต้องรีบ migrate ทุกอย่างทันที

แต่ถ้าเริ่มสร้าง capability ใหม่ในวันนี้ ผมจะพิจารณา skills/ ก่อน เพราะ skill รองรับ workflow ที่ซับซ้อนกว่า มี SKILL.md เป็นมาตรฐานกว่า และ body ของ skill โหลดเข้ามาเมื่อ relevant ไม่ใช่โหลดทุกอย่างตั้งแต่ต้นเหมือน CLAUDE.md

Rules, skills, agents ควรใช้ตอนไหน

ผมจะแยกง่าย ๆ แบบนี้ครับ

1) ใช้ rules/ เมื่อ instruction มี scope ชัด

เช่น project มี code style สำหรับ frontend, API convention สำหรับ backend หรือ testing rule เฉพาะไฟล์บางแบบ

ถ้าเอาทุกอย่างไปใส่ใน CLAUDE.md ไฟล์จะยาวและ Claude ต้องแบก context ที่ไม่เกี่ยวกับงานปัจจุบันตลอดเวลา

2) ใช้ skills/ เมื่อเป็น workflow ที่ทำซ้ำ

เช่น security review checklist, deploy checklist, run verification, release note, migration review

ถ้าคุณพบว่าต้อง copy paste prompt เดิมซ้ำ ๆ ให้ Claude ทำงานแบบเดิม นั่นคือสัญญาณว่าควรแยกเป็น skill

3) ใช้ agents/ เมื่ออยากได้ persona เฉพาะทาง

เช่น code reviewer, security auditor, test engineer หรือ doc reviewer

Subagent ช่วยแยกมุมมองและ context ได้ แต่ไม่ควรสร้างเยอะเกินจำเป็น เพราะจะเพิ่ม process overhead ถ้าทีมยังไม่มี workflow ชัด

ทำไมเรื่องนี้สำคัญกับทีมจริง

ผมมองว่าจุดสำคัญที่สุดของ .claude/ ไม่ใช่เรื่อง folder สวย ๆ ครับ

แก่นจริงคือการทำให้ AI coding agent ทำงานบน operating manual เดียวกับทีม

ถ้าไม่มีคู่มือ Agent จะเดาเองจากไฟล์ที่เปิด เจออะไรใน context ก็ยึดสิ่งนั้น บางครั้งเดาถูก บางครั้งเดาผิด และทุก session เริ่มใหม่เหมือนพนักงานใหม่ที่ยังไม่เคย onboarding

แต่ถ้า project มี CLAUDE.md, settings, rules, skills และ agents ที่ออกแบบพอดี Agent จะเริ่มงานจากบริบทที่ทีมตั้งใจให้ใช้ ไม่ใช่จากความจำลอย ๆ หรือ prompt สั้น ๆ ที่คนพิมพ์สดในแต่ละวัน

สำหรับ founder หรือ operator ที่เริ่มให้ AI coding agent ช่วยทีม dev ผมมองว่านี่คือจุดเปลี่ยนจากการใช้ AI แบบ individual productivity ไปสู่การใช้ AI แบบ team workflow

Operator Kit: .claude/ Project Setup Checklist

ใช้ checklist นี้กับโปรเจกต์ Claude Code ของคุณได้เลยครับ

Step 1: สร้าง CLAUDE.md

ใส่เฉพาะสิ่งที่ Claude ควรรู้ทุก session:

• build command
• test command
• lint command
• stack หลัก
• project layout
• API convention
• testing convention
• rule ที่ทีมตกลงร่วมกัน

ถ้าไฟล์เริ่มเกิน 200 บรรทัด ให้ถามตัวเองว่าอะไรควรย้ายไปเป็น rule หรือ skill

Step 2: ตั้ง .claude/settings.json

ใส่ config ที่ทีมควรแชร์ร่วมกัน เช่น permission, hook หรือ env ที่จำเป็นกับ project

อย่าใส่ personal preference หรือ secret ลงไปในไฟล์นี้

Step 3: แยก local override

ใช้ CLAUDE.local.md และ .claude/settings.local.json สำหรับของส่วนตัว เช่น sandbox URL, permission ทดลอง, preference เฉพาะเครื่อง

ถ้าสร้างเอง อย่าลืมใส่ใน .gitignore

Step 4: เพิ่ม rules/ เมื่อ instruction เริ่มแยกตามบริบท

ตัวอย่าง:

.claude/rules/testing.md
.claude/rules/api-conventions.md
.claude/rules/code-style.md

Step 5: เพิ่ม skills/ เมื่อมี workflow ซ้ำ

ตัวอย่าง:

.claude/skills/security-review/SKILL.md
.claude/skills/deploy/SKILL.md

ถ้างานเป็น procedure หลายขั้นและต้องใช้ซ้ำ skill มักเหมาะกว่าใส่ใน CLAUDE.md

Step 6: เพิ่ม agents/ เมื่อต้องการ reviewer เฉพาะทาง

ตัวอย่าง:

.claude/agents/code-reviewer.md
.claude/agents/security-auditor.md

อย่าสร้าง subagent เพราะมันดู advanced ให้สร้างเมื่อทีมมีงานที่ต้องการมุมมองแยกจริง ๆ

สรุป

ในความเห็นของผม .claude/ ไม่ใช่ของแต่งโปรเจกต์ แต่เป็น operating manual ของ Claude Code

ถ้าใช้คนเดียวแบบเล่น ๆ อาจยังไม่รู้สึกต่างมาก แต่ถ้าใช้กับทีม ใช้กับ production repo หรือใช้กับงานที่ต้องทำซ้ำบ่อย ๆ ความต่างจะชัดขึ้นเรื่อย ๆ

เริ่มง่ายที่สุดคือ CLAUDE.md กับ .claude/settings.json

จากนั้นค่อยเพิ่ม rules/, skills/, และ agents/ ตาม pain จริง ไม่ใช่ตามความอยากทำ folder ให้ครบ

สุดท้าย AI coding agent ที่ดีไม่ได้ต้องการ prompt ยาวที่สุดครับ

มันต้องการบริบทที่ถูกที่ ถูกเวลา และถูก scope มากกว่า