PLAYBOOK SDD ADD & CODEX | Chương 14

Roadmap 15 Tuần

Áp dụng cho đồ án Software Engineering theo mô hình Hybrid SDD + ADD

5

Sections

15

Tuần / Bước

5

Bảng dữ liệu

15

Trang tài liệu

Giới thiệu chương

Vì sao Chương 14 là bản đồ thực thi quan trọng nhất?

Chương 14 chuyển toàn bộ playbook từ mức nguyên tắc sang mức tuần-theo-tuần, dành riêng cho team 5 sinh viên làm đồ án SE. Mỗi tuần đều có mục tiêu, deliverable, công cụ và checklist để tránh làm việc cảm tính hoặc bị trễ dây chuyền.

Khác với các chương thiên về framework, chương này đóng vai trò operating plan: team biết rõ tuần nào phải chốt spec, tuần nào được tăng tốc agent coding, tuần nào dừng viết feature để kiểm thử bảo mật và tuần nào tập trung polish để demo hội đồng.

Nó kết nối trực tiếp chương trước về Hybrid workflow và chuẩn bị cho chương sau về case studies thực tế: một bên là phương pháp, bên kia là lịch trình triển khai để phương pháp trở thành kết quả thật.

INFO - Tinh thần chương

100% thực hành, không có lý thuyết thừa. Nếu team bám đúng roadmap, bạn giảm mạnh rework, giữ nhịp release đều, và đến tuần 15 có đủ code, docs, slides, video để nộp đồ án hoàn chỉnh.

Mục lục

Cấu trúc Chương 14

14.1

Giai đoạn 1: Foundation (Tuần 1-4)

14.2

Giai đoạn 2: Core Development (Tuần 5-12)

14.3

Giai đoạn 3: Polish & Delivery (Tuần 13-15)

14.4

Phân công 5 vai trò và rotation theo sprint

14.5

Ceremony calendar, template agenda, milestones

14.1

Section Header

Giai Đoạn 1: Foundation

Tuần 1-4 đặt nền móng cho 11 tuần còn lại: nếu foundation yếu, mọi sprint sau sẽ liên tục sửa sai. Chương yêu cầu team ưu tiên chuẩn hóa context, spec và kiến trúc trước khi lao vào code.

Tuần 1: Setup toolchain + CONSTITUTION.md + project memory
Tuần 2-3: SDD Sprint thuần túy, chưa viết code feature
Tuần 4: Architecture & Scaffolding, cầu nối SDD sang ADD

Table

Tổng Quan 15 Tuần (Phần 1/2)

Tuần	Giai đoạn	Trọng tâm	Phương pháp	Công cụ chính	Output
1	Foundation	Setup & Constitution	SDD	Claude Code, Cursor	CONSTITUTION.md
2	Foundation	Spec tính năng cốt lõi	SDD	Spec Kit / Kiro	Spec files
3	Foundation	Spec review & hoàn thiện	SDD	Spec Kit / Kiro	Approved Specs
4	Foundation	Architecture & Scaffolding	SDD + ADD	Claude Code, Cline	DB Schema + API
5	Core Dev	Sprint 1 - Auth & Users	ADD	Cursor Agent, Claude	Auth module
6	Core Dev	Sprint 1 tiếp tục + review	ADD	Cursor Agent, Claude	PR merged
7	Core Dev	Sprint 2 - Business Logic	ADD	Cursor Agent, Claude	Core features
8	Core Dev	Sprint 2 tiếp tục + review	ADD	Cursor Agent, Claude	PR merged

Table

Tổng Quan 15 Tuần (Phần 2/2)

Tuần	Giai đoạn	Trọng tâm	Phương pháp	Công cụ chính	Output
9	Core Dev	Sprint 3 - Nâng cao	ADD	Cursor Agent, Claude	Advanced features
10	Core Dev	Sprint 3 - Dashboard	ADD	Cursor Agent, Claude	Dashboard
11	Polish	Testing Sprint Unit/Integration	ADD + SDD	Claude Code, pytest	80% coverage
12	Polish	Security audit + bug fixing	ADD + SDD	Claude Code, Snyk	Security report
13	Polish	Docs & CI/CD deployment	ADD	Claude Code, GitHub	Staging deploy
14	Polish	User testing & performance	ADD	Claude Code	Optimized app
15	Delivery	Final report & presentation	Manual	AI writing assist	Đồ án hoàn chỉnh

