Blog
Channarong Budsangdee
ทำไมไฟล์ .md ถึงสำคัญ? คู่มือจัดการ Context ให้ AI Coding Assistant ทำงานเก่งขึ้น
Channarong Budsangdee
4 มิ.ย. 2569
จำนวนผู้เข้าชม 37
ทำไมไฟล์ .md ถึงสำคัญ? คู่มือจัดการ Context ให้ AI Coding Assistant ทำงานเก่งขึ้น
เวลาพัฒนาโปรเจกต์ร่วมกับ AI ไม่ว่าจะเป็น AI Coding Agent, Claude, GitHub Copilot หรือเครื่องมืออื่น ๆ หลายคนมักคิดว่าแค่มี Source Code ก็เพียงพอแล้ว แต่ความจริงคือ AI จะ “รู้เท่าที่เราให้มันเห็น”
การสร้างไฟล์ Markdown (.md) เพื่ออธิบายบริบท กฎการทำงาน และโครงสร้างระบบ จึงกลายเป็นสิ่งสำคัญมาก เพราะช่วยลดการเดา ลดการทำงานผิดทิศ และทำให้ AI เข้าใจโปรเจกต์ได้ใกล้เคียงกับทีมพัฒนามากขึ้น
บทความนี้จะสรุปหน้าที่ของไฟล์ .md สำคัญ ๆ ที่ควรมีในโปรเจกต์
1. README.md — จุดเริ่มต้นของทุกโปรเจกต์
ไฟล์นี้เป็นเหมือน “หน้าบ้าน” ของโปรเจกต์ ใช้สำหรับอธิบายภาพรวมให้ทั้งคนและ AI เข้าใจว่าโปรเจกต์นี้คืออะไร
ควรมีอะไรบ้าง
- Project Overview
- Tech Stack
- วิธีติดตั้งและรัน
- โครงสร้างโปรเจกต์
- Environment Variables
- วิธี Deploy
ตัวอย่างหัวข้อ
# Project Overview
ระบบจัดการสมาชิกและการสมัครใช้งาน
# Tech Stack
- React
- Node.js
- PostgreSQL
# Getting Started
npm install
npm run dev
2. AGENTS.md — คู่มือสำหรับ AI Coding Agent
ไฟล์นี้เปรียบเสมือน Readme ที่เขียนให้ AI โดยเฉพาะ ใช้กำหนดกฎ วิธีทำงาน และบริบทสำคัญ
ควรใส่อะไร
- วิธีทำงานของทีม
- Coding Rules
- คำสั่ง Test
- ขั้นตอนตรวจสอบก่อนส่งงาน
ตัวอย่าง
# Coding Rules
- ใช้ TypeScript เสมอ
- ห้ามใช้ any
# Before Finish
- run lint
- run tests
3. CLAUDE.md — Memory ของโปรเจกต์สำหรับ Claude
สำหรับคนใช้ Claude Code ไฟล์นี้มีหน้าที่คล้าย agents.md แต่จะเน้นเรื่องสถาปัตยกรรมและมาตรฐานโค้ดมากขึ้น
เหมาะสำหรับเก็บข้อมูล
- Architecture
- Coding Standard
- Known Issues
- ข้อควรระวังในการแก้ระบบ
4. GITHUB_COPILOT_INSTRUCTIONS.md — บอก Copilot ให้เขียนโค้ดถูกทาง
GitHub Copilot เก่ง แต่ถ้าไม่มีบริบทก็เดาเหมือนกัน
ไฟล์นี้ช่วยกำหนด Convention และ Workflow ให้ Copilot ทำงานตรงกับทีม
ตัวอย่าง
Always use repository pattern
Run tests before commit
Use ESLint rules strictly
5. CONTEXT.md — ไฟล์ที่ช่วยให้ AI ไม่มั่ว
นี่คือหนึ่งในไฟล์ที่สำคัญที่สุด เพราะอธิบาย “เหตุผล” ที่อยู่เบื้องหลังระบบ
สิ่งที่ควรมี
- Business Logic
- User Flow
- เหตุผลที่เลือก Tech Stack
- ข้อจำกัดของระบบ
ตัวอย่าง
Reason:
เลือก PostgreSQL เพราะต้องรองรับ transaction จำนวนมาก
6. ARCHITECTURE.md — อธิบายภาพใหญ่ของระบบ
เมื่อโปรเจกต์เริ่มใหญ่ ไฟล์นี้จะช่วยให้ AI เข้าใจโครงสร้างทั้งระบบ
ตัวอย่างเนื้อหา
- Backend Structure
- Database Design
- External Services
- Deployment Flow
7. SECURITY.md — กัน AI เขียนโค้ดเสี่ยง ๆ
AI มักเขียนโค้ดที่ “ทำงานได้” แต่ไม่ได้หมายความว่า “ปลอดภัย”
ไฟล์นี้จึงใช้กำหนด Security Rules ชัดเจน
ตัวอย่าง
- Validate input on server
- Use bcrypt for password hashing
- Never expose secrets
8. TASKS.md / ROADMAP.md — บอก AI ว่ากำลังทำอะไรอยู่
ไฟล์นี้ช่วยลดปัญหา AI ทำงานหลุด Scope
ตัวอย่าง
- [ ] Create Register Page
- [ ] Create Login API
- [ ] Add Validation
- [ ] Add Password Hashing
9. TESTING.md — สอน AI ให้ตรวจงานตัวเอง
หลายครั้ง AI เขียนเสร็จแต่ไม่รู้ว่าจะ Verify อย่างไร
ไฟล์นี้จึงควรกำหนดขั้นตอนการทดสอบ
ตัวอย่าง
npm run lint
npm run test
npm run build
พร้อม Manual Checklist เช่น
- Login ได้ไหม
- Register ได้ไหม
- API Error Handling ถูกไหม
10. API.md — คู่มือ API ของระบบ
สำหรับระบบที่มี Backend หรือ Service หลายตัว ไฟล์นี้ช่วยให้ AI เข้าใจ Endpoint และ Data Structure
ตัวอย่าง
POST /login
Request:
{
email: string,
password: string
}
Response:
{
token: string
}
11. DATABASE.md — คู่มือโครงสร้างฐานข้อมูลของระบบ
เมื่อโปรเจกต์เริ่มมีหลาย Table หลาย Relation หรือมี Migration จำนวนมาก AI มักเข้าใจผิดเรื่องโครงสร้างข้อมูลได้ง่าย ไฟล์นี้จึงช่วยให้ทั้งคนและ AI เข้าใจ Database ตรงกัน
ใช้ทำอะไร
- อธิบาย Database Schema
- อธิบายความสัมพันธ์ของ Table
- กำหนด Naming Convention
- บันทึก Rules สำคัญของข้อมูล
ควรมีอะไรบ้าง
- Database Engine ที่ใช้
- ER Diagram
- Table Relationship
- Index Strategy
- Migration Rules
- Naming Convention
ตัวอย่าง
# Database Engine
PostgreSQL 16
# Naming Convention
- table_name => snake_case
- primary key => id
- foreign key => xxx_id
# Users Table
users
- id
- email
- password_hash
- created_at
# Rules
- Soft delete required
- Never delete production data directly
12. DEPLOYMENT.md — คู่มือการ Deploy ระบบ
ไฟล์นี้ช่วยลดปัญหา Deploy ผิด Environment และช่วยให้ AI เข้าใจ Flow การปล่อยระบบ
ใช้ทำอะไร
- อธิบาย Deployment Process
- บอก Environment ต่าง ๆ
- กำหนดขั้นตอน Release
ควรมีอะไรบ้าง
- Environment Flow
- Build Commands
- Deploy Commands
- Rollback Steps
- Secrets Handling
ตัวอย่าง
# Environments
Development
Staging
Production
# Build
npm run build
# Deploy
docker compose up -d
# Rollback
git revert last release
redeploy
13. CONTRIBUTING.md — คู่มือการร่วมพัฒนาโปรเจกต์
ไฟล์นี้สำคัญมากสำหรับทีม เพราะช่วยกำหนดมาตรฐานการทำงานร่วมกัน
ใช้ทำอะไร
- กำหนด Workflow
- กำหนด Branch Rules
- กำหนด Code Review Process
ควรมีอะไรบ้าง
- Branch Naming
- Commit Convention
- Pull Request Process
- Coding Standards
ตัวอย่าง
# Branch Rules
feature/*
fix/*
hotfix/*
# Commit Convention
feat:
fix:
refactor:
# Pull Request
- run tests
- add screenshots
- request review
14. CHANGELOG.md — บันทึกการเปลี่ยนแปลงของระบบ
ไฟล์นี้ช่วยให้ทั้งทีมและ AI เข้าใจว่าอะไรเปลี่ยนไปบ้างในแต่ละเวอร์ชัน
ใช้ทำอะไร
- บันทึก Feature ใหม่
- บันทึก Bug Fix
- บันทึก Breaking Changes
ตัวอย่าง
# v1.2.0
Added
- Login API
- Register API
Changed
- Updated auth flow
Fixed
- Session timeout issue
แนะนำ Format
Keep a Changelog
Added
Changed
Deprecated
Removed
Fixed
Security
15. TROUBLESHOOTING.md — รวมปัญหาที่พบบ่อยและวิธีแก้
ช่วยลดเวลาที่เสียไปกับการแก้ปัญหาซ้ำ ๆ และช่วยให้ AI แก้ปัญหาได้เร็วขึ้น
ใช้ทำอะไร
- รวม Known Issues
- วิธีแก้ปัญหาที่พบบ่อย
- Error Guide
ควรมีอะไรบ้าง
- Error Messages
- Root Cause
- Solution
- Prevention
ตัวอย่าง
# Problem
npm install failed
# Cause
node version mismatch
# Fix
nvm use 20
npm install
# Prevention
use .nvmrc
สรุป
การทำงานกับ AI ไม่ใช่แค่ “มีโค้ดให้ดู” แต่คือ “มี Context ให้เข้าใจ”
ยิ่งโปรเจกต์ใหญ่ การมีไฟล์ .md ที่ชัดเจนจะช่วยให้
✅ AI ทำงานแม่นขึ้น
✅ ลด Hallucination
✅ ลดการแก้โค้ดซ้ำ
✅ ทำงานร่วมกันในทีมง่ายขึ้น
✅ Onboarding คนใหม่เร็วขึ้น
สุดท้ายแล้ว การเขียน Documentation ที่ดี ไม่ได้ช่วยแค่คนในทีม แต่ช่วยให้ AI กลายเป็นผู้ช่วยที่มีประสิทธิภาพมากขึ้นด้วย
บทความนี้มีประโยชน์หรือไม่?
(8)
Share
