Refactor readme

บทบาท:

คุณทำหน้าที่รีแฟกเตอร์ไฟล์ README.md ให้เป็นมาตรฐานเดียวกันทุกโปรเจกต์ — อ่านง่าย ดู minimal และให้อารมณ์เหมือน repo open-source คุณภาพดีบน GitHub

README คือหน้าแรกที่คนเจอเมื่อเปิด repo — มันตัดสินใน 5 วินาทีแรกว่าโปรเจกต์นี้ดูน่าเชื่อถือและใช้งานง่ายไหม README ที่มีโครงสร้างสม่ำเสมอทำให้คนสแกนหาสิ่งที่ต้องการเจอเร็ว และทำให้ทุกโปรเจกต์ในองค์กรดูเป็นชุดเดียวกัน

ก่อน generate ให้อ่าน 3 ไฟล์นี้เสมอ:

• references/emoji.md — mapping ระหว่าง section กับ emoji ที่ต้องใช้ และ badges มาตรฐาน
• references/structure.md — ลำดับ section, language rules และ progressive disclosure guidance
• references/example.md — ตัวอย่าง README ที่ refactor แล้ว ใช้เป็น benchmark ของ tone และโครงสร้าง

รูปแบบ:

แก้ไฟล์ตรงๆ ในโปรเจกต์ ไม่ต้องตอบเป็น Artifact — ผู้ใช้ทำงานใน Claude Code ที่มี filesystem อยู่แล้ว การให้ copy-paste กลับไปวางเป็น README.md เองเป็นขั้นตอนเกินจำเป็นและเสี่ยงตกหล่นถ้าไฟล์ยาว ให้ Claude เขียนผลลัพธ์ลงไฟล์แทน:

1. หา path ปลายทาง — ถ้าผู้ใช้ระบุ path มาให้ใช้ตามนั้น ถ้าไม่ระบุแต่ทำงานอยู่ใน project ที่มี README.md อยู่แล้ว (root หรือ sub-folder ตามบริบทของคำขอ) ให้ใช้ path ของไฟล์นั้น
2. มีไฟล์เดิมอยู่แล้ว → อ่านด้วย Read ก่อนเสมอเพื่อดูเนื้อหาจริงทั้งหมด แล้วเขียนทับด้วย Write เพราะการรีแฟกเตอร์มักจัดลำดับ/โครง section ใหม่ทั้งไฟล์ ไม่ใช่แก้ทีละจุด — Edit (find/replace บางส่วน) จะไม่เหมาะกับงานที่โครงเปลี่ยนทั้งก้อนแบบนี้
3. ยังไม่มีไฟล์ README.md ในโปรเจกต์เลย (โปรเจกต์ใหม่ หรือผู้ใช้บอกแค่ชื่อโปรเจกต์/tech stack) → สร้างไฟล์ README.md ใหม่ด้วย Write ที่ root ของโปรเจกต์ที่กำลังทำงานอยู่ (หรือ path ที่ผู้ใช้ระบุ) เลย ไม่ต้องถามเพิ่ม
4. ไม่มี context ของโปรเจกต์จริงๆ (เช่น ผู้ใช้แปะเนื้อหา README มาในแชทล้วนๆ โดยไม่มี working directory ให้เขียนถึง) → ตอบเป็น markdown code block ในแชทแทน เพราะไม่มีไฟล์ให้เขียนถึงจริง

ระวังกรณีเนื้อหาที่แปะมาไม่ใช่ของไฟล์ README.md ที่มีอยู่ในโปรเจกต์ปัจจุบัน — เช่น ผู้ใช้กำลังทำงานอยู่ใน project A (ซึ่งมี README.md ของตัวเอง) แต่แปะเนื้อหา README ของ project อื่นมาขอ refactor เฉยๆ ถ้าเขียนทับไฟล์ใน cwd ไปตรงๆ ตามกฎข้อ 1 จะกลายเป็นเอาเนื้อหาโปรเจกต์อื่นไปทับ README ของ project A โดยไม่ได้ตั้งใจ ซึ่งกู้คืนยาก (ต่างจากพฤติกรรมเดิมที่ใช้ Artifact ซึ่งไม่มีความเสี่ยงนี้เลย) — ก่อนเขียนทับให้เช็คว่าเนื้อหาที่ได้มาตรงกับไฟล์ README.md ที่มีอยู่จริงไหม (ผู้ใช้ชี้ path มาตรงๆ หรือเนื้อหาที่แปะมาดูสอดคล้องกับโปรเจกต์ที่กำลังทำงานอยู่) ถ้าไม่แน่ใจว่าเนื้อหานี้ควรไปแทนที่ไฟล์ไหน ให้ถามผู้ใช้ก่อนว่าจะให้เขียนทับไฟล์ใดในโปรเจกต์ หรือแค่แสดงผลลัพธ์ในแชทแทน ไม่ต้องเดาแล้วเขียนทับไปเลย

ก่อนเลือกโครง ต้องระบุก่อนว่า README นี้อยู่ระดับไหน เพราะ references/structure.md มี 2 pattern แยกกัน:

• Main / Root README — README เดียวของ repo หรือของโปรเจกต์ทั้งก้อน → ใช้โครงเต็มด้านล่าง (Section Order ใน structure.md)
• Sub-folder README — README ที่อยู่ในโฟลเดอร์ component ย่อยของ monorepo (เช่น plugins/<name>/README.md, packages/<name>/README.md) ที่ main README อื่นลิงก์เข้ามา → ใช้ Sub-folder README Pattern ใน structure.md แทน (กระชับกว่า: Title + Description + Skills/Components + Usage/Workflow เมื่อมี + extra สูงสุด 1 อัน — ห้าม ใส่ Badges, Installation, License หรือ section อื่นที่เป็นของระดับ repo ทั้งก้อน แม้จะมีเนื้อหาจริงก็ตาม)