14.1 - Tuần 1

Tuần 1: Setup & Constitution

Tuần 1 được gọi là tuần quan trọng nhất vì quyết định ở đây ảnh hưởng trực tiếp toàn bộ 14 tuần còn lại. Team phải ưu tiên đồng thuận hệ thống làm việc trước khi bắt đầu bất kỳ module nào.

Mục tiêu: thống nhất tech stack, công cụ AI, quy tắc phối hợp.
Deliverable 1: `CONSTITUTION.md` với coding standards, security rules, Git conventions.
Deliverable 2: `AGENTS.md` + `CLAUDE.md` đã setup và chạy thử thành công.
Deliverable 3: cấu trúc repo chuẩn `/.spec`, `/.agents`, `/src`, `/tests`.

Công cụ chính: Cursor hoặc Claude Code để verify luồng làm việc; GitHub cho repo setup.
Phân công: Spec Architect khởi tạo constitution, cả team review và ký-off.
Nguyên tắc: không vội, vì sửa nền tảng ở tuần sau luôn tốn hơn làm đúng ngay từ đầu.

14.1 - Tuần 1 Checklist

Checklist Gate Tuần 1

Tất cả thành viên đã cài và chạy thử Claude Code hoặc Cursor thành công.
`CONSTITUTION.md` đã merge vào `main` và có đồng thuận toàn team.
`AGENTS.md` định nghĩa rõ tech stack, coding style, forbidden patterns.
`CLAUDE.md` có project context, constraints, definition of done.
Repo có đủ `/.spec/constitution.md`, `/.agents/CLAUDE.md`, `/.agents/AGENTS.md`.
Git branching strategy đã chốt: `spec/*` và `agent/*` branches.

DANGER - Rule

Không pass sang tuần 2 nếu checklist này chưa hoàn thành, vì mọi sprint sau sẽ thiếu chuẩn chung và tạo ra debt hệ thống.

14.1 - Tuần 2-3

SDD Sprint: Specification Thuần Túy

Hai tuần này không viết code feature. Toàn bộ năng lượng dồn vào việc tạo spec đủ rõ để agent có thể implement mà không phải đoán ý. Chất lượng spec ở tuần 2-3 quyết định chất lượng phần code tuần 5-12.

Tuần 2: Viết Spec Draft

Phân tích requirements từ thầy/khách hàng.
Áp dụng EARS notation cho 3-5 tính năng cốt lõi.
Mỗi file có Business Context, User Stories, Acceptance Criteria.
Dùng GitHub Spec Kit hoặc template Markdown tự thiết kế.

Tuần 3: Review & Finalize

Cross-review chéo giữa các thành viên.
Clarification session với AI để tìm ambiguity.
Merge toàn bộ spec vào `/.spec/`.
Output: bộ spec approved làm source of truth.

14.1 - Quy tắc vàng

3 Câu Hỏi Vàng Trước Khi Approve Spec

"Agent có thể implement từ spec này mà không cần hỏi thêm gì không? Nếu không, spec thiếu chi tiết."

"Nếu spec được implement đúng 100%, khách hàng có hài lòng không? Nếu không, spec sai business logic."

"Spec này có mâu thuẫn spec khác không? Nếu có, phải resolve trước khi code."

14.1 - Tuần 4

Tuần 4: Architecture & Scaffolding

Tuần 4 là cầu nối SDD sang ADD: team dùng SDD để chốt kiến trúc và contract, sau đó dùng ADD để generate boilerplate theo đúng chuẩn vừa chốt.

Mục tiêu: hoàn chỉnh database schema + API skeleton.
SDD task: viết design spec cho models (ERD) và API contracts (OpenAPI/Swagger).
ADD task: agent generate folder structure, config files, base classes.

