ลงมือจริง: ทำ feature หนึ่งตัวครบวงจร Superpowers

หกบทที่ผ่านมาเราเรียนแต่ละ skill แยกชิ้น — brainstorming, writing-plans, subagent-driven-development, requesting-code-review, writing-skills เอง ฯลฯ บทนี้เป็นบทปิดแทร็ก เราจะ เดินครบวงจรจริงตั้งแต่ต้นจนจบ กับโจทย์เดียว เพื่อให้เห็นว่า skill พวกนี้ "ต่อกัน" เป็น pipeline เดียวได้ยังไง ไม่ใช่เครื่องมือแยกกระเป๋าที่ต้องเลือกใช้เอง — มันคือ ลำดับที่ agent เดินเองโดยอัตโนมัติ ถ้าคุณตั้ง using-superpowers เป็น bootstrap ไว้ตั้งแต่ต้น session

โจทย์จริงที่จะใช้เดินทั้งบท

เพื่อไม่ให้ลอยไปกับทฤษฎี เราจะสมมติโจทย์เดียวที่ใกล้เคียงงานจริงของสาย NestJS/Postgres แล้วเดินทุกเฟสกับโจทย์นี้:

"เพิ่ม feature การแจ้งเตือน (notification) ให้ระบบ: สร้างแจ้งเตือนใหม่ให้ user คนหนึ่ง และดึงรายการแจ้งเตือนของ user แบบแบ่งหน้า (pagination) พร้อมสถานะ unread/read"

หลัง endpoint ก็จะมี POST /notifications กับ GET /notifications/:userId บน NestJS + TypeORM/Postgres — เล็กพอจะเดินจบใน 1 บท แต่จริงพอจะมี table ใหม่, service, controller, test และ pull request จริงรอ merge

แผนที่ 5 เฟสที่ Superpowers บังคับให้เดิน

using-superpowers บอกไว้ว่า "ถ้ามี skill ที่เกี่ยวข้อง ต้องเรียกใช้ก่อนทำอะไรทั้งนั้น รวมถึงก่อนถามคำถามชี้แจง (clarifying questions)" — และสำหรับงานสร้าง feature ลำดับที่ต้องเดินคือนี้:

เฟส 1 — Brainstorm: ห้ามพิมพ์โค้ดจนกว่าจะมี design ที่อนุมัติแล้ว

brainstorming skill มี hard gate ชัดเจน: ห้ามเรียก skill implementation, ห้ามเขียนโค้ด, ห้าม scaffold โปรเจกต์ จนกว่าจะ "present design แล้ว user approve" — ใช้กับทุกโปรเจกต์ ไม่ว่าจะดู "ง่าย" แค่ไหน (มันเรียก anti-pattern นี้ตรง ๆ ว่า "This Is Too Simple To Need A Design")

คุณพิมพ์ในแชท:

// สิ่งที่คุณพิมพ์
เพิ่ม feature แจ้งเตือนให้ user หน่อย สร้างได้ ดึงรายการได้ พร้อมสถานะ read/unread

agent ที่มี bootstrap ถูกต้องจะตอบทันทีว่า:

// สิ่งที่ agent ตอบก่อนถามอะไรทั้งนั้น
Using brainstorming skill to design the notification feature.

จากนั้น agent เดินตาม checklist ของ skill นี้ทีละข้อ:

1. สำรวจ context โปรเจกต์ก่อน — เปิดดูว่ามี module/entity อะไรอยู่แล้วใน NestJS ของคุณ
2. ถามทีละคำถาม เช่น "แจ้งเตือน 1 อันผูกกับ user เดียวใช่ไหม หรือ broadcast ได้หลาย user?" — ถามทีละข้อ ไม่ยิงรวด เน้น multiple choice ถ้าเป็นไปได้
3. เสนอ 2-3 แนวทาง พร้อม trade-off เช่น (ก) insert ตรง ๆ + read ปกติ (ข) แยก read model แบบ CQRS (ค) ใช้ message queue ยิง event — แล้วบอกว่าแนะนำอันไหนเพราะอะไร (สำหรับโจทย์นี้คือ (ก) ง่ายสุด พอกับ scope)
4. present design เป็นส่วน ๆ — สถาปัตยกรรม, entity, error handling, testing — ถามหลังทุกส่วนว่า "โอเคไหม" ก่อนไปส่วนถัดไป
5. เขียน spec ลงไฟล์ ที่ docs/superpowers/specs/2026-07-11-notifications-design.md แล้ว commit
6. self-review สเปกตัวเอง — เช็คว่ามี "TBD" หลุดไหม มีข้อความขัดกันเองไหม scope ใหญ่เกินไปจนต้องแตกเป็นหลาย spec ไหม
7. ให้คุณ (user) รีวิว spec ที่เขียนไว้ก่อนไปต่อ — agent จะพูดประมาณ "Spec written and committed to `<...>`. Please review it and let me know if you want to make any changes"

