SDLC Agile × AI Agent — Naming & File Mapping

เอกสารนี้อธิบายการ map โครงสร้าง SDLC แบบ Agile ที่ Human ออกแบบ เข้ากับโครงสร้างไฟล์ที่ AI Agent เข้าใจและทำงานได้ง่าย

SDLC Hierarchy (Agile)

System (Project)
└── Module (Epic)
    └── Program (Feature)
        └── Function (PBI / User Story)
            └── Task (Dev Task — FE / API / API-UT)
                └── Subtask (Implementation Steps — AI generated)

Mapping: Agile Term → ไฟล์

SDLC Term	Agile Label	ตัวอย่าง	ไฟล์/โครงสร้าง
System	Project	bbd-content-web	workspace folder
Module	Epic	Content System, Member System	folder grouping เท่านั้น ไม่มี PLAN.md
Program	Feature ⭐	articles-section, videos-section	1 PLAN.md + 1 Kanban card
Function	Story	”Migrate Content”, “SEO Setup”	`## Story N.X` ใน PLAN.md + CHECKLIST.md
Task	Task	`TASK: [FE] ArticleCard`, `TASK: [API] POST /articles`	`- [ ]` checkbox ใน CHECKLIST.md (Human เขียน)
—	Subtask	”สร้าง ArticleCard.astro”, “รับ props: title”	`- [ ]` indented checkbox (AI generate)

⭐ Feature (Program) คือ unit ที่เล็กที่สุดที่ deliver business value ให้ User ได้ครบในตัวเอง
— User เห็นและใช้งาน Feature ได้จริงโดยไม่รอ Feature อื่น
— Kanban track ในระดับนี้

นิยามแต่ละ Level

Epic (Module)

กลุ่มของ Feature ที่เกี่ยวข้องกัน เช่น “Content System” หรือ “Member System”
ไม่มี PLAN.md — เป็นแค่ folder grouping เพื่อจัด organize
ตัวอย่าง: content-system/ ประกอบด้วย articles, videos, courses

Feature (Program) ⭐

unit ที่เล็กที่สุดที่ deliver business value ให้ User ได้ครบในตัวเอง
แม้ว่าจะ deploy ได้ในระดับ Story แต่ Story อาจ deliver value ไม่ครบ
(เช่น edit-article deploy ได้ แต่ user ใช้งานไม่ได้จริงถ้าไม่มี create-article)
Agent อ่าน PLAN.md เดียวแล้วทำงานได้ครบ ไม่ต้อง cross-reference Feature อื่น = 1 PLAN.md + 1 CHECKLIST.md + 1 Kanban card
ตัวอย่าง: articles-section — user อ่านบทความได้ทั้งหมดโดยไม่ต้องมี videos

Story (PBI / User Story)

กลุ่มงานภายใน Feature ที่ deliver ความสามารถชัดเจน 1 อย่าง
Deploy ได้ แต่อาจ deliver value ไม่ครบ ถ้าขาด Story อื่นใน Feature เดียวกัน
Agent ทำจบได้ใน 1 context โดยไม่ต้องถามเพิ่ม มี input/output ชัดเจน
ตัวอย่าง: Story 1.3: Pages — สร้าง pages ทั้งหมดของ articles section

Task

งานระดับ Developer ที่จับต้องได้ — Human เขียน label ใน format TASK: [TYPE] Title เท่านั้น
Test scenario ไม่ได้เขียนไว้ใน PLAN.md — PLAN.md แค่ link ไปหา test-spec file ใน tests/ เท่านั้น
Task Type กำหนดว่าต้องมี test-spec file แบบไหน — AI Agent generate test-spec file ให้ Human review
Task tick [x] ได้ก็ต่อเมื่อ subtask ครบ และ test ของ Task type นั้นผ่าน

Task Types และ Test ที่ประกบ:

Task Type	ความหมาย	Test ที่ประกบ	Test file ใน tests/
`TASK: [API]`	Backend endpoint / service / schema	Unit Test ทุก Layer (service, controller, repository)	`task-N.N-api-[name].md`
`TASK: [FE-BL]`	Frontend Business Logic (store, composable, hook)	Unit Test Frontend BL	`task-N.N-fe-bl-[name].md`
`TASK: [FE]`	UI Component หรือ Page	Manual Test — render + layout ใน browser	`task-N.N-fe-[name].md`
`TASK: [FE-IT]`	Integration Test FE ↔ API	E2E flow ทำงานครบ end-to-end	`task-N.N-fe-it-[name].md`
`TASK: [Config]`	Config / Env / Schema definition	`pnpm astro check` + ตรวจ env vars	`task-N.N-config-[name].md`
`TASK: [CHORE]`	Non-code maintenance task — ย้ายไฟล์, ลบ legacy, rename, migrate content	ตรวจ path ถูกต้อง + `pnpm astro check`	`task-N.N-chore-[name].md`

[CHORE] มาจาก git conventional commits (chore:) — AI Agent อ่านแล้วรู้ทันทีว่าเป็น non-code maintenance task ไม่ใช่ code task ทุก Story ต้องมี Task เสมอ รวมถึงงานที่ไม่ใช่ code — เพื่อให้ Template สม่ำเสมอและ CHECKLIST.md ติดตามได้ครบ

Subtask