Deliverable: migrations + stub endpoints + tests pass (dù endpoint còn empty).
Công cụ: Claude Code, Cursor, dbdiagram.io.
Chi phí thay đổi API hậu kỳ rất cao, nên phải review contract thật kỹ.

WARN

Đổi API contracts sau tuần 4 thường kéo theo sửa hàng loạt client và integration tests, dễ tạo breaking chain.

14.2

Section Header

Giai Đoạn 2: Core Development

Tuần 5-12 là trái tim dự án: 3 feature sprints (mỗi sprint 2 tuần) và 1 testing-security sprint. Chương yêu cầu team giữ chu kỳ tuần cố định để giảm chaos khi làm với agent.

Chu kỳ chuẩn: Thứ 2 chốt spec, Thứ 4 Agent Jam, Thứ 6 Demo & Retro
Sprint 1: Auth & User Management
Sprint 2: Business Logic
Sprint 3: Advanced Features & Dashboard
Tuần 11-12: Testing Sprint + Security Audit

14.2 - Weekly Cycle

Chu Kỳ Tuần Chuẩn (Tuần 5-10)

THỨ 2 - Spec Sync Chốt spec cho tuần đó. Không có approved spec thì Agent Pilot không được code. THỨ 4 - Agent Jam Pair programming Agent Pilot + AI. Thành viên còn lại review code ngay. THỨ 6 - Demo & Retro Demo feature, chấm điểm technical debt, lên kế hoạch refactor tuần sau.

TIP

Giữ nhịp đều quan trọng hơn chạy thật nhanh một tuần rồi đứt nhịp tuần kế tiếp.

14.2 - Sprint 1

Sprint 1 (Tuần 5-6): Auth & User Management

Sprint đầu tiên chốt năng lực sống còn của hệ thống: xác thực, phân quyền và vòng đời token. Đây là sprint cần kỹ luật test cao vì mọi feature sau đều phụ thuộc auth layer.

Mục tiêu: Authentication system + User CRUD hoàn chỉnh có tests.
Scope: Register, Login, JWT, Refresh Token, RBAC (Admin/User).
Deliverable: auth module đạt >=80% coverage, Swagger cập nhật.
Refactoring cuối sprint: Human-led review code do agent sinh.
Công cụ: Cursor Agent Mode cho daily work, Claude Code cho logic phức tạp.

Rủi ro chính

JWT implementation sai có thể mở lỗ hổng bảo mật nghiêm trọng. Quality Gatekeeper phải review kỹ từng quyết định auth flow.

14.2 - Sprint 2

Sprint 2 (Tuần 7-8): Business Logic

Giai đoạn này đẩy các năng lực nghiệp vụ lõi của domain vào hệ thống. Mục tiêu không chỉ là code chạy được, mà phải đi hết end-to-end với integration tests để chắc hành vi nghiệp vụ đúng.

Implement 3-4 core features được định nghĩa trong spec, ưu tiên happy path trước.
Deliverable: core features hoạt động end-to-end và integration tests pass.
Giữa sprint phải kiểm tra code bloat từ sprint 1-2 và extract common patterns.
Nếu logic thực tế phức tạp hơn dự kiến: update spec trước rồi mới yêu cầu agent code lại.
Công cụ: Claude Code cho multi-file refactor, Cursor cho daily feature work.

14.2 - Sprint 3

Sprint 3 (Tuần 9-10): Advanced Features & Dashboard

Sprint này tạo phần "wow" cho demo: dashboard, reporting, visualizations, export, notification. Vì dễ chạy theo hứng thú, team cần bám spec discipline chặt hơn bình thường.

Scope: advanced search/filter, data visualization, export PDF/Excel, notification.
Deliverable: dashboard chạy với dữ liệu thật và có output báo cáo rõ ràng.
Cuối sprint: full codebase review trước khi vào testing sprint.

Đây là sprint dễ trượt vào vibe coding.
Muốn thêm gì mới phải qua spec gate, không làm trực tiếp theo cảm hứng.
Nếu dashboard phức tạp, có thể dùng multi-agent chia UI Agent và Logic Agent.