เฟส 2 — Writing Plans: แปลง spec เป็น task ที่ทำได้จริงทีละก้อน

หลัง spec ผ่านการอนุมัติ ขั้นตอนต่อไปคือ เท่านั้น — invoke writing-plans skill (ห้ามข้ามไปเรียก implementation skill ตรง ๆ) skill นี้เขียนแผนโดยสมมติว่าคนอ่านคือวิศวกรที่ "ไม่มี context อะไรเกี่ยวกับโค้ดเราเลย และ taste ยังน่าสงสัย" — ต้องบอกทุกอย่างละเอียดจริง

ก่อนตัด task ต้องวางไฟล์ก่อน (File Structure) — งานนี้น่าจะมี NotificationEntity, NotificationsService, NotificationsController, test คู่กันของแต่ละไฟล์ แต่ละไฟล์ต้องมีความรับผิดชอบเดียวชัดเจน (single responsibility)

แต่ละ task ต้องเล็กระดับ "step ละ 2-5 นาที" และจบด้วย deliverable ที่ทดสอบได้เอง ตัวอย่างท่อนหนึ่งของแผน:

### Task 2: NotificationsService.create()

Files:
- Create: src/notifications/notifications.service.ts
- Test: src/notifications/notifications.service.spec.ts

Interfaces:
- Produces: create(dto: CreateNotificationDto): Promise<Notification>

- [ ] Step 1: เขียน failing test

it('creates a notification with status "unread"', async () => {
  const result = await service.create({
    userId: 'u_123',
    message: 'ยินดีต้อนรับ!',
  });
  expect(result.status).toBe('unread');
});

- [ ] Step 2: รันแล้วต้อง FAIL ด้วย "Cannot read property 'create' of undefined"
- [ ] Step 3: เขียน implementation ให้น้อยที่สุดเพื่อผ่าน
- [ ] Step 4: รันแล้วต้อง PASS
- [ ] Step 5: commit

สังเกตว่าแผนไม่มีคำว่า "add appropriate error handling" หรือ "similar to Task 1" ลอย ๆ เลย — skill นี้ถือว่านั่นคือ plan failure ทุก step ต้องมีโค้ดจริงที่ copy ไปรันได้ทันที

จบแผนแล้ว agent จะถามคุณว่าจะ execute แบบไหน: Subagent-Driven (แนะนำ — dispatch subagent ใหม่ต่อ task, review ระหว่างทาง) หรือ Inline Execution (รันในเซสชันเดียว พร้อม checkpoint) — บทนี้เราเลือกทางแรกเพราะเป็นแนวทางที่ superpowers แนะนำ

เฟส 3 — Execute: subagent สดใหม่ต่อ task พร้อม TDD ในตัว

subagent-driven-development คือหัวใจของ "ทำงานยาวได้โดยไม่หลุด" หลักการคือ subagent สดใหม่ต่อ task + task review (spec + quality) + broad review ท้ายสุด

ในแต่ละ task agent แม่ (controller) จะ:

1. รัน task-brief เพื่อตัด task นั้นออกมาเป็นไฟล์เดี่ยว (ไม่ให้ subagent อ่านทั้งแผน)
2. dispatch implementer subagent พร้อม brief + context ที่จำเป็น เช่น interface ของ task ก่อนหน้า — ถ้า subagent ถามกลับ ("ควร validate userId เป็น UUID ไหม?") ต้องตอบให้ครบก่อนปล่อยทำงานต่อ
3. implementer subagent เดิน TDD เอง: RED → GREEN → self-review → commit → รายงานสถานะกลับมาหนึ่งใน 4 แบบ (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED)
4. controller สร้าง diff package แล้ว dispatch task reviewer subagent อีกตัว (คนละ context กับ implementer) ให้ตรวจ 2 เรื่อง: ตรง spec ไหม + คุณภาพโค้ดโอเคไหม
5. ถ้าเจอปัญหา Critical/Important → dispatch fix subagent → review ใหม่ จนผ่านถึงไปต่อ task ถัดไป

ตัวอย่าง RED แล้ว GREEN ของ controller ฝั่ง endpoint GET /notifications/:userId:

// RED — test ที่เขียนก่อน (ต้อง fail)
it('returns paginated notifications for a user', async () => {
  const res = await request(app.getHttpServer())
    .get('/notifications/u_123?page=1&limit=10');

  expect(res.status).toBe(200);
  expect(res.body.items).toHaveLength(10);
});