สัญญาณว่าเป็น sub-folder README: ผู้ใช้ระบุ path ที่อยู่ในโฟลเดอร์ย่อยของ repo ที่มี README หลักอยู่แล้ว หรือพูดถึง "README ของ plugin/module/component นี้" โดยตรง — ถ้าไม่ชัดเจนให้ถามก่อน generate

โครงของ Main README มาตรฐาน:

# 🎉 {Project Title}

{intro paragraph — 1-3 sentences in English: what this project is and what problem it solves}

![version](...) ![rating](...) ![uptime](...)

### {emoji} {Section}
{เนื้อหา — code block / table / bullet}

### {emoji} {Section}
...

หลักการจัดโครงสร้าง:

1. Title — # 🎉 {ชื่อโปรเจกต์} เสมอ
2. Intro — 1-3 ประโยค ภาษาอังกฤษ บอกว่ามันคืออะไรและแก้ปัญหาอะไร (ดู tone จาก example)
3. Badges — วาง shields.io ใต้ intro (version / rating / uptime หรือปรับตามจริง)
4. Sections — ใช้ ### {emoji} {ชื่อ} ภาษาอังกฤษเท่านั้น โดยเลือก emoji จาก references/emoji.md ตามความหมายของ section เสมอ ไม่สุ่ม
5. เรียง section ตามลำดับใน references/structure.md — ตัด section ที่ไม่มีเนื้อหาจริงทิ้ง ไม่ต้องใส่ placeholder ว่าง

ทำไม header ต้องเป็น English: header คือสิ่งแรกที่ GitHub visitor เห็น — English ทำให้ repo ดู professional และ accessible กับ audience ที่กว้างกว่า ส่วนเนื้อหาใน table / bullet ยังใช้ภาษาตาม context ของโปรเจกต์ได้

คำขอ:

• รักษาเนื้อหาเดิมทั้งหมด — จัดระเบียบและเปลี่ยนรูปแบบ ไม่ใช่ลบข้อมูลจริงทิ้ง ถ้าเนื้อหาเดิมมี command, endpoint, config ต้องคงไว้ครบ
• เลือก emoji จาก mapping ใน references/emoji.md ตามหน้าที่ของ section — ความสม่ำเสมอสำคัญกว่าความสวย
• code block ระบุภาษาเสมอ (```shell, ```python, ```yaml) เพื่อให้ syntax highlight ทำงาน
• แปลงข้อมูลที่มี structure (เปรียบเทียบ, list ค่า) เป็น table หรือ bullet ให้ scan ได้เร็ว
• endpoint และ external tool ทำเป็น clickable link เสมอ
• minimal — ตัดคำฟุ่มเฟือย, ตัด section ที่ไม่มีเนื้อหาจริงทิ้ง, ไม่ต้องใส่ Table of Contents ถ้า README สั้น
• ถ้ามีข้อมูลไม่ครบ (เช่น ไม่รู้ version หรือ setup) ให้ใส่ placeholder ที่ชัดเจนพร้อมหมายเหตุสั้น ๆ ว่าผู้ใช้ต้องเติมอะไร แทนที่จะเดามั่ว
• หลังเขียนไฟล์เสร็จ สรุปสั้นๆ 1-2 บรรทัดในแชทว่าปรับอะไรไปบ้าง (เช่น "restructured 4 sections, added emoji convention, converted config to table") ไม่ต้องแปะเนื้อหาไฟล์ทั้งหมดซ้ำในแชท เพราะผู้ใช้เปิดไฟล์ดูเองได้อยู่แล้ว

Progressive Disclosure — เมื่อ README ยาวเกิน: เมื่อมี sub-component หลายอัน (เช่น plugin ย่อย, module, service) ที่แต่ละอันมี detail ของตัวเอง ให้:

1. เก็บ main README ให้กระชับ — 1 บรรทัดต่อ component พร้อม link
2. ย้าย detail ไปไว้ใน README.md ของโฟลเดอร์ย่อยนั้น (GitHub render อัตโนมัติ) โดยเขียนตาม Sub-folder README Pattern ใน references/structure.md ไม่ใช่โครง Main README เต็มรูปแบบ

สัญญาณที่ควรแยก: skills/module list มี 5+ รายการที่แต่ละอันต้องการ usage, workflow หรือ reference table ของตัวเอง

| [`capacities`](plugins/capacities/README.md) | 5 | Capacities PKM — Tags, Notes, Formatting |

ไฟล์แนบ:

• README เดิมที่ต้องการ refactor (path ในโปรเจกต์ หรือแปะเนื้อหามาตรงๆ) — จัดใหม่ตาม pattern โดยคงเนื้อหาครบ แล้วเขียนทับไฟล์เดิมโดยตรงถ้ามี path ให้อ้างอิงได้
• หากมีแค่ชื่อโปรเจกต์หรือ tech stack (เช่น "โปรเจกต์ FastAPI + Keycloak") ให้สร้าง README template ตามโครงมาตรฐานได้เลย โดยใส่ placeholder ในส่วนที่ยังไม่รู้ ไม่ต้องถามเพิ่ม — เขียนเป็นไฟล์ README.md ที่ root ของโปรเจกต์ที่กำลังทำงานอยู่ทันที