Implementation steps ภายใน Task — AI Agent generate เอง จาก Task label + context ใน PLAN.md
Human ไม่ต้องเขียน
ใน CHECKLIST.md = indented checkbox - [ ] ใต้ Task
บันทึกใน CHECKLIST.md เสมอ — ใช้เป็น Handoff checkpoint เมื่อ session เต็มกลางคัน Task
ไม่มี test ระดับ Subtask — ใช้ Task-level test ครอบคลุม

โครงสร้างไฟล์ต่อ Feature

plan/
├── KANBAN.md                     ← board หลัก: track status ระดับ Feature
├── doing/
│   └── articles-section/         ← Feature ที่กำลังทำ
│       ├── PLAN.md               ← Stories + implementation detail
│       ├── CHECKLIST.md          ← Tasks ทั้งหมด (checkbox)
│       ├── HANDOFF.md            ← context สำหรับ session ต่อไป
│       └── tests/
│           ├── feature-test-scenarios.md        ← E2E / Acceptance tests ระดับ Feature (ก่อน merge)
│           ├── story-1.1-[story-name].md         ← Story test (ก่อน commit)
│           ├── story-1.2-[story-name].md
│           ├── task-1.1-api-[name].md            ← Task test (AI generate, Human review)
│           ├── task-1.1-fe-[name].md
│           ├── task-1.1-fe-it-[name].md
│           └── task-N.N-[type]-[name].md
├── todos/
│   ├── videos-section/
│   │   └── PLAN.md               ← แค่ PLAN พอ ยังไม่ต้อง CHECKLIST
│   ├── courses-section/
│   │   └── PLAN.md
│   └── auth-payment/
│       └── PLAN.md
├── pending/                      ← Blocked: รอ dependency จาก Feature อื่น
└── done/                         ← Feature ที่ deploy แล้ว

KANBAN.md — ตัวอย่าง

# BBD Content Web — Kanban

## 🔄 Doing
- [articles-section](doing/articles-section/PLAN.md)

## 📋 Todos
- [videos-section](todos/videos-section/PLAN.md)
- [courses-section](todos/courses-section/PLAN.md)

## ⏸ Pending (Blocked)
- [auth-payment](pending/auth-payment/PLAN.md) — รอ articles + videos + courses done

## ✅ Done
(ว่าง)

Kanban แต่ละ card = 1 Feature (Program) ที่ deliver business value ให้ User ได้ครบในตัวเอง

PLAN.md — โครงสร้างภายใน

# Feature Name — Implementation Plan

> Last updated: YYYY-MM-DD

## Goal
deploy แล้ว user ทำอะไรได้บ้าง — 1-2 บรรทัด

## Scope (ทำ)
> ระบุ Capability ในแง่ที่ User เห็นได้ + Story ที่รับผิดชอบ
> ทุก Scope item ต้องมี Story อ้างอิง — ถ้าไม่มี = งานหาย

| Capability | Story |
|---|---|
| [สิ่งที่ User ได้ — ภาษา business ไม่ใช่ technical] | Story 1.X |
| [Pages / Routes ที่ deliver] | Story 1.X |
| [Functionality หลักที่ User เห็น] | Story 1.X |

## Out of Scope (ไม่ทำ)
> เขียนเฉพาะสิ่งที่ "อาจเข้าใจผิดว่าต้องทำใน Feature นี้"
> - defer → ระบุว่าไปอยู่ Feature ไหน
> - ตัดออก → อธิบายสั้นๆ ว่าทำไม

- [สิ่งที่ defer ไป Feature อื่น] → ทำใน `feature-name`
- [สิ่งที่ตัดออกเพื่อ simplify] (เหตุผลสั้นๆ)
- [สิ่งที่ดูเกี่ยวแต่เป็น concern ของ Feature อื่น]

## Current State
สถานะไฟล์และ code ปัจจุบัน

สิ่งที่ Agent ต้องการจาก Human

Human ทำ	Agent ทำ
แบ่ง Feature ตาม Business Requirement	อ่าน PLAN.md และทำตาม Story
เขียน Goal + Scope + Out of Scope	ทำงานให้ตรง scope ไม่บาน
เขียน Task label ใน format `TASK: [TYPE] Title`	Generate subtask steps จาก Task label + PLAN.md context
เขียน implementation detail ใน PLAN.md ต่อ Task	Generate task test-spec file (`tests/task-N.N-[type]-[name].md`)
Review task test-spec ที่ AI generate + เพิ่ม edge case	Mark `[x]` Subtask ทีละขั้น + รัน test ตาม Task Type
ระบุ dependency ระหว่าง Feature	วาง Feature ใน `pending/` ถ้า blocked
อัป KANBAN.md เมื่อ Feature เสร็จ	รัน Story Test ก่อน commit, Feature Test ก่อน merge

Test Strategy

TASK: [API] เสร็จ    → Unit Test ทุก Layer ผ่าน        → tick [x]
TASK: [FE-BL] เสร็จ  → Unit Test Frontend BL ผ่าน      → tick [x]
TASK: [FE] เสร็จ     → Manual Test render/layout ผ่าน  → tick [x]
TASK: [Config] เสร็จ → pnpm astro check ผ่าน           → tick [x]
                               ↓
    TASK: [FE-IT] — Integration Test FE ↔ API ผ่าน     → tick [x]