// GREEN — implementation ขั้นต่ำที่ทำให้ผ่าน
async findByUser(userId: string, page = 1, limit = 20) {
  const [items, total] = await this.repo.findAndCount({
    where: { userId },
    order: { createdAt: 'DESC' },
    skip: (page - 1) * limit,
    take: limit,
  });
  return { items, total, page, limit };
}

ระหว่างทาง controller ยังเลือก model ให้เหมาะกับงาน ด้วย: task เชิงกลไกล้วน ๆ (แค่ 1-2 ไฟล์, สเปกครบในแผนแล้ว) ใช้โมเดลถูก/เร็ว, task ที่ต้องประสานหลายไฟล์ใช้โมเดลมาตรฐาน, ส่วน final whole-branch review ใช้โมเดลที่ฉลาดที่สุดที่มี — เพราะเป็นจุดตัดสินใจสำคัญสุดของทั้งกิ่ง

และเพราะ conversation memory หายได้เมื่อ context ถูก compact controller จะบันทึกความคืบหน้าไว้ใน ledger file (.superpowers/sdd/progress.md) ทุกครั้งที่ task ผ่าน review — ถ้า session หลุดกลางทาง กลับมาอ่าน ledger + git log แล้วทำต่อจาก task ที่ยังไม่เสร็จ ไม่ใช่เริ่มใหม่หรือทำซ้ำ

เฟส 4 — Code Review: ตรวจทั้งกิ่งก่อนถึงมือ main

requesting-code-review ถูกเรียกทั้งระหว่างทาง (หลังทุก task ใน subagent-driven-development) และเป็นครั้งใหญ่ท้ายสุดก่อน merge หลักการคือ dispatch reviewer subagent พร้อม context เฉพาะที่จำเป็น — ไม่ใช่ history ทั้ง session ของคุณ — reviewer เห็นแค่ diff กับสิ่งที่ควรเป็น

# วิธี dispatch (แนวคิด — ไม่ใช่ script ต้องรันเป๊ะ)
BASE_SHA=$(git merge-base main HEAD)
HEAD_SHA=$(git rev-parse HEAD)

# dispatch general-purpose subagent พร้อม template code-reviewer.md
# DESCRIPTION: เพิ่ม create + list notifications พร้อม pagination
# PLAN_OR_REQUIREMENTS: docs/superpowers/plans/2026-07-11-notifications.md

reviewer ตอบกลับเป็น 3 ระดับ: Critical (ต้องแก้ทันที) / Important (ต้องแก้ก่อนไปต่อ) / Minor (บันทึกไว้ทีหลัง) — กติกาคือห้ามข้าม Critical และห้ามเดินต่อทั้งที่ Important ยังไม่แก้ ถ้าคุณคิดว่า reviewer ผิด ให้ push back ด้วยเหตุผลทางเทคนิค ไม่ใช่เถียงเฉย ๆ

เฟส 5 — Finish: ปิด branch แล้วส่งต่อ

หลัง final whole-branch review ผ่าน ขั้นสุดท้ายตาม flow ของ subagent-driven-development คือเรียก finishing-a-development-branch — เป็นจุดจบของวงจร ที่ทำให้งานที่ผ่าน TDD + task review + broad review มาตลอดทาง พร้อม merge เข้า main จริง ไม่ใช่แค่ "โค้ดรันผ่านในเครื่องเรา"

ทำไมวงจรนี้ถึงทำให้ agent ทำงานยาวได้โดยไม่หลุด

เฟส	ประตูอนุมัติ	artifact ที่เหลือไว้
Brainstorm	user approve ทีละ section + review สเปกที่เขียนจริง	spec ไฟล์ commit แล้ว
Plan	self-review ตรวจ placeholder/type ก่อนส่งมือ	plan ไฟล์ระดับ step ละ 2-5 นาที
Execute	task reviewer ตัดสิน spec+quality ทุก task	commit + ledger progress.md
Review	Critical/Important ต้องแก้ก่อนไปต่อ	diff package + คำตัดสิน
Finish	ผ่านทุกประตูก่อนหน้าแล้วเท่านั้น	branch ที่ merge ได้จริง

สังเกตแพทเทิร์นเดียวกันซ้ำทุกเฟส: งานถูกตัดเป็นก้อนเล็กที่ตรวจสอบได้อิสระ (spec section, task, diff) และทุกก้อนต้องผ่านประตูก่อนไปก้อนถัดไป — subagent แต่ละตัว ได้ context สดใหม่เฉพาะที่จำเป็น (ไม่ใช่ history สะสมทั้ง session) ทำให้ไม่ "หลุด" แม้งานจะยาวข้าม หลาย task หลายชั่วโมง เพราะไม่มี agent ตัวไหนต้องแบกความจำทั้งหมดไว้คนเดียว — ledger กับ git log ต่างหากที่เป็นความจำจริงของระบบ