ทีมไทยสร้าง Agent Skill โอเพนซอร์สที่เปลี่ยนคำอธิบายหรือ repository จริงให้กลายเป็นไดอะแกรม interactive ที่ผ่าน validation 5 ชั้น - เจาะแนวคิด Typed JSON IR, pipeline Generate-Validate-Deliver และพาลงมือทำตาม 15 นาทีตั้งแต่ติดตั้งจนได้ผลลัพธ์ใช้งานจริง
ทีมไทยสร้างเครื่องมือโอเพนซอร์สที่คว้าอันดับ 1 GitHub Trending ประจำสัปดาห์ทั้งภาษา ด้วยจำนวนดาวกว่า 69,000 ดวงในเวลาไม่กี่เดือน - Archify คือ Agent Skill ที่ทำให้ AI assistant ของคุณ (Cursor, Claude Code, Codex CLI, OpenCode) วาด "ไดอะแกรมที่ตรวจสอบได้" แบบที่เครื่องมือแปลงข้อความเป็นภาพทั่วไปทำไม่ได้ บทความนี้เจาะแนวคิด โครงสร้าง และพาทำตามจริงตั้งแต่ติดตั้งจนได้ผลลัพธ์
ปัญหาที่ Archify มาแก้
ไดอะแกรมสถาปัตยกรรมมีสองโลก: เครื่องมือแบบเดิม (draw.io, Visio) วาดสวยควบคุมได้ แต่ช้าและเก่าเร็วเมื่อระบบเปลี่ยน กับ auto-diagram (Mermaid ฯลฯ) เร็วแต่ผลลัพธ์มักอ่านยาก ลายเส้นทับกัน และไม่มีทางรู้เลยว่ารูปที่ได้ "ถูกต้อง" จริงไหม Archify เลือกทางที่สาม: ให้ AI agent เป็นช่างเลย์เอาต์ แต่บังคับด้วยระบบตรวจสอบที่เข้มงวด - ทุกชิ้นงานต้องผ่าน validation ครบทุกชั้นก่อนส่งมอบ
แนวคิดหลัก: Typed JSON IR + Validation Pipeline
หัวใจของ Archify คือการแยก "ความหมาย" ออกจาก "การวาด" เป็นสองชั้น:
- Typed JSON IR (Intermediate Representation) - agent ไม่ได้วาด SVG ตรง ๆ แต่สร้าง JSON ที่มี schema กำหนดชัดเจน ทุกโหนด ทุกความสัมพันธ์ มีชนิดข้อมูลและกติกาที่ตรวจได้ เหมือนโค้ดที่ compile ได้ ไฟล์เดียวกันจะได้รูปเดิมทุกครั้ง (reproducible)
- Atomic Validation - ก่อนส่งมอบ ทุกชิ้นงานต้องผ่าน 5 ด่าน: schema check, layout rules, HTML/SVG render check, route check และ label-to-route clearance (ตัวหนังสือไม่ทับเส้น) ถ้าตกด่านไหน ระบบไม่พังเงียบ แต่ออก repair receipt เป็น JSON ระบุรหัสกฎที่ละเมิด ตัวปัญหาเป๊ะ ๆ และวิธีแก้ที่รองรับเท่านั้น - agent แก้ได้ตรงจุดในสองรอบ ไม่ต้องเดา
pipeline เต็มมี 5 ขั้น: Generate (agent สร้าง JSON IR จากคำอธิบายหรือ repository จริง) → Validate → Preview (desktop mode ที่รีเฟรชเฉพาะเวอร์ชันผ่านทุกด่าน ถ้า save ค้างจะยังโชว์ของเดิมที่ดีล่าสุด) → Deliver (ตรวจผ่านก่อนค่อยแทนที่ไฟล์จริงแบบ atomic) → Iterate (แก้เฉพาะจุด ส่วนอื่นไม่ขยับ)
5 ประเภทไดอะแกรม - เลือกให้ถูกงาน
| ประเภท | เหมาะกับ |
|---|---|
| Architecture | ส่วนประกอบระบบ บริการ ฐานข้อมูล trust boundary |
| Workflow | CI/CD การอนุมัติ ขั้นตอน agent ที่มี branch และ exception |
| Sequence | การเรียก API, cache miss, authentication ตามลำดับเวลา |
| Data Flow | pipeline ข้อมูล การไหลของ PII ขอบเขตความอ่อนไหว |
| Lifecycle | state machine ที่มี retry, wait และ terminal state |
แต่ละประเภทมี prompt guide ของตัวเอง - บอก scope ใหญ่ component หลัก และเส้นทางสำคัญ ส่วนรายละเอียดเสริมให้ใส่ใน "การ์ด" ของแต่ละโหนดแทนการเพิ่มเส้นเชื่อมจนรก
ลงมือทำตาม: 15 นาทีจากศูนย์ถึงไดอะแกรมของ project คุณ
ขั้นที่ 1: ติดตั้ง (คำสั่งเดียว)
npx skills add tt-a1i/archify -gตัวติดตั้งจะถามว่าใช้ agent ตัวไหน (Cursor / Claude Code / Codex / OpenCode) แล้ววาง skill ลงตำแหน่งที่ถูกต้องให้เอง ใช้เวลาไม่ถึงนาที ไม่ต้องมี repository ใด ๆ
ขั้นที่ 2: เริ่มจากคำอธิบาย (ยังไม่ต้องมีโค้ด)
เปิด agent แล้วพิมพ์:
Use Archify to diagram a web request: Browser calls the API,
the API checks Redis, and a cache miss queries PostgreSQL and fills the cache.ไม่กี่วินาทีคุณจะได้ไฟล์ HTML หนึ่งไฟล์ที่เปิดใน browser ได้เลย - ลองกดโหนดไหนก็ได้เพื่อดูรายละเอียด กด R เพื่อไล่เส้นทางจริงระหว่างสองโหนด หรือ F เข้าโหมดนำเสนอ
ขั้นที่ 3: สั่งต่อเป็นภาษาธรรมชาติ
เพิ่ม authentication ก่อนถึง API
ไฮไลต์เส้นทาง cache miss
สลับเป็นธีมสว่างArchify เก็บ JSON source ไว้ตลอด ทุกคำสั่งแก้เฉพาะส่วนที่ขอ ส่วนอื่นอยู่เหมือนเดิม (stable iteration)
ขั้นที่ 4: ทำกับ repository จริง
อันนี้คือจุดที่ทีม Devsign มองว่า "ทรงพลังที่สุด" เปิดโปรเจกต์ใน agent แล้วสั่ง:
วิเคราะห์ repository นี้ แล้วใช้ Archify สร้าง runtime architecture diagram
แสดง 8-12 core components, เส้นทางหลักหนึ่งเส้น, external dependencies
และ trust boundaries - รายละเอียดรองใส่ในการ์ด อย่าเพิ่มเส้นเชื่อมสิ่งที่ได้ไม่ใช่ภาพจากการเดา: โหนดที่มีหลักฐานจะติดป้าย SRC n กดแล้วเปิดไฟล์จริงพร้อมบรรทัดที่ pin ไว้กับ commit เฉพาะเจาะจง - คุณตรวจย้อนกลับไปที่โค้ดได้ทุกกล่อง ดูตัวอย่างจริงที่สร้างจาก repo mco ได้ที่นี่
ขั้นที่ 5: ส่งต่อให้ทีม
ไฟล์ HTML เป็นแบบ self-contained ฝังทุกอย่างครบในไฟล์เดียว ส่งให้ใครก็เปิดอินเทอร์แอคทีฟได้โดยไม่ต้องติดตั้งอะไร เมนู Export ก๊อป PNG ใส่คลิปบอร์ดหรือทำ share card 1200x630 สำหรับ README ได้ทันที
จุดเด่นเชิงวิศวกรรมที่ควรรู้
- Layout judgment ไม่ใช่ auto-layout - agent เลือกลำดับชั้น ระยะห่าง และเส้นทางเส้นเอง จุดปลายที่ใช้ร่วมกันกระจายแบบ deterministic ไม่ซ้อนกันเป็นพุ่ม
- Truthful interaction - ปุ่ม focus, upstream/downstream reach, route ทำงานจากข้อมูลที่ป้อนจริง ไม่ประดิษฐ์ topology หรืออ้างผลกระทบ runtime โดยไม่มีหลักฐาน
- Architecture Delta - เทียบ snapshot ก่อน/หลังแบบ machine-verified พร้อม receipt เหมาะกับ PR review
- เคารพ accessibility - อนิเมชัน finite และเปิดรับ prefers-reduced-motion อัตโนมัติ
เหมาะกับนักพัฒนาที่ต้องอธิบายสถาปัตยกรรม ทีม DevOps ทำ runbook หรือ tech lead เขียน design doc - แทนการลากกล่องใน draw.io ครึ่งชั่วโมง พิมพ์สามบรรทัดให้ agent ทำ แล้วใช้เวลาที่เหลือตรวจความถูกต้องแทน ซึ่งสำหรับงานวิศวกรรมคือสิ่งที่ควรใช้เวลามากกว่า
โปรเจกต์เป็น MIT license ใช้ฟรีทั้งทีม ดูโค้ดทั้งหมดและ Proof Lab ที่รวมตัวอย่าง 11 สถานการณ์พร้อม validation receipt ได้ที่ github.com/tt-a1i/archify
แหล่งอ้างอิง
- ดูตัวอย่างจริงที่สร้างจาก repo mco ได้ที่นี่ tt-a1i.github.io
- Proof Lab ที่รวมตัวอย่าง 11 สถานการณ์พร้อม validation receipt tt-a1i.github.io
- github.com/tt-a1i/archify github.com
