ขอให้แก้การจัดการไฟล์ CSV แต่สิ่งที่ได้กลับมาคือคลาสฐานของตัวนำเข้า (importer) รีจิสทรีของ handler และโครงเผื่อฟอร์แมตที่โปรเจกต์ไม่มีเลย งานตั้งต้นเสร็จก็จริง แต่ผลลัพธ์อ่านยากและดูแลยากขึ้น หลักการเขียนโค้ดที่ดีช่วยให้ตรวจงานของ AI เอเจนต์ได้ว่าอะไรจำเป็นต่องานจริง ๆ และอะไรแค่ทำให้โปรเจกต์ซับซ้อนขึ้น
Claude Code, Codex และเอเจนต์อื่น ๆ ควรได้รับข้อจำกัดเรื่องความซับซ้อน ก่อนรีวิวให้ถามตัวเองสามคำถามหลัก: การเปลี่ยนแปลงนี้จำเป็นต่องานตอนนี้ไหม พฤติกรรมที่คาดไว้ยังอยู่ครบไหม และตรวจผลลัพธ์ด้วยอะไร เช็กลิสต์ฉบับเต็มอยู่ท้ายบทความ
หลักการสิบข้อด้านล่างช่วยตอบคำถามเหล่านี้ เริ่มจาก YAGNI และ KISS ส่วน DRY ให้ใช้คู่กับ AHA: การไล่กำจัดโค้ดซ้ำไม่ควรกลายเป็นโรงงานผลิตโครงสร้างอเนกประสงค์ ทุกข้อมีบรรทัด “เช็กสำหรับเอเจนต์” ซึ่งเป็นคำถามที่ควรถามกับ diff
หลักการเขียนโค้ดที่ดี: YAGNI, KISS, DRY และ AHA
1. YAGNI: อย่าทำสิ่งที่แค่คาดว่าจะต้องใช้
You Aren’t Gonna Need It — อย่าเพิ่มความสามารถจนกว่าจะต้องใช้จริง ถ้างานคือส่งออกรายงานเป็น CSV ตอนนี้ยังไม่ต้องรองรับ Excel ไม่ต้องมีผู้ให้บริการจัดเก็บข้อมูลแบบสลับได้ และไม่ต้องมีระบบปลั๊กอิน
แต่ YAGNI ไม่ใช่ข้ออ้างให้ทิ้งความเสถียร การตรวจข้อมูลขาเข้าและเทสต์สำหรับบั๊กที่กำลังแก้เป็นส่วนหนึ่งของงานตอนนี้ ไม่ใช่การเพ้อฝันถึงอนาคต
เช็กสำหรับเอเจนต์: requirement ข้อไหนของงานตอนนี้ที่ทำให้คลาส พารามิเตอร์ หรือไฟล์ใหม่นี้สมเหตุสมผล? ถ้าคำตอบคือ “เดี๋ยวก็ได้ใช้” ก็เป็นเหตุผลให้เลื่อนการเปลี่ยนแปลงนี้ออกไปก่อน
2. KISS: เลือกทางที่ง่ายที่สุดที่เพียงพอ
Keep It Simple, Stupid หรือในเวอร์ชันสุภาพกว่าคือ Keep It Short and Simple: ความเรียบง่ายสำคัญกว่าสถาปัตยกรรมที่ดูหวือหวา สำหรับการแปลงข้อมูลเฉพาะจุด ฟังก์ชันธรรมดาอาจเข้าใจง่ายกว่าสายโซ่ของ factory และ strategy
ทางที่ง่ายไม่จำเป็นต้องสั้นที่สุด การเช็กแบบตรงไปตรงมาพร้อมข้อความ error ที่อ่านรู้เรื่องดีกว่า one-liner แสนฉลาด เกณฑ์คือต้องรู้มากแค่ไหนถึงจะแก้พฤติกรรมได้อย่างปลอดภัย
เช็กสำหรับเอเจนต์: งานนี้แก้ได้โดยเพิ่มคลาส พารามิเตอร์ หรือเลเยอร์ใหม่ให้น้อยกว่านี้ไหม? ถ้าได้ อะไรคือเหตุผลของทางที่ซับซ้อนกว่า?
3. DRY: อย่าก๊อปกฎธุรกิจข้อเดียวไปหลายที่
Don’t Repeat Yourself — เรื่องหลักคือการมีแหล่งความรู้แหล่งเดียว ไม่ใช่การห้ามบรรทัดที่หน้าตาคล้ายกัน ถ้ากฎคำนวณค่าคอมมิชชันถูกก๊อปไปไว้หลายที่ ก็ง่ายมากที่จะแก้ไม่ครบทุกที่ กฎแบบนี้ควรย้ายไปไว้ที่เดียว ไม่ว่าจะเป็นฟังก์ชัน ค่าคงที่ หรือการตั้งค่า แล้วเรียกใช้จากตรงนั้น
แต่ลูปสองอันที่คล้ายกันยังไม่ได้พิสูจน์ว่าต้องมีฟังก์ชันร่วม ต้องดูก่อนว่ามันสะท้อนกฎข้อเดียวกันไหม และต้องเปลี่ยนไปพร้อมกันหรือเปล่า
เช็กสำหรับเอเจนต์: ถ้าพรุ่งนี้กฎข้อนี้เปลี่ยน ต้องแก้โค้ดกี่ที่? คำตอบที่ถูกคือที่เดียว
4. AHA: รอให้ abstraction ชัดก่อน
Avoid Hasty Abstractions — อย่ารีบสร้างโครงสร้างกลางที่ครอบหลายกรณี ถ้า handler ตัวกลางต้องใช้แฟล็ก is_preview, skip_validation และ special_case เป็นไปได้ว่ามันรวมงานคนละอย่างเข้าไว้ด้วยกัน
บางครั้งปล่อยฟังก์ชันเล็ก ๆ สองตัวไว้ชั่วคราวก็สมเหตุสมผลกว่าผูกมันด้วยโมเดลที่ผิด Sandi Metz สรุปไว้สั้น ๆ ว่าโค้ดซ้ำถูกกว่า abstraction ที่ผิด ค่อยเอาส่วนที่ซ้ำออกเมื่อเห็นชัดแล้วว่าอะไรเหมือนกันจริงและอะไรต่างกัน
เช็กสำหรับเอเจนต์: ในฟังก์ชันตัวกลางมีแฟล็กและเงื่อนไขแตกแขนงเพิ่มขึ้นมากี่อัน? ถ้าทุกงานใหม่เพิ่มมาอีกหนึ่ง ควรแยก abstraction กลับเป็นฟังก์ชันเดี่ยว ๆ
SRP และขอบเขตของโมดูล: ทำยังไงไม่ให้สถาปัตยกรรมซับซ้อน
5. SRP: มีเหตุผลหลักในการเปลี่ยนแค่ข้อเดียว
Single Responsibility Principle — โมดูลควรมีเหตุผลหลักในการเปลี่ยนแปลงเพียงข้อเดียว Robert Martin ขยายความว่าเหตุผลของการเปลี่ยนแปลงก็คือคน: requirement ของโมดูลควรมาจากกลุ่มเดียว เช่น ฝ่ายบัญชี หรือทีมที่ดูแลการส่งอีเมล ดังนั้นการเปลี่ยนฟอร์แมตรายงานไม่ควรบังคับให้ต้องไปแก้ลอจิกการส่งอีเมล
นี่ไม่ได้แปลว่าต้องแยกทุกการกระทำเป็นคลาสของตัวเอง สคริปต์เล็ก ๆ เป็นไฟล์เดียวที่มีฟังก์ชันชัดเจนก็ได้ ขอบเขตควรอยู่ตรงที่ช่วยให้เปลี่ยนพฤติกรรมได้อย่างอิสระ ไม่ใช่ตรงที่แค่คิดชื่อใหม่ได้อีกชื่อ
เช็กสำหรับเอเจนต์: การเปลี่ยนแปลงครั้งต่อไปของโมดูลนี้จะมาจากใคร? ถ้ามาจากสองกลุ่ม ควรแยกโมดูล ถ้ามาจากกลุ่มเดียว ไม่ต้องมีคลาสใหม่
6. High Cohesion, Low Coupling: ของที่เกี่ยวกันอยู่ใกล้กัน dependency ชัดเจน
Cohesion สูง (ความเกาะกลุ่ม) ภายในโมดูลหมายความว่าส่วนต่าง ๆ ของมันทำงานที่ใกล้เคียงกัน Coupling ต่ำ (การผูกติดกัน) ระหว่างโมดูลหมายความว่าการเปลี่ยนโมดูลหนึ่งไม่ต้องรู้ไส้ในของโมดูลอื่น Martin Fowler ให้วิธีทดสอบง่าย ๆ: ถ้าการเปลี่ยนโมดูลหนึ่งบังคับให้ต้องเปลี่ยนอีกโมดูล แปลว่าสองโมดูลนี้มี coupling กัน
ตัวอย่างเช่น กฎการคำนวณราคาออร์เดอร์ควรอยู่ด้วยกัน โมดูลส่งการแจ้งเตือนแค่รับยอดที่คำนวณเสร็จแล้วก็พอ ไม่ต้องไปอ่านตารางคำนวณภายใน ทุกอย่างที่โมดูลต้องการจากโมดูลข้าง ๆ มันรับมาอย่างชัดเจนผ่านพารามิเตอร์และการเรียกฟังก์ชัน ไม่ใช่ผ่านตัวแปร global หรือข้อมูลภายในของโมดูลอื่น
เช็กสำหรับเอเจนต์: กฎนี้ใช้ได้สองทาง เอเจนต์กำลังโยนทุกอย่างลง utils ส่วนกลาง หรือกระจายขั้นตอนที่ต่อกันของงานเดียวไปหลายไฟล์โดยไม่มีเหตุผลหรือเปล่า?
Fail Fast และ POLA: error ที่ชัดเจนและพฤติกรรมที่คาดเดาได้
7. Fail Fast: เจอปัญหาที่ต้นเหตุ
Fail Fast — แจ้ง error ทันทีตรงจุดที่มันเกิด Jim Shore ในบทความปี 2547 ยอมรับตรง ๆ ว่าวิธีนี้ไม่ได้ทำให้บั๊กน้อยลง แต่จะหาบั๊กได้ง่ายขึ้นมาก
ถ้างานต้องใช้พารามิเตอร์ใน config ให้เช็กมันก่อนเริ่มทำงาน ถ้าไฟล์ขาเข้าเสีย ให้แจ้งออกมา อย่าคืนผลลัพธ์ว่าง ๆ ที่ดูเหมือนประมวลผลสำเร็จ
ที่น่าสงสัยเป็นพิเศษคือโค้ดที่ดักทุก exception แล้วทำงานต่อเงียบ ๆ error จะโผล่ทีหลังตอนที่ข้อมูลพังไปแล้ว และหาสาเหตุได้ยาก เอเจนต์ก็มีกับดักนี้ในเวอร์ชันของตัวเอง: พอเทสต์ล้ม เอเจนต์อาจห่อโค้ดด้วย try/except หรือใส่ค่า default อย่าง config.get("api_key", "") แค่ให้เทสต์ผ่าน เทสต์เขียวแล้ว แต่ error แค่ย้ายไปโผล่ข้างหน้า
Fail Fast ไม่ได้แปลว่า “ให้ทั้งเซอร์วิสล่มทุกครั้งที่มี error” ต้องเจอ error ให้เร็ว แล้วจัดการที่ขอบเขตที่เหมาะสม: ปฏิเสธ request แยกงานที่ล้มออกมา หรือจบงานด้วยสถานะที่เข้าใจได้
เช็กสำหรับเอเจนต์: ใน diff มีการดัก exception และค่า default ใหม่ไหม? แต่ละอันต้องบอกได้ว่าจัดการ error อะไร และทำไมการเงียบตรงนี้ถึงปลอดภัย
8. POLA: อย่าเซอร์ไพรส์โค้ดที่เรียกใช้
Principle of Least Astonishment — หลักการทำให้ประหลาดใจน้อยที่สุด ดูจากชื่อและ contract ของฟังก์ชันแล้วควรรู้ทันทีว่ามันจะทำอะไร
get_user() ไม่ควรแอบสร้างผู้ใช้ใหม่ และโหมดพรีวิวไม่ควรส่งอีเมลจริง ถ้า side effect จำเป็นจริง ต้องทำให้เห็นชัดใน interface และเอกสาร: ฟังก์ชันที่อาจสร้างผู้ใช้ได้ ถ้าตั้งชื่อว่า get_or_create_user() จะตรงไปตรงมากว่า
เช็กสำหรับเอเจนต์: contract เดิม ทั้งชื่อ พารามิเตอร์ ค่าที่คืน และ side effect ถูกเปลี่ยนเพื่อความสะดวกของโค้ดเฉพาะจุดหรือเปล่า? ถ้างานไม่ได้ต้องการ การเปลี่ยนนี้ก็เกินจำเป็น
การ optimize และการเก็บกวาด: ควรหยุดตรงไหน
9. Premature Optimization: อย่า optimize ถ้ายังไม่ได้วัด
ประโยคที่ว่าการ optimize ก่อนเวลาอันควรคือต้นเหตุของความชั่วร้ายทั้งปวง Donald Knuth เขียนไว้เมื่อปี 2517 และมีข้อแม้สำคัญ: เขาหมายถึงการปรับปรุงเล็ก ๆ น้อย ๆ ที่ไม่จำเป็นในราว 97% ของกรณี แคช การทำงานแบบขนาน และโครงสร้างข้อมูลซับซ้อนไม่ได้เพิ่มแค่ความเร็ว แต่เพิ่มความเสี่ยงของบั๊กใหม่ด้วย
ขั้นแรกให้ยืนยันว่า requirement ด้านประสิทธิภาพไม่ผ่าน แล้วหาคอขวดด้วยการวัด หลัง optimize แล้วให้วัดซ้ำและเช็กว่าพฤติกรรมยังเหมือนเดิม
นี่ไม่ใช่การชวนให้เลือกอัลกอริทึมที่รู้อยู่แล้วว่าไม่มีประสิทธิภาพ Knuth คนเดิมเตือนว่าใน 3% ที่สำคัญที่เหลือ ห้ามมองข้ามโอกาสที่จะทำให้โค้ดเร็วขึ้น ประเด็นคืออย่าจ่ายด้วยความซับซ้อนเพื่อความเร็วที่ยังไม่มีใครยืนยันว่าจำเป็น
เช็กสำหรับเอเจนต์: การวัดไหนที่แสดงว่าตรงนี้เป็นคอขวด? เอเจนต์ชอบเพิ่มแคชและการทำงานแบบขนาน “เพื่อความเร็ว” ถ้าไม่มีตัวเลขก่อนและหลัง เอาการแก้แบบนี้ออกดีกว่า
10. Boy Scout Rule: ปรับให้ดีขึ้นทีละนิด อย่ายึดทั้งโปรเจกต์
กฎลูกเสือเป็นที่รู้จักแพร่หลายเพราะ Robert Martin: ทิ้งโค้ดไว้ให้สะอาดกว่าตอนที่เจอสักนิด ทำชื่อตัวแปรให้ชัดขึ้น ลบ branch ที่เข้าไม่ถึงจริง ๆ แก้คอมเมนต์ที่อยู่ข้างลอจิกที่กำลังเปลี่ยน
แต่กฎนี้มีขอบเขต งานแก้บั๊กไม่ได้ให้สิทธิ์เอเจนต์เปลี่ยนชื่อโมดูลยกชุดหรือเขียน subsystem ข้าง ๆ ใหม่ทั้งหมด การเก็บกวาดครั้งใหญ่ควรเสนอแยก เพื่อให้ตรวจได้และย้อนกลับได้อย่างอิสระถ้าจำเป็น
เช็กสำหรับเอเจนต์: การปรับเล็ก ๆ แตะเฉพาะจุดที่เอเจนต์ต้องแก้ตามงานอยู่แล้วหรือเปล่า? ที่เหลือทั้งหมดให้เป็นข้อเสนอแยก ไม่ใช่อยู่ใน diff เดียวกัน
เมื่อ DRY ขัดกับ KISS และ AHA
ลองนึกถึงฟังก์ชันสองตัว: ตัวหนึ่งคำนวณออร์เดอร์เบื้องต้น อีกตัวคำนวณขั้นสุดท้าย ตอนแรกมันคล้ายกัน เอเจนต์รวมมันเข้าด้วยกันเพื่อ DRY แล้วเพิ่มแฟล็กสำหรับส่วนที่ต่าง: การคำนวณเบื้องต้นไม่มีการชำระเงิน การคำนวณขั้นสุดท้ายต้องมีการตรวจสอบ แล้วก็มีกรณีที่สามโผล่มาพร้อมการปัดเศษแบบของตัวเอง
ในทางทฤษฎีโค้ดซ้ำลดลง แต่ในทางปฏิบัติจำนวนชุดพารามิเตอร์ที่เป็นไปได้เพิ่มขึ้น และนักพัฒนาต้องจำเองว่าพารามิเตอร์ไหนสัมพันธ์กันยังไง
เกณฑ์ในการเลือกคือกฎที่ใช้ร่วมกัน ไม่ใช่หน้าตาที่คล้ายกัน ถ้างานทั้งสองต้องคำนวณภาษีแบบเดียวกัน ก็ควรแยกการคำนวณนั้นออกมา ถ้าตัวงานเองเปลี่ยนด้วยเหตุผลต่างกัน ฟังก์ชันที่ควบคุมงานก็แยกกันไว้ได้ แบบนี้ DRY ปกป้องความรู้จากการถูกก๊อปซ้ำ ส่วน AHA และ KISS ปกป้องโค้ดจากการถูกรวมผิด ๆ
กับดักคล้ายกันคือการเรียกร้อง SOLID ครบชุดจากสคริปต์ Python เล็ก ๆ SOLID คือชุดหลักการออกแบบห้าข้อ และ SRP คือตัวอักษรตัวแรกของชุดนี้ SRP ช่วยแยกการอ่านไฟล์ออกจากการคำนวณได้ แต่ตัวมันเองไม่ได้ต้องการ dependency container หรือลำดับชั้นของ interface ขนาดของวิธีแก้ควรพอดีกับขนาดของงาน
ลำดับความสำคัญในทางปฏิบัติของเราคือ พฤติกรรมที่ต้องการและความเสถียรมาก่อน ตามด้วยความเข้าใจง่าย แล้วค่อยเป็น abstraction และการ optimize ที่มีเหตุผลรองรับแล้ว
พรอมต์สำหรับ Claude Code และ Codex: จำกัดโค้ดเกินจำเป็นยังไง
ด้านล่างคือเทมเพลตตั้งต้น เรายังไม่ได้วัดว่ามันเปลี่ยนพฤติกรรมของเอเจนต์แค่ไหน เพราะฉะนั้นปรับให้เข้ากับโปรเจกต์ของตัวเองได้เลย ใส่ไว้ใน AGENTS.md, CLAUDE.md หรือในข้อความของงานแต่ละงานก็ได้:
ทำตามหลักการ YAGNI, KISS, DRY, AHA, SRP และ Fail Fast
ศึกษาโค้ดที่มีอยู่ก่อน และนำวิธีที่เหมาะสมกลับมาใช้ซ้ำ
อย่าเพิ่มฟังก์ชันการทำงาน abstraction และ dependency
ถ้างานตอนนี้ไม่ได้จำเป็นต้องใช้
อย่าทำ business logic ซ้ำ แต่ก็อย่าทำโค้ดให้ซับซ้อนเพื่อ DRY
อย่าซ่อน error และอย่า optimize ถ้ายังไม่ได้วัดว่าจำเป็น
รักษา contract เดิมและพฤติกรรมที่คาดเดาได้
อย่าแก้โค้ดนอกขอบเขตของงาน
การปรับเล็ก ๆ ทำได้เฉพาะในจุดที่คุณแก้อยู่แล้ว
ส่วนการ refactor ใหญ่ให้เสนอแยกต่างหาก
ถ้าหลักการขัดกัน ให้เลือกวิธีที่ง่ายที่สุดโดยไม่เสียความเสถียร
หลังแก้เสร็จ ให้รันเทสต์และการตรวจสอบที่เกี่ยวข้อง
บอกว่ารันอะไรไปบ้าง ผลเป็นยังไง และอะไรที่ตรวจไม่ได้
อย่าบอกว่าการตรวจที่ไม่ได้รันนั้นผ่านแล้วข้อความแบบนี้เป็นส่วนหนึ่งของบริบทที่เอเจนต์ได้รับ ไม่ใช่กลไกบังคับให้ทำตาม ต่อให้เขียนกฎไว้ดีแค่ไหน ก็ไม่รับประกันว่าโมเดลจะใช้มันกับทุกการเปลี่ยนแปลง
ทำไม AGENTS.md และ CLAUDE.md ใช้แทนเทสต์ไม่ได้
นอกจากข้อความแล้ว ต้องมีการตรวจสอบด้วยโปรแกรมควบคู่กันไป:
- เทสต์ ตรวจพฤติกรรมที่ต้องการ และกันไม่ให้บั๊กที่เคยเจอกลับมาอีก
- Linter และ static analysis หาการละเมิดที่เจาะจงตามกฎที่ตั้งไว้
- การตรวจสถาปัตยกรรม ห้าม dependency ที่ไม่ต้องการและการ import ข้ามเลเยอร์ได้ เช่น import-linter สำหรับ Python หรือ dependency-cruiser สำหรับ JavaScript
- Hook ทำงานทุกครั้ง ต่างจากคำสั่งใน CLAUDE.md ที่โมเดลอาจข้ามไป เช่นใน Claude Code นั้น Stop hook สามารถกันไม่ให้เอเจนต์จบงานจนกว่าการตรวจจะผ่าน
- การตรวจบังคับใน CI ไม่ยอมให้ merge การเปลี่ยนแปลง ถ้าเทสต์หรือ linter ไม่ผ่าน
ไม่มีเครื่องมือไหนในนี้ที่พิสูจน์ได้ด้วยตัวเองว่า abstraction นั้นดี ตรงนี้ยังต้องมีการรีวิว: มันโผล่มาเพราะอะไร แก้ปัญหาอะไร และไม่มีมันได้ไหม การตรวจสอบของเอเจนต์ใหญ่ ๆ ทำงานยังไง ทั้งรีวิวอัตโนมัติด้วยโมเดลแยกต่างหากและงานทดสอบที่รวบรวมจากข้อผิดพลาดที่เคยเกิด มีเล่าไว้ในบทสรุปเลกเชอร์เรื่องการทำงานของ AI เอเจนต์อัตโนมัติ
เช็กลิสต์: ตรวจโค้ดจาก AI เอเจนต์ก่อน merge ยังไง
เปิด diff ซึ่งก็คือรายการการเปลี่ยนแปลง แล้วตรวจผลลัพธ์ด้วยห้าคำถาม:
- requirement ข้อไหนของงานตอนนี้ที่รองรับเลเยอร์ พารามิเตอร์ และ dependency ใหม่แต่ละตัว?
- การไล่กำจัดโค้ดซ้ำกลายเป็นฟังก์ชันอเนกประสงค์ที่มีแฟล็กเต็มไปหมดหรือเปล่า?
- contract เดิมและ side effect ที่คาดไว้ยังอยู่ครบไหม?
- มี error ถูกซ่อนไว้หลังผลลัพธ์ว่าง การดัก exception หรือสถานะ “สำเร็จ” หรือเปล่า?
- เทสต์และการตรวจไหนที่รันจริง ผลเป็นยังไง และอะไรยังไม่ได้ตรวจ?
ถ้าการเปลี่ยนแปลงบางส่วนอธิบายได้แค่ว่า “เผื่ออนาคต” ให้บอกเอเจนต์เอาออกแล้วรันการตรวจซ้ำ ยิ่งการสร้างโค้ดถูกลงเท่าไร ทักษะการหยุดเมื่อได้วิธีที่เพียงพอแล้วก็ยิ่งมีค่ามากขึ้นเท่านั้น
