วิธีเก็บความรู้ของโปรเจกต์ Laravel ให้ AI agent อ่านทุกครั้งที่เริ่มงาน

ทุกครั้งที่เปิด session ใหม่ AI agent รู้จัก Laravel ทั่วไปอยู่แล้ว แต่ไม่รู้ว่าโปรเจกต์นี้ตกลงอะไรกันไว้ เมื่อวานเพิ่งบอกไปว่าห้ามใช้ migrate:fresh วันนี้ก็ต้องบอกใหม่ ถ้าไม่ได้เขียนไว้ที่ไหน

Laravel Boost ช่วยส่วนที่เป็นความรู้ของ Laravel และ package ตามเวอร์ชันที่ติดตั้งจริง โพสต์นี้เล่าส่วนที่ผมเขียนเพิ่มเองบนนั้น ว่าเก็บอะไรไว้ที่ไหน และได้บทเรียนอะไรจากการแก้ไฟล์พวกนี้หลายสิบรอบ

ความรู้แต่ละแบบเก็บคนละที่#

ช่วงแรกผมเขียนสรุปโปรเจกต์ไว้ใน .ai/guidelines ให้ Boost รวมเข้า CLAUDE.md ทุกบรรทัดจึงอยู่ใน context ตลอดเวลา ไม่ว่างานตรงหน้าจะเกี่ยวหรือไม่ ทีหลังผมเลยแยกตามหน้าที่ของความรู้

ทุกที่ commit เข้า repo ยกเว้น skill ทั่วไปที่ผมเก็บใน repo ของตัวเองแล้ว sync ไปทุกเครื่อง คนอื่นในทีมหรือ agent ตัวอื่นที่เปิดโปรเจกต์นี้จึงเห็นเหมือนกัน

CLAUDE.md สั้นเป็นสารบัญ#

CLAUDE.md อยู่ใน context ทุก session ตลอดเวลา ทุกบรรทัดที่ใส่ไว้จึงเบียดที่ของงานจริง CLAUDE.md ของเว็บนี้ยาว 25 บรรทัด บอกว่าใช้ stack อะไร หน้าเว็บกับหลังบ้านอยู่โฟลเดอร์ไหน รัน test ยังไง และชี้ไปที่ .ai/documents/index.md กับ .ai/rules/index.md ต่อท้ายด้วย guideline ที่ Boost สร้างให้

ถ้าอยากเพิ่มอะไรลง CLAUDE.md ผมจะถามก่อนว่าเรื่องนี้ต้องรู้ทุก session จริงไหม ส่วนใหญ่ไม่ใช่ และมีที่ที่เหมาะกว่า

.ai/rules ให้ agent อ่านเฉพาะกฎของไฟล์ที่กำลังแก้#

.ai/rules เป็นส่วน project rules ของ Laravel Boost แต่ละไฟล์เป็น markdown สั้น ๆ ที่บอกใน front matter ว่าใช้กับ path ไหน แล้ว Boost ทำไฟล์ .ai/rules/index.md เป็นตารางจับคู่ glob กับไฟล์ rule ให้