14.2 - Tuần 11-12

Testing & Security Sprint

Hai tuần này không build feature mới, chỉ tập trung chất lượng. Đây là nơi nhiều team bỏ qua rồi trả giá ở buổi demo khi bug vỡ ra hàng loạt hoặc bị hỏi security mà không trả lời được.

Tuần 11 - Testing Sprint

Agent generate unit tests cho business logic.
Agent generate integration tests cho API endpoints.
Mục tiêu coverage >= 80% và Test Engine fill gaps còn sót.

Tuần 12 - Security Audit

Claude Code audit toàn bộ codebase.
Fix toàn bộ vulnerabilities mức Critical/High.
Dependency audit với `npm audit` hoặc `pip check`.
Output: Security report + clean build.

14.3

Section Header

Giai Đoạn 3: Polish & Delivery

Tuần 13-15 tập trung biến project thành sản phẩm có thể bàn giao: có môi trường chạy thật, tài liệu thật, hiệu năng ổn định và trình bày rõ ràng với hội đồng.

Tuần 13: Documentation & Deployment
Tuần 14: User Testing & Performance
Tuần 15: Final Delivery & Presentation

14.3 - Tuần 13

Documentation & Deployment

Mục tiêu tuần 13 là hệ thống chạy được trên staging/production với quy trình CI/CD ổn định. Tài liệu không còn là phần phụ mà trở thành tiêu chí đánh giá mức độ chuyên nghiệp của đội dự án.

Docs task: AI hỗ trợ viết technical docs (architecture overview, API reference, deployment guide).
Manual task: AI hỗ trợ viết user manual có screenshot và hướng dẫn từng bước.
Deploy task: thiết lập GitHub Actions/GitLab CI, deploy staging, chạy smoke test.
Deliverable: staging URL hoạt động + technical docs draft + README hoàn chỉnh.

14.3 - Tuần 14

User Testing & Performance

Tuần 14 biến phản hồi người dùng thành bản polished release. Team cần lấy feedback thật từ 3-5 người ngoài nhóm và ưu tiên sửa các vấn đề tác động trực tiếp đến trải nghiệm demo.

User testing: thu thập feedback, ưu tiên fix theo mức ảnh hưởng.
ADD task: dùng agent sửa nhanh UI bugs và tinh chỉnh UX flows.
Performance: phân tích slow queries bằng EXPLAIN ANALYZE.

Thêm caching cho hot paths để giảm độ trễ.
Deliverable: production deploy + performance report before/after + bug fix log.
Rule cứng: không add feature mới trong tuần này.

WARN

Tuần 14 chỉ fix và polish những gì đã có. Thêm feature mới lúc này thường phá ổn định cuối kỳ.

14.3 - Tuần 15

Final Delivery

Tuần cuối cùng chốt cả sản phẩm và năng lực thuyết trình. Không chỉ nộp code, team phải chứng minh được tư duy kỹ thuật và quá trình ra quyết định xuyên suốt dự án.

Report task: hoàn thiện báo cáo, dùng AI biên tập consistency và format.
Presentation: chuẩn bị 10-15 slides theo flow Problem -> Solution -> Demo -> Lessons Learned.
Demo prep: rehearsal ít nhất 2 lần, chuẩn bị Q&A về technical decisions và AI workflow.
Final deliverables: source code, technical report, user manual, presentation slides, demo video backup.

PRO TIP

Câu hỏi thường gặp nhất từ hội đồng là "Tại sao chọn giải pháp này?". Bộ spec chính là bằng chứng quyết định kỹ thuật tốt nhất của team.

14.4

Section Header

Phân Công Vai Trò - Nhóm 5 Người

Section này định nghĩa cơ chế phân vai và luân chuyển vai trò theo sprint để mọi thành viên nhìn được full lifecycle của Hybrid workflow, thay vì chỉ giỏi một lát cắt hẹp.

Mô tả chi tiết 5 vai trò và năng lực cần có
Bảng rotation theo từng sprint
Giải thích vì sao rotation là cơ chế học tập bắt buộc

Table

Mô Tả Chi Tiết 5 Vai Trò

