คู่มือปฏิบัติสำหรับการเขียน CLAUDE.md: คำสั่ง, สถาปัตยกรรม, การดำเนินการต้องห้าม และการอ้างอิงไฟล์ โดยใช้โปรเจกต์ Rails จริงเป็นตัวอย่าง
ทุกครั้งที่คุณเปิด Claude Code มันเริ่มต้นจากศูนย์เสมอ — ไม่จำการสนทนาก่อนหน้า ไม่รู้ว่าโปรเจกต์ของคุณทำอะไร ไม่รู้ว่าคำสั่งทดสอบคือ rspec หรือ pytest และไม่รู้ว่าการกระทำใดที่ห้ามทำ
CLAUDE.md แก้ปัญหานี้ มันคือไฟล์คำแนะนำถาวรที่คุณเขียนให้ Claude โดยจะถูกโหลดโดยอัตโนมัติในตอนเริ่มต้นของทุกการสนทนา CLAUDE.md ที่เขียนดีทำให้ Claude เข้าสู่โหมดทำงานได้ทันที — ไม่มีคำถามที่ไม่จำเป็น ไม่มีข้อผิดพลาดพื้นฐาน
Claude Code รองรับระบบ CLAUDE.md แบบหลายชั้นสามระดับ:
~/.claude/CLAUDE.md: การตั้งค่าสากล ใช้กับทุกโปรเจกต์ ใช้สำหรับค่าที่ต้องการทั่วไป เช่น "อย่า commit git โดยอัตโนมัติ" หรือ "ตอบเป็นภาษาไทย"CLAUDE.md ในโฟลเดอร์หลักของโปรเจกต์: การตั้งค่าระดับโปรเจกต์ ตำแหน่งที่พบบ่อยที่สุดCLAUDE.md ในโฟลเดอร์ย่อย: โหลดเฉพาะเมื่อ Claude ทำงานกับไฟล์ในโฟลเดอร์นั้น เหมาะสำหรับให้คำแนะนำเฉพาะแก่ frontend/, api/ หรือ infra/ไฟล์ CLAUDE.md หลายไฟล์จะสะสมผลกัน — ไฟล์ที่เฉพาะเจาะจงกว่ามีลำดับความสำคัญเหนือไฟล์ทั่วไป
หนึ่งย่อหน้าที่บอก Claude ว่าโปรเจกต์คืออะไรและใช้เทคโนโลยีอะไร:
## Project Overview
**Pickful AI** is a Ruby on Rails 8 cryptocurrency-focused social media platform.
Users can create posts, follow others, earn points, track coin prices,
and participate in a gamification system with leaderboards and VIP status.
- **Ruby Version:** 3.3.2
- **Rails Version:** 8.0.2
- **Database:** PostgreSQL with 4 separate databases (primary, cache, queue, cable)
การระบุหมายเลขเวอร์ชันมีความสำคัญ การรู้ว่าเป็น Rails 8 ป้องกันไม่ให้ Claude แนะนำ pattern จากยุค Rails 6 การรู้ว่ามี 4 ฐานข้อมูลป้องกันข้อผิดพลาดใน migration
นี่คือส่วนที่ให้ผลตอบแทนสูงสุดใน CLAUDE.md ใดๆ หากไม่มีส่วนนี้ Claude จะเดา — และเดาผิด
## Development Commands
### Running the Application
bin/dev # Start Rails server (port 3000) + Tailwind watcher
bin/rails server # Start Rails server only
### Testing
bundle exec rspec # Run all tests
bundle exec rspec spec/models # Run model tests
bundle exec rspec spec/path/to/file_spec.rb:42 # Run test at line 42
### Linting & Security
bin/rubocop # Run RuboCop linter (Rails Omakase preset)
bin/rubocop -a # Auto-correct offenses
bin/brakeman # Security vulnerability scan
### Deployment (Kamal)
bin/kamal deploy # Deploy to production
bin/kamal app logs # View application logs
bin/kamal app console # Remote Rails console
รายการนี้บอก Claude ว่า: การทดสอบใช้ bundle exec rspec ไม่ใช่ rails test; การ deploy ใช้ Kamal ไม่ใช่ Capistrano หรือ Fly.io; linter คือ RuboCop ที่ตั้งค่าด้วย preset Rails Omakase หากไม่เขียน Claude ต้องเดาทุกอย่าง
จุดประสงค์ของบันทึกสถาปัตยกรรมคือการบันทึก การตัดสินใจที่ไม่ปรากฏในโค้ดเอง Claude สามารถอ่านโครงสร้างโฟลเดอร์ได้ แต่ไม่สามารถรู้ว่าทำไมถึงจัดระเบียบแบบนั้น
## Key Architectural Patterns
**Services Layer:**
Complex business logic extracted to `app/services/`.
Keep controllers thin, delegate to services.
**Authorization:**
Pundit policies in `app/policies/`.
Check UserPolicy, PostPolicy, etc. for permission rules.
**Background Jobs:**
Use `app/jobs/` for async processing.
Solid Queue handles job processing.
สามจุดนี้บอก Claude ว่า: อย่าสะสม business logic ใน controllers; หากฎการอนุญาตใน app/policies/; ใช้ Solid Queue สำหรับทุกสิ่งที่ต้องการการประมวลผลแบบ asynchronous
การจัดกลุ่ม domain model ตามพื้นที่ฟังก์ชันก็มีคุณค่า:
## Core Domain Models
**Social Features:** User, Follow, Block, Referral
**Content:** Post, Comment, Topic, Tag, Draft
**Engagement:** Like, Favorite, Share, Report
**Cryptocurrency:** Coin, CoinPrice, Payment
**Gamification:** PointTransaction (VIP status at 400+ points)
นี่มีประสิทธิภาพมากกว่าการให้ Claude สแกน app/models/ เอง และยังสื่อความหมายทางธุรกิจ เช่น 400 คะแนนคือเกณฑ์ VIP ซึ่งไม่ชัดเจนเมื่อดูจากโค้ดเพียงอย่างเดียว
นี่คือส่วนที่ถูกละเลยมากที่สุดและมักสำคัญที่สุด:
## Important Configuration
**Multi-Database:**
Always be aware of the multi-database setup.
Most migrations should target the primary database
unless working with cache/queue/cable features.
**Lexxy Integration:**
The app uses Lexxy gem (beta) for enhanced ActionText editing.
Configured in config/application.rb with:
config.lexxy.override_action_text_defaults = false
**Asset Handling:**
Uses Propshaft (not Sprockets).
Assets in app/assets/ are served without fingerprinting in development,
with fingerprinting in production.
ทั้งสามเป็นข้อมูลประเภท "ไม่เขียนแล้วจะเสียใจ": multi-database ต้องระบุ target ของ migration อย่างชัดเจน; Lexxy คือ gem เบต้าที่มีพฤติกรรมต่างจาก ActionText มาตรฐาน; Propshaft ทำงานต่างจาก Sprockets
นี่คือส่วนที่ถูกประเมินค่าต่ำที่สุด การบอก Claude ว่าไม่ควรทำอะไรมีประสิทธิภาพมากกว่าการแก้ไขหลังจากเกิดเหตุ
## Do Not
- Do NOT run `git commit` automatically — always ask me to confirm first
- Do NOT modify files in `db/migrate/` that already exist
- Do NOT touch `.kamal/secrets*` files — production secrets, handle manually
- Do NOT run `bin/kamal deploy` without explicit instruction
ข้อแรกควรอยู่ในเกือบทุกโปรเจกต์ คำสั่ง deploy สำคัญยิ่งกว่า — bin/kamal deploy ที่รันผิดพลาดจะไปถึง production โดยตรง
CLAUDE.md รองรับการอ้างอิง @ เพื่อรวมไฟล์อื่น:
การตั้งค่า deploy: @config/deploy.yml
Schema ฐานข้อมูล: @db/schema.rb
Claude อ่านไฟล์เหล่านี้เมื่อจำเป็น db/schema.rb มีประโยชน์เป็นพิเศษ — ในโปรเจกต์ Rails มันคือแหล่งความจริงเดียวสำหรับโครงสร้างฐานข้อมูล
เขียนมากเกินไป: CLAUDE.md ใช้ context window การวาง README ทั้งหมดทำให้ Claude มีพื้นที่น้อยลงในการทำงานกับโค้ดจริง เขียนเฉพาะสิ่งที่ Claude ไม่สามารถอนุมานจากการอ่าน codebase เอง
แนวทางที่คลุมเครือ: "เขียนโค้ดดีๆ" ไม่มีประโยชน์ ให้ชัดเจน: "อย่าใส่ business logic โดยตรงใน controllers — มอบหมายให้ app/services/"
ลืมอัปเดต: ย้ายจาก Sprockets ไป Propshaft หรือจาก Sidekiq ไป Solid Queue — หาก CLAUDE.md ไม่ตามทัน Claude จะทำงานบนสมมติฐานที่ล้าสมัย รวมการอัปเดต CLAUDE.md ใน checklist ของการ refactor ครั้งสำคัญใดๆ
เขียนตัวอย่างโค้ด: ตัวอย่างใช้ context และ Claude อ่านโค้ดจริงได้แม่นยำกว่า snippet ที่ใช้อธิบาย ใช้การอ้างอิง @ เพื่อชี้ไปยังไฟล์จริง
# [ชื่อโปรเจกต์]
[คำอธิบายหนึ่งประโยค]
- **Ruby:** x.x.x
- **Rails:** x.x.x
- **Database:** PostgreSQL
## Development Commands
bin/dev # Start server
bundle exec rspec # Run tests
bin/rubocop # Lint
bin/kamal deploy # Deploy (ask before running)
## Architecture
[วิธีแบ่งความรับผิดชอบระหว่าง Services / Jobs / Policies]
[Domain model จัดกลุ่มตามพื้นที่ฟังก์ชัน]
## Important Notes
[การตั้งค่าที่ไม่ชัดเจน พฤติกรรมพิเศษของ gem]
## Do Not
- Do NOT run git commit automatically
[การดำเนินการความเสี่ยงสูงอื่นๆ]
เริ่มจากเทมเพลตนี้และเติมสิ่งที่โปรเจกต์ของคุณต้องการจริงๆ ไม่จำเป็นต้องครอบคลุมทุกอย่าง — CLAUDE.md ที่มีห้าจุดที่แม่นยำมีค่ามากกว่าที่เต็มไปด้วยสัญญาณรบกวน