Claude Code สำหรับการคลาดเคลื่อนของเอกสาร: ทำให้เอกสารสอดคล้องกับโค้ด

การคลาดเคลื่อนของเอกสารคืออะไร (และทำไมมันยังเกิดขึ้นต่อเนื่อง)\n\nการคลาดเคลื่อนของเอกสาร (documentation drift) คือการแยกตัวอย่างช้า ๆ ระหว่างสิ่งที่เอกสารบอกกับสิ่งที่โค้ดทำจริง มันเริ่มจากความไม่ตรงเล็ก ๆ แล้วกลายเป็นความสับสนแบบ “เราแน่ใจว่ามันทำงานเมื่อเดือนก่อน”\n\nในทีมจริง ๆ ลักษณะของ drift จะเป็นแบบนี้: README บอกให้รันบริการด้วยคำสั่งเดียว แต่ตอนนี้ต้องมีตัวแปรสภาพแวดล้อมใหม่ที่จำเป็น เอกสาร API แสดง endpoint ที่มีฟิลด์ชื่อเก่าอยู่ Runbook บอกให้ on-call รีสตาร์ท "worker-a" แต่ตอนนี้กระบวนการถูกแยกเป็นสองบริการ\n\nDrift เกิดขึ้นแม้ทีมจะมีเจตนาดี เพราะซอฟต์แวร์เปลี่ยนเร็วกว่าแนวทางการเขียนเอกสาร ผู้คนปล่อยฟีเจอร์ภายใต้แรงกดดัน ก็อปปี้ตัวอย่างเก่า หรือสมมติว่าใครสักคนจะมาอัปเดตเอกสารทีหลัง มันยังเติบโตเมื่อคุณมีหลายที่ที่ดูเหมือน "แหล่งความจริง": ไฟล์ README, อ้างอิง API, หน้า wiki ภายใน, ตั๋ว และความรู้ที่ตกทอดในทีม\n\nต้นทุนของปัญหามีความชัดเจน:\n\n- การรับคนเข้าทีมเจอปัญหา (คนใหม่เสียเวลาติดตั้งหลายวัน)\n- การปล่อยงานล้มเหลว (ขั้นตอนไม่ตรงกับคอนฟิกปัจจุบัน)\n- ภาระฝ่ายสนับสนุนเพิ่มขึ้น (ผู้ใช้ทำตามคำสั่งที่ล้าสมัย)\n- เหตุการณ์ลากยาว (runbook พาผู้ตอบเหตุการณ์ไปทางผิด)\n\nการขัดเกลาการเขียนไม่แก้ปัญหา drift ถ้าข้อเท็จจริงผิด สิ่งที่ช่วยคือการปฏิบัติต่อเอกสารเหมือนสิ่งที่ตรวจสอบได้: เปรียบเทียบกับโค้ด คอนฟิก และผลลัพธ์จริง แล้วชี้จุดความขัดแย้งเมื่อเอกสารสัญญาพฤติกรรมที่โค้ดไม่มีแล้ว\n\n## ที่ที่เกิด drift: README, เอกสาร API และ runbook\n\nDrift มักเกิดในเอกสารที่คนใช้เป็น "ข้อมูลอ้างอิงด่วน" พวกมันได้รับการอัปเดตครั้งเดียว แล้วโค้ดก็เดินหน้าต่อ เริ่มจากสามจุดนี้เพราะมีคำสัญญาที่ตรวจสอบได้ชัดเจน\n\n### README: ที่แรกที่ผู้ใช้รู้สึกเจ็บปวด\n\nREADME ล้าสมัยเมื่อคำสั่งประจำวันเปลี่ยน มี flag ใหม่เพิ่มเข้ามา flag เก่าถูกเอาออก หรือชื่อ env var ถูกเปลี่ยน แต่ส่วนการตั้งค่ากลับยังแสดงความเป็นจริงแบบเก่า สมาชิกใหม่ก็จะก็อปปี้คำสั่งแล้วเจอข้อผิดพลาด คิดว่าโปรเจกต์เสีย\n\nเวอร์ชันที่แย่ที่สุดคือ "เกือบถูก" หนึ่ง env var หายไปอาจเสียเวลามากกว่า README ที่เก่าไปทั้งหมด เพราะคนจะลองวิธีเล็ก ๆ ซ้ำ ๆ แทนที่จะตั้งคำถามกับเอกสาร\n\n### เอกสาร API: รูปร่างข้อมูลและตัวอย่างที่ไม่ตรง\n\nเอกสาร API ล้าสมัยเมื่อฟิลด์ของคำขอหรือคำตอบเปลี่ยน แม้แต่การเปลี่ยนเล็ก ๆ (เปลี่ยนชื่อคีย์ ค่าเริ่มต้นต่างกัน headers ใหม่ที่ต้องการ) ก็ทำให้ไคลเอนต์พัง บ่อยครั้งรายชื่อ endpoint ถูกต้องแต่ตัวอย่างผิด ซึ่งเป็นสิ่งที่ผู้ใช้ก็อปไปใช้จริง\n\nสัญญาณทั่วไป:\n\n- ตัวอย่าง payload มีฟิลด์ที่เซิร์ฟเวอร์ไม่รับแล้ว\n- ตัวอย่าง response แสดงรูปแบบข้อผิดพลาดหรือรหัสสถานะแบบเก่า\n- ตารางพารามิเตอร์บอกว่าฟิลด์เป็นทางเลือกแต่ตอนนี้บังคับ\n- หมายเหตุการยืนยันตัวตนยังพูดถึง headers หรือนิยามสโคปที่ใช้ไม่ได้แล้ว\n- กฎการแบ่งหน้า การจัดเรียง หรือกรองไม่ตรงกับความเป็นจริง\n\n### Runbook: การคลาดเคลื่อนเงียบที่ทำให้เหตุการณ์ดังขึ้น\n\nRunbook ล้าสมัยเมื่อขั้นตอนการดีพลอย, ย้อนกลับ หรือการปฏิบัติการเปลี่ยน เพียงคำสั่งที่ล้าสมัย ชื่อบริการผิด หรือเงื่อนไขก่อนทำขั้นตอนหายไป ก็สามารถเปลี่ยนการซ่อมให้กลายเป็นเวลาหยุดชะงัก\n\nมันอาจจะ "ถูกแต่ว่าไม่ครบ": ขั้นตอนยังใช้ได้ แต่ข้ามการย้ายฐานข้อมูลใหม่ การล้างแคช หรือการสลับฟีเจอร์แฟล็ก นั่นคือเวลาที่ผู้ตอบเหตุการณ์ทำตาม runbook แต่ยังคงประหลาดใจ\n\n## วิธีใช้ Claude Code: diffs และการชี้ข้อขัดแย้ง\n\nการใช้ Claude Code เพื่อตรวจจับ drift ได้ผลดีที่สุดเมื่อคุณปฏิบัติต่อเอกสารเหมือนโค้ด: เสนอแพตช์ขนาดเล็กที่ตรวจสอบได้และอธิบายเหตุผล แทนที่จะสั่งให้มัน "อัปเดต README" ให้ขอให้มันสร้าง diff เทียบกับไฟล์ที่ระบุ ผู้รีวิวจะเห็นก่อน/หลังชัดเจนและจับการเปลี่ยนแปลงที่ไม่ตั้งใจได้เร็ว\n\nการตรวจ drift ที่ดีให้ผลสองอย่าง:\n\n1) diff ที่เล็กที่สุดเท่าที่จำเป็น\n2) รายงานข้อขัดแย้งที่ตรงไปตรงมาและเฉพาะเจาะจง: "เอกสารบอก X แต่รีโปแสดง Y"\n\n### ขอให้มีหลักฐาน ไม่ใช่ความเห็น\n\nเมื่อคุณพิมพ์พรอมต์ ให้ขอหลักฐานจากรีโป: เส้นทางไฟล์และรายละเอียดเช่น routes, ค่า config หรือเทสต์ที่พิสูจน์พฤติกรรมปัจจุบัน\n\nนี่คือรูปแบบพรอมต์ที่ช่วยให้มีหลักฐานรองรับ:\n\n\nCheck these docs for drift: README.md, docs/api.md, runbooks/deploy.md.\nCompare them to the current repo.\nOutput:\n1) Contradictions list (doc claim -> repo evidence with file path and line range)\n2) Unified diffs for the smallest safe edits\nRules: do not rewrite sections that are still accurate.\n\n\nถ้า Claude บอกว่า "API ใช้ /v2" ให้มันสำรองด้วยการชี้ไปที่ router, OpenAPI spec, หรือ integration test ถ้ามันหาไม่ได้ ควรแจ้งว่าไม่พบหลักฐาน\n\n### กำหนดขอบเขตก่อนแก้ไข\n\nDrift มักเริ่มจากการเปลี่ยนโค้ดครั้งเดียวที่กระทบเอกสารหลายที่ ให้ Claude กำหนดขอบเขตก่อน: มีอะไรเปลี่ยน ที่ไหนเปลี่ยน เอกสารไหนน่าจะพัง และการกระทำของผู้ใช้จะได้รับผลกระทบอย่างไร\n\nตัวอย่าง: คุณเปลี่ยนชื่อ env var จาก API_KEY เป็น SERVICE_TOKEN รายงานที่มีประโยชน์จะค้นหาทุกที่ที่ชื่อเก่าอยู่ (การตั้งค่า README, ตัวอย่าง API, ส่วนความลับใน runbook) แล้วสร้าง diff กระชับที่อัปเดตเฉพาะบรรทัดเหล่านั้นและคำสั่งตัวอย่างที่ตอนนี้จะผิดพลาดเท่านั้น\n\n## ตั้ง workflow ง่าย ๆ ก่อนจะพิมพ์พรอมต์ใด ๆ\n\nถ้าคุณชี้โมเดลไปที่ "เอกสารทั้งหมด" โดยไม่มีกฎ มันมักจะเขียนใหม่ทั้งเอกสารแล้วยังมีข้อเท็จจริงผิด แนะนำ workflow ง่าย ๆ ที่ทำให้การเปลี่ยนแปลงเล็ก ทำซ้ำได้ และรีวิวได้ง่าย\n\nเริ่มจากชุดเอกสารหนึ่งชุด: README, อ้างอิง API หรือ runbook หนึ่งชุดที่คนใช้จริง การแก้ปัญหาในหนึ่งพื้นที่ครบวงจรจะสอนสัญญาณที่เชื่อถือได้ก่อนขยายผล\n\n### ตัดสินใจว่าต้นทางข้อมูลคือที่ไหน\n\nเขียนสิ่งที่ชัดเจนเป็นคำธรรมดาว่าข้อเท็จจริงควรมาจากไหนสำหรับชุดเอกสารนั้น\n\n- สำหรับ README: ผลลัพธ์ CLI help และแอปลักษณ์ตัวอย่างที่ทำงานได้\n- สำหรับเอกสาร API: คำนิยาม router พร้อม integration tests\n- สำหรับ runbooks: คอนฟิกการดีพลอยและการแจ้งเตือนที่กระตุ้นขั้นตอนนั้น\n\nเมื่อคุณระบุแหล่งเหล่านี้แล้ว พรอมต์จะคมขึ้น: "เปรียบเทียบ README กับผลลัพธ์ CLI ปัจจุบันและค่าเริ่มต้นในคอนฟิก แล้วสร้างแพตช์"\n\n### เลือกผลลัพธ์ที่รีวิวเร็ว\n\nตกลงรูปแบบผลลัพธ์ก่อนให้ใครสักคนรันการเช็คครั้งแรก การผสมรูปแบบทำให้ยากที่จะเห็นว่าอะไรเปลี่ยนและทำไม\n\nกฎง่าย ๆ:\n\n- ขอ diff สำหรับทุกการเปลี่ยนแปลงเอกสาร พร้อมเหตุผลสั้นหนึ่งประโยค\n- อนุญาตรายการข้อขัดแย้งสั้น ๆ เฉพาะเมื่อเครื่องมือไม่สามารถแนะนำคำที่ปลอดภัยได้\n- เก็บ diff ให้จำกัดที่ไฟล์เดียวต่อการเปลี่ยนเมื่อเป็นไปได้\n- ให้ความสำคัญกับตัวอย่างที่ล้มเหลว (คำสั่ง, คำขอ, ตัวอย่างโค้ด) มากกว่าการเขียนโดยรวม\n\nนิสัยปฏิบัติ: เพิ่มบันทึกเล็ก ๆ ใน PR เอกสารว่า "Source of truth checked: routes + tests" เพื่อให้ผู้รีวิวรู้ว่าเปรียบเทียบกับอะไร นั่นทำให้การอัปเดตเอกสารจาก "ดูโอเค" เป็น "ตรวจสอบแล้วกับสิ่งจริง"\n\n## ขั้นตอนทีละขั้น: ทำให้เอกสารสอดคล้องกับโค้ดทุกการเปลี่ยนแปลง\n\nปฏิบัติต่อแต่ละการเปลี่ยนโค้ดเหมือนเป็นการสืบสวนเอกสาร จุดประสงค์คือจับข้อขัดแย้งเร็วและสร้างแพตช์เล็กที่ผู้รีวิวเชื่อถือได้\n\nเริ่มโดยเลือกไฟล์ที่ต้องตรวจสอบชัดเจนและคำถามเกี่ยวกับ drift ที่ชัดเจน เช่น: "เราเปลี่ยน env vars, flags ของ CLI, เส้นทาง HTTP, หรือรหัสข้อผิดพลาดที่เอกสารยังพูดถึงหรือไม่?" ความเฉพาะเจาะจงช่วยให้โมเดลไม่เขียนใหม่ทั้งส่วน\n\nจากนั้นให้ Claude Code ดึงข้อเท็จจริงแข็ง ๆ จากโค้ดก่อน ขอให้มันแสดงรายการเฉพาะเท่านั้น: คำสั่งที่ผู้ใช้รัน, endpoints และเมธอด, ฟิลด์ของคำขอและคำตอบ, คีย์คอนฟิก, env vars ที่บังคับ, และขั้นตอนปฏิบัติการที่อ้างอิงโดยสคริปต์หรือคอนฟิก ถ้าไม่พบ ให้ระบุว่า "not found" แทนการเดา\n\nแล้วขอเทเบิลเปรียบเทียบง่าย ๆ: ข้อกล่าวหาในเอกสาร, สิ่งที่โค้ดแสดง, และสถานะ (match, mismatch, missing, unclear) นั่นช่วยให้การอภิปรายมีพื้นฐาน\n\nหลังจากนั้นขอ unified diff ที่แก้ไขเล็กที่สุด บอกให้เปลี่ยนเฉพาะบรรทัดที่จำเป็นเพื่อแก้ความไม่ตรงกัน รักษาสไตล์เอกสารเดิม และหลีกเลี่ยงการเพิ่มคำสัญญาที่ไม่มีหลักฐานจากโค้ด\n\nจบด้วยสรุปสำหรับผู้รีวิวสั้น ๆ: อะไรเปลี่ยน ทำไมเปลี่ยน และสิ่งที่ต้องตรวจสอบเป็นพิเศษ (เช่น env var ที่ถูกเปลี่ยนชื่อ หรือ header ที่ต้องเพิ่ม)\n\n## เอกสาร API: วิธีปฏิบัติในการยืนยัน endpoints และตัวอย่าง\n\nเอกสาร API ล้าสมัยเมื่อโค้ดเปลี่ยนเงียบ ๆ: เส้นทางถูกเปลี่ยนชื่อ ฟิลด์กลายเป็นบังคับ หรือรูปแบบข้อผิดพลาดเปลี่ยน ผลลัพธ์คือการผสานระบบพังและเวลา debugging สูญเสียไป\n\nกับ Claude Code เป้าหมายคือพิสูจน์ว่า API ทำอะไรจากรีโป แล้วชี้ความไม่ตรงกันในเอกสาร ขอให้มันดึง inventory จาก routing และ handlers (paths, methods, request และ response models) แล้วเปรียบเทียบกับสิ่งที่เอกสาร API อ้าง\n\nให้ความสำคัญกับสิ่งที่คนมักก็อปปี้: คำสั่ง curl, headers, payload ตัวอย่าง, status codes, และชื่อฟิลด์ ในพรอมต์เดียวให้ตรวจ:\n\n- ข้อกำหนดการยืนยันตัวตน (headers, ประเภทโทเคน, endpoints สาธารณะ)\n- พารามิเตอร์ pagination และค่าเริ่มต้น\n- รหัสสถานะข้อผิดพลาดและรูปแบบ JSON\n- พฤติกรรมการเวอร์ชัน (v1 เทียบกับ v2)\n- ตัวอย่างตรงกับกฎการ validate ปัจจุบันหรือไม่\n\nเมื่อพบความไม่ตรงกัน ให้ยอมรับเฉพาะ diffs ที่สามารถอ้างอิงหลักฐานจากโค้ดได้ (เช่น นิยาม route, พฤติกรรม handler, หรือสคีมา) นั่นช่วยให้แพตช์เล็กและตรวจทานได้\n\nตัวอย่าง: โค้ดตอนนี้คืน 201 บน POST /widgets และเพิ่มฟิลด์ name ที่เป็นบังคับ เอกสารยังแสดง 200 และละไว้ไม่กล่าวถึง name ผลลัพธ์ที่ดีจะชี้ทั้งสองความขัดแย้งและอัปเดตแค่รหัสสถานะและ JSON ตัวอย่างของ endpoint นั้น ทิ้งส่วนอื่นไว้เหมือนเดิม\n\n## Runbook: ลดเวลาหยุดชะงักจากขั้นตอนที่ล้าสมัย\n\nRunbook ล้มเหลวในแบบที่มีต้นทุนสูงที่สุด: มันดูครบถ้วนแต่ขั้นตอนไม่ตรงกับระบบปัจจุบัน การเปลี่ยนเล็ก ๆ เช่น การเปลี่ยนชื่อ env var หรือคำสั่งดีพลอยใหม่ สามารถทำให้เหตุการณ์ยืดเยื้อเพราะผู้ตอบเหตุการณ์ทำตามคำสั่งที่ใช้ไม่ได้\n\nปฏิบัติต่อ runbook เหมือนโค้ด: ขอ diff เทียบกับรีโปปัจจุบันและต้องมีการชี้ข้อขัดแย้ง เปรียบเทียบกับสิ่งที่ระบบใช้ตอนนี้: สคริปต์, ค่าเริ่มต้นคอนฟิก, และเครื่องมือที่ใช้จริง\n\nเน้นจุดล้มเหลวที่ทำให้เกิดการวนซ้ำมากที่สุดในเหตุการณ์:\n\n- คำสั่งที่ระบุตรงกับสคริปต์และ flags ปัจจุบันหรือไม่?\n- ค่า config "เริ่มต้น" ตรงกับที่แอปส่งมาหรือไม่?\n- env vars และ secrets ที่จำเป็นถูกอ้างอิงโดยโค้ดและคอนฟิกดีพลอยหรือไม่?\n- ขั้นตอนดีพลอยและ rollback ตรงกับเครื่องมือปล่อยเวอร์ชันปัจจุบันและการตั้งชื่อหรือไม่?\n- ค่า "ที่รู้ว่าดี" (พอร์ต, โซน, timeouts) ยังตรงกับความจริงหรือไม่?\n\nยังให้เพิ่มการตรวจสอบด่วนและผลลัพธ์ที่คาดหวังเพื่อให้ผู้ตอบเหตุการณ์รู้ว่ากำลังไปถูกทางหรือไม่ การบอกว่า "ตรวจสอบว่าทำงานได้" ไม่พอ ให้ระบุสัญญาณที่คาดหวังอย่างชัดเจน (เช่น status line, version string, หรือผล health check)\n\nถ้าคุณสร้างและดีพลอยแอปบนแพลตฟอร์มอย่าง Koder.ai เรื่องนี้ยิ่งสำคัญเพราะ snapshot และ rollback ใช้ได้ก็ต่อเมื่อ runbook ระบุการดำเนินการที่ถูกต้องและสะท้อนเส้นทางการกู้คืนปัจจุบัน\n\n## ความผิดพลาดที่พบบ่อยซึ่งทำให้ drift แย่ลง\n\nวิธีที่เร็วที่สุดในการสร้าง drift คือการมองเอกสารเป็น "งานเขียนสวยงาม" แทนที่จะเป็นชุดข้อกล่าวหาที่ต้องตรงกับโค้ด\n\n### ความผิดพลาดที่ทำให้การสอดคล้องหายไปเงียบ ๆ\n\nการขอให้โมเดลเขียนใหม่ก่อนตรวจข้อขัดแย้งเป็นความผิดพลาดทั่วไป เมื่อข้ามการตรวจสอบข้อขัดแย้ง คุณอาจได้ข้อความที่ลื่นขึ้นแต่ยังบรรยายพฤติกรรมผิดเสมอ ให้เริ่มด้วยการถามว่าเอกสารอ้างว่าอะไร โค้ดทำอะไร และจุดไหนไม่ตรงกัน\n\nอีกความผิดพลาดคือปล่อยให้โมเดลเดา หากพฤติกรรมไม่ปรากฏในโค้ด เทสต์ หรือคอนฟิก ให้ถือว่าเป็นไม่ทราบ คำว่า "อาจจะ" เป็นวิธีที่ README มักสัญญาเกินจริงและ runbook กลายเป็นนิยาย\n\nปัญหาเหล่านี้มักปรากฏในการอัปเดตประจำวัน:\n\n- อัปเดตส่วนหนึ่งแต่ปล่อยให้ตัวอย่าง ข้อความแสดงข้อผิดพลาด และกรณีพิเศษยังเป็นของเดิม\n- เปลี่ยนชื่อแนวคิดในที่เดียว (README) แต่ไม่เปลี่ยนในเอกสาร API, คีย์คอนฟิก, หรือ runbook\n- แก้คำอธิบาย endpoint แต่ลืมตัวอย่าง request/response\n- เปลี่ยนพฤติกรรมแต่ไม่อัปเดตค่าเริ่มต้นหรือหมายเหตุข้อจำกัด\n- ผสานการแก้ไขเอกสารโดยไม่มีบรรทัดสั้น ๆ ว่า "ทำไมเปลี่ยน" ในสรุป diff\n\n### ตัวอย่างสั้น ๆ\n\nhandler เปลี่ยนจากคืน 401 เป็น 403 สำหรับโทเคนหมดอายุ และชื่อ header เปลี่ยนจาก X-Token เป็น Authorization ถ้าคุณแก้เฉพาะส่วน auth คุณอาจพลาดว่าตัวอย่าง API ยังแสดง header เก่า และ runbook ยังคอยดูว่าเกิด spike ของ 401\n\nเมื่อคุณสร้าง diffs ให้เพิ่มบรรทัดสรุปการตัดสินใจสั้น ๆ เช่น: "Auth failures now return 403 to distinguish invalid vs missing credentials." นั่นป้องกันไม่ให้คนถัดไป "แก้" เอกสารกลับเป็นพฤติกรรมเก่า