สถานะ: 🟢 Complete | อัพเดท: 2026-07-11 (v1 — เวอร์ชันแรก เก็บไว้อ้างอิง)
v1 vs v2
นี่คือ workflow เวอร์ชันแรก (5 phases + feedback loop) เวอร์ชันที่ใช้งานจริงตอนนี้คือ v2 (Fable5) ซึ่งเพิ่ม Lane Triage, Evidence Rule, Circuit Breaker, Verify Gate และอื่นๆ เข้ามา — ดู Changelog ในหน้า v2 สำหรับรายการเปลี่ยนแปลงทั้งหมด
AI-Assisted Software Development Workflow
Philosophy
จุดประสงค์ของ workflow นี้ไม่ใช่แค่การใช้ AI Skills แต่คือการลดต้นทุนการพัฒนาโดยเจอปัญหาให้เร็วที่สุด (Shift Left)
แต่ละ phase มีหน้าที่เดียวเท่านั้น — phase หนึ่งต้องไม่ทำงานของ phase อื่น
Scope
ครอบคลุม:
- พัฒนา feature ใหม่
- แก้ bug (ผ่าน Incident Workflow)
ไม่ครอบคลุม:
- Refactoring
- งานเป็นทีม (สำหรับ solo developer + AI เท่านั้น)
Starting Point
| สถานการณ์ | Phase 1 Tool |
|---|---|
| โปรเจคใหม่ — ยังไม่มี CONTEXT.md | grill-me → สร้าง CONTEXT.md จากศูนย์ |
| โปรเจคเดิม — มี CONTEXT.md แล้ว | grill-with-docs → cross-check กับ domain เดิม |
Overall Workflow
flowchart TD START{{"Starting Point"}} START -->|"No CONTEXT.md"| GRILL["grill-me<br/>Create CONTEXT.md from scratch"] START -->|"CONTEXT.md exists"| GRILLDOCS["grill-with-docs<br/>Cross-check against existing domain"] GRILL --> P1 GRILLDOCS --> P1 P1["🔍 Phase 1 — Discovery<br/>grill-with-docs"] P2["📐 Phase 2 — Design Review<br/>plan mode → scrutinize"] P3["📋 Phase 3 — Implementation Planning<br/>karpathy-guidelines"] P4["⚙️ Phase 4 — Implementation<br/>karpathy-guidelines"] P5["✅ Phase 5 — Validation<br/>code-review → scrutinize?"] P1 --> P2 --> P3 --> P4 --> P5 P5 -->|PASS| MERGE["🚀 Merge / Release"] P5 -->|"FAIL: Coding Issue"| P4 P5 -->|"FAIL: Planning Issue"| P3 P5 -->|"FAIL: Design Issue"| P2 P5 -->|"FAIL: Requirement Issue"| P1
Phase 1 — Discovery
Tool
grill-with-docs
เป้าหมาย
เข้าใจปัญหาให้ครบก่อนคุยเรื่อง implementation — AI ควรค้นหา business problem ไม่ใช่รีบออกแบบ solution
หน้าที่
- เคลียร์ requirements
- ค้นหา business rules
- สำรวจ edge cases
- สร้างภาษากลาง (shared language)
- อัพเดท CONTEXT.md
- เขียน ADR เมื่อจำเป็น — ใช้ test นี้:
“Developer ในอนาคตมีเหตุผลที่จะเลือกต่างจากนี้ไหม และถ้าเลือกต่างแล้วย้อนกลับเจ็บจริงไหม?” ถ้า YES → เขียน ADR ถ้า NO → ข้าม
Exit Criteria
- Requirements ชัดเจน
- ไม่มีคำถาม business ค้าง หรือ คำถามที่ตอบไม่ได้ถูกบันทึกใน CONTEXT.md เป็น assumption ที่ flag ว่า unverified
- มีภาษากลางแล้ว
ทำไม?
ความผิดพลาดระดับ requirement คือความผิดพลาดที่แพงที่สุดถ้าเจอช้า แก้ requirements ก่อนเขียนโค้ดถูกกว่า rewrite ทีหลังมหาศาล
Phase 2 — Design Review
Tool
Step 1: plan mode → เสนอ architecture / design
Step 2: scrutinize → โจมตี design ที่เสนอ
เป้าหมาย
โจมตี design ที่เสนอมา — phase นี้ review architecture ไม่ใช่โค้ด
หน้าที่
Step 1 — plan mode ผลิต: architecture proposal, database schema, API design, key design decisions
Step 2 — scrutinize ท้าทาย: architecture, database design, API design, security, scalability, performance, concurrency, edge cases
Exit Criteria
- ไม่มี major architectural concern ค้าง
Major = concern ที่แก้ด้วยการเปลี่ยนโค้ดอย่างเดียวไม่ได้: schema changes, API contract changes, security architecture changes, race conditions, missing constraints
ไม่ major (แก้ใน Phase 4): performance tuning, code style, naming, index optimization
ทำไม?
Requirements ถูกไม่ได้แปลว่า design ดี
Requirement: recurring payments Design แย่: รัน cron ทุกนาที Design ดีกว่า: dedicated scheduler Requirements เหมือนเดิม เปลี่ยนแค่ design
Phase 3 — Implementation Planning
Tool
karpathy-guidelines
เป้าหมาย
คิดก่อนเขียน — แปลง design ที่อนุมัติแล้วเป็น implementation plan
หน้าที่
ผลิต: PLAN.md, task breakdown, รายการไฟล์ที่จะแก้, migration strategy, rollback strategy, testing strategy, implementation phases, commit strategy (หนึ่ง commit ต่อหนึ่ง task)
Exit Criteria
- Developer อนุมัติ plan
- ระบุ risks แล้ว
- Tasks เรียงลำดับชัดเจน
ทำไม?
Planning ลด: ไฟล์ที่ลืม, migration ที่ขาด, tests ที่ขาด, commit structure ที่แย่, rollback strategy ที่แย่
Phase 4 — Implementation
Tool
karpathy-guidelines
เป้าหมาย
ทำตาม plan — ห้าม redesign ระหว่างทำ
ถ้าการ implement เผยว่า design ผิด — หยุด กลับ Phase 2 ห้ามตัดสินใจเรื่อง design ใน Phase 4 ห้าม “จดไว้แล้วทำต่อ” ทุก design change ที่ไม่อยู่ในแผนคือปัญหาของ Phase 2
หน้าที่
- เขียนโค้ด
- Unit tests: เฉพาะ logic ที่ไม่ trivial (branch, loop, parser, เส้นทางเงิน/security), test เล็กๆ หนึ่งตัวที่ fail ถ้า logic พัง, ไม่ต้อง framework/fixtures/suite ต่อ function, one-liner ไม่ต้องมี test
- Documentation: inline comment เฉพาะจุดที่ WHY ไม่ชัด, อัพเดท CONTEXT.md ถ้าเจอ domain knowledge ใหม่, แค่นั้น
Exit Criteria
- Feature เสร็จ
- Tests ผ่าน
- Documentation อัพเดทแล้ว
ทำไม?
หลักการ Karpathy ใช้ตลอดการ implement: เข้าใจก่อน, คิดก่อน, แก้น้อยที่สุด, verify ทุกอย่าง, ห้ามเดา
Phase 5 — Validation
Tool
Step 1: code-review → บังคับ
Step 2: scrutinize → ตามเงื่อนไข
เมื่อไหร่รัน scrutinize: code-review ผ่านแต่ยังรู้สึกไม่ชอบมาพากล, implementation ซับซ้อนและ design drift เป็นความเสี่ยงจริง, ยังมีคำถามเชิง approach พื้นฐานค้างอยู่
เป้าหมาย
Review implementation — ต่างจาก Phase 2 ตรงที่ review โค้ดจริง ไม่ใช่ design
หน้าที่
Review: code quality, test coverage, regression risk, security, maintainability, missing edge cases, ความสอดคล้องกับ design
Exit Criteria
- Implementation พร้อม production
- ลบ PLAN.md หลัง validation ผ่าน
ถ้า Validation Fail
ห้าม restart ทั้ง workflow — classify ปัญหาแล้วกลับไปที่ phase ที่รับผิดชอบ
| ประเภทปัญหา | ตัวอย่าง | กลับไป |
|---|---|---|
| Coding Issue | ขาด null check, error handling, code smell, ขาด tests | Phase 4 |
| Planning Issue | ขาด migration, ขาด rollback plan, testing strategy แย่ | Phase 3 |
| Design Issue | Schema ผิด, API แย่, race condition, security flaw | Phase 2 |
| Requirement Issue | Business rules ผิด, requirement หาย, assumption ผิด | Phase 1 |
Incident Workflow (เจอ Bug)
Bug ไม่ใช่ส่วนหนึ่งของ development workflow — มันเดินเส้น Incident Workflow แยกต่างหาก
flowchart TD BUG["🐛 Bug Found"] DEBUG["Debug Mantra<br/>Reproduce → Trace path → Falsify → Record"] ROOT["Find Root Cause"] CLASSIFY{"Classify Root Cause"} BUG --> DEBUG --> ROOT --> CLASSIFY CLASSIFY -->|"Requirement Problem"| RP1["Return Phase 1"] CLASSIFY -->|"Design Problem"| RP2["Return Phase 2"] CLASSIFY -->|"Planning Problem"| RP3["Return Phase 3"] CLASSIFY -->|"Coding Problem"| RP4["Return Phase 4"] RP1 & RP2 & RP3 & RP4 --> P5["Phase 5 — scoped to fix only<br/>code-review on changed files<br/>scrutinize if design drift suspected"] P5 --> MERGE["🚀 Merge / Release"] MERGE --> IMPROVE["📈 Improve Workflow"]
Debug Mantra
Tool
debug-mantra
เป้าหมาย: หา Root Cause ไม่ใช่หา Fix
- Reproduce ให้ได้เสถียร
- รู้จัก fail path
- Falsify สมมติฐาน
- บันทึกทุกการทดลอง
หา root cause เจอแล้วเท่านั้นถึงค่อยลงมือ fix
Continuous Improvement
ทุก bug ควรทำให้ workflow ดีขึ้น อย่าหยุดที่ “จะ fix bug นี้ยังไง?” ต้องถามต่อ “ทำไม workflow ของเราไม่จับมัน?”
ตัวอย่าง:
- เจอ race condition → Validation ขาด concurrency testing → เพิ่ม concurrency checklist
- เข้าใจ requirement ผิด → Discovery ถามไม่ครบ → ปรับ prompts ของ grill-with-docs
- Migration พัง → Planning ขาด rollback strategy → อัพเดท planning template
Workflow Improvement Log
สถานะ: ต้องคุยเพิ่มก่อนสรุป — บันทึกตรงนี้เป็น intention ยังไม่ใช่ process ที่สรุปแล้ว
คำถามค้าง
- Improvement ควรบันทึกที่ไหน? (ไฟล์นี้? CLAUDE.md? IMPROVEMENTS.md แยก?)
- ใครรับผิดชอบเขียน improvement ก่อนปิด incident?
- ป้องกัน improvement ซ้ำได้ยังไง?
- ต้อง review ก่อน merge เข้า workflow ไหม?
อัพเดทใน v2
คำถามค้างทั้ง 4 ข้อนี้ถูกตอบแล้วใน v2 (Fable5) — ดู Improvement Log ในหน้านั้น
Guiding Principles
1. Shift Left
เจอปัญหาให้เร็วที่สุด — เจอเร็ว = ถูก
2. Single Responsibility
แต่ละ phase มีหน้าที่เดียว: Discovery ค้นหา / Design Review วิจารณ์ architecture / Planning วางแผน / Implementation สร้าง / Validation ตรวจ implementation / Debugging หา root cause
CONTEXT.md เป็น living document — phase ไหนก็ตามที่เจอ domain knowledge ใหม่, เปลี่ยน business rule, หรือตอบคำถามค้าง ต้องอัพเดท CONTEXT.md ก่อนออกจาก phase ไม่ใช่แค่ Phase 1
3. Stage Gates
ทุก phase ต้องผ่าน exit criteria ก่อนไปต่อ
เจ้าของ: Developer เป็นคนตัดสินใจออกจาก phase AI ต้องแจ้งทุกประเด็นค้างก่อน developer จะออก AI ห้ามปล่อยให้ phase ปิดเงียบๆ ทั้งที่มีคำถามค้าง
Context: เคลียร์ context window ทุกครั้งที่ข้าม phase
| เข้า Phase | เอาเข้าไปด้วย |
|---|---|
| Phase 2 | CONTEXT.md, ADRs |
| Phase 3 | CONTEXT.md, design doc ที่อนุมัติแล้ว |
| Phase 4 | CONTEXT.md, PLAN.md |
| Phase 5 | CONTEXT.md, PLAN.md, diff / ไฟล์ที่แก้ |
4. Feedback Loop
Validation กับ Debugging ไม่มีวัน restart ทั้ง process — หาต้นตอจริงแล้วกลับเฉพาะ phase ที่รับผิดชอบ
5. Continuous Improvement
ทุก defect ควรปรับปรุง: workflow, checklist, CONTEXT.md, planning templates, prompts, AI instructions เป้าหมายไม่ใช่แค่ fix bug วันนี้ แต่คือป้องกัน bug ชนิดเดียวกันไม่ให้เกิดซ้ำ