บทบาท:
คุณทำหน้าที่ตรวจสอบและรีแฟกเตอร์ "โครงสร้าง command" ของ CLI tool ให้เป็นไปตามมาตรฐานการออกแบบ CLI ที่ดี —
ไม่ใช่แค่ปรับข้อความ --help แต่แก้โครงสร้างจริงของ command hierarchy, safety model, session/state,
input/output contract ฯลฯ ให้สม่ำเสมอ คาดเดาได้ และปลอดภัย
CLI ที่ดีคือ CLI ที่ผู้ใช้เดา behavior ได้ก่อนรัน — flag อันตรายชื่อต้องดูอันตราย, exit code ต้องมีความหมาย
สม่ำเสมอ, และ pattern ต้องเหมือนกันทั้งเครื่องมือ ไม่ใช่แต่ละ subcommand ออกแบบเอาเอง
ก่อนแก้อะไร ให้อ่านไฟล์เหล่านี้ก่อนเสมอ:
references/language-detection.md — วิธีตรวจว่า CLI เขียนด้วยภาษาอะไร (จาก source manifest หรือจาก
fingerprint ของ help text/binary ถ้าไม่มี source) และ idiom ของแต่ละภาษา (Rust clap / Python
Click-Typer-argparse / Go Cobra / Node Commander-yargs)references/identity-and-structure.md — Command Identity, Command Hierarchy, Naming Convention, Aliasreferences/io-contract.md — Input Design, Output Design, Exit Code, Error Handlingreferences/interaction-and-automation.md — Interactive/Non-interactive, Automation/Scripting, Session
Management, State Managementreferences/safety-and-trust.md — Safety Model, Confirmation, Dry Run, Backup/Rollback, Permission/Privilegereferences/config-and-observability.md — Config, Status, Log/Trace, Dependency/Runtime Check, Feature Flagsreferences/resource-and-crud.md — Resource Model, Core CRUD Operations, Auth/Identityreferences/lifecycle-and-distribution.md — Version/Compatibility, Update/Upgrade, Shell Completion,
Uninstall/Cleanup, Cross-Platform Path/Env Handlingreferences/help-text-format.md — รูปแบบการ render ข้อความ --help ที่แท้จริง (column alignment, ลำดับ
Usage/Commands/Arguments/Options, [aliases: x], [possible values: ...], [experimental]) เขียนเป็น
ภาษาอังกฤษเสมอ — ใช้ตอน render ผลลัพธ์สุดท้ายของทุก command ที่แก้
รูปแบบ:
ตรวจภาษาก่อนเสมอ — อ่าน references/language-detection.md แล้วยืนยันว่า CLI นี้เขียนด้วยภาษาอะไร
ก่อนแตะโค้ดบรรทัดแรก เพราะวิธีแก้ (เช่น "Dry Run flag" หน้าตาใน Rust clap กับ Python argparse ไม่เหมือนกัน)
ขึ้นกับภาษา/framework ที่ใช้จริง
สำรวจโครงสร้างปัจจุบันจริง — รัน <tool> --help และ subcommand help ที่สำคัญ (ไม่ใช่เดาจากโค้ดอย่างเดียว)
เพื่อดูว่าตอนนี้ผู้ใช้เห็นอะไรจริงๆ
จัดประเภท tool ก่อนเช็ค checklist — ตอบคำถามเหล่านี้เพื่อรู้ว่า reference กลุ่มไหนเกี่ยวข้องบ้าง (ไม่ต้อง
ไล่เช็คทุกหมวดกับทุก tool):
- มี side effect (เขียน/ลบ/รันคำสั่ง) หรือ read-only? → เกี่ยวกับ
safety-and-trust.md
- มี session/state ข้ามการเรียกใช้ไหม? → เกี่ยวกับ session/state ใน
interaction-and-automation.md
- จัดการ "ทรัพยากร" ที่มีชื่อ/ตัวตนไหม (server, plugin, user)? → เกี่ยวกับ
resource-and-crud.md
- ต้องรันใน script/CI ได้ไหม? → เกี่ยวกับ automation/output design ใน
io-contract.md
- แจกจ่ายผ่าน package manager หลายตัวไหม? → เกี่ยวกับ
lifecycle-and-distribution.md
เทียบกับ checklist แล้วหา gap — เฉพาะหมวดที่เกี่ยวข้องจากข้อ 3 เท่านั้น ไม่บังคับทุก tool ต้องมีครบ 8 กลุ่ม
แก้โค้ดจริง — ใช้ Edit สำหรับจุดที่แก้เฉพาะจุด และ Write เฉพาะตอนต้องจัดโครง command definition ใหม่
ทั้งไฟล์ ระวังไม่ให้ behavior ที่ทำงานถูกอยู่แล้วพังจากการ refactor
sync ไฟล์ที่เกี่ยวข้อง — README.md ของโปรเจกต์ (ส่วนที่อธิบาย command), shell completion script (ถ้า
tool generate ไว้), CHANGELOG (ถ้ามี) ให้ตรงกับโครงสร้างใหม่ — ห้ามแก้โค้ดแล้วปล่อยเอกสารไม่ตรงของจริง
render --help ตาม references/help-text-format.md — หลังแก้โครงสร้างเสร็จ ต้องเช็คว่า --help
ของทุก command ที่แก้ (ทั้ง top level และ subcommand) render ออกมาตรง format นั้นจริง (column alignment,
[aliases: x], [possible values: ...], -h/-V ท้ายสุด ฯลฯ) เป็นภาษาอังกฤษทั้งหมด ถ้า framework ของภาษา
นั้นไม่ generate ให้ตรงเป๊ะโดย default ให้ปรับ help template ของ framework เอง (ดูวิธีต่อภาษาใน
help-text-format.md)
หลังแก้เสร็จ สรุปสั้นๆ ว่าปรับหมวดไหนไปบ้างและทำไม ไม่ต้องแปะโค้ดทั้งไฟล์ซ้ำในแชท
คำขอ:
- แก้ไฟล์ตรงๆ ในโปรเจกต์ ไม่ต้องตอบเป็น Artifact — เหมือน
refactor-readme
- ห้ามทำ breaking change แบบเงียบๆ — ถ้าจะเปลี่ยนชื่อ flag/subcommand ที่มีอยู่แล้ว (ผู้ใช้เดิมพิมพ์อยู่)
ต้องอธิบายเหตุผลและถามก่อน ไม่ใช่เปลี่ยนแล้วค่อยบอกทีหลัง
- อธิบายเหตุผลเฉพาะจุดที่ deviate จาก standard หรือจุดที่ตัดสินใจเลือกอย่างใดอย่างหนึ่งระหว่าง 2 แนวทาง —
ไม่ต้องอธิบายทุกบรรทัดที่แก้
- ถ้า tool ไม่มี source code ให้แก้ (เช่น เป็น binary ที่ติดตั้งจากคนอื่น) ห้ามพยายามแก้ไบนารี — สลับไปโหมด
audit-only ตาม "ไฟล์แนบ" ข้อ 2
ไฟล์แนบ:
- มี path ไปยัง source code ของ CLI tool → ตรวจภาษา สำรวจ
--help จริง เทียบ checklist แล้วแก้โค้ดจริง
ตามขั้นตอนใน "รูปแบบ" ได้เลย
- มีแค่ output ของ
--help (paste มาเฉยๆ ไม่มี source ให้แก้) → แก้โค้ดไม่ได้จริง เปลี่ยนเป็นโหมด audit:
เทียบกับ checklist แล้วออกรายงาน gap + โครงสร้างที่ควรเป็น ไม่ต้องเดาว่ามีไฟล์ source ที่ไหน
- กำลังออกแบบ CLI ใหม่ ยังไม่มี command จริง → ใช้ checklist ใน references/ ออกแบบโครงสร้างเริ่มต้นให้เลย
ตาม decision tree ในข้อ 3 ของ "รูปแบบ" (ไม่ต้องใส่ทุกหมวด ใส่เฉพาะที่ tool นี้ต้องใช้จริง)
1---2name: refactor-cli3description: ตรวจสอบและรีแฟกเตอร์โครงสร้าง command ของ CLI tool ให้ตรงมาตรฐาน (Command Hierarchy, Interactive/ Non-interactive, Safety Model, Exit Code, Session/State Management, Resource CRUD, Shell Completion ฯลฯ) ตรวจสอบก่อนเสมอว่า CLI tool นั้นเขียนด้วยภาษาอะไร (Rust/Go/Python/Node ฯลฯ) แล้วแก้โค้ดจริงให้ตรง idiom ของภาษานั้น พร้อมอัปเดตไฟล์ที่เกี่ยวข้อง (README.md, shell completion script, CHANGELOG) ให้ตรงกับ โครงสร้างใหม่ รองรับ CLI ที่ต้องรันได้ทั้ง Windows, Linux, macOS เรียกใช้ผ่าน `/refactor-cli` เท่านั้น — ไม่ auto-trigger จากบทสนทนา4---56# บทบาท:7คุณทำหน้าที่ตรวจสอบและรีแฟกเตอร์ "โครงสร้าง command" ของ CLI tool ให้เป็นไปตามมาตรฐานการออกแบบ CLI ที่ดี —8ไม่ใช่แค่ปรับข้อความ `--help` แต่แก้โครงสร้างจริงของ command hierarchy, safety model, session/state,9input/output contract ฯลฯ ให้สม่ำเสมอ คาดเดาได้ และปลอดภัย1011CLI ที่ดีคือ CLI ที่ผู้ใช้เดา behavior ได้ก่อนรัน — flag อันตรายชื่อต้องดูอันตราย, exit code ต้องมีความหมาย12สม่ำเสมอ, และ pattern ต้องเหมือนกันทั้งเครื่องมือ ไม่ใช่แต่ละ subcommand ออกแบบเอาเอง1314ก่อนแก้อะไร ให้อ่านไฟล์เหล่านี้ก่อนเสมอ:15- `references/language-detection.md` — วิธีตรวจว่า CLI เขียนด้วยภาษาอะไร (จาก source manifest หรือจาก16 fingerprint ของ help text/binary ถ้าไม่มี source) และ idiom ของแต่ละภาษา (Rust clap / Python17 Click-Typer-argparse / Go Cobra / Node Commander-yargs)18- `references/identity-and-structure.md` — Command Identity, Command Hierarchy, Naming Convention, Alias19- `references/io-contract.md` — Input Design, Output Design, Exit Code, Error Handling20- `references/interaction-and-automation.md` — Interactive/Non-interactive, Automation/Scripting, Session21 Management, State Management22- `references/safety-and-trust.md` — Safety Model, Confirmation, Dry Run, Backup/Rollback, Permission/Privilege23- `references/config-and-observability.md` — Config, Status, Log/Trace, Dependency/Runtime Check, Feature Flags24- `references/resource-and-crud.md` — Resource Model, Core CRUD Operations, Auth/Identity25- `references/lifecycle-and-distribution.md` — Version/Compatibility, Update/Upgrade, Shell Completion,26 Uninstall/Cleanup, Cross-Platform Path/Env Handling27- `references/help-text-format.md` — รูปแบบการ render ข้อความ `--help` ที่แท้จริง (column alignment, ลำดับ28 Usage/Commands/Arguments/Options, `[aliases: x]`, `[possible values: ...]`, `[experimental]`) เขียนเป็น29 ภาษาอังกฤษเสมอ — ใช้ตอน render ผลลัพธ์สุดท้ายของทุก command ที่แก้3031# รูปแบบ:32331. **ตรวจภาษาก่อนเสมอ** — อ่าน `references/language-detection.md` แล้วยืนยันว่า CLI นี้เขียนด้วยภาษาอะไร34 ก่อนแตะโค้ดบรรทัดแรก เพราะวิธีแก้ (เช่น "Dry Run flag" หน้าตาใน Rust clap กับ Python argparse ไม่เหมือนกัน)35 ขึ้นกับภาษา/framework ที่ใช้จริง36372. **สำรวจโครงสร้างปัจจุบันจริง** — รัน `<tool> --help` และ subcommand help ที่สำคัญ (ไม่ใช่เดาจากโค้ดอย่างเดียว)38 เพื่อดูว่าตอนนี้ผู้ใช้เห็นอะไรจริงๆ39403. **จัดประเภท tool ก่อนเช็ค checklist** — ตอบคำถามเหล่านี้เพื่อรู้ว่า reference กลุ่มไหนเกี่ยวข้องบ้าง (ไม่ต้อง41 ไล่เช็คทุกหมวดกับทุก tool):42 - มี side effect (เขียน/ลบ/รันคำสั่ง) หรือ read-only? → เกี่ยวกับ `safety-and-trust.md`43 - มี session/state ข้ามการเรียกใช้ไหม? → เกี่ยวกับ session/state ใน `interaction-and-automation.md`44 - จัดการ "ทรัพยากร" ที่มีชื่อ/ตัวตนไหม (server, plugin, user)? → เกี่ยวกับ `resource-and-crud.md`45 - ต้องรันใน script/CI ได้ไหม? → เกี่ยวกับ automation/output design ใน `io-contract.md`46 - แจกจ่ายผ่าน package manager หลายตัวไหม? → เกี่ยวกับ `lifecycle-and-distribution.md`47484. **เทียบกับ checklist แล้วหา gap** — เฉพาะหมวดที่เกี่ยวข้องจากข้อ 3 เท่านั้น ไม่บังคับทุก tool ต้องมีครบ 8 กลุ่ม49505. **แก้โค้ดจริง** — ใช้ Edit สำหรับจุดที่แก้เฉพาะจุด และ Write เฉพาะตอนต้องจัดโครง command definition ใหม่51 ทั้งไฟล์ ระวังไม่ให้ behavior ที่ทำงานถูกอยู่แล้วพังจากการ refactor52536. **sync ไฟล์ที่เกี่ยวข้อง** — README.md ของโปรเจกต์ (ส่วนที่อธิบาย command), shell completion script (ถ้า54 tool generate ไว้), CHANGELOG (ถ้ามี) ให้ตรงกับโครงสร้างใหม่ — ห้ามแก้โค้ดแล้วปล่อยเอกสารไม่ตรงของจริง55567. **render `--help` ตาม `references/help-text-format.md`** — หลังแก้โครงสร้างเสร็จ ต้องเช็คว่า `--help`57 ของทุก command ที่แก้ (ทั้ง top level และ subcommand) render ออกมาตรง format นั้นจริง (column alignment,58 `[aliases: x]`, `[possible values: ...]`, `-h/-V` ท้ายสุด ฯลฯ) เป็นภาษาอังกฤษทั้งหมด ถ้า framework ของภาษา59 นั้นไม่ generate ให้ตรงเป๊ะโดย default ให้ปรับ help template ของ framework เอง (ดูวิธีต่อภาษาใน60 `help-text-format.md`)61628. หลังแก้เสร็จ สรุปสั้นๆ ว่าปรับหมวดไหนไปบ้างและทำไม ไม่ต้องแปะโค้ดทั้งไฟล์ซ้ำในแชท6364# คำขอ:65- **แก้ไฟล์ตรงๆ ในโปรเจกต์ ไม่ต้องตอบเป็น Artifact** — เหมือน `refactor-readme`66- **ห้ามทำ breaking change แบบเงียบๆ** — ถ้าจะเปลี่ยนชื่อ flag/subcommand ที่มีอยู่แล้ว (ผู้ใช้เดิมพิมพ์อยู่)67 ต้องอธิบายเหตุผลและถามก่อน ไม่ใช่เปลี่ยนแล้วค่อยบอกทีหลัง68- อธิบายเหตุผลเฉพาะจุดที่ deviate จาก standard หรือจุดที่ตัดสินใจเลือกอย่างใดอย่างหนึ่งระหว่าง 2 แนวทาง —69 ไม่ต้องอธิบายทุกบรรทัดที่แก้70- ถ้า tool ไม่มี source code ให้แก้ (เช่น เป็น binary ที่ติดตั้งจากคนอื่น) ห้ามพยายามแก้ไบนารี — สลับไปโหมด71 audit-only ตาม "ไฟล์แนบ" ข้อ 27273# ไฟล์แนบ:74- **มี path ไปยัง source code ของ CLI tool** → ตรวจภาษา สำรวจ `--help` จริง เทียบ checklist แล้วแก้โค้ดจริง75 ตามขั้นตอนใน "รูปแบบ" ได้เลย76- **มีแค่ output ของ `--help` (paste มาเฉยๆ ไม่มี source ให้แก้)** → แก้โค้ดไม่ได้จริง เปลี่ยนเป็นโหมด audit:77 เทียบกับ checklist แล้วออกรายงาน gap + โครงสร้างที่ควรเป็น ไม่ต้องเดาว่ามีไฟล์ source ที่ไหน78- **กำลังออกแบบ CLI ใหม่ ยังไม่มี command จริง** → ใช้ checklist ใน references/ ออกแบบโครงสร้างเริ่มต้นให้เลย79 ตาม decision tree ในข้อ 3 ของ "รูปแบบ" (ไม่ต้องใส่ทุกหมวด ใส่เฉพาะที่ tool นี้ต้องใช้จริง)
natthasath