SpecGuard - ปลั๊กอิน CLI/Codex ที่ตรวจสอบสเปกก่อนให้ AI เขียนโค้ด

 (github.com/KoreaNirsa)
7 คะแนน โดย veltrix 6 일 전 | 1 ความคิดเห็น | แชร์ทาง WhatsApp

สวัสดีครับ ผมกำลังสร้างเครื่องมือโอเพนซอร์สชื่อ SpecGuard อยู่

เวลาใช้เครื่องมือเขียนโค้ดด้วย AI อย่าง Codex หรือ Claude Code ความเร็วในการพัฒนาจะเพิ่มขึ้นอย่างเห็นได้ชัด แต่หลังจากลองใช้ซ้ำอยู่หลายครั้ง ผมพบว่าปัญหาที่เจอบ่อยจริง ๆ ไม่ใช่ “AI เขียนโค้ดไม่ได้” แต่เป็น “สเปกที่ส่งให้ AI นั้นไม่สมบูรณ์ตั้งแต่ต้น” มากกว่า

ถ้าสเปกมีข้อบกพร่อง AI ก็จะเดาช่องว่างนั้นแล้วลงมือเขียนตามที่มันเข้าใจเอง ตอนแรกอาจดูเหมือนใช้ได้ แต่ยิ่งพัฒนาไป ปัญหาต่อไปนี้ก็ยิ่งชัดขึ้น

  • คุณภาพและโครงสร้างของโค้ดค่อย ๆ เสื่อมลง
  • สเปกกับโค้ดค่อย ๆ ไม่สอดคล้องกัน
  • สุดท้ายจะแยกได้ยากว่าโค้ดผิด สเปกล้าสมัย หรือความต้องการตั้งแต่แรกคลุมเครือกันแน่

เพราะแบบนี้ ผมจึงคิดว่าการมีแค่ code review หลังเขียนเสร็จยังไม่พอ ก่อนที่สเปกที่มีข้อบกพร่องจะถูกส่งต่อไปยังเอเจนต์สำหรับลงมือ implement เราควรมีขั้นตอนที่ช่วยเปิดเผยช่องโหว่ของสเปกก่อน

SpecGuard คือปลั๊กอิน CLI/Codex ที่สร้างขึ้นมาเพื่อลดปัญหานี้ มันไม่ใช่เครื่องมือที่ตรวจผลลัพธ์หลังสร้างโค้ดแล้ว แต่เป็นเครื่องมือที่ตรวจสเปกก่อนมอบงานให้ AI ไป implement

ลำดับการทำงานพื้นฐานที่ผมตั้งใจไว้เป็นแบบนี้

  1. คนเขียนสเปกของผลิตภัณฑ์
  2. ใช้ SpecGuard ตรวจสเปก
  3. ถ้าเป็น NOT_READY ก็เสริมสเปกให้ครบ
  4. ถ้าเป็น READY ค่อยส่งต่อให้เอเจนต์สำหรับ implement อย่าง Codex/Claude Code

SpecGuard จะเน้นหาช่องโหว่ประเภทนี้เป็นหลัก

  • ขอบเขตของการยืนยันตัวตน/สิทธิ์การเข้าถึงไม่ชัดเจน
  • ขาดขอบเขต tenant/user ownership
  • ไม่มีการจัดการเรื่อง idempotency, replay, race condition
  • กฎของการหมดอายุ/การเพิกถอน/การเปลี่ยนสถานะคลุมเครือ
  • ไม่มีนโยบายสำหรับ external side effects, webhook, การ retry ของ background job
  • ข้อกำหนดที่เชื่อถือการตรวจสอบฝั่ง client เพียงอย่างเดียว

ผลลัพธ์หลักมี 3 แบบ

  • READY: สามารถส่งต่อให้เอเจนต์ implement ได้
  • READY_WITH_WARNINGS: ส่งต่อได้ แต่มีจุดที่ต้องระวัง
  • NOT_READY: มีปัญหาระดับ Critical/Major ต้องปรับสเปกเพิ่มเติม

เส้นทางหลักคือการตรวจแบบ heuristic ด้วย --no-llm เพราะใน CI หรือ PR Review ผมมองว่าสิ่งสำคัญคือผลลัพธ์ที่เร็วและทำซ้ำได้ แม้จะสามารถต่อรีวิวเชิงลึกบน OpenAI Platform หรือ Codex ได้ด้วย แต่ตอนนี้ตั้งใจให้เป็นเส้นทางเสริมแบบเลือกใช้เฉพาะเวลาที่ต้องการดูละเอียดขึ้น

สิ่งที่เพิ่มเข้ามาใน v0.4.0

ใน v0.4.0 นี้ได้เพิ่ม Codex app plugin MVP เข้ามา

pip install spec-guard  
specguard --help  
codex plugin marketplace add KoreaNirsa/spec-guard --ref main

ใน Codex app หากเลือก source เป็น SpecGuard Plugins แล้วติดตั้งปลั๊กอิน SpecGuard ก็จะสามารถขอให้รัน SpecGuard จากใน Codex ได้ ตัวอย่างเช่น หลังจากสร้างสเปกตัวอย่างแล้ว

specguard example copy specs/your-feature-name --force

