Claude Code ถอดสมอง EP.2 — Spec Files เขียนก่อน code ให้ได้ feature ตรงเสปค

สวัสดีค่าาาาาา 👋

กลับมาแล้วกับ Claude Code ถอดสมอง EP.2 ต่อจาก EP แรกที่เราตั้ง CLAUDE.md ให้ Claude จำบริบทของโปรเจคได้ EP นี้จะมาดูเรื่องที่หลายคนข้ามไป แล้วก็งงว่าทำไม Claude ถึงทำ feature ออกมาไม่ตรงสเปค 😩

เพราะมันยังขาด Spec Files ไงเล่าาาาา มาดูกัน

เสียงในหัว Claude ตอนที่เราสั่งงาน

ก่อนจะไปเรื่อง Spec Files ต้องเข้าใจก่อนว่า เวลาเราสั่งมันว่า "สร้าง login form ให้หน่อย" Claude มันทำอะไรบ้าง

รับคำสั่ง: "สร้าง login form ให้หน่อย"
      ↓
Claude ต้องตัดสินใจเองทุกอย่างที่เราไม่ได้บอก:
- ใช้ email หรือ username?
- มี remember me ไหม?
- validate แบบไหน?
- error message หน้าตาเป็นยังไง?
- ส่ง form ไปที่ endpoint ไหน?
      ↓
Claude เดาจากสิ่งที่รู้ทั้งหมด → code ออกมา

ปัญหาคือ Claude ต้อง เวิ้บทูเดา สิ่งที่เราไม่ได้บอก และมันก็จะเดาจาก "ค่าเฉลี่ยของโปรเจคทั่วโลก" ซึ่งอาจไม่ตรงกับสิ่งที่เราต้องการเลย

ดังนั้นก็เลยมี Spec Files เพื่อมาแก้ปัญหานี้ โดยบังคับให้เราตอบคำถามพวกนั้นก่อน ก่อนที่จะสั่ง Claude จะเริ่ม code

Spec File คืออะไร?

Spec File คือไฟล์ markdown ที่เราเขียน "ข้อกำหนดของ feature" ไว้อย่างละเอียด วางไว้ที่ docs/features/<ชื่อ feature>/spec.md

ดูยุ่งยาก มากความ แต่จริงๆ แล้วมันช่วยประหยัดเวลาได้เยอะ เพราะ

ถ้า Claude เข้าใจผิดตั้งแต่แรก แก้ทีหลังงานหยาบกว่าเดิม 5555

โครงสร้าง Spec File ที่ดี

# Feature: Login Form

## ภาพรวม (Overview)
หน้า login สำหรับให้ user เข้าสู่ระบบ
ใช้ email + password เท่านั้น ไม่มี social login ใน scope นี้

## ผู้ใช้ที่เกี่ยวข้อง (Users)
- ลูกค้าที่ลงทะเบียนแล้ว
- Admin ที่มี role พิเศษ

## สิ่งที่ต้องทำ (Requirements)
- [ ] email field: validate รูปแบบ email
- [ ] password field: ซ่อน character, มีปุ่ม toggle show/hide
- [ ] ปุ่ม login: disabled ตอน loading
- [ ] error state: แสดงข้อความเมื่อ login ผิด ไม่บอกว่าผิดที่ email หรือ password
- [ ] success: redirect ไป /dashboard
- [ ] remember me checkbox: เก็บ session 30 วัน

## สิ่งที่ไม่ต้องทำ (Out of Scope)
- ลืมรหัสผ่าน (EP ถัดไป)
- Social login
- Two-factor authentication

## Design
- ใช้ component จาก /components/ui/
- สี error คือ red-500 ตาม design system
- ดู mockup ได้ที่ /docs/designs/login.figma

## API
- POST /api/auth/login
- Body: { email: string, password: string, rememberMe: boolean }
- Response: { token: string, user: User } หรือ { error: string }

## คำถามที่ยังไม่ได้ตัดสินใจ (Open Questions)
- Rate limiting: จะ block หลังจาก fail กี่ครั้ง? → ถามทีมก่อน

