Quy trình Phát triển Phần mềm

1. Tổng quan: Specification-Driven Agentic Workflow

Mô hình phát triển hiện đại kết hợp "Agentic Workflow" và "Specification-Driven" (hướng đặc tả) giúp tối ưu hóa sự cộng tác giữa Con người và AI. Nguyên lý cốt lõi là chuyển dịch trọng tâm từ "viết code" sang "viết đặc tả" (Spec).

Kết quả đầu ra mong muốn (Expected Output):

• Clean Source Code: Mã nguồn sạch, dễ bảo trì.
• User Manual: Hướng dẫn sử dụng (cho End-user).
• Technical Documentation: Tài liệu kỹ thuật & Hướng dẫn triển khai (cho Dev/DevOps/Maintenance).
• API Doc: Đặc tả API (cho Integration team).

2. Hệ sinh thái & Vai trò

Vai trò (Con người)

• BA (Business Analyst): Phân tích yêu cầu & quản lý đặc tả (sử dụng Excel => Markdown).
• Designer: Thiết kế UI/UX (sử dụng Figma).
• Developer: Đóng vai trò kiểm duyệt, kiểm tra kết quả và chạy thử (Accept/Reject).
• Tester: Kiểm thử cuối cùng & quản lý lỗi (sử dụng Excel).

Công cụ & Hệ thống (AI & System)

• Spec Kit: Bộ công cụ chuẩn hóa đặc tả kỹ thuật.
• AI-Agent IDE: Môi trường thực thi (Claude, Antigravity, Cursor) đóng vai trò "Coder".
• Live Doc: Hệ thống tài liệu (Docusaurus).
• GitLab: Quản lý source code, CI/CD.
• Repomix: Công cụ gộp source code thành context cho AI.
• Pandoc: Công cụ chuyển đổi tài liệu (Excel => Markdown, Markdown => Word,...).
• Figma: Thiết kế UI/UX.
• MCP Tools: Figma Dev Mode MCP, Excel MCP.

3. Hướng dẫn sử dụng Spec Kit

Các câu lệnh cơ bản cho quy trình phát triển theo đặc tả (Spec-Driven Development):

Lệnh cốt lõi (Core Commands)

Lệnh	Mô tả
/speckit.constitution	Tạo hoặc cập nhật các nguyên tắc quản trị dự án và hướng dẫn phát triển
/speckit.specify	Định nghĩa những gì bạn muốn xây dựng (yêu cầu và user stories)
/speckit.plan	Tạo kế hoạch triển khai kỹ thuật với tech stack đã chọn
/speckit.tasks	Tạo danh sách công việc (tasks) khả thi để triển khai
/speckit.implement	Thực thi tất cả các công việc để xây dựng tính năng theo kế hoạch

Lệnh tùy chọn (Optional Commands)

Các lệnh bổ sung để nâng cao chất lượng và kiểm định:

Lệnh	Mô tả
/speckit.clarify	Làm rõ các khu vực chưa rõ ràng (khuyên dùng trước /speckit.plan; trước đây là /quizme)
/speckit.analyze	Phân tích tính nhất quán & độ bao phủ giữa các tài liệu (chạy sau /speckit.tasks, trước /speckit.implement)
/speckit.checklist	Tạo danh sách kiểm tra chất lượng tùy chỉnh để xác thực tính đầy đủ, rõ ràng và nhất quán (giống như "unit tests cho tiếng Anh")

4. Chiến lược phân loại nhiệm vụ

Để tránh lãng phí thời gian cho các task đơn giản, quy trình cần linh hoạt dựa trên độ phức tạp của công việc:

Mức độ	Định nghĩa	Quy trình Áp dụng	Công cụ & Cách làm
Simple (L1)	Thay đổi nhỏ, tính năng đơn giản.	Direct Execution	- BA/Tester log bug trực tiếp lên Excel. - Dev dùng chế độ Fast của AI IDE. - Không cần Planning. - Không cần full Specification-Driven Agentic Workflow. - Cần review code.
Medium (L2)	Thêm tính năng nhỏ, sửa logic nghiệp vụ cục bộ.	Lightweight Spec	- Cập nhật Spec ngắn gọn (Markdown). - Dev dùng chế độ Planning của AI IDE. - Không cần full Specification-Driven Agentic Workflow. - Cần review code.
Complex (L3)	Tính năng mới, thay đổi database, ảnh hưởng nhiều module, cấu trúc hệ thống. Bao gồm cả refactor lớn, migrate công nghệ.	Full Workflow	- Tuân thủ tuyệt đối quy trình Specification-Driven Agentic Workflow. - Review kỹ lưỡng & Test. - Với Refactor: cần plan kiến trúc chi tiết.

5. Chiến lược Kết nối Dữ liệu

