Chào mừng mọi người đến với buổi học Day 2 của chương trình AIDF-NEXA. Hôm nay chúng ta sẽ đi sâu vào ba chủ đề quan trọng: SoT, Templates và Quy trình làm việc. Điều kiện tiên quyết là các bạn đã hoàn thành Day 1 và đã thiết lập xong Claude Code trên máy. Nếu ai chưa hoàn thành, hãy báo cho tôi biết ngay bây giờ. Chúng ta sẽ có hai phần chính: một giờ lý thuyết và một giờ thực hành. Hãy bắt đầu thôi!

Đây là chương trình chi tiết cho buổi học hôm nay. Chúng ta bắt đầu bằng 5 phút ôn tập lại những gì đã học ở Day 1. Tiếp theo là 20 phút về SoT — đây là chủ đề cốt lõi của hệ thống NEXA. Sau đó là Templates và Prompts, rồi Quy trình làm việc cùng các cổng chất lượng. Sau giải lao 5 phút, chúng ta chuyển sang phần thực hành với hai bài tập cụ thể. Cuối buổi sẽ có kiểm tra nhanh và xem trước nội dung Day 3. Tổng cộng khoảng 2 giờ — hãy tận dụng thời gian tốt nhé.

Bắt đầu Phần 1 — phần lý thuyết. Trong một giờ này, chúng ta sẽ xây dựng nền tảng kiến thức vững chắc trước khi bước vào thực hành. Tôi sẽ giải thích từng khái niệm với ví dụ thực tế từ dự án, không chỉ lý thuyết suông. Nếu có thắc mắc, hãy giơ tay — chúng ta sẽ giải đáp ngay trong phần lý thuyết.

Hãy cùng ôn lại nhanh những gì chúng ta đã học ở Day 1. NEXA không phải là một công cụ đơn lẻ mà là một framework điều phối AI — đây là điểm quan trọng nhất. Chúng ta có 5 giai đoạn: RD, BD, DD, CODE và TEST — mỗi giai đoạn có đầu vào và đầu ra rõ ràng. SoT là Source of Truth, tất cả tài liệu chính thức đều nằm trong thư mục 90_Input. DocumentMap đóng vai trò như GPS giúp điều hướng trong dự án. Hôm nay chúng ta sẽ đi sâu hơn vào SoT, Templates và Quy trình — ba thứ này là "xương sống" của hệ thống NEXA trong thực tế.

Hôm nay tôi muốn nhấn mạnh một điều quan trọng mà Day 1 chưa nói rõ: SoT KHÁC với Output. Output là thứ AI hoặc con người tạo ra — nó CÓ THỂ sai, có thể chưa được duyệt. SoT là thứ đã được xác nhận — là "sự thật" chính thức. Ngoài 4 quy tắc, có một khái niệm nữa là phân cấp SoT. Đứng trên cùng là 00_Input — chứa thông tin trực tiếp từ khách hàng. Đây là truth có authority cao nhất trong toàn bộ dự án. Không ai được "sáng tạo" khác đi so với 00_Input. Tiếp theo là 90_Input của từng giai đoạn — theo thứ tự RD, BD, DD. Khi có mâu thuẫn giữa các tầng, tầng trên luôn thắng. Ví dụ: nếu BD nói field X là required nhưng DD nói optional — BD thắng, DD phải sửa lại.

Vậy khi nào chúng ta cần thực hiện đồng bộ SoT? Có ba tình huống chính. Thứ nhất, khi BD được phê duyệt — đây là lúc cần sao chép BD vào thư mục 90_Input của giai đoạn DD. Thứ hai, khi BD được cập nhật sau phê duyệt — cần đồng bộ lại và cập nhật DD tương ứng. Thứ ba, khi DD hoàn thành — DD trở thành tài liệu tham chiếu cho giai đoạn CODE. Quy trình đồng bộ rất đơn giản: xác định nguồn, sao chép sang đích, rồi kiểm tra bằng lệnh diff để đảm bảo hai file giống nhau 100%. NEXA cũng cung cấp sẵn lệnh `/sot:check` để tự động hóa việc này.