| Applies to | Rule file |
| --- | --- |
| app/Http/Controllers/** | .ai/rules/controllers.md |
| app/Models/*.php | .ai/rules/models.md |
| database/migrations/** | .ai/rules/migrations.md |
| routes/console.php | .ai/rules/routes.md |

guideline ใน AGENTS.md สั่ง agent ไว้ว่าก่อนวางแผนหรือแก้ไฟล์ไหน ให้เปิด index นี้ก่อน อ่านทุก rule ที่ glob ตรงกับไฟล์ที่จะแก้ แล้วค้นคำสำคัญในโฟลเดอร์ .ai/rules อีกรอบ เผื่อมีกฎที่เกี่ยวแต่ path ไม่ตรง agent ที่กำลังแก้ model จึงอ่านแค่ rule ของ model ไม่ต้องแบกกฎของทั้งโปรเจกต์ไว้ใน context ตลอด เว็บนี้มี rule 13 ไฟล์ แต่ละไฟล์มีแค่หนึ่งสองหัวข้อ

เรื่องที่ควรเป็น rule มีสามแบบ

• ข้อตกลงที่ตัดสินแล้ว เช่น model ทุกตัวไม่ต้องมี $fillable เพราะโปรเจกต์เรียก Model::unguard() ไว้ agent ที่เห็น Laravel ทั่วไปมักใส่ให้เอง
• กับดักที่ดูจากโค้ดไม่ออก เช่น งานที่ตั้งเวลาทุกงานต้องอยู่ใน routes/console.php ห้ามเพิ่มเป็นบรรทัดใน crontab
• ข้อจำกัดที่ใช้ทั้งโปรเจกต์ เช่น โค้ดใน app/ รับ dependency ผ่าน injection เสมอ ห้ามเรียก app() หรือ resolve()

วิธีเพิ่ม rule คือบอก agent ตรง ๆ ว่าอยากให้จำเรื่องไหน agent จะเรียกเครื่องมือ record-rule ของ Boost ซึ่งเขียนไฟล์และแก้ index ให้ guideline ของ Boost เองสั่งไว้ด้วยว่าให้บันทึก rule เฉพาะตอนที่เราขอ คำสั่งของงานตรงหน้า อย่าง "แก้คำผิดตรงนี้" หรือ "ใช้ X ตรงนี้" ใช้แค่กับงานนั้น ข้อนี้ช่วยได้มาก ถ้า agent บันทึกเองทุกครั้งที่ผมพูดหนักแน่น ไม่นาน .ai/rules ก็เต็มไปด้วยกฎที่ใช้ได้แค่ครั้งเดียว

rule บอกสิ่งที่ต้องทำ ส่วนเหตุผลอยู่ในเอกสาร#

rule เขียนเป็นประโยคคำสั่งสั้น ๆ ส่วนเหตุผลว่าทำไมระบบเป็นแบบนี้ ผมแยกไปไว้ใน .ai/documents ตั้งแต่ช่วงกลางปี เอกสารอธิบายว่าระบบทำงานยังไงและทำไมถึงเลือกแบบนี้ เช่น SSR ทำงานยังไง หรือ sync บทความระหว่างเครื่องกับ production ยังไง เว็บนี้มี 17 เรื่อง

ใน skill ทำเอกสารของผมมีกฎข้อหนึ่งที่ช่วยมาก คือห้ามเขียนคำอธิบายไว้ใน docblock หรือ comment ในโค้ด ให้ชี้ไปที่หัวข้อในเอกสารแทน ถ้าเหตุผลเดียวกันอยู่สองที่ อีกไม่นานก็จะเขียนไม่ตรงกัน และที่อยู่ในโค้ดมักเป็นที่ที่ไม่มีใครกลับไปแก้ ถ้าอยากเปิดเอกสารพวกนี้เป็นเว็บให้คนในทีมอ่าน ผมเขียนแพ็กเกจที่ทำหน้านี้ไว้

แนวนี้ใกล้กับที่ Matt Pocock ใช้ใน skill ของเขา คือมีไฟล์ศัพท์ของโปรเจกต์ให้ agent กับคนใช้คำเดียวกัน และเก็บการตัดสินใจที่อธิบายยากเป็น ADR (Architecture Decision Record) ไว้ใน repo

skill เก็บขั้นตอนที่ต้องสั่งซ้ำ#

อะไรที่ผมเคยอธิบายให้ agent ฟังเกินสองครั้ง ผมจะให้เขียนเป็น skill เช่น ขั้นตอนตั้งโปรเจกต์ใน git worktree วิธีเขียน test ด้วยฐานข้อมูลจาก snapshot หรือวิธีเข้าเซิร์ฟเวอร์ของแต่ละโปรเจกต์

ข้อที่ต้องระวังคือคำอธิบายของ skill ทุกตัวอยู่ใน context ตลอดเวลา ส่วนเนื้อหาข้างใน agent โหลดเมื่อใช้ ผมจึงตั้งเพดานให้คำอธิบายไม่เกิน 350 ตัวอักษร และมี skill อีกตัวไว้ตรวจเรื่องนี้ทุกครั้งที่แก้ skill เพราะ Claude Code ไม่โหลด skill ที่คำอธิบายยาวเกิน 1,024 ตัวอักษรเลย

skill ที่ผูกกับ Laravel หรือ package ไหน ตอนนี้ Boost ส่งมาให้กับ package ได้ ส่วน skill ของผมเองเก็บเป็น plugin ที่ติดตั้งได้ทุกเครื่อง

กฎสไตล์ช่วยน้อยกว่าที่คิด#

skill กฎการเขียน Laravel ส่วนตัวของผมยาวกว่า 200 บรรทัด มีทั้งเรื่องที่กันบั๊กจริง อย่างวิธีตั้ง retry ของ HTTP request กับของ queue job ให้ทำงานคู่กันได้ และเรื่องที่เป็นแค่รสนิยม อย่างไม่เขียน else หรือไม่ใส่วงเล็บรอบ new ตาม PHP 8.4

พอใช้มานาน ผมเห็นแบบเดียวกับที่ Jason McCreary เล่าไว้ในสี่ขั้นที่เขาปล่อยงานให้ AI agent กฎที่สอนให้ agent เขียนเหมือนเราเหนื่อยแต่ได้ผลน้อย agent ทำตามบ้างไม่ทำบ้าง และไม่ได้ทำให้งานถูกขึ้น

ตอนนี้ผมย้ายเรื่องสไตล์ไปให้เครื่องมืออย่าง Pint และ Rectorจัดให้ทุกครั้งที่ agent จบงาน ส่วนกฎที่ยังเก็บไว้คือเรื่องที่ดูจากโค้ดรอบ ๆ ไม่ออก และพลาดแล้วเสียหายจริง

ความรู้ที่ล้าสมัยต้องแก้ทันทีที่เจอ#

ความรู้ในไฟล์ล้าสมัยได้ทุกวันที่โค้ดเปลี่ยน และ agent เชื่อสิ่งที่เขียนไว้มากกว่าที่เราคิด เอกสารที่ยังบอกวิธีเก่าอาจพา agent ไปแก้ผิดที่ ทั้งที่โค้ดจริงไม่ได้เป็นแบบนั้นแล้ว ผมจึงตั้งไว้สองข้อ

• ปิดงานแล้วแก้เอกสารในรอบเดียวกัน ขั้น implement ของผมแก้ .ai/documents ที่เกี่ยวข้องก่อนปิดงานทุกครั้ง
• เจอของล้าสมัยระหว่างทำอย่างอื่น ให้แก้ด้วย ไม่ใช่แค่จดไว้ อย่างตอนเขียนบทความเรื่อง test แล้ว agent พบว่า skill testing ยังบอกว่า Laravel 13 โยน exception เมื่อสั่ง migrate:fresh ในที่ที่ห้ามไว้ ทั้งที่จริงแค่เตือนแล้วจบคำสั่ง agent ก็แก้ skill นั้นไปในรอบเดียวกัน

กฎที่ผมสั่งเพิ่มช่วงหลังมีผู้สั่งกับวันที่กำกับไว้ เช่น "(owner, 2026-10-26)" ผ่านไปสองเดือนจะได้รู้ว่ากฎข้อนี้มาจากไหน และตัดสินได้ว่ายังใช้อยู่หรือควรลบ

Claude Code มี memory ส่วนตัวของแต่ละโปรเจกต์ด้วย แต่เก็บอยู่ในเครื่องของเรา คนอื่นไม่เห็น บทเรียนที่ควรใช้ต่อทุกครั้ง ผมจึงย้ายจาก memory ไปอยู่ใน skill หรือ .ai/rules