# บทที่ 1: พื้นฐาน Vibe Coding สำหรับเว็บที่ส่งมอบได้จริง

## เป้าหมายการเรียนรู้

เมื่อจบบทนี้ ผู้เรียนสามารถเปลี่ยนไอเดียเว็บบริษัท, เว็บสินค้า หรือเว็บเช่าอุปกรณ์ ให้เป็น spec ที่ agent ทำงานได้, สั่งงานเป็นรอบเล็ก, ตรวจผลด้วยหลักฐาน และหยุดก่อนการเปลี่ยนแปลงที่ส่งผลต่อ production. Vibe coding ในหลักสูตรนี้หมายถึงการสนทนากับ AI เพื่อสร้างซอฟต์แวร์อย่างรวดเร็ว โดยผู้เรียนยังเป็น product owner, reviewer และผู้อนุมัติการเปลี่ยนแปลงเสมอ

## สิ่งที่ต้องเตรียม

* Git, Node.js รุ่นที่โปรเจกต์เลือก และบัญชี Git provider
* coding agent หนึ่งตัว (Codex หรือ Claude Code) และ browser สำหรับตรวจหน้าเว็บ
* repository ว่างหรือ starter project; อย่าเริ่มงานจริงในโฟลเดอร์ที่มีไฟล์สำคัญโดยไม่มี Git
* บัญชี Cloudflare ใช้ในบท deploy ภายหลัง แต่บทนี้ยังไม่ใช้ credential หรือ production token

### หมายเหตุสำหรับ repository ของหลักสูตรนี้

เปิด terminal ที่ root ที่มี `package.json`. คำสั่งที่ประกาศจริงคือ `npm run build`, `npm run dev`, `npm run types`, `npm run typecheck`, `npm run db:local` และ `npm run deploy:check`; ใช้ `npm run` เพื่อดูรายการก่อนเสมอ. หน้าแบบฝึกหัดอยู่ที่ `/examples/company/`, `/examples/rental/` และ `/examples/store/` เมื่อ `npm run dev` เปิดที่ port 3320. `npm run test` และ `npm run test:e2e` มีอยู่ใน package scripts แต่ให้รายงานผลจริงจากเครื่องเท่านั้น ไม่สมมติว่าผ่าน.

## 1. ความเร็วไม่ได้แทนความชัดเจน

คำสั่ง “สร้างเว็บบริษัทให้หน่อย” มีช่องว่างมากเกินไป: AI ไม่รู้ว่าบริษัทขายอะไร, ลูกค้าหลักคือใคร, ต้องมี CTA ใด, เนื้อหาไหนเป็นข้อเท็จจริง, สี/ภาพมาจากไหน, form ส่งข้อมูลที่ใด, หรือเกณฑ์ว่าใช้ได้บนมือถือคืออะไร. ผลลัพธ์จึงดูเหมือนเว็บได้เร็ว แต่แก้ไปมาและเสี่ยงให้ agent เดาข้อมูลธุรกิจ