5 lỗi phổ biến nhất trong quản lý SoT. Lỗi 1: dùng sai phiên bản — developer mở file cũ mà không kiểm tra 90_Input. Lỗi 2: sửa trực tiếp file trong 90_Input — vi phạm nghiêm trọng, phá vỡ tính toàn vẹn SoT. Lỗi 3: quên đồng bộ — BD cập nhật nhưng DD team không biết, tiếp tục dùng version cũ. Lỗi 4: nhầm Output là SoT — file trong 91_Output chưa được review nhưng đã được dùng như tài liệu chính thức. Lỗi 5: không phát hiện SoT gốc thay đổi — 00_Input (thông tin từ khách hàng) đã được cập nhật nhưng các tầng dưới (BD, DD) vẫn dùng thông tin cũ. Đây là lỗi nguy hiểm nhất vì ảnh hưởng lan tỏa xuống mọi giai đoạn.

Đây là bảng so sánh cách xử lý thủ công vs NEXA tự động hóa. Lỗi 1: thay vì phải nhớ kiểm tra 90_Input mỗi lần, NEXA có lệnh `/sot:check` tự động xác minh. Lỗi 2: thay vì dựa vào kỷ luật team, NEXA có scope-guard hook tự động chặn khi ai đó cố ghi vào 90_Input. Lỗi 3: thay vì chạy diff thủ công, dùng `/sync:bd-to-dd` để tự động sao chép và xác minh. Lỗi 4: Quality Gate tự động chặn việc promote Output thành SoT nếu chưa qua review. Lỗi 5: `/sot:check` kiểm tra toàn bộ SoT consistency, và `session-init` hook chạy khi khởi động Claude — phát hiện khi SoT gốc (00_Input) đã thay đổi mà các tầng dưới chưa cập nhật. Thông điệp quan trọng nhất: NEXA không dựa vào "kỷ luật con người" mà tạo hệ thống tự động bảo vệ. Dù bạn quên, hệ thống vẫn phát hiện và nhắc nhở.

Tại sao chúng ta cần template? Hãy tưởng tượng hai developer cùng viết BD cho hai màn hình khác nhau mà không có template. Dev A viết đủ layout và fields nhưng quên error handling. Dev B viết đủ hết nhưng theo format riêng của mình. Kết quả là lead phải đọc hai tài liệu hoàn toàn khác nhau để review — mất thời gian và dễ bỏ sót lỗi. Khi có template, tất cả BD đều theo cùng một cấu trúc, AI generate đúng và nhất quán, và review trở nên nhanh hơn nhiều vì bạn biết chính xác cần tìm gì ở đâu. Về thứ tự ưu tiên: luôn dùng template của dự án trước, rồi mới đến template của AIDF framework.

Dự án TaskBoard có template thực tế trong thư mục 02_基本設計/98_Template/. Template 画面設計書テンプレート.md dùng cho mọi loại màn hình — cả login, CRUD, danh sách — chỉ một template chung thay vì tách riêng từng loại. Template API設計テンプレート.md dùng cho REST API — cả xác thực lẫn CRUD. Template データベース設計テンプレート.md cho ER diagram và thiết kế bảng. Ngoài ra còn có template cho 基本設計書 (tổng thể hệ thống) và 非機能要件設計書 (hiệu năng, bảo mật). Mỗi BD template đều có 7 phần bắt buộc — từ tổng quan, layout, danh sách trường, đến xử lý lỗi. Phần quan trọng thường bị bỏ quên nhất là phần 6 — xử lý lỗi. Hãy đảm bảo điền đầy đủ cả 7 phần.

Prompt là cầu nối giữa bạn và AI — viết prompt tốt sẽ cho ra kết quả tốt. NEXA có hai nguồn template: template dự án trong 02_基本設計/98_Template/ (ưu tiên cao nhất) và template AIDF chuẩn trong .aidf/templates/. Ngoài ra, các lệnh như /bd:generate và /dd:generate đã tích hợp sẵn prompt + template bên trong. Hãy xem ví dụ mẫu tạo DD từ BD: chúng ta dùng `@` để chỉ rõ file SoT và file template — không viết mơ hồ. Nguyên tắc vàng là: 1 prompt cho 1 màn hình hoặc 1 API — đừng cố generate tất cả cùng lúc. Sau mỗi lần generate, hãy review output trước khi tiếp tục — đây không phải là bước tùy chọn. Và luôn chỉ định template rõ ràng, đừng để AI tự chọn.

