# แนวทางการเขียนและ anti-patterns

แนวทางเหล่านี้ซ้อนอยู่บนสเปก (ที่บังคับแค่ `type`) เพื่อให้ทั้งคนและ agent ใช้ wiki ได้อย่างเชื่อถือได้

## กฎทอง

1. **หนึ่ง concept ต่อไฟล์** — อย่ายัด 3 เรื่องลงไฟล์เดียว
2. **เขียน `description` เพื่อ agent** — เป็นบรรทัดเดียวที่ agent อ่านเพื่อตัดสินใจโหลดไฟล์ เขียนให้เจาะจง
3. **โครงสร้างชนะย่อหน้า** — heading, bullet (`**key** — value`), ตาราง โมเดลดึงข้อมูลจาก Markdown ที่มีโครงสร้างได้แม่นกว่า
4. **identity = path** — ตั้งชื่อไฟล์นิ่ง ๆ kebab-case การเปลี่ยนชื่อทำลายลิงก์ที่ชี้เข้ามา
5. **`type` สม่ำเสมอ** — ใช้ controlled vocabulary
6. **อ้างอิงแหล่งเสมอ** — ทุก claim ที่สังเคราะห์ควรสืบกลับไปไฟล์ใน `raw/` ได้ ใส่ใต้ `# Citations`

## ตาราง anti-patterns

| Anti-pattern | ทำไมแย่ | ทำแทน |
|--------------|---------|--------|
| **ingest อัตโนมัติเบื้องหลัง** | สะสม noise เร็วเท่าสัญญาณ wiki เน่าเงียบ ๆ | ทำให้ ingest เป็นคำสั่งที่คนสั่ง + รีวิว |
| **เท PDF ดิบลง `wiki/`** | retrieval ไม่น่าเชื่อถือ ทำลายการสังเคราะห์ | สังเคราะห์เป็น concept Markdown เก็บดิบไว้ `raw/` |
| **frontmatter ยัดเกิน** | noise ลดความแม่นการค้น | เก็บ `tags` ให้เป็น semantic และน้อย |
| **ข้ามระดับ heading** (H1→H3) | ทำลายโครงเอกสารสำหรับโมเดล | รักษาลำดับ H1→H2→H3 |
| **ย่อหน้าแทรกกลางรายการ** | รายการแตกเป็นชิ้นในสายตา parser | ใช้ย่อหน้าซ้อน หรือจบรายการก่อน |
| **ชื่อ `type`/ฟิลด์ไม่สม่ำเสมอ** | เครื่องรวมข้อมูลไม่ได้ | ใช้ controlled vocabulary |
| **anchor text กำกวม** ("คลิกที่นี่") | ไม่มีสัญญาณหัวข้อให้ LLM | ใช้ข้อความลิงก์ที่บรรยาย |
| **ขึ้นต้นลิงก์ด้วย `/`** | พัง GitHub rendering | ใช้ relative path |
| **ลดความอ่านง่ายเพื่อเครื่อง** | wiki ต้องรับใช้คนด้วย | โครงสร้างเพื่อเครื่อง ความชัดเจนเพื่อคน |

## สเปกหลัก vs แนวปฏิบัติของชุมชน

แยกให้ออก:

- **สเปก OKF v0.1 (เล็กมาก):** บังคับแค่ `type` + กฎ index/log + กฎ conformance
- **แนวปฏิบัติที่ดี (ในเล่มนี้):** ส่วนใหญ่มาจากชุมชน LLM-wiki และ reference implementation ของ Google
  เช่น confidence decay, hybrid search, การจัดกลุ่ม `references/` — ถือเป็น pattern เสริม ไม่ใช่ข้อบังคับ

## ประเด็นที่แหล่งข้อมูลเห็นไม่ตรงกัน

- **"RAG ตายแล้ว"** — วิศวกรส่วนใหญ่บอกว่า wiki = Layer 1, RAG = Layer 2 fallback ไม่ใช่เลือกอย่างใดอย่างหนึ่ง
- **ลิงก์ absolute vs relative** — สเปกแนะนำ absolute แต่ implementation ใช้ relative (เราตาม implementation)
- **freshness scoring 4 มิติ** — เป็นแนวทางที่ vendor (Atlan) โปรโมต ไม่ใช่ส่วนของสเปก

ต่อไปเข้าสู่ระดับองค์กร → [ภาพรวมสถาปัตยกรรม](../part6/architecture.md)
