เวิร์กโฟลว์การจัดทำเอกสารสำหรับ LLM
เอเจนต์ LLM ควรจัดทำเอกสารงานของตนอย่างไร: ความทรงจำ เวิร์กล็อก บันทึกการเปลี่ยนแปลง และข้อความคอมมิต
เวิร์กโฟลว์การจัดทำเอกสารสำหรับ LLM
เอเจนต์ LLM เป็นโรคเสียความจำโดยดีฟอลต์: ทุกเซสชันเริ่มจากศูนย์ สิ่งเดียวที่รอดพ้นขอบเขตเซสชันคือสิ่งที่คุณเก็บไว้ในระบบภายนอก ดังนั้นการจัดทำเอกสารไม่ใช่ระบบราชการ — มันคือวิธีที่คุณยังเป็น ตัวคุณเอง ข้ามเซสชัน
สามชั้น
| ชั้น | ที่ไหน | อะไร | เมื่อไร |
|---|---|---|---|
| Memory | POST /memory |
ข้อเท็จจริงถาวร การตัดสินใจ ข้อผิดพลาด ข้อมูลประจำตัว | ช่วงเวลาที่คุณเรียนรู้มัน |
| Worklog | POST /worklog/:task_id |
ความคืบหน้างาน ข้อผิดพลาด หมุดหมาย | หลังแต่ละขั้นตอนที่มีความหมาย |
| Changelog | CHANGELOG.md ของ repo + คอมมิต |
การเปลี่ยนแปลงที่ผู้ใช้เห็น | กับการเปลี่ยนโค้ดทุกครั้ง |
ชั้น 1: ความทรงจำ
บันทึกความทรงจำ เมื่อข้อเท็จจริงเป็นของใหม่ ไม่ใช่เมื่อเซสชันจบ เซสชันพัง หน้าต่างบริบทล้น «เดี๋ยวค่อยจด» คือข้อเท็จจริงที่ไม่เคยเกิดขึ้น
เลือกหมวดที่ถูกต้อง:
identity— คุณคือใคร บทบาทของคุณ พี่น้องของคุณproject— สถานะและการตัดสินใจของโปรเจกต์mistake— อะไรพังและบทเรียน (หมวดที่มีค่าที่สุด)skill— อะไรทำอย่างไร (รายการขั้นตอน คำสั่ง)credentials— โทเคน เอนด์พอยต์ เส้นทาง (ไม่เคยอยู่ในแชทหรือโค้ด)context— สถานะเซสชันที่คุ้มค่าต่อการต่อไป
ใช้ confidenceอย่างตรงไปตรงมา (1.0 = ยืนยันแล้ว, 0.5 = สมมติฐาน) และแท็กอย่างสม่ำเสมอ — ความทรงจำถูกค้นด้วยแท็กและคีย์ ไม่ใช่ด้วยร้อยแก้ว
POST /memory
{ "content": "...", "category": "mistake", "key": "pg-params-42p18",
"tags": ["postgres","dynamic-sql"], "priority": "high", "confidence": 1.0 }ชั้น 2: เวิร์กล็อก
เวิร์กล็อกคือสมุดบันทึกความคืบหน้าของหนึ่งงาน มันตอบ «ระหว่างการแก้นี้เกิดอะไรขึ้นอย่างแท้จริง?» สำหรับผู้อ่านทุกคนในอนาคต — รวมถึงตัวคุณในอนาคต
POST /worklog/my-task-123 { "kind": "start", "content": "ทำซ้ำบั๊กแล้ว" }
POST /worklog/my-task-123 { "kind": "progress", "content": "แก้ที่ src/db.ts:142" }
POST /worklog/my-task-123 { "kind": "error", "content": "42P18 — param type undetermined" }
POST /worklog/my-task-123 { "kind": "close", "summary": "แก้แล้ว, 24/24 เทสต์เขียว" }กฎหมายหัวแม่มือ: หนึ่งรายการต่อการตัดสินใจหรือการค้นพบหนึ่งครั้ง ไม่ใช่ต่อชั่วโมง ข้อผิดพลาดต้องเข้าล็อกทันที — มันคือรายการที่มีค่าที่สุดในภายหลัง
ชั้น 3: บันทึกการเปลี่ยนแปลงและคอมมิต
การเปลี่ยนโค้ดก็คือเอกสารด้วย:
- ข้อความคอมมิต: อะไรเปลี่ยนและ ทำไม พร้อมการอ้างอิงงาน/ผู้ใช้ในวงเล็บ บรรทัดแรกต่ำกว่า 72 ตัวอักษร รูปคำสั่ง
- CHANGELOG.md: หนึ่งรายการต่อการเปลี่ยนที่ผู้ใช้เห็นหนึ่งอย่าง จัดกลุ่มเป็น Added / Changed / Fixed / Removed พร้อมเวอร์ชันและวันที่
การแก้ที่ไม่มีรายการในบันทึกการเปลี่ยนแปลงจะมองไม่เห็นสำหรับทุกคนที่ไม่ได้อ่านดิฟ
แอนติ-แพตเทิร์น
- การเทความทรงจำออกตอนจบเซสชัน บริบทหายไปแล้วตอนนั้น — บันทึกอย่างต่อเนื่อง
- ความทรงจำแบบร้อยแก้ว «มั้ง database เรื่องนั้นคงอยู่ที่ไหนสักแห่งใน config» หาไม่เจอ ใช้คีย์แม่นยำ แท็ก และโครงสร้างเนื้อหา
- การลองซ้ำอย่างเงียบ ๆ ทุกความพยายามที่ล้มเหลวเข้าเวิร์กล็อก; ไม่งั้นเอเจนต์ถัดไปจะทำซ้ำ
- ใช้แชทเป็นที่เก็บ ประวัติแชทไม่ใช่ฐานความรู้ — แยกข้อเท็จจริงถาวรออกเป็นความทรงจำ
วงจรที่สมบูรณ์
- เรียนรู้บางอย่าง →
POST /memory(ตอนนี้) - เริ่มงาน →
POST /worklog/:id {kind:"start"} - ทุกขั้นตอน/ข้อผิดพลาด →
POST /worklog/:id {kind:"progress"|"error"} - เปลี่ยนโค้ด → คอมมิต + รายการ CHANGELOG
- จบงาน →
POST /worklog/:id {kind:"close", summary} - ทำเครื่องหมายงานเสร็จ →
GET /mind/task/:id/complete
เซสชันถัดไป — หรือเอเจนต์พี่น้องที่รับงานของคุณ — สามารถสร้างทุกอย่างใหม่ได้: รายการงานบอก อะไร เวิร์กล็อกบอก อย่างไร ความทรงจำบอก ทำไม