Để quy trình này vận hành trơn tru nhất, chìa khóa không nằm ở việc mỗi người làm việc tốt hơn, mà là ở việc "Kết nối dữ liệu" giữa các công cụ. Mục tiêu là biến Excel thành "nguồn sự thật" mà AI có thể đọc được, và biến Git thành "trung tâm điều phối".

Bước 1: BA tạo Excel làm "Dữ liệu đầu vào cho AI"

BA là người đặt nền móng. Để Dev và AI làm việc dễ nhất, BA cần thay đổi cách viết Excel:

Bảng 1: Functional Requirements (Yêu cầu chức năng)

Feature ID	Feature Name	User Story	Acceptance Criteria (AC)	Business Logic / Rules	Status
FEAT_001	Đăng nhập	Là người dùng, tôi muốn đăng nhập để vào hệ thống.	1. Hiển thị lỗi nếu sai email/pass. 2. Chuyển hướng Dashboard nếu đúng.	- Pass phải có ít nhất 8 ký tự. - Khóa tài khoản nếu nhập sai 5 lần.	API_READY
FEAT_002	Tạo đơn hàng	Là nhân viên, tôi muốn tạo đơn hàng mới cho khách.	1. Giảm tồn kho sau khi tạo. 2. Gửi mail thông báo khách hàng.	- Kiểm tra tồn kho trước khi cho phép lưu. - Trạng thái mặc định: "Chờ xử lý".	IN_PROGRESS_BE

Note - Quy ước trạng thái (Status Best Practices):

• TODO: Chưa bắt đầu.
• IN_PROGRESS_BE: Backend đang phát triển.
• API_READY: API đã hoàn thành, sẵn sàng cho Frontend tích hợp.
• IN_PROGRESS_FE: Frontend đang phát triển.
• IN_REVIEW: Đã code xong, đang đợi Review.
• QA_VERIFIED: Tester đã kiểm tra và xác nhận đạt yêu cầu.
• DONE: Tính năng đã hoàn thành trọn vẹn và merge vào nhánh chính.

Bảng 2: Database Schema (Cấu trúc dữ liệu) (Optional)

Feature ID	Table Name	Field Name	Data Type	Constraints	Description
FEAT_001	Users	email	String	Unique, Not Null	Email dùng để đăng nhập
FEAT_001	Users	password_hash	String	Not Null	Mật khẩu đã mã hóa
FEAT_002	Orders	order_id	UUID	Primary Key	Mã đơn hàng duy nhất
FEAT_002	Orders	total_amount	Decimal	Min 0	Tổng tiền đơn hàng

Bảng 3: API Specification (Đặc tả API) (Optional)

Feature ID	Endpoint	Method	Request Body / Params	Response (Success)	Error Codes
FEAT_001	/api/auth/login	POST	{"email": "", "pwd": ""}	{"token": "abc", "role": ""}	401: Unauthorized
FEAT_002	/api/orders	POST	{"items": [], "total": 0}	{"order_id": "123", "status": "ok"}	400: Out of stock

Bảng 4: Test Cases (Kịch bản kiểm thử):

Từ Acceptance Criteria của BA, AI sẽ tự sinh ra bộ Test Cases trong Excel. Tester chỉ cần review và chỉnh sửa.

Feature ID	Test ID	Scenario	Step-by-step	Expected Result	Actual Status
FEAT_001	TC_01	Đăng nhập sai định dạng email	1. Nhập 'abc'. 2. Nhấn Login.	Báo lỗi "Email không hợp lệ".	Pending
FEAT_001	TC_02	Đăng nhập thành công	1. Nhập đúng email/pass. 2. Nhấn Login.	Chuyển vào trang Dashboard.	Pass
FEAT_002	TC_03	Tạo đơn khi kho hết hàng	1. Chọn sản phẩm tồn = 0. 2. Nhấn Lưu.	Báo lỗi "Sản phẩm đã hết hàng".	Fail

• Cấu trúc hóa (Structured Data): Thay vì viết văn bản tự do, hãy chia Excel thành các cột rõ ràng: Feature ID, User Story, Acceptance Criteria (AC), Logic Rules.
• Xuất ra định dạng AI-friendly: Sử dụng Pandoc chuyển đổi Excel sang Markdown. AI-Agent (Cursor/Claude/Antigravity) hiểu Markdown tốt hơn rất nhiều so với việc đọc trực tiếp file Excel thô.
• Live Doc Sync: Mỗi khi cập nhật Excel, BA chỉ cần chạy lệnh để đẩy nội dung đó lên Docusaurus.

Bước 2: Dev và AI Agent làm việc với Spec Kit

Dev không nên bắt đầu bằng việc gõ code, mà bắt đầu bằng việc nạp ngữ cảnh (Context Indexing):

• Download/Copy file Markdown Spec từ hệ thống Docusaurus và đưa vào Context của AI IDE.
• Prompt khởi đầu: Luôn bắt đầu bằng /speckit.specify dựa trên nội dung file Markdown Spec đã nạp (Ví dụ: "Hãy thực hiện tính năng Login dựa trên Spec ID #100...").
• Backend Dev:
  • Dùng markdown spec để generate code (API, Database,..).
  • Output bắt buộc là OpenAPI Spec (Swagger JSON).
• Frontend Dev:
  • Dùng Markdown Spec để định nghĩa yêu cầu (UI/Interaction).
  • Sử dụng OpenAPI Spec làm input tạo API Client.
  • Kết nối Figma Dev Mode MCP để lấy design system & layout.
• Quy trình lệnh bắt buộc (Full Command Sequence): Cả FE và BE Developer đều phải tuân thủ nghiêm ngặt trình tự sau:
  1. /speckit.specify: Định nghĩa yêu cầu.
  2. /speckit.clarify: Làm rõ yêu cầu (optional).
  3. /speckit.plan: Lên kế hoạch.
  4. /speckit.analyze: Phân tích rủi ro & nhất quán (optional).
  5. /speckit.tasks: Chia task.
  6. /speckit.implement: Thực thi code.
• Tự động hóa Documentation: Khi code xong, dùng AI để tự động cập nhật cho Technical Doc và API Doc (Swagger/OpenAPI).
• Cập nhật trạng thái: Sau khi hoàn thành, dùng Excel MCP để chuyển trạng thái tính năng sang "Hoàn thành" trực tiếp trên Excel.

6. Công cụ & Giải pháp cho BA (Excel + AI)

Để BA viết Functional Requirements dễ dàng và tự động hóa các khâu thủ công, giải pháp cốt lõi là biến Excel thành công cụ "AI-enabled" (có tích hợp AI). Dưới đây là 3 cấp độ triển khai giải pháp:

6.1. Cấp độ 1: Sử dụng Add-in AI trực tiếp (Cơ bản)

Thay vì BA phải tự nghĩ và gõ từng dòng User Story hay AC, họ chỉ cần gõ tên tính năng, và AI sẽ điền phần còn lại.

• Công cụ: GPT for Excel (từ Talarian hoặc các Generic GPT add-ins).
• Cách hoạt động: Dùng hàm giống hệt công thức Excel thông thường.
  • Cột A (Feature Name): Chức năng Đăng nhập
  • Cột B (User Story): =GPT("Viết User Story chuẩn Scrum cho tính năng: " & A2)
  • Cột C (Acceptance Criteria): =GPT("Viết 3 tiêu chí chấp nhận (AC) gạch đầu dòng cho: " & A2)
• Lợi ích: Viết cực nhanh. BA chỉ cần review và sửa lại thay vì viết mới 100%.

6.2. Cấp độ 2: Template "Điền vào chỗ trống" (Quy trình)

Để đảm bảo nhất quán với Bảng 1 (Mục 5), Template Excel cần thiết kế đúng các cột sau:

Feature ID	Feature Name	User Story	Acceptance Criteria (AC)	Business Logic / Rules	Status
FEAT_01	Đăng nhập	=GPT("Viết User Story...")	=GPT("Viết AC...")	- Pass > 8 chars - Khóa sau 5 lần sai	TODO
(Input)	(Input)	(AI Generated)	(AI Generated)	(Input)	(Dropdown)

Hướng dẫn:

• Input (BA nhập): Feature Name, Business Logic / Rules.
• Output (AI sinh): User Story, Acceptance Criteria (AC).
• Status: Sử dụng Dropdown list đúng chuẩn (TODO, IN_PROGRESS_BE, API_READY, IN_PROGRESS_FE, IN_REVIEW, QA_VERIFIED, DONE).

6.3. Cấp độ 3: Đưa AI vào quy trình Review (Nâng cao)

Sau khi viết xong, BA cần biết mình viết có đủ ý chưa, có thể dùng chính GPT for Excel để tạo cột "Review".

• Công thức: =GPT("Đọc User Story ở ô B2 và AC ở ô C2, hãy tìm ra các lỗ hổng logic nếu có. Trả lời ngắn gọn.", B2, C2)
• Kết quả: Excel sẽ tự động "chấm điểm" và cảnh báo lỗ hổng (ví dụ: "Chưa xử lý trường hợp mất internet").

6.4. Hướng dẫn Setup nhanh cho BA

1. Cài đặt: Add-in "GPT for Excel" trên Microsoft Store (thường có Free Tier hoặc dùng API Key).
2. Template: Tech Lead tạo sẵn file Excel mẫu với các công thức =GPT(...) đã điền sẵn.
3. Quy trình: BA mở file -> Gõ tên tính năng -> Kéo công thức xuống -> Review nội dung -> Save.