เป้าหมายของบทนี้: ให้ output ของ Claude คาดเดาได้ และผ่านรีวิวได้โดยไม่ต้องแก้ซ้ำ
หลักคิดเดียวที่ต้องจำ:
Claude ไม่ได้อ่านใจทีมคุณ มันอ่านสิ่งที่อยู่ใน context เท่านั้น ผลลัพธ์ที่ผิด convention เกือบทุกครั้ง = คุณไม่ได้บอก ไม่ใช่มันไม่รู้
CLAUDE.md ที่วางไว้ที่ราก repo จะถูกอ่านอัตโนมัติทุก session
สร้างร่างแรกด้วย /init แล้ว แก้ด้วยมือ เพราะร่างอัตโนมัติจะยาวเกินและอธิบาย "อะไร" มากกว่า "ทำไม"
| ที่อยู่ | ใช้เก็บอะไร |
|---|---|
~/.claude/CLAUDE.md |
ความชอบส่วนตัว เช่น ภาษาที่ให้ตอบ — ไม่เกี่ยวกับ repo |
<repo>/CLAUDE.md |
กติกาของทีม — commit ลง git ให้ทุกคนได้เหมือนกัน |
<repo>/<subdir>/CLAUDE.md |
กติกาเฉพาะโมดูล เช่น addons/CLAUDE.md ของ Odoo |
- คำสั่งที่ใช้จริง: build / test / lint / รัน dev server (พร้อมชื่อ script ที่ถูกต้อง)
- โครงสร้างโฟลเดอร์ + หน้าที่ของแต่ละชั้น
- ข้อห้ามของ repo นี้ ("ห้ามแก้
migrations/ที่ merge ไปแล้ว", "ห้ามเรียก API ตรงจาก controller") - pattern ที่ทีมเลือกไว้ พร้อมเหตุผล ("ใช้ repository pattern เพราะจะสลับ ORM ปีหน้า")
- สิ่งที่ดูโค้ดแล้วไม่รู้ เช่น service ตัวนี้ถูกเรียกโดย repo ไหนบ้าง
- อธิบายสิ่งที่โค้ดบอกอยู่แล้ว ("โฟลเดอร์ models เก็บ model")
- ตำราเขียนโค้ดทั่วไป ("เขียนโค้ดให้อ่านง่าย") — เปลืองที่ ไม่เปลี่ยนพฤติกรรม
- secret, connection string, ชื่อ host ภายใน
- ประวัติการเปลี่ยนแปลง — นั่นคือหน้าที่ของ git
ยาวเกิน = ไม่มีใครอ่าน ทั้งคนและ Claude ตั้งเป้าไว้ ไม่เกิน 100 บรรทัด ถ้าเกิน ให้แยกไปไฟล์ย่อยแล้วอ้างถึงด้วย
@docs/architecture.md
Template พร้อมใช้อยู่ที่ templates/ — มี base + 3 stack
ระหว่าง session ถ้าเจอว่า Claude ทำผิดซ้ำ ๆ พิมพ์ # ตามด้วยกติกา
มันจะถามว่าจะบันทึกลงไฟล์ไหน — เลือก project memory เพื่อให้ทั้งทีมได้ด้วย
กด Shift+Tab เพื่อวนโหมด จนขึ้น plan mode
โหมดนี้ Claude จะอ่านและเสนอแผน แต่ แก้ไฟล์ไม่ได้ จนกว่าคุณจะอนุมัติ
ใช้เมื่อ:
- งานแตะหลายไฟล์ / หลายชั้น
- คุณยังไม่แน่ใจว่าโค้ดเดิมทำงานยังไง
- งานที่ย้อนยาก เช่น migration, เปลี่ยน schema, refactor ใหญ่
อ่านแผนแล้วแก้แผน อย่ากด accept รวด — แก้แผนถูกกว่าแก้โค้ดที่เขียนไปแล้ว 15 ไฟล์
งานเล็ก (แก้ typo, เพิ่ม log, แก้ config บรรทัดเดียว) ไม่ต้องใช้ plan mode มันช้าเปล่า ๆ
ตั้ง allowlist ต่อ repo ที่ .claude/settings.json (commit ลง git ได้ ทีมจะได้เหมือนกัน)
ส่วนของส่วนตัวใส่ .claude/settings.local.json (gitignore ไว้)
Template: templates/claude/settings.json
หลักการตั้ง:
| ประเภทคำสั่ง | ตั้งเป็น | เหตุผล |
|---|---|---|
อ่านอย่างเดียว (git status, ls, pytest, npm run lint) |
allow |
ถามทุกครั้งแล้วน่ารำคาญจนคนกด "อนุญาตทุกอย่าง" |
| เขียนไฟล์ในโปรเจกต์ | ปล่อยให้ถาม | คุณต้องเห็น diff |
git push, gh pr merge, rm -rf, docker compose down -v |
deny |
ย้อนไม่ได้ / กระทบคนอื่น |
| แตะ production (kubectl, ssh prod, psql prod) | deny |
ไม่มีเหตุผลให้ agent ทำเอง |
deny ชนะ allow เสมอ — ตั้ง deny ให้ครบก่อน แล้วค่อยเปิด allow เพิ่มทีหลัง
ถ้าอยากลด prompt ที่เด้งบ่อย ๆ ให้รัน /fewer-permission-prompts มันจะสแกนจากสิ่งที่คุณกดอนุญาตไปแล้วจริง ๆ
อาการที่แปลว่า context เละแล้ว: มันเริ่มลืมสิ่งที่ตกลงกันไว้ตอนต้น, แก้ไฟล์ที่ไม่เกี่ยว, วนแก้เรื่องเดิม
| คำสั่ง | ใช้เมื่อ |
|---|---|
/clear |
เปลี่ยนงาน — ล้างทิ้ง เริ่มใหม่ ใช้บ่อยกว่าที่คิด |
/compact |
งานเดิมยังไม่จบแต่ยาวมาก อยากเก็บบทสรุปไว้ |
/context |
อยากดูว่าตอนนี้อะไรกิน context อยู่บ้าง |
อย่าทำงานสองเรื่องใน session เดียว เพราะ context ของงานแรกจะไปกวนงานที่สอง และ diff จะปนกันจนแยก PR ไม่ออก
| แทนที่จะสั่งว่า | สั่งแบบนี้ |
|---|---|
| "แก้บั๊ก login" | "login ด้วยอีเมลที่มีตัวพิมพ์ใหญ่แล้ว 401 — ดู auth/service.py แล้วบอกสาเหตุก่อน อย่าเพิ่งแก้" |
| "เพิ่ม test" | "เขียน test ให้ calculate_vat() ครอบ: ค่าติดลบ, 0, ทศนิยม 3 ตำแหน่ง — ใช้ pytest ตาม pattern ใน tests/test_pricing.py" |
| "ทำให้เร็วขึ้น" | "หน้า /orders โหลด 8 วิ สงสัย N+1 — วัดก่อนว่า query ยิงกี่รอบ แล้วค่อยเสนอแนวทาง" |
สามอย่างที่ทำให้คำสั่งดีขึ้นทันที:
- บอกอาการ ไม่ใช่บอกวิธีแก้ — ถ้าคุณเดาสาเหตุผิด มันจะแก้ผิดตามคุณ
- ชี้ไฟล์/ฟังก์ชันที่เกี่ยวข้อง ด้วย
@path/to/file.py— ประหยัดเวลาค้นและลดการเดา - แยกขั้น "วิเคราะห์" กับ "แก้" — ให้มันอธิบายสาเหตุก่อน ถ้าเหตุผลผิดคุณจะจับได้ตั้งแต่ยังไม่มี diff
git diff # หรือ git diff --stagedอ่านทุกบรรทัดที่จะ commit ถ้ามีบรรทัดที่อธิบายไม่ได้ว่ามีไว้ทำไม แปลว่ายังไม่พร้อม merge
สิ่งที่ต้องมองหาเป็นพิเศษในโค้ดที่ agent เขียน:
TODO/pass/throw new Error("not implemented")ที่หลุดมาtry/exceptที่กลืน error เงียบ ๆ- ไฟล์ที่ถูกแก้ทั้งที่ไม่เกี่ยวกับงานนี้ (เช่น จัด format ใหม่ทั้งไฟล์ ทำให้ diff บวมจนรีวิวไม่ได้)
- dependency ใหม่ที่ไม่ได้ขอ
- ค่า config ที่ถูก hardcode แทนที่จะอ่านจาก env
- ห้ามให้ Claude
git push/mergeเอง — คนกดเอง ทุกครั้ง - ห้ามใช้
--dangerously-skip-permissionsบนเครื่องที่มี credential ของ production - ห้าม merge โค้ดที่ตัวเองอธิบายไม่ได้ — ถ้าอ่านไม่เข้าใจ ให้ถามมันจนเข้าใจ หรือทิ้งแล้วเขียนใหม่
- ห้าม paste secret ลง prompt — รวมถึง production dump และ log ที่มี token
- เปิด repo จริงของตัวเอง สั่งงานหนึ่งอย่างที่รู้คำตอบอยู่แล้ว โดยยังไม่มี
CLAUDE.md— จดว่ามันเดาผิดตรงไหน - ก๊อป
templates/CLAUDE.md.baseไปไว้ที่รากแล้วเติมของจริง 5 หัวข้อ /clearแล้วสั่งงานเดิมซ้ำ — เทียบผลกับรอบแรก- commit
CLAUDE.mdขึ้น branch แล้วเปิด PR (ไปต่อบทหน้า)
ถัดไป → 03 — Branch / PR / Review