Vai trò	Trách nhiệm chính	Kỹ năng cần có
Spec Architect	Đảm bảo spec đúng EARS, không mâu thuẫn; review spec trước khi Agent Pilot code.	Viết tốt, tư duy hệ thống
Agent Pilot	Điều khiển Cursor/Claude Code thực thi; chịu trách nhiệm prompt engineering và context setup.	Prompt engineering, kiên nhẫn
Quality Gatekeeper	Review code AI sinh ra theo constitution; chặn PR không qua checklist review.	Code review, bảo mật
Test Engine	Điều phối agent viết test, kiểm soát coverage >=80% trước merge.	Testing, CI/CD
Ops & Integration	Quản lý branch, merge code, deployment; duy trì CLAUDE.md và AGENTS.md cập nhật.	DevOps, Git workflow

Table

Lịch Rotation Theo Sprint

Sprint	Spec Architect	Agent Pilot	Quality Gatekeeper	Test Engine	Ops & Integration
Sprint 1 (Tuần 5-6)	Thành viên A	Thành viên B	Thành viên C	Thành viên D	Thành viên E
Sprint 2 (Tuần 7-8)	Thành viên E	Thành viên A	Thành viên B	Thành viên C	Thành viên D
Sprint 3 (Tuần 9-10)	Thành viên D	Thành viên E	Thành viên A	Thành viên B	Thành viên C
Testing Sprint (11-12)	Thành viên C	Thành viên D	Thành viên E	Thành viên A	Thành viên B

Quote Spotlight

"Rotation hơi bất tiện trong ngắn hạn, nhưng tạo ra kỹ sư full-picture tốt hơn nhiều về dài hạn."

14.5

Section Header

Ceremony Calendar

Ba ceremony cố định mỗi tuần tạo nhịp vận hành cho team. Khi nhịp ổn định, mọi người giảm chờ đợi, giảm bất ngờ và phối hợp mượt hơn trong môi trường làm việc cùng agent.

Thứ 2: Spec Sync (45-60 phút)
Thứ 4: Agent Jam (2-3 giờ)
Thứ 6: Demo & Retro (60-90 phút)

14.5 - Thứ 2

Spec Sync (45-60 phút)

Toàn team họp để chốt spec cho tuần đó.
Spec Architect trình bày draft, cả team review và đặt câu hỏi.
Chỉ khi spec đồng thuận, Agent Pilot mới được bắt đầu code.
Output: spec merge vào `/.spec/` với tag `approved`.
Rule: Không có approved spec thì không code, không có ngoại lệ.

14.5 - Thứ 4

Agent Jam (2-3 giờ)

Agent Pilot chia sẻ màn hình để cả team theo dõi agent làm việc realtime.
Mỗi task agent nhận đều cần review plan trước khi approve execution.
Quality Gatekeeper review code ngay khi agent xong từng module.
Test Engine verify tests pass tại chỗ.
Output: feature branch sẵn sàng mở PR.
Tip: ghi hình session làm tài liệu và hỗ trợ thành viên vắng mặt.

14.5 - Thứ 6

Demo & Retro (60-90 phút)

Demo 15 phút: Agent Pilot trình diễn tính năng build trong tuần.
Technical Debt Review: Quality Gatekeeper báo cáo vấn đề phát hiện.
Debt scoring: phân mức Critical / High / Medium và lên kế hoạch xử lý.
Retrospective nhanh: Keep / Stop / Try cho tuần kế tiếp.
Update `CLAUDE.md` với lessons learned và constraints mới.
Output: `TECH_DEBT.md` cập nhật + retro notes + plan tuần sau.

Table

Template Agenda Demo & Retro

Thời gian	Nội dung	Người dẫn	Output
0-15 phút	Demo feature tuần này (live trên staging)	Agent Pilot	Feedback notes
15-30 phút	Technical Debt Review - vấn đề phát hiện	Quality Gatekeeper	Debt list updated
30-45 phút	Retrospective: Keep / Stop / Try	Spec Architect (host)	Action items
45-60 phút	Planning tuần sau: spec assignment, agent tasks	Toàn team	Next week plan
60-75 phút	(Nếu cần) update CLAUDE.md và AGENTS.md	Ops & Integration	Updated context