จากนั้นเปิดโฟลเดอร์นั้นใน Codex แล้วสั่งแบบนี้ได้

1. @SpecGuard ช่วยรัน SpecGuard สำหรับ specs/your-feature-name ให้หน่อย  
2. @SpecGuard ช่วยรัน SpecGuard กับสเปกแพ็กเกจ specs/your-feature-name แล้วสรุปสถานะ READY/NOT_READY และ finding หลักให้หน่อย  
3. @SpecGuard ช่วยรัน SpecGuard สำหรับ specs/your-feature-name โดยใช้การตรวจ heuristic พื้นฐาน และสรุปสถานะผลลัพธ์กับสิ่งที่ควรทำต่อไปให้หน่อย

ปลั๊กอินนี้ไม่ได้เขียน SpecGuard engine ขึ้นมาใหม่ แต่จะเรียกใช้ specguard CLI ที่มีอยู่เดิม แล้วอ่านผลลัพธ์ที่สร้างขึ้นมาเพื่อสรุปสถานะปัจจุบันและการดำเนินการถัดไป

เมื่อ SpecGuard ทำให้สเปกอยู่ในสถานะ READY ได้แล้ว ก็มีเป้าหมายให้สร้างเอกสาร handoff สำหรับส่งต่อไปยังเอเจนต์ implement แล้วจากนั้นให้ Codex เริ่มลงมือ implement ต่อ

รองรับ PR Review ด้วย

ยังมีเวิร์กโฟลว์ SpecGuard PR Review ที่ทำงานบน GitHub Actions ให้ด้วย

เป็นรูปแบบที่เมื่อสเปกแพ็กเกจมีการเปลี่ยนแปลงใน PR ก็จะรัน SpecGuard Review แล้วฝากผลลัพธ์ไว้ใน PR โดยฟีเจอร์นี้ทำงานผ่านการเรียกใช้ OpenAI

เป้าหมายไม่ใช่ “รีวิวโค้ดที่ AI สร้าง” แต่เป็น “รีวิวอินพุตสเปกก่อนส่งให้ AI”

ใช้ได้เมื่อทีมต้องการตั้งกติกาแบบนี้

  • ไม่ส่งสเปกที่เป็น NOT_READY ไปสู่ขั้น implement
  • เปิดเผย finding ระดับ Critical/Major ตั้งแต่ใน PR ก่อน
  • จัดการคุณภาพของอินพุตความต้องการก่อน แทนที่จะไปเน้นเฉพาะผลลัพธ์ที่ implement ออกมา

การติดตั้งสามารถใช้ specguard actions install-pr-review จาก CLI หรือขอให้ Codex ตั้งค่าด้วยคำสั่ง @specguard ช่วยตั้งค่าเวิร์กโฟลว์ SpecGuard PR Review ให้หน่อย

อย่างไรก็ตาม ฟีเจอร์นี้ยังอยู่ในช่วงทดลอง จึงยังไม่รองรับการตั้งค่าอัตโนมัติ และต้องตั้งค่าใน GitHub Secret ตามด้านล่างด้วยตนเอง

SPECGUARD_OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx  
SPECGUARD_PR_REVIEW_MODEL=gpt-5.4-nano  
SPECGUARD_REVIEW_SPEC_PATHS=specs/your-feature-name

สถานะปัจจุบันและข้อจำกัด

ตอนนี้ยังเป็นเวอร์ชันเริ่มต้น จึงยังไม่ใช่เครื่องมือที่ตัดสินสเปกทุกแบบได้อย่างสมบูรณ์

แต่ถ้าคุณกำลังใช้ AI coding แล้วเจอปัญหา “สเปกอ่อนจนทำให้การ implement เพี้ยน” ก็น่าจะลองใช้มันเป็นตัวกรองความปลอดภัยก่อนเริ่ม implement ได้

ผมอยากได้ฟีดแบ็กครับ โดยเฉพาะประเด็นต่อไปนี้

  • สเปกประเภทไหนที่มันใช้งานได้ดี
  • finding แบบไหนที่มากเกินไปหรือน้อยเกินไป
  • flow ของ Codex plugin ใช้งานได้จริงแค่ไหน
  • การบังคับใช้ผ่าน PR Review เข้ากับเวิร์กโฟลว์ของทีมหรือไม่

ตอนนี้ยังอยู่ในช่วงก่อนเบต้า เป็นระดับที่เพิ่งเริ่มพัฒนาไปได้ไม่นาน แต่ตั้งใจจะพัฒนาให้กลายเป็นโปรเจกต์ที่ใช้งานในงานจริงได้อย่างเต็มที่ในอนาคต

ถ้าสนใจ issue/PR จากทุกคนก็ยินดีต้อนรับ ตอนนี้ issue และ PR ในรีโพซิทอรีจะจัดการเป็นภาษาอังกฤษเป็นหลัก แต่หากเขียนเป็นภาษาเกาหลีก็ไม่มีปัญหา

GitHub : https://github.com/KoreaNirsa/spec-guard

บทความที่เกี่ยวข้อง

1 ความคิดเห็น

 
veltrix 6 일 전

สามารถดูรายละเอียดเพิ่มเติมของโปรเจกต์นี้ได้ที่ https://nirsa.tistory.com/487