ให้ AI ช่วยเขียนเอกสาร: README, Docstring, Changelog

เอกสารเป็นงานที่นักพัฒนาส่วนใหญ่รู้ว่าสำคัญแต่มักเลื่อนไปทำทีหลัง จนสุดท้ายไม่ได้ทำ หรือทำแล้วไม่มีใครอัปเดต AI ช่วยลดแรงเสียดทานตรงนี้ได้มาก เพราะมันอ่านโค้ดแล้วร่างเอกสารได้เร็ว แต่ก็มีกับดักใหญ่คือ AI เขียนเอกสารที่ "ฟังดูดี" ได้ง่ายมาก แม้เนื้อหาจะไม่ตรงกับโค้ดจริง บทความนี้จะพาดูหลักคิดว่าเอกสารที่ดีต้องตรงกับโค้ด แนวทางให้ AI ร่างแล้วคนตรวจ พร้อม template README ตัวอย่าง PHPDoc ที่มีประโยชน์ และวิธีทำ Changelog จากประวัติ Git

หลักข้อแรก: เอกสารที่ผิดแย่กว่าไม่มีเอกสาร

ถ้าไม่มีเอกสาร นักพัฒนาจะไปอ่านโค้ดเอง แต่ถ้าเอกสารบอกผิด เช่น บอกว่า method คืน null เมื่อไม่พบข้อมูล ทั้งที่จริงโยน exception คนที่เชื่อเอกสารจะเขียนโค้ดผิดตาม และเสียเวลา debug นานกว่าเดิม

ปัญหาที่พบบ่อยในเอกสารที่ AI เขียน:

• แต่งฟีเจอร์ที่ไม่มี เช่น README บอกว่ารองรับ Redis cache ทั้งที่โค้ดไม่มี เพราะโปรเจกต์แบบนี้ "มักจะมี"
• คำสั่งติดตั้งที่ไม่มีจริง เช่น ชื่อ console command หรือ environment variable ที่ AI เดาเอา
• Docstring ที่แค่ทวนชื่อ method เช่น getUser() มีคำอธิบายว่า "ดึงผู้ใช้" ซึ่งไม่ได้เพิ่มข้อมูลอะไร
• ระบุ type ผิด เช่น บอกว่า return array ทั้งที่บางกรณีคืน false

ดังนั้นกติกาคือ AI ร่าง คนตรวจ และทุกประโยคที่อ้างถึงพฤติกรรมของระบบต้องตรวจกับโค้ดหรือรันดูจริงได้

Workflow: ให้ AI ร่าง คนตรวจ

1. ให้บริบทจริง แนบไฟล์โค้ดที่เกี่ยวข้อง composer.json ไฟล์ config ตัวอย่าง (ที่ไม่มี secret) และโครงสร้างโฟลเดอร์ อย่าให้ AI เขียนจากชื่อโปรเจกต์อย่างเดียว
2. สั่งห้ามเดา ให้ AI ใส่เครื่องหมาย เช่น TODO: ยืนยัน ในจุดที่ข้อมูลไม่พอ แทนการแต่งเติม
3. ตรวจทีละประโยค คำสั่งทุกบรรทัดใน README ต้องรันได้จริงในเครื่องใหม่ ชื่อ environment variable ต้องตรงกับที่โค้ดอ่าน
4. เก็บเอกสารไว้ใกล้โค้ด และอัปเดตใน pull request เดียวกับการแก้โค้ด เพื่อให้ reviewer เห็นทั้งสองอย่างพร้อมกัน

เปรียบเทียบ prompt:

ไม่ดี:
เขียน README สำหรับโปรเจกต์ Yii2 ของฉันให้หน่อย

ดี:
เขียน README.md สำหรับโปรเจกต์นี้จากไฟล์ที่แนบเท่านั้น
(composer.json, config/web.php, .env.example, โครงสร้างโฟลเดอร์)
- ใช้หัวข้อตาม template ที่ให้
- ทุกคำสั่งต้องอ้างอิงจากสิ่งที่มีในไฟล์ที่แนบ
- ถ้าข้อมูลไม่พอ ให้เขียน "TODO: ยืนยัน" ห้ามเดา
- อย่าใส่ค่า secret จริงใด ๆ ใช้ค่าตัวอย่างจาก .env.example
- ท้ายคำตอบ ให้ลิสต์สิ่งที่คุณไม่แน่ใจ