Spec เปลี่ยน Claude จาก "นักเดา" เป็น "ผู้รับเหมา"

ลองเปรียบเทียบให้เห็นภาพ

ไม่มี Spec:

เรา: "สร้าง login form ให้หน่อย"

Claude: [เดาทุกอย่าง ทำออกมา 200 บรรทัด]

เรา: "อ้าว ทำไมมี Google login ด้วย ไม่ต้องการ"
เรา: "error message ไม่ถูกต้อง"
เรา: "ทำไม redirect ไป / ไม่ไป /dashboard"

→ แก้ไปแก้มา เสียเวลา 2 ชั่วโมง

มี Spec:

เรา: "อ่าน spec ที่ docs/features/login/spec.md แล้วทำ login form"

Claude: [อ่าน spec → ทำตาม requirements ทุกข้อ]

เรา: "โอเคเลย มีแก้นิดนึงตรง error message"

→ เสร็จใน 20 นาที

ความต่างคือ Spec บังคับให้ เราตัดสินใจก่อน แทนที่จะให้ Claude ตัดสินใจแทนเรา เผา token เปล่าๆ

ลำดับที่ถูกต้อง: Spec → Plan → Code

นี่คือ golden rule ของการใช้ Claude Code แบบ advanced:

1. เขียน SPEC ก่อน
   "ต้องการอะไร, edge cases คืออะไร, out of scope คืออะไร"
         ↓
2. ให้ Claude เขียน PLAN
   "จะทำยังไง, ไฟล์ไหนต้องแก้, sequence เป็นยังไง"
         ↓
3. ถึงค่อย CODE
   "ทำตาม plan ที่เห็นด้วยกันแล้ว"

EP ถัดไปจะพูดถึง Plan-First Workflow โดยเฉพาะเลยค่ะ

เทคนิค: @imports ใน Spec

CLAUDE.md รองรับ syntax @path/to/file เพื่อ reference ไฟล์อื่น ใน Spec ก็ใช้ได้เช่นกัน เช่น

## Design Reference
ดู mockup ที่ @docs/designs/login.png
ดู API schema ที่ @docs/api/auth.md
ดู existing components ที่ @components/ui/Button.tsx

เวลา Claude อ่าน Spec มันจะไปตาม reference เหล่านั้นมาอ่านด้วยโดยอัตโนมัติ ไม่ต้องอธิบายซ้ำในไฟล์เดียวกัน

โครงสร้างโฟลเดอร์ที่แนะนำ

docs/
  features/
    login/
      spec.md        ← เขียนไว้ก่อน
      plan.md        ← Claude เขียนให้ (EP หน้า)
    booking-form/
      spec.md
      plan.md
  decisions/         ← เดี๋ยวจะพูดถึงใน EP.4 
  sessions/          ← เดี๋ยวจะพูดถึงใน EP.4 เช่นกัน 

ลองทำดู!

เลือก feature ที่กำลังจะทำต่อไปในโปรเจค แล้วลองเขียน spec.md ก่อนสั่งให้เพื่อนรัก code

1. สร้างโฟลเดอร์ docs/features/<ชื่อ feature>/

2. สร้างไฟล์ spec.md

3. เขียน Overview, Requirements, Out of Scope, Open Questions ที่บอกไปตะกี้

4. สั่ง Claude: "อ่าน docs/features/<ชื่อ>/spec.md แล้ว implement ให้หน่อย"

5. สังเกตว่าเปลือง token น้อยกว่าที่ไม่มี spec ไหม

สรุป

Spec Files คือการ ย้ายการตัดสินใจมาอยู่ที่เรา แทนที่จะให้ Claude เดาเอง ใช้เวลาเขียนสัก 10-15 นาที แต่ประหยัดได้หลายชั่วโมงในการแก้ code ที่ไม่ตรงความต้องการ

EP ถัดไป: Plan-First Workflow บังคับ Claude ให้วางแผนก่อน

ขอบคุณที่อ่านจนจบนะคะ ขอให้มีวันที่ดีค่าา <3

Tags: Claude Code, AI, Spec, Developer Tools, Workflow