improve-codebase-architecture

name	improve-codebase-architecture
description	สแกน codebase หาโอกาส deepening แล้วนำเสนอเป็น HTML report แบบ visual จากนั้น grill เจาะลึกตัวที่คุณเลือก
disable-model-invocation	true

Improve Codebase Architecture

ขุดหาจุดฝืดเชิงสถาปัตยกรรม แล้วเสนอ โอกาส deepening — refactor ที่เปลี่ยน module ตื้น ๆ ให้กลายเป็น deep module เป้าหมายคือให้ test ได้ง่ายและให้ AI นำทางใน codebase ได้สะดวก

คำสั่งนี้_อิง_ domain model ของโปรเจกต์ และสร้างบนคลังคำศัพท์ด้าน design ที่ใช้ร่วมกัน:

• รัน skill /codebase-design เพื่อโหลดคำศัพท์ด้านสถาปัตยกรรม (module, interface, depth, seam, adapter, leverage, locality) และหลักการของมัน (deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real") ใช้คำเหล่านี้ให้ตรงเป๊ะในทุกข้อเสนอ — อย่าเผลอไปใช้คำอย่าง "component," "service," "API," หรือ "boundary"
• ภาษา domain ใน CONTEXT.md ช่วยตั้งชื่อให้ seam ที่ดี ส่วน ADR ใน docs/adr/ บันทึกการตัดสินใจที่คำสั่งนี้ไม่ควรหยิบมาถกใหม่

ขั้นตอนการทำงาน

1. Explore

อ่าน domain glossary ของโปรเจกต์ (CONTEXT.md) และ ADR ในบริเวณที่กำลังจะแตะก่อน

จากนั้นใช้ Agent tool แบบ subagent_type=Explore เดินสำรวจ codebase อย่ายึด heuristic ตายตัว — สำรวจแบบเป็นธรรมชาติ แล้วจดจุดที่รู้สึกฝืด:

• ตรงไหนที่การทำความเข้าใจ concept เดียวต้องกระโดดไปมาระหว่าง module เล็ก ๆ หลายตัว?
• ตรงไหนที่ module ตื้น — interface ซับซ้อนแทบเท่าตัว implementation เอง?
• ตรงไหนที่แยก pure function ออกมาเพียงเพื่อให้ test ได้ แต่บั๊กจริง ๆ ซ่อนอยู่ในวิธีที่มันถูกเรียก (ไม่มี locality)?
• ตรงไหนที่ module ซึ่งผูกกันแน่นรั่วข้าม seam ของตัวเอง?
• ส่วนไหนของ codebase ที่ไม่มี test หรือ test ผ่าน interface ปัจจุบันได้ยาก?

ใช้ deletion test กับทุกอย่างที่สงสัยว่าตื้น: ถ้าลบมันทิ้ง ความซับซ้อนจะถูกรวมศูนย์ หรือแค่ย้ายที่? คำตอบ "ใช่ รวมศูนย์" คือสัญญาณที่เราต้องการ

2. นำเสนอ candidate เป็น HTML report

เขียนไฟล์ HTML แบบ self-contained ลง temp directory ของ OS เพื่อไม่ให้อะไรหลุดเข้าไปใน repo หา temp dir จาก $TMPDIR ถ้าไม่มีให้ fallback เป็น /tmp (หรือ %TEMP% บน Windows) แล้วเขียนไปที่ <tmpdir>/architecture-review-<timestamp>.html เพื่อให้แต่ละรอบได้ไฟล์ใหม่เสมอ เปิดไฟล์ให้ผู้ใช้ดู — xdg-open <path> บน Linux, open <path> บน macOS, start <path> บน Windows — แล้วบอก absolute path ให้เขาด้วย

report ใช้ Tailwind ผ่าน CDN สำหรับ layout และ styling และ Mermaid ผ่าน CDN สำหรับ diagram ในจุดที่ graph/flow/sequence สื่อโครงสร้างได้ชัดกว่า ผสม Mermaid กับ visual ที่วาดเองด้วย CSS/SVG — ใช้ Mermaid เมื่อความสัมพันธ์มีรูปทรงแบบ graph (call graph, dependency, sequence) และใช้ div/SVG ที่ประกอบเองเมื่ออยากได้อะไรที่ editorial กว่า (mass diagram, cross-section, animation การยุบรวม) candidate แต่ละตัวต้องมี before/after visualisation เน้น visual เข้าไว้

candidate แต่ละตัว render เป็น card ที่มี:

• Files — ไฟล์/module ไหนบ้างที่เกี่ยวข้อง
• Problem — ทำไมสถาปัตยกรรมปัจจุบันถึงสร้างความฝืด
• Solution — อธิบายเป็นภาษาคนว่าอะไรจะเปลี่ยนไป
• Benefits — อธิบายในแง่ locality กับ leverage และ test จะดีขึ้นอย่างไร
• Before / After diagram — วางคู่กัน วาดเอง แสดงให้เห็นความตื้นและการ deepen
• Recommendation strength — หนึ่งใน Strong, Worth exploring, Speculative แสดงเป็น badge

ปิดท้าย report ด้วยส่วน Top recommendation: candidate ตัวไหนที่ควรลงมือก่อน และเพราะอะไร

ใช้คำศัพท์จาก CONTEXT.md สำหรับฝั่ง domain และคำศัพท์จาก /codebase-design สำหรับฝั่งสถาปัตยกรรม ถ้า CONTEXT.md นิยามคำว่า "Order" ก็พูดว่า "the Order intake module" — ไม่ใช่ "the FooBarHandler" และไม่ใช่ "the Order service"

ความขัดแย้งกับ ADR: ถ้า candidate ขัดกับ ADR ที่มีอยู่ ให้ยกขึ้นมาเฉพาะเมื่อความฝืดนั้นจริงจังพอที่จะคุ้มกับการเปิด ADR มาทบทวนใหม่ ทำเครื่องหมายให้ชัดใน card (เช่น warning callout: "ขัดกับ ADR-0007 — แต่ควรเปิดมาคุยใหม่เพราะ…") อย่าไล่ลิสต์ refactor เชิงทฤษฎีทุกตัวที่ ADR ห้ามไว้

ดู HTML-REPORT.md สำหรับ HTML scaffold ฉบับเต็ม pattern ของ diagram และแนวทาง styling

อย่าเพิ่งเสนอ interface ในขั้นนี้ หลังเขียนไฟล์เสร็จ ถามผู้ใช้ว่า: "อยากเจาะลึกตัวไหนต่อ?"

3. Grilling loop

พอผู้ใช้เลือก candidate แล้ว รัน skill /grilling เพื่อเดิน design tree ไปกับเขา — ข้อจำกัด, dependency, รูปทรงของ module ที่ deepen แล้ว, อะไรอยู่หลัง seam, test ตัวไหนรอด

side effect เกิดขึ้นระหว่างทางทันทีที่การตัดสินใจตกผลึก — รัน skill /domain-modeling เพื่อให้ domain model ทันสมัยอยู่เสมอ:

• ตั้งชื่อ module ที่ deepen แล้วตาม concept ที่ไม่มีใน CONTEXT.md? เพิ่มคำนั้นลง CONTEXT.md ถ้าไฟล์ยังไม่มีค่อยสร้างตอนนั้นเลย
• คำที่คลุมเครือคมขึ้นระหว่างคุยกัน? อัปเดต CONTEXT.md ตรงนั้นทันที
• ผู้ใช้ปัด candidate ทิ้งด้วยเหตุผลที่มีน้ำหนัก? เสนอทำ ADR โดยถามว่า: "อยากให้บันทึกเรื่องนี้เป็น ADR ไหม เพื่อให้ architecture review รอบหน้าไม่เสนอซ้ำอีก?" เสนอเฉพาะเมื่อเหตุผลนั้นจำเป็นจริง ๆ สำหรับคนที่มาสำรวจในอนาคตเพื่อไม่ให้เสนอเรื่องเดิมซ้ำ — ข้ามเหตุผลชั่วคราว ("ตอนนี้ยังไม่คุ้ม") และเหตุผลที่ชัดในตัวเองอยู่แล้ว
• อยากลองสำรวจ interface ทางเลือกสำหรับ module ที่ deepen แล้ว? รัน skill /codebase-design แล้วใช้ pattern design-it-twice แบบ sub-agent ขนานของมัน