Template README ที่ใช้ได้จริง

README ที่ดีตอบคำถามของคนที่เพิ่งเปิด repository เป็นครั้งแรก: นี่คืออะไร ต้องมีอะไรก่อน ติดตั้งยังไง รันยังไง ทดสอบยังไง และถ้าติดปัญหาไปดูที่ไหน

# ชื่อโปรเจกต์

อธิบาย 1-2 ประโยคว่าระบบนี้ทำอะไร ใช้โดยใคร

## ความต้องการของระบบ
- PHP 8.x พร้อม extension: pdo_pgsql, mbstring, intl
- PostgreSQL
- Composer

## การติดตั้ง
```bash
git clone <repository-url>
cd project
composer install
cp .env.example .env   # แล้วแก้ค่าให้ตรงกับเครื่อง
php yii migrate
```

## การตั้งค่า
| ตัวแปร | ความหมาย | ตัวอย่าง |
|--------|----------|----------|
| DB_DSN | การเชื่อมต่อฐานข้อมูล | pgsql:host=localhost;dbname=app |
| LLM_API_URL | endpoint ของ AI API | (ดูเอกสารผู้ให้บริการ) |

## การรันและทดสอบ
```bash
php yii serve
vendor/bin/codecept run
```

## โครงสร้างโฟลเดอร์ที่สำคัญ
- `controllers/` รับ request และเรียก service
- `services/` business logic
- `migrations/` โครงสร้างฐานข้อมูล

## ปัญหาที่พบบ่อย
## การมีส่วนร่วมพัฒนา

ตารางการตั้งค่าเป็นส่วนที่ AI ช่วยได้ดีมาก ถ้าเราให้มันอ่านโค้ดแล้วลิสต์ทุกจุดที่เรียก getenv() หรือ $_ENV ได้ครบ ซึ่งคนมักลืม แต่ต้องตรวจซ้ำด้วยการค้นในโค้ดเอง เช่น grep -rn "getenv(" --include=*.php .

PHPDoc ที่มีประโยชน์จริง

PHP 8 มี type declaration ที่ครอบคลุมขึ้นมาก PHPDoc จึงไม่ควรทวนสิ่งที่ type บอกอยู่แล้ว แต่ควรเพิ่มสิ่งที่ type บอกไม่ได้ เช่น รูปร่างของ array, หน่วยของค่า, เงื่อนไขที่โยน exception และผลข้างเคียง

<?php

namespace app\services;

class PointService
{
    // ไม่ดี: ทวนชื่อ method และ type ที่มีอยู่แล้ว
    /**
     * Add points.
     * @param int $userId user id
     * @param int $points points
     * @return int
     */
    public function addBad(int $userId, int $points): int
    {
        return 0;
    }

    // ดี: บอกพฤติกรรม เงื่อนไข และผลข้างเคียง
    /**
     * เพิ่มแต้มสะสมให้ผู้ใช้และบันทึกประวัติลงตาราง point_log ใน transaction เดียวกัน
     *
     * @param int $points จำนวนแต้มที่เพิ่ม ต้องมากกว่า 0 (ใช้ deduct() สำหรับการหักแต้ม)
     * @return int ยอดแต้มคงเหลือหลังเพิ่ม
     * @throws \InvalidArgumentException เมื่อ $points น้อยกว่าหรือเท่ากับ 0
     * @throws \yii\web\NotFoundHttpException เมื่อไม่พบผู้ใช้
     */
    public function add(int $userId, int $points): int
    {
        if ($points <= 0) {
            throw new \InvalidArgumentException('points must be positive');
        }
        // ...
        return 0;
    }

    /**
     * @return array<int, array{id: int, name: string, points: int}> เรียงตามแต้มจากมากไปน้อย
     */
    public function topUsers(int $limit = 10): array
    {
        return [];
    }
}

