# บทที่ 3: Specs และ Prompts สำหรับเว็บบริษัท, Catalog และเว็บ animation

ต่อยอดโจทย์รายวิชาได้ใน [สร้างเว็บไซต์หลักสูตรด้วย Codex แบบทีละขั้น](../labs/build-course-website-step-by-step.md) พร้อม prompt ที่รันจริงและภาพผลลัพธ์แต่ละช่วง

ถ้าข้อมูลโจทย์ยังเป็น notes หรือไฟล์กระจัดกระจาย ให้ใช้ [Lab Research → Website brief → Brandbook](../labs/research-to-brand-website.md) เพื่อให้ AI ช่วยค้นและสังเคราะห์ brief พร้อมแหล่งอ้างอิง ก่อนเขียน spec หรือเลือกภาพ

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

ผู้เรียนเขียน spec ที่ AI และ stakeholder ตรวจร่วมกันได้, เลือก prompt ให้เหมาะกับแต่ละ phase, ป้องกัน content ที่แต่งขึ้น, และกำหนด evidence สำหรับเว็บไซต์สามรูปแบบ: เว็บบริษัท, เว็บเช่าอุปกรณ์/สินค้า catalog และ showroom ที่ใช้ GSAP animation

## 1. Spec ก่อน code: ลดการเดาในจุดที่ราคาแพง