Table

Checklist Milestone (Phần 1/2)

Milestone	Tuần	Tiêu chí Pass	Rủi ro nếu bỏ qua
Constitution signed	1	Toàn team đồng thuận, đã merge vào main	Team làm theo nhiều convention khác nhau
Specs approved	3	Tất cả core specs qua peer review	Agent code theo assumption sai, rework tốn kém
Architecture lock	4	DB schema + API contracts finalized	Breaking changes đau đớn ở giai đoạn sau
Auth working	6	Auth module có >=80% test coverage	Security holes ở production
Core features done	10	Core features pass acceptance tests	Không đủ thời gian polish và test

Table

Checklist Milestone (Phần 2/2)

Milestone	Tuần	Tiêu chí Pass	Rủi ro nếu bỏ qua
80% coverage	11	Test Engine verify coverage report	Bugs phát hiện khi demo trước hội đồng
Security clean	12	Không có Critical/High vulnerabilities	Bị hỏi security và lúng túng phản biện
Staging deployed	13	Staging URL hoạt động, CI/CD pass	Demo chỉ chạy localhost, thiếu chuyên nghiệp
Final delivery	15	Code + Docs + Slides hoàn chỉnh	Mất điểm vì thiếu documentation

Quote Spotlight

"Đừng bao giờ tin AI khi nó nói 'I have finished the task'. Hãy tin khi Unit Test xanh và Spec Checklist hoàn thành."

Summary

Summary + Next Chapter

Section	Key Technique	Điểm cốt lõi
14.1 Foundation	Spec-first + architecture lock	Không có nền tảng đúng thì các sprint sau chỉ chữa cháy
14.2 Core Development	Chu kỳ tuần cố định + sprint discipline	Giữ nhịp Spec Sync -> Agent Jam -> Demo & Retro để giảm chaos
14.3 Polish & Delivery	Docs, deploy, user test, performance	Tập trung độ hoàn thiện thay vì thêm feature phút chót
14.4 Role Rotation	Luân chuyển vai trò theo sprint	Đào tạo kỹ sư full-picture thay vì chuyên một mắt xích
14.5 Ceremony & Milestone	Ceremony cố định + gate theo tuần	Nhịp đều và điểm kiểm tra rõ giúp team đi xa mà không vỡ nhịp

Next Chapter

Chương 15 - Case Studies Thực Tế

Sau roadmap tuần-theo-tuần, chương tiếp theo đi vào các ca triển khai thực tế để thấy cách hybrid playbook vận hành trong điều kiện thật, cùng các bài học thành công và thất bại.

Takeaways

5 Key Takeaways

1) Foundation quyết định vận tốc toàn dự án

Tuần 1-4 là nơi khóa context, spec và kiến trúc. Làm tốt giai đoạn này giúp tuần 5-15 chạy mượt; làm ẩu sẽ trả giá bằng rework liên tục.

2) Spec là điều kiện để agent làm đúng

Không có approved spec thì không code. Spec rõ giúp agent ít đoán, ít loop lỗi và tạo output sát business intent.

3) Sprint discipline quan trọng hơn cảm hứng

Chu kỳ Spec Sync - Agent Jam - Demo & Retro giữ team ở trạng thái kiểm soát, thay vì chạy theo ngẫu hứng từng thành viên.

4) Testing và security không phải việc "làm sau"

Tuần 11-12 dành riêng cho chất lượng là bắt buộc để tránh rủi ro demo và để trả lời được các câu hỏi phản biện kỹ thuật.

5) Rotation biến nhóm sinh viên thành team kỹ sư

Luân chuyển vai trò giúp mọi thành viên hiểu trọn vòng đời product engineering và phối hợp tốt hơn khi đi làm thực tế.

Author Closing

Chương 14

Roadmap 15 Tuần - Hybrid PLAYBOOK SDD ADD & CODEX

LinhNDM

Nguyễn Đình Mạnh Linh