prompt สำหรับให้ AI เขียน PHPDoc: "เขียน PHPDoc ให้ method ในไฟล์นี้ ห้ามทวนสิ่งที่ type declaration บอกอยู่แล้ว ให้ระบุรูปร่างของ array ที่คืน, exception ที่โยนพร้อมเงื่อนไข, และผลข้างเคียงต่อฐานข้อมูล อ้างอิงเฉพาะสิ่งที่เห็นในโค้ด" แล้วตรวจทุก @throws ว่ามีจริงในโค้ด เครื่องมือ static analysis อย่าง PHPStan หรือ Psalm ช่วยจับ PHPDoc ที่ type ไม่ตรงกับโค้ดได้อีกชั้น

Changelog จากประวัติ Git

Changelog เขียนให้ "คนใช้งาน" อ่าน ไม่ใช่ให้นักพัฒนาอ่าน จึงไม่ควรเป็นแค่ git log ที่คัดลอกมา รูปแบบที่นิยมคือแบ่งตามเวอร์ชัน และจัดกลุ่มเป็น Added, Changed, Fixed, Removed, Security

ดึงประวัติตั้งแต่ tag ล่าสุดมาเป็น input ให้ AI:

# commit ตั้งแต่ tag ล่าสุดจนถึงปัจจุบัน ไม่รวม merge commit
git log "$(git describe --tags --abbrev=0)"..HEAD --no-merges --pretty=format:"%h %s"

จาก git log ข้างล่าง เขียน changelog สำหรับเวอร์ชัน 1.4.0
- จัดกลุ่มเป็น Added / Changed / Fixed / Security
- เขียนเป็นภาษาที่ผู้ใช้ระบบเข้าใจ ไม่ใช่ชื่อ class หรือไฟล์
- ข้าม commit ที่เป็นงานภายใน เช่น refactor, test, ci
- ห้ามเพิ่มรายการที่ไม่มีใน log
- ถ้า commit ไหนไม่ชัดว่ากระทบผู้ใช้อย่างไร ให้ลิสต์แยกไว้ท้ายเพื่อให้ฉันตัดสินใจ

ยิ่ง commit message ในทีมเขียนดี changelog ที่ได้จาก AI ก็ยิ่งแม่นยำ ซึ่งเป็นอีกเหตุผลหนึ่งที่ควรเขียน commit message ให้มีความหมาย

Checklist ตรวจเอกสารที่ AI ร่าง

• ทุกคำสั่งใน README ลองรันในเครื่องที่ไม่เคยติดตั้งโปรเจกต์มาก่อน (หรือใน container ใหม่)
• ชื่อ environment variable, console command และ route ตรงกับในโค้ด
• ไม่มี secret, URL ภายใน หรือข้อมูลส่วนบุคคลหลุดเข้าไปในเอกสาร
• PHPDoc ทุก @throws และ @return ตรงกับพฤติกรรมจริง
• changelog ไม่มีรายการที่ไม่ได้เกิดขึ้นจริง
• จุด TODO: ยืนยัน ถูกเคลียร์ครบก่อน merge

สรุป

• เอกสารที่ไม่ตรงกับโค้ดสร้างความเสียหายมากกว่าไม่มีเอกสาร ทุกประโยคต้องตรวจได้
• ให้ AI ร่างจากไฟล์จริงที่แนบไป สั่งห้ามเดาและให้ทำเครื่องหมายจุดที่ไม่แน่ใจ
• README ที่ดีพาคนใหม่จากการ clone ไปจนรันและทดสอบได้ ทุกคำสั่งต้องรันได้จริง
• PHPDoc ควรบอกสิ่งที่ type บอกไม่ได้ เช่น รูปร่าง array, exception และผลข้างเคียง
• changelog เขียนให้ผู้ใช้อ่าน ใช้ git log เป็น input และคนเป็นผู้ตัดสินขั้นสุดท้าย

ลองทำ

เลือกโปรเจกต์หนึ่งที่ README ยังไม่สมบูรณ์ แนบ composer.json, .env.example และโครงสร้างโฟลเดอร์ให้ AI ร่าง README ตาม template ข้างบน จากนั้นทดสอบด้วยการ clone repository ลงโฟลเดอร์ใหม่แล้วทำตาม README ทีละบรรทัดโดยห้ามใช้ความรู้เดิม จดทุกจุดที่ติดหรือไม่ตรง แล้วแก้ README จนคนที่ไม่รู้จักโปรเจกต์ทำตามได้จนรันเทสต์ผ่าน