Spec ไม่จำเป็นต้องเป็น RFC ยาว 40 หน้า. สำหรับ MVP ให้เขียน 1–3 หน้า แต่ต้องตอบคำถามที่ code ตอบไม่ได้: ใครใช้, ทำไม, content ไหนอนุมัติแล้ว, conversion ใดสำคัญ, ข้อจำกัด, out of scope, และอะไรคือหลักฐานว่าเสร็จ. เอกสาร Anthropic แนะนำให้ feature ใหญ่เริ่มจาก interview แล้วเขียน spec ที่ self-contained, ระบุ files/interfaces, out of scope และ end-to-end verification ([Claude Code best practices](https://code.claude.com/docs/en/best-practices)). หลักนี้ใช้ได้กับ agent ทุกตัว

### Template `SPEC.md`

```md
# [ชื่อเว็บไซต์] — MVP spec
## Problem / audience
ใครกำลังพยายามทำอะไร และอะไรขัดขวางอยู่

## Outcome
ผู้ใช้ทำ action ใดสำเร็จ; metric ที่วัดได้ (ถ้ามี) และ owner ของ metric

## Approved facts and assets
- Copy/ราคา/โทรศัพท์/เงื่อนไข: URL หรือชื่อเจ้าของที่ยืนยัน
- Images: แหล่งที่มา/สิทธิ์ใช้/alt intent
- Unknown facts: `[TODO owner]` ห้ามให้ agent แต่ง

## Information architecture
Routes, sections, CTA และ state สำคัญ (loading/error/empty/success)

## UX and accessibility
Breakpoints, keyboard/focus, headings/landmarks, form labels/errors,
reduced motion, content language

## Technical constraints
Framework, existing design system, API/data boundaries, allowed dependencies,
secrets/deploy rules

## Acceptance evidence
Commands, browser flows, screenshots/viewports, preview behavior, owner sign-off

## Out of scope
สิ่งที่ไม่สร้างในรอบนี้
```

## 2. Specs สำหรับสาม archetype

### A. เว็บบริษัท (company information)

เป้าหมายมักเป็นความน่าเชื่อถือและการติดต่อ. ต้องยืนยัน brand name, services, location, hours, legal identity, contact details และ claims ก่อนเผยแพร่. CTA อาจเป็น “ขอคำปรึกษา” หรือ “นัดหมาย” แต่ต้องนิยามว่าจะเกิดอะไรหลังส่ง form: แสดง success state, ส่ง email, เก็บ D1 หรือเพียง mock ใน MVP. ห้ามปล่อย form ที่ดูเหมือนส่งจริงแต่ไม่มี endpoint.

**Acceptance example:** ทุก CTA ชี้ไปปลายทางจริง; mobile navigation ใช้ keyboard ได้; contact form มี label/validation; privacy notice ได้รับข้อความจากเจ้าของ; 404/error state ไม่ทำให้ผู้ใช้หลงทาง

### B. เว็บเช่าอุปกรณ์หรือ catalog

ให้ model ข้อมูลเป็น product, availability, lead time, deposit, location, pricing rules และ inquiry/booking state. อย่าเริ่ม payment หรือ availability real-time หาก data source ยังไม่มี. MVP ที่ดีอาจเป็น catalog filter + quote request พร้อม “ราคา/สถานะเป็นข้อมูลตัวอย่าง” ชัดเจน. ออกแบบ state: no results, unavailable, pending quote, validation error, duplicate submission. เริ่มด้วย fixtures ที่มี `isDemo: true`; ก่อน production เปลี่ยนเป็น D1/API ที่มี migration, validation และ audit requirement ตามบท Cloudflare

**Acceptance example:** filter ไม่ทำให้ URL/state หาย; product card ระบุข้อมูลที่ user ตัดสินใจได้; request form ไม่บันทึก PII หากไม่มี privacy flow; API failure แสดงข้อความและไม่หลอกว่าสำเร็จ

### C. Product showroom ที่มี GSAP animation

Animation เป็นชั้นเสริม ไม่ใช่ content architecture. เขียน motion spec: trigger, property, duration range, easing intent, what happens on resize, error/loading fallback, และ behavior เมื่อ `prefers-reduced-motion: reduce`. ต้องวัดบนโทรศัพท์จริง/CPU ต่ำ เพราะ animation ที่ดีในเครื่อง developer อาจทำให้ conversion แย่. อย่าให้ scroll-jacking หรือ motion ที่ซ่อนข้อมูลสำคัญ; content/CTA ต้องเข้าถึงได้แม้ JavaScript หรือ animation ไม่เริ่ม

**Acceptance example:** headline/price/CTA ปรากฏโดยไม่มี animation; animation cleanup เมื่อ component unmount; reduced-motion ลด/ปิด movement ที่ไม่จำเป็น; image size ไม่ทำให้ LCP แย่จนรับไม่ได้; keyboard/focus ไม่ถูก animation บัง

## 3. Prompt เป็น phase-specific artifact

![เวิร์กโฟลว์แปลงโจทย์เป็นแผนภาพ โดยเริ่มจาก source และ audience เลือก semantic pattern กับชนิดภาพ จำกัดรายละเอียด สร้าง SVG และ HTML แล้วตรวจความหมาย การเข้าถึง และ geometry ก่อนเผยแพร่](/diagrams/diagram-workflow.svg)

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

แผนภาพช่วยให้เห็นว่า prompt สำหรับ “สร้างภาพ” ยังต้องมี source, ผู้ชม, ขนาด และ fidelity ledger ไม่ต่างจาก prompt สร้างโค้ด หาก source มีความสัมพันธ์ที่จำเป็น ห้ามลดทอนเงียบ ๆ; ให้เขียนสิ่งที่ merge, collapse หรือ omit ไว้ข้าง deliverable

**ฝึกอ่านภาพ:** นำ spec หนึ่งชิ้นในบทนี้มาเขียน prompt สร้างภาพหนึ่งย่อหน้า แล้ววงคำที่ล็อก audience, ขอบเขต และหลักฐานตรวจรับ ดูแม่แบบเพิ่มเติมใน [ชุด prompt diagram-design](../prompts/diagram-design-prompts.md)

หนึ่ง prompt ไม่ควรทำ research, redesign, database, analytics และ deploy พร้อมกัน. แยก prompt ตาม phase:

| Phase | Prompt ต้องมี | Output ที่รับได้ |
|---|---|---|
| Discover | spec/brief, questions ที่ตอบไม่ได้ | assumption log + plan, ยังไม่ edit |
| Implement | slice เดียว, file constraints, design references | diff เล็ก + tests |
| Verify | acceptance checklist, exact commands, viewport | result + gaps, ไม่ claim เกิน evidence |
| Preview | target env, test data policy | preview URL + smoke test record |
| Release | approved commit/URL, rollback, owner | production evidence หลังมนุษย์อนุมัติ |

OpenAI แนะนำ prompt agentic coding ให้ชัดเรื่อง reuse, delegation, test expectation และ acceptance criteria ([OpenAI Model guidance](https://developers.openai.com/api/docs/guides/latest-model)). แปลเป็น prompt contract คืออย่าสั่ง “ช่วยตรวจให้หน่อย” แต่สั่ง “run `npm run typecheck` และ `npm run build`; ถ้า test files/config พร้อมจึง run `npm run test`; test flow X at viewport Y, report output; ถ้าทำไม่ได้ให้ระบุ gap”

## 4. Lab: เขียน spec และทำ prompt chain

**เวลาศึกษาอิสระสำหรับแบบฝึกเต็ม:** 75 นาที. เลือกหนึ่ง archetype ด้านบน

1. เขียน `SPEC.md` จาก template. ให้ stakeholder/เพื่อนทำหน้าที่ content owner แล้วตอบ `[TODO]` อย่างน้อย 5 จุด
2. สร้าง assumption log มีคอลัมน์ `assumption`, `owner`, `due`, `impact if wrong`.
3. ใช้ prompt “discover” จาก [workflow-prompts.md](../prompts/workflow-prompts.md). ตรวจว่า agent ถามประเด็นจริงแทนเดา
4. เลือก slice แรก เช่น page shell + hero. ใช้ prompt implement. review diff ก่อน accept
5. ใช้ prompt verify. เปิดหน้าเว็บด้วย 320px/768px/desktop, tab ผ่าน CTA และลอง invalid form
6. เขียน release note สั้น: done, known gaps, preview evidence, สิ่งที่ต้อง human approve

**ผลลัพธ์ที่คาดหวัง:** spec ที่ไม่มี hidden assumption สำคัญ, prompt chain 3 อัน, และ evidence log ที่แยกว่า passed/failed/not run

## 5. Common failures

* **“Use GSAP ให้อลังการ”** — ไม่มี motion spec, performance budget หรือ reduced motion. แก้ด้วย story board และ criteria ที่ตรวจได้
* **“เว็บขายของ” แต่ไม่มี catalog data model** — agent invents product fields/ราคา. เริ่ม fixture contract และ label demo
* **ทำ form ก่อน privacy flow** — PII ไปที่ endpoint ที่ไม่ชัด. ใช้ mock หรือกำหนด retention/consent/handler ก่อน
* **ยอมรับ screenshot เป็น test ทั้งหมด** — screenshot ไม่พิสูจน์ navigation/form failure. เพิ่ม smoke interactions และ automated test ที่เหมาะสม
* **Copy prompt ข้าม host โดยตรง** — tool names/skill invocation/permission semantics ต่างกัน. คงเจตนาและ acceptance criteria แต่ตรวจ syntax ของ host

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

- [ ] มี source owner สำหรับ business facts และ asset provenance
- [ ] `SPEC.md` บอก out of scope และ acceptance evidence
- [ ] แยก discovery/implementation/verification/release prompts
- [ ] ระบบทำงานได้โดยไม่พึ่ง animation และเคารพ reduced motion
- [ ] Human checkpoint อยู่ก่อน production, migration, payment และ PII write