ให้ใช้ **brief ที่ตรวจได้** แทน. Brief ที่ดีมี 7 ส่วน: ผู้ใช้และงานที่ต้องทำ, ข้อความธุรกิจที่ถูกต้อง, pages/sections, brand/content assets, interaction, ข้อจำกัดทางเทคนิค, และ evidence of done. เขียน fact ที่ต้องยืนยันด้วย `[TODO: owner confirms]` แทนการแต่งราคา/เงื่อนไข/คำรับรองขึ้นมาเอง. แนวทาง prompt ของ OpenAI เน้นให้ระบุ acceptance criteria และความคาดหวังการทดสอบสำหรับ coding agents ([OpenAI Model guidance](https://developers.openai.com/api/docs/guides/latest-model)).

ตัวอย่าง brief สำหรับบริษัทเช่าอุปกรณ์:

```md
เป้าหมาย: หน้า landing page ภาษาไทยสำหรับ “Northlight Rental” ให้ผู้จัดงานส่งคำขอใบเสนอราคา
ผู้ใช้: event organizer บนมือถือ ต้องการดูชุดอุปกรณ์และขอราคาเร็ว
เนื้อหาที่เป็นจริง: โทร [TODO], ราคา “เริ่มต้นที่ …” [TODO]; ห้ามแต่งรีวิวลูกค้าหรือราคา
หน้า/section: hero, หมวดอุปกรณ์, ขั้นตอนเช่า 3 ขั้น, FAQ, แบบฟอร์มขอใบเสนอราคา, footer
การเข้าถึง: keyboard ใช้งานได้, label ทุก field, error message อ่านได้, contrast ผ่าน
นิยามว่าเสร็จ: responsive 320–1440px, form validation ฝั่ง client, lint/typecheck ผ่าน,
มี screenshot desktop+mobile และรายการสิ่งที่ยังเป็น TODO
ไม่อยู่ในขอบเขต: payment, login, database, deploy production
```

## 2. วงจรที่ปลอดภัย: Spec → Plan → Build → Verify → Preview → Release

![วงจรส่งมอบแบบย่อจาก brief ผ่านการจัดบริบท การสร้างและการตรวจ โดยผลไม่ผ่านย้อนกลับไปแก้จากหลักฐาน ส่วนผลผ่านจึง deploy และ smoke test](/diagrams/delivery-loop.svg)

[เปิดแผนภาพขนาดเต็ม พร้อม prompt และแหล่งข้อมูลที่ใช้สร้าง](/diagrams/delivery-loop.html)

ภาพรวมขั้น plan/preview/approval บางจุดเพื่อให้เห็นวงจร feedback ชัด ส่วนความสัมพันธ์จาก source เดิมยังต้องใช้ครบ: Brief/Spec ที่ยืนยันแล้ว → AI สำรวจและเสนอแผน → มนุษย์ตรวจขอบเขต → สร้างงานย่อยหนึ่งชิ้น → lint/test/build และตรวจหน้าจอ → Preview URL กับ smoke test → จุดอนุมัติ release; ถ้ายังไม่อนุมัติให้ย้อนกลับไปสร้าง/แก้ชิ้นงาน ถ้าอนุมัติจึง deploy production และบันทึกหลักฐาน

**ฝึกอ่านภาพ:** ชี้จุดที่ “หน้าเว็บดูดี” ยังไม่เพียงพอ แล้วระบุหลักฐานอย่างน้อยสองชนิดที่ต้องผ่านก่อนถึง release

จุดสำคัญคืออย่าให้ prompt เดียวข้ามจาก idea ไป production. การ deploy, DNS, migration, billing, การส่งอีเมล และการเขียนข้อมูลลูกค้าเป็น **checkpoint ที่มนุษย์อนุมัติ**. Preview เป็นที่ให้ stakeholder ตรวจ copy, brand, form flow และมือถือก่อน ส่วน CI/test เป็นที่ตรวจพฤติกรรมทางเทคนิค ทั้งคู่ต้องมี

Anthropic แนะนำ tight feedback loops และให้แก้ทิศทางทันทีเมื่อเห็นว่า agent ออกนอกทาง; long session ที่เต็มด้วยความพยายามผิดทำให้คุณภาพลดลง ([Claude Code best practices](https://code.claude.com/docs/en/best-practices)). ในการสอน จึงให้ “one vertical slice per turn”: เช่น เฉพาะ hero ก่อน, แล้ว nav, แล้ว product card, แล้ว contact form. หลังแต่ละ slice ให้ request report ว่าแตะไฟล์ใด, รันอะไร, ผลอะไร, ยังไม่แน่ใจเรื่องใด

## 3. Prompt เป็นสัญญางาน ไม่ใช่คาถา

ใช้โครง `Context → Goal → Constraints → Deliverable → Evidence → Stop`. ยิ่งเป็นงานใหญ่ยิ่งให้ agent สำรวจและเสนอแผนก่อน edit. Prompt ควรเรียกชื่อ technology หรือ reference ที่มีจริง ไม่ควรสั่ง “ใช้ stack ที่ดีที่สุด” โดยไม่มีข้อกำหนด

```text
คุณเป็น frontend engineer ใน repository นี้

Context: อ่าน README และ AGENTS.md ก่อน ห้ามเดาข้อมูลธุรกิจที่ไม่มีในไฟล์
Goal: สร้างเฉพาะ section hero ของหน้าเว็บบริษัทตาม brief ด้านล่าง
Constraints: ใช้ component/style pattern ที่มีอยู่; ไม่เพิ่ม dependency; mobile-first;
ใช้ข้อความ placeholder ที่ติดป้าย [TODO] สำหรับข้อเท็จจริงที่ยังไม่ได้รับรอง
Deliverable: component และ CSS ที่จำเป็น, ไม่มีการแก้ส่วนอื่น
Evidence: รันคำสั่ง lint/typecheck ที่ repository กำหนด; บอกผลและไฟล์ที่แก้
Stop: หลังเสนอ diff และหลักฐาน หยุดรอ review ก่อนเริ่ม section ถัดไป

Brief: [วาง brief]
```

คำสั่งแบบนี้เปิดทางให้ AI ใช้ความสามารถของตน แต่ล็อกสิ่งสำคัญ: scope, truthfulness, และ evidence. ถ้างานเป็นการแก้ bug ให้เพิ่ม reproduction, expected/actual result และ test ที่ต้องแดงก่อนแก้. ถ้างาน design ให้แนบ wireframe, token, image reference หรือ screenshot ที่มีสิทธิ์ใช้; อย่าบรรยายคำว่า “modern” อย่างเดียว

## 4. Context hygiene: ทำให้ agent รู้เท่าที่จำเป็น

เก็บกติกาถาวรของ repository ไว้ใน `AGENTS.md` เช่น command ที่ใช้ทดสอบ, package manager, folder ownership, เส้นทาง preview, และนโยบาย secrets/deploy. อย่าแปะ documentation ยาวหรืออธิบายทุกไฟล์ เพราะ agent สำรวจ code ได้. หลักฐานจาก Claude Code แนะนำให้ context file เก็บเฉพาะสิ่งที่ agent หาเองไม่ได้ และ prune เป็นระยะ เพราะไฟล์ยาวทำให้ instruction สำคัญหลุด ([Best practices](https://code.claude.com/docs/en/best-practices)).

ตัวอย่าง `AGENTS.md` แบบสั้นสำหรับ workshop:

```md
# Project rules
- Use npm. Start by checking `npm run`; normal validation is `npm run typecheck` and `npm run build`.
- Run `npm run test` or `npm run test:e2e` only when their required test files/configuration exist, and report the real output.
- UI source lives in `src/`; public images must have provenance in `docs/assets.md`.
- Never invent prices, client names, testimonials, legal claims, or accessibility results.
- Deploy only to preview unless a human explicitly names the production environment.
- Secrets stay in Cloudflare/CI secret stores; never put secret values in source, prompts, or docs.
- Before finishing, report changed files, commands/results, and remaining TODOs.
```

## 5. Lab: จาก brief สู่หน้าเว็บบริษัทหนึ่ง section

**เวลาศึกษาอิสระสำหรับแบบฝึกเต็ม:** 45–60 นาที. **ผลลัพธ์ที่คาดหวัง:** branch/commit ที่มี hero section responsive, TODO ที่มองเห็น, และ validation report

1. สร้าง `brief.md` จาก template ด้านบน เลือกธุรกิจจริงหรือธุรกิจสมมติที่ไม่อ้าง claim อันตราย
2. สั่ง agent: “อ่าน repo และ brief แล้วเสนอแผนทำ hero, บอกไฟล์ที่จะเปลี่ยนและคำถามที่ขาด; ยังไม่แก้ไฟล์”
3. ตรวจแผน: ยืนยัน copy, CTA, asset, responsive behavior. หากไม่รู้ข้อเท็จจริง ให้คง `[TODO]`
4. ส่ง prompt build ตัวอย่างข้างต้น แล้วให้ agent สร้างเฉพาะ hero
5. รัน command validation ของโปรเจกต์, เปิด dev server, ตรวจ keyboard tab order, 320px, 768px และ desktop
6. บันทึก screenshot และเขียน `verification.md`: สิ่งที่ตรวจ, ผล, known gaps, next step

**เกณฑ์ผ่าน:** ไม่มี claim แต่งขึ้น, CTA ทำงานตามที่ระบุ, ภาพมี alt ที่มีความหมายหรือเป็น decorative อย่างชัดเจน, ไม่มี horizontal scroll บนมือถือ, และ report ไม่ปิดบัง test ที่ไม่ได้รัน

## ความผิดพลาดที่พบบ่อย

| อาการ | สาเหตุ | วิธีแก้ในรอบถัดไป |
|---|---|---|
| Agent เปลี่ยนทั้ง repository | Prompt ไม่จำกัด deliverable | ระบุ file/slice และบอกให้เสนอแผนก่อน edit |
| หน้าเว็บมีราคา/รีวิวปลอม | Brief ไม่มี source of truth | ใช้ `[TODO]`, fixture label หรือ owner-provided content |
| “test ผ่าน” แต่หน้าใช้ไม่ได้ | รันแต่ unit test | เพิ่ม browser smoke test และ viewport checklist |
| UI สวยแต่ใช้ keyboard ไม่ได้ | ไม่ระบุ accessibility | ใส่ acceptance criteria เรื่อง focus, label, contrast, reduced motion |
| แก้แล้วพังรอบก่อน | ไม่มี Git checkpoint | commit เล็กหลัง validation; ใช้ branch/preview ต่อ feature |

## เช็กลิสต์ก่อนจบบท

- [ ] Brief บอก user, content truth, scope และ definition of done
- [ ] Prompt ขอแผนก่อนงานใหญ่ และขอหลักฐานหลังแก้
- [ ] `AGENTS.md` สั้นและเก็บเฉพาะกติกาถาวร
- [ ] งานถูกแบ่งเป็น slice ที่ตรวจได้
- [ ] ยังไม่มี production deployment หรือ secret ในบทนี้