Slide trước đã giới thiệu cách viết prompt thủ công — 4 dòng, chỉ rõ file prompt, SoT, và template. Đó là cách để hiểu cơ chế bên trong. Nhưng trong thực tế, NEXA cung cấp lệnh /dd:generate giúp tự động hóa toàn bộ: chỉ cần 1 lệnh, NEXA sẽ tự tìm SoT trong 90_Input, tự chọn template phù hợp (màn hình, API, hay DB), tự áp dụng prompt tích hợp, và tự chạy Quality Gate sau khi generate. Kết quả được lưu vào 91_Output. Tương tự, /bd:generate làm điều tương tự cho BD. Nhưng hãy nhớ: hiểu prompt thủ công là nền tảng — khi lệnh tự động cho kết quả không tốt, bạn cần biết cách điều chỉnh prompt thủ công.

Quy trình NEXA có 3 cổng chất lượng quan trọng: sau RD, sau BD, và sau DD. Mỗi cổng đều phải vượt qua trước khi được chuyển sang giai đoạn tiếp theo — đây không phải là thủ tục hình thức mà là bảo đảm chất lượng thực sự. Mỗi tài liệu phải qua 3 cấp review: tự review, đồng nghiệp review, và lead duyệt cuối. Nguyên tắc cốt lõi là "đầu vào sai thì đầu ra sai" — nếu BD có lỗi mà không được bắt trước khi sang DD, thì DD sẽ sai, và code từ DD đó cũng sẽ sai. Chi phí sửa lỗi tăng theo cấp số nhân khi lỗi đi qua nhiều giai đoạn. NEXA cung cấp lệnh `/rd:review`, `/bd:review`, `/dd:review` để hỗ trợ quá trình review.

NEXA cung cấp các công cụ chất lượng tự động hỗ trợ quy trình review. Với /rd:review, /bd:review, /dd:review — AI sẽ chấm điểm tài liệu, phát hiện lỗi, và đề xuất cải thiện. Điều này tương đương với Level 1 — tự review — giúp tác giả phát hiện lỗi trước khi gửi cho đồng nghiệp. Ngoài ra, scope-guard là hook chạy tự động, cảnh báo khi bạn viết file ngoài phạm vi vai trò — ví dụ frontend developer viết vào backend/. Và session-init hook chạy khi bắt đầu session Claude — kiểm tra SoT consistency, phát hiện khi SoT gốc đã thay đổi nhưng DD vẫn dùng version cũ — đây chính là Error 5 ở slide trước. Điểm quan trọng nhất: NEXA KHÔNG thay thế review con người. NEXA tự động hóa Level 1 để con người tập trung vào Level 2 và 3 — nơi cần kinh nghiệm và phán đoán.

Chúng ta chuyển sang Phần 2 — phần thực hành. Đây là phần quan trọng nhất của buổi học vì kiến thức chỉ thực sự ngấm khi bạn tự tay làm. Chúng ta sẽ có hai bài tập: bài tập 1 về đồng bộ SoT trong 20 phút, và bài tập 2 về áp dụng template trong 25 phút. Hãy mở máy tính lên và vào thư mục dự án. Nếu gặp khó khăn, hãy giơ tay — tôi sẽ đi xung quanh hỗ trợ.

Bài tập 1 giúp các bạn nhìn thấy thực trạng của dự án ngay bây giờ. QUAN TRỌNG: phải chuyển sang branch exercise/sot-dirty trước — branch này đã được chuẩn bị sẵn với dữ liệu "bẩn" để thực hành. Bước 1: dùng lệnh `ls` để xem thủ công nội dung hai thư mục — BD Output và DD Input. Bước 2: nhìn vào bảng — DD Input đang có cả file cũ (_v1, _v2, _v3, _v4) lẫn file mới. Đây là tình trạng "bẩn" thực tế — câu hỏi là: file nào là SoT? File nào cần xóa? Bước 3: dùng `diff` để so sánh BD Output và DD Input. SCREEN-001 ra trống = OK, hai file giống nhau 100%. Nhưng SCREEN-005 ra khác biệt = NG! Có 3 vấn đề: (1) thiếu câu về validation trong phần概要, (2) API endpoint sai /api/boards/:id/tasks/:taskId thay vì /api/tasks/:id, (3) thiếu error handler 権限なし（403）. Đây là ví dụ thực tế của Error #5 (SoT gốc đã thay đổi mà DD Input chưa cập nhật). Bước 4: đây là bước quan trọng nhất — các bạn thực hành SỬA LỖI. Copy file BD đúng vào DD Input để thay thế file cũ, và xóa tất cả các phiên bản cũ (_v1, _v2...) — chỉ giữ lại file với tên đúng chuẩn. Sau khi sửa, chạy diff lần nữa để xác nhận diff trống = OK.

Bài tập 2 giúp các bạn thực hành áp dụng template từ đầu đến cuối với file thực tế của dự án TaskBoard. Chúng ta sẽ tạo BD cho màn hình SCREEN-009 — màn hình thông báo. Đây là loại màn hình danh sách nên chúng ta dùng 画面設計書テンプレート.md — template duy nhất cho tất cả các loại màn hình. Bước 1: sao chép template từ 02_基本設計/98_Template/ — LƯU Ý đây là lệnh `cp` thực tế trên terminal, các bạn copy-paste và chạy trực tiếp. File mới sẽ nằm đúng thư mục BD Output. Bước 2 và 3 là điền thông tin vào template — hãy điền đúng theo thông tin đã cho. Thông báo trong TaskBoard gồm: phân công task, comment mới, thay đổi deadline. Bước 4 là điền phần actions, transitions, error handling — 3 action chính là lấy danh sách, đánh dấu đã đọc, và chuyển sang chi tiết task khi click. Bước 5 (bonus): nếu còn thời gian, hãy nhờ Claude review file đã tạo. Claude sẽ so sánh với template và chỉ ra phần nào còn thiếu. Đây là workflow thực tế khi dùng Claude Code trong dự án NEXA. Sau khi hoàn thành, hãy đọc lại để kiểm tra xem đã đủ 7 phần của template chưa (概要, レイアウト, 項目一覧, アクション, 遷移, エラー, 関連要件). Ai làm xong sớm có thể thêm phần layout ASCII hoặc bổ sung thêm error cases.

Ba fact này tóm tắt những điểm cốt lõi nhất của Day 2. Fact 1: khi BD cập nhật, luôn đồng bộ lại vào DD Input trước — không bao giờ sửa DD trực tiếp vì đó vi phạm SoT quy tắc 4. Fact 2: NEXA dùng 画面設計書テンプレート.md cho tất cả các loại màn hình — login, CRUD, danh sách — chỉ một template chung, không tách riêng. API và DB có template riêng của chúng. Fact 3: implementation_ready: true là cổng chất lượng giữa DD và CODE — không có nghĩa là code đã xong hay đã pass review, mà là DD đã đủ chất lượng để bắt đầu generate code. Hãy ghi nhớ ba điểm này vì chúng sẽ xuất hiện thường xuyên trong thực tế dự án.

Tổng kết lại những gì chúng ta đã học hôm nay: 4 quy tắc SoT và quy trình đồng bộ, template thực tế của dự án TaskBoard cùng thứ tự ưu tiên, cách viết prompt hiệu quả với ký hiệu @, quy trình làm việc với 3 cổng chất lượng và 3 cấp review, và đã thực hành cả hai kỹ năng quan trọng nhất. Đây là nền tảng để làm việc hiệu quả với NEXA trong thực tế. Day 3 sẽ là phần thú vị nhất — chúng ta sẽ tạo DD từ BD thực tế và generate code từ DD đó, hoàn thành pipeline BD → DD → Code đầy đủ. Hãy ôn lại slide hôm nay trước khi đến Day 3. Cảm ơn mọi người đã tham gia tích cực!

Phần phụ lục này chứa bảng thuật ngữ quan trọng cho buổi học Day 2. Các bạn có thể tham khảo lại bất cứ lúc nào khi làm việc với NEXA. Thuật ngữ kỹ thuật trong NEXA được dùng nhất quán — hãy làm quen với chúng để giao tiếp hiệu quả với team.

Bảng thuật ngữ này tóm tắt 7 khái niệm quan trọng nhất của Day 2. SoT Sync là quy trình đồng bộ tài liệu giữa các giai đoạn — chúng ta đã thực hành điều này trong bài tập 1. Template là mẫu tài liệu chuẩn giúp đảm bảo chất lượng đồng đều. Quality Gate hay cổng chất lượng là điểm kiểm tra bắt buộc trước khi chuyển giai đoạn. Và implementation_ready là trạng thái của DD khi đã sẵn sàng để generate code. Hãy lưu slide này lại để tham khảo khi làm việc thực tế.

Hẹn gặp lại mọi người ở Day 3! Chúng ta sẽ tiếp tục với phần thú vị nhất — tạo DD từ BD thực tế và generate code. Nếu có câu hỏi sau buổi học hôm nay, hãy đặt vào channel Slack của nhóm. Hãy ôn lại 4 quy tắc SoT và 7 phần của BD template — đó là kiến thức nền tảng cho Day 3. Chúc mọi người buổi chiều tốt lành!