AI Agent trong iBom Mobile

1. Tóm Tắt Tổng Quan

Dự án iBom Mobile đã áp dụng quy trình phát triển dựa trên AI, thay đổi căn bản cách xây dựng tính năng, xử lý lỗi và duy trì chất lượng mã nguồn. AI Agent không phải là một chatbot đơn lẻ mà là một hệ sinh thái tích hợp chặt chẽ gồm ba hệ thống bổ trợ nhau: Khung Phát Triển Hướng Đặc Tả (SDD Framework), Pipeline Xử Lý Lỗi Tự Động, và GitNexus Code Intelligence.

Các hệ thống này cùng nhau tạo thành một pipeline liên tục chuyển đổi các yêu cầu dạng văn bản thành mã React Native sẵn sàng triển khai, được kiểm thử đầy đủ—với khả năng truy xuất toàn diện từ mỗi dòng mã nguồn về yêu cầu gốc của nó. Tài liệu này cung cấp cái nhìn toàn diện về kiến trúc, quy trình vận hành, lợi ích thực tế, và hướng dẫn cho các thành viên trong đội.

2. AI Agent là gì?

AI Agent trong dự án iBom Mobile không phải là một bot đơn lẻ. Nó là sự kết hợp của quy trình tự động hóa SDD, pipeline xử lý lỗi, và trí tuệ đồ thị mã nguồn được tích hợp trực tiếp vào repository. Mỗi thành phần phục vụ một mục đích riêng biệt đồng thời hỗ trợ lẫn nhau, tạo ra trải nghiệm phát triển nhanh hơn, an toàn hơn và có thể truy xuất được.

2.1 Khung SDD (Specification-Driven Development)

Khung SDD là xương sống của khả năng phát triển tính năng của AI Agent. Nó tạo ra các đặc tả, bản thiết kế kiến trúc, đồ thị tác vụ, mã triển khai, unit test và báo cáo xác minh—tất cả đều từ các tài liệu yêu cầu dạng văn bản lưu trong thư mục documents/. Mọi artifact đều được liên kết với mã định danh yêu cầu (FR-XXX), đảm bảo truy xuất xuyên suốt.

Nguyên tắc cốt lõi: Đặc tả đầu vào, mã sẵn sàng triển khai đầu ra. Khung này áp dụng một pipeline có kỷ luật: không có mã nào được viết mà không có đặc tả tương ứng, và không có đặc tả nào được coi là hoàn chỉnh nếu chưa qua bước xác minh.

2.2 Pipeline Xử lý Lỗi Tự Động

Pipeline Xử lý Lỗi tự động hóa hành trình từ một ticket thô trên pro.ibom.vn đến một pull request được merge trên GitHub. Nó thu thập ticket, áp dụng OCR cho ảnh chụp màn hình đính kèm, phân loại vấn đề theo module (MATERIAL, NAV, AUTH, v.v.), chẩn đoán nguyên nhân gốc, viết regression test, áp dụng bản vá và tạo pull request—tất cả không cần can thiệp thủ công.

Nguyên tắc cốt lõi: Ticket đầu vào, pull request đầu ra. Mọi bản sửa lỗi đều bắt đầu bằng một test thất bại để đảm bảo lỗi không thể tái xuất hiện một cách âm thầm.

2.3 GitNexus – Trí Tuệ Mã Nguồn

GitNexus là tầng trí tuệ mã nguồn của dự án, được xây dựng trên chỉ mục toàn bộ codebase với hơn 100.000 symbol và 156.000 mối quan hệ. Nó cung cấp tìm kiếm ngữ nghĩa, ngữ cảnh 360 độ cho symbol, phân tích tác động và đổi tên an toàn đa tệp—đảm bảo mọi chỉnh sửa đều dựa trên đồ thị phụ thuộc thực tế của mã.

Nguyên tắc cốt lõi: Hiểu mã trước khi chỉnh sửa. Không hàm, lớp hay phương thức nào nên được sửa mà không chạy phân tích tác động trước.

3. Cách Hoạt Động: Pipeline SDD

3.1 Sáu Giai Đoạn

Khung SDD vận hành qua sáu giai đoạn tuần tự, mỗi giai đoạn tạo ra một artifact rõ ràng làm đầu vào cho giai đoạn tiếp theo. Pipeline này đảm bảo mọi tính năng đều đi từ yêu cầu mơ hồ đến mã sản xuất được xác minh đầy đủ qua một quy trình có cấu trúc, lặp lại được.

Giai đoạn	Lệnh	Mô tả
1. Specify	/specify	Tạo đặc tả yêu cầu chính thức (FR-XXX) từ các tài liệu trong thư mục documents/. Mọi yêu cầu nhận một mã định danh duy nhất được duy trì xuyên suốt các giai đoạn.
2. Plan	/plan	Ghi nhận thiết kế kiến trúc vào DESIGN.md, bao gồm quyết định công nghệ, sơ đồ luồng dữ liệu và ranh giới component.
3. Tasks	/tasks	Tạo đồ thị có hướng không chu trình (DAG) các tác vụ triển khai, mỗi tác vụ có tiêu chí chấp nhận, phụ thuộc và phạm vi ước lượng.
4. Implement	/implement	Thực thi DAG tác vụ theo TDD: viết test thất bại trước, sau đó viết mã tối thiểu để test pass, rồi refactor.
5. Verify	/verify	Truy xuất mọi đoạn mã về yêu cầu FR-XXX gốc và chạy toàn bộ test suite để xác nhận tuân thủ.
6. Review	/review	Thực hiện kiểm tra chất lượng toàn diện bao gồm coding rules, độ phủ test, accessibility và hiệu năng.

Mỗi giai đoạn đều có thể được kiểm tra độc lập. Thành viên đội có thể xem lại đặc tả trước khi lên kế hoạch, xem lại DAG tác vụ trước khi triển khai, hoặc xác minh khả năng truy xuất bất kỳ lúc nào.

3.2 Chế độ Autopilot và Chế độ Thủ Công

Khung SDD cung cấp hai chế độ vận hành, cho phép đội chọn mức độ giám sát phù hợp với từng tình huống.

Khía cạnh	Chế độ Autopilot	Chế độ Thủ Công
Lệnh	/autopilot mobile	/specify → /plan → /tasks → /implement → /verify → /review
Thực thi	Tự động toàn bộ; sáu giai đoạn chạy tuần tự không cần can thiệp.	Mỗi giai đoạn được kích hoạt riêng lẻ, cho phép kiểm tra và chỉnh sửa thủ công giữa các phase.
Kiểm tra artifact	Artifact được tạo và xác minh tự động.	Thành viên có thể kiểm tra và sửa mọi artifact (specs, design, tasks) trước khi tiếp tục.
Khôi phục gán đoạn	Không áp dụng.	Dùng /resume để tiếp tục từ giai đoạn hoàn thành cuối cùng sau bất kỳ gán đoạn nào.
Phù hợp nhất với	Tính năng mới hoàn toàn, các đợt quét lớn và yêu cầu được tài liệu hóa rõ ràng.	Thay đổi phức tạp, chỉnh sửa rủi ro cao và các tình huống cần kiểm soát chi tiết.

Trong thực tế, hầu hết các đội sử dụng Autopilot cho công việc tính năng tiêu chuẩn và chuyển sang Chế độ Thủ Công khi xử lý các vấn đề xuyên suốt, refactor nhạy cảm, hoặc thay đổi ảnh hưởng đến hạ tầng dùng chung.

4. Cách Hoạt Động: Xử lý Lỗi Tự Động

Pipeline xử lý lỗi kết nối hai dự án. Dự án thứ nhất (ibom-crawling) hoạt động bên ngoài: thu thập ticket từ pro.ibom.vn, chạy OCR trên ảnh chụp màn hình, phân loại từng vấn đề theo module và xuất file categorized_tasks.json. Dự án thứ hai (ibommobile—repository này) tiêu thụ file đó và đưa mỗi lỗi đến pull request.

Giai đoạn 1: Thu thập và Phân tích

Crawler kéo ticket từ hệ thống quản lý dự án và áp dụng nhận dạng ký tự quang học (OCR) cho ảnh chụp màn hình đính kèm, trích xuất thông báo lỗi, stack trace và văn bản giao diện.

Giai đoạn 2: Phân loại

Mỗi ticket được tự động phân loại theo module—MATERIAL, NAV, AUTH, CONSTRUCTION, SELL, TRANSFER, v.v.—dựa trên nội dung, tag và component bị ảnh hưởng. Kết quả là một manifest JSON có cấu trúc.

Giai đoạn 3: Chẩn đoán

Lệnh /bugfix xác định nguyên nhân gốc trong codebase. Nó tận dụng GitNexus để truy vết các luồng thực thi liên quan đến triệu chứng, kiểm tra đồ thị gọi của các hàm nghi ngờ và xác định đường mã cụ thể gây ra lỗi.

Giai đoạn 4: Sửa lỗi với TDD

Một test thất bại được viết trước, ghi lại chính xác hành vi được mô tả trong báo cáo lỗi. Agent sau đó vá mã nguồn cho đến khi test pass. Điều này đảm bảo bản sửa có thể xác minh được và bất kỳ regression nào trong tương lai sẽ được phát hiện ngay.

Giai đoạn 5: Tạo Pull Request

Lệnh /automate-git-flow tạo feature branch, commit các thay đổi với annotation truy xuất phù hợp (Implements: FR-XXX, Task: #NNNNNN) và mở pull request trên GitHub để người review.

5. Cách Hoạt Động: GitNexus Intelligence

GitNexus cung cấp cho AI Agent—và mọi thành viên trong đội—sự hiểu biết sâu, dựa trên đồ thị về codebase. Nó lập chỉ mục hơn 100.000 symbol và 156.000 mối quan hệ, ánh xạ mọi lời gọi hàm, import và phụ thuộc luồng dữ liệu vào một đồ thị có thể truy vấn.

Công cụ	Mục đích	Khi nào sử dụng
gitnexus_query	Tìm mã theo khái niệm sử dụng luồng thực thi được xếp hạng, không phải tìm kiếm văn bản thuần.	Khám phá mã chưa quen, tìm logic nghiệp vụ theo ý định.
gitnexus_context	Góc nhìn 360 độ về một symbol: tất cả caller, callee và luồng thực thi mà nó tham gia.	Hiểu vai trò của hàm trước khi chỉnh sửa.
gitnexus_impact	Phân tích bán kính ảnh hưởng: caller trực tiếp (d=1), phụ thuộc gián tiếp (d=2) và consumer chuyển tiếp (d=3).	Bắt buộc trước khi sửa bất kỳ symbol nào. Rủi ro HIGH/CRITICAL cần thảo luận đội.
gitnexus_detect_changes	Xác minh trước commit rằng chỉ các symbol và luồng dự kiến bị ảnh hưởng.	Chạy trước mọi commit để ngăn tác dụng phụ ngoài ý muốn.
gitnexus_rename	Đổi tên đa tệp dựa trên đồ thị, hiểu call graph, tránh lỗi của find-and-replace.	Bất kỳ việc đổi tên symbol nào trong codebase.

Các mức rủi ro tác động

GitNexus phân loại tác động của bất kỳ thay đổi nào thành ba mức độ sâu. Độ sâu 1 (d=1) xác định các caller và importer trực tiếp sẽ bị hỏng—bắt buộc phải cập nhật. Độ sâu 2 (d=2) đánh dấu các phụ thuộc gián tiếp có thể bị ảnh hưởng và cần được test. Độ sâu 3 (d=3) nhấn mạnh các consumer chuyển tiếp có thể cần test nếu nằm trên đường dẫn quan trọng.

6. Điểm Nổi Bật

AI Agent mang đến nhiều khả năng mang tính chuyển đổi cho quy trình phát triển iBom Mobile. Dưới đây là những điểm nổi bật quan trọng nhất.

Tự động hóa toàn trình: Từ bản tóm tắt trong thư mục documents/ đến mã sản xuất được kiểm thử đầy đủ, chế độ Autopilot có thể phân phối một tính năng hoàn chỉnh trong vài phút thay vì vài ngày.
Truy xuất yêu cầu 100%: Mọi hàm, lớp và test case đều được gắn mã FR-XXX. Script scripts/verify-traceability.py có thể xác nhận độ phủ bất kỳ lúc nào, đảm bảo không yêu cầu nào bị bỏ sót.
Xử lý lỗi hướng TDD: Pipeline xử lý lỗi viết test thất bại trước khi sửa, đảm bảo mọi lỗi được giải quyết đều có regression test tương ứng.
Trí tuệ mã nguồn dựa trên đồ thị: GitNexus loại bỏ sự phỏng đoán khỏi refactoring bằng phân tích bán kính ảnh hưởng chính xác, tìm kiếm ngữ nghĩa và đổi tên an toàn dựa trên đồ thị phụ thuộc thực tế.
Artifact có cấu trúc, kiểm tra được: Mọi giai đoạn của pipeline SDD tạo ra một artifact riêng biệt—đặc tả, tài liệu thiết kế, đồ thị tác vụ, test và báo cáo xác minh—có thể được bất kỳ thành viên nào xem lại.
Hai chế độ thực thi: Autopilot cho tốc độ; Chế độ Thủ Công cho kiểm soát và chính xác. Đội có thể chọn chế độ phù hợp cho từng tác vụ mà không mất lợi ích của pipeline.
Tích hợp liền mạch: AI Agent hoạt động hoàn toàn trong cấu trúc repository hiện tại, quy trình Git và CI/CD pipeline. Không cần hạ tầng mới, dịch vụ bên ngoài hay phụ thuộc triển khai bổ sung.

7. Lợi Ích

7.1 Tăng Tốc Phát Triển Tính Năng

Chế độ Autopilot chuyển đổi bản tóm tắt dự án thành đặc tả, tác vụ, mã và test trong một phần nhỏ thời gian so với phát triển thủ công. Các tính năng trước đây mất nhiều ngày lên kế hoạch, triển khai và kiểm thử nay có thể được phân phối trong chu kỳ rút ngắn đáng kể. Năng lực của đội được nhân lên mà không cần tăng nhân sự hay giờ làm tương ứng.

7.2 Truy Xuất Yêu Cầu Toàn Diện

Mọi hàm trong codebase đều được gắn mã yêu cầu FR-XXX tương ứng, và mọi commit message đều tham chiếu các yêu cầu mà nó triển khai. Tiện ích scripts/verify-traceability.py có thể xác nhận độ phủ trên toàn bộ codebase bất kỳ lúc nào, cung cấp bằng chứng có thể kiểm toán rằng không yêu cầu nào bị bỏ qua.

7.3 Giảm Rủi Ro Khi Refactor

Phân tích tác động của GitNexus loại bỏ sự không chắc chắn thường đi kèm với refactoring. Trước mọi chỉnh sửa, bán kính ảnh hưởng được định lượng: caller trực tiếp sẽ hỏng (d=1), phụ thuộc gián tiếp cần test (d=2), và consumer chuyển tiếp có thể cần chú ý (d=3). Cảnh báo HIGH và CRITICAL đảm bảo đội nhận thức được hậu quả trước khi commit.

7.4 Tiêu Chuẩn Chất Lượng Nhất Quán

Phương pháp TDD-first được áp dụng bởi cả pipeline SDD và pipeline xử lý lỗi đảm bảo mọi đoạn mã mới đều đi kèm test tương ứng. Giai đoạn /review kiểm tra coding rules, tuân thủ accessibility (testID và accessibilityLabel trên mọi phần tử tương tác), độ chính xác của bản địa hóa và tiêu chuẩn hiệu năng—phát hiện vấn đề trước khi đến production.

7.5 Xử Lý Lỗi Nhanh và Đáng Tin Cậy Hơn

Pipeline tự động từ ticket đến pull request loại bỏ chi phí phân loại thủ công và đảm bảo quy trình sửa lỗi nhất quán, lặp lại được. Bằng cách viết test thất bại trước mỗi bản sửa, pipeline đảm bảo các lỗi đã được giải quyết không thể tái xuất hiện trong các bản phát hành tương lai.

7.6 Bảo Tồn Tri Thức

Vì pipeline SDD tạo ra đặc tả chính thức, tài liệu thiết kế và đồ thị tác vụ cho mọi tính năng, tri thức tổ chức được lưu trữ trong repository thay vì bị khóa trong đầu của từng cá nhân. Thành viên mới có thể hòa nhập nhanh hơn bằng cách đọc các artifact có cấu trúc đi kèm mọi đoạn mã.

8. Hướng Dẫn Sử Dụng Hàng Ngày

Làm việc hiệu quả với AI Agent đòi hỏi tuân thủ một tập hợp các thực hành đảm bảo đầu ra của pipeline luôn đáng tin cậy, truy xuất được và an toàn. Các hướng dẫn sau áp dụng cho mọi thành viên tương tác với codebase.

8.1 Thực Hành Tốt Nhất

Luôn chạy phân tích tác động trước. Trước khi sửa bất kỳ hàm, lớp hay phương thức nào, chạy gitnexus_impact để hiểu bán kính ảnh hưởng. Nếu kết quả trả về HIGH hoặc CRITICAL, thảo luận với đội trước khi tiếp tục.
Gắn mã định danh yêu cầu vào mã. Mọi hàm hoặc lớp triển khai yêu cầu phải bao gồm annotation Requirements: FR-XXX trong docstring. Mọi commit message phải tham chiếu yêu cầu (Implements: FR-XXX).
Sử dụng API wrapper của dự án. Mọi HTTP request phải đi qua Api.get và Api.post từ app/constants/Api. Không bao giờ đưa vào HTTP dependency mới như fetch hay axios.
Thêm testID và accessibilityLabel cho mọi phần tử tương tác. Đây là yêu cầu bắt buộc cho kiểm thử tự động (Detox/WDIO/Appium) và hỗ trợ đọc màn hình. Component thiếu các thuộc tính này được coi là lỗi.
Chờ xác minh hoàn tất trước khi commit. Luôn chạy /verify để xác nhận khả năng truy xuất và /review để kiểm tra chất lượng mã trước khi push.
Chạy gitnexus_detect_changes trước mọi commit. Kiểm tra trước commit này xác minh rằng chỉ các symbol và file dự kiến bị ảnh hưởng.
Đưa mọi văn bản hiển thị qua i18n. Không bao giờ hardcode chuỗi. Trong functional component, dùng hook useTranslation()—không gọi I18n.t trực tiếp.

8.2 Những Sai Lầm Cần Tránh

Không dùng find-and-replace để đổi tên symbol. Dùng gitnexus_rename vì nó hiểu call graph và tạo ra đổi tên chính xác đa tệp.
Không bỏ qua cảnh báo HIGH hoặc CRITICAL. Chúng cho biết thay đổi có hậu quả lan rộng có thể làm hỏng các đường dẫn quan trọng.
Không commit mà không chạy gitnexus_detect_changes(). Commit chưa xác minh có nguy cơ gây ra tác dụng phụ ngoài ý muốn.
Không gọi I18n.t trực tiếp trong functional component. Luôn dùng hook useTranslation() để đảm bảo reactivity và nhất quán.
Không hardcode chuỗi trong giao diện. Mọi nhãn, thông báo và placeholder phải đi qua lớp i18n để hỗ trợ bản địa hóa.

9. Bảng Lệnh Tham Khảo Nhanh

Bảng sau tóm tắt các lệnh được sử dụng thường xuyên nhất và khi nào nên dùng chúng.

Lệnh	Khi nào sử dụng
/autopilot mobile	Phân phối một tính năng hoàn chỉnh từ thư mục documents/ trong một lần chạy.
/specify → /plan → /tasks	Đi qua pipeline SDD thủ công với kiểm tra giữa các giai đoạn.
/implement	Thực thi DAG tác vụ đã tạo với Test-Driven Development.
/verify	Xác nhận mọi đoạn mã đều truy xuất về yêu cầu chính thức.
/review	Kiểm tra chất lượng toàn diện bao gồm rules, độ phủ và accessibility.
/bugfix	Chẩn đoán lỗi, viết regression test và áp dụng bản sửa.
bash scripts/pipeline.sh	Chạy toàn bộ pipeline thu thập và sửa lỗi.
npx gitnexus analyze	Lập lại chỉ mục đồ thị mã trước các đợt refactor lớn hoặc sau merge lớn.
/resume	Tiếp tục pipeline SDD bị gán đoạn từ giai đoạn hoàn thành cuối cùng.

Mẹo: Trước khi bắt đầu bất kỳ tác vụ nào, luôn tải openspec/specs/TECHNICAL.md và BOUNDARIES.md để đảm bảo bạn làm việc với các ràng buộc kiến trúc và quy tắc dự án mới nhất.

10. Kết Luận

AI Agent trong iBom Mobile đại diện cho một bước chuyển căn bản trong cách đội tiếp cận phát triển phần mềm. Bằng cách kết hợp tự động hóa hướng đặc tả, xử lý lỗi test-first và trí tuệ mã nguồn dựa trên đồ thị vào một quy trình thống nhất, dự án đạt được mức độ nhanh, an toàn và truy xuất được mà khó có thể duy trì bằng quy trình thủ công.

Quy trình rất rõ ràng: đặc tả đầu vào, mã sẵn sàng triển khai đầu ra—an toàn. Pipeline SDD (Specify, Plan, Tasks, Implement, Verify, Review) đảm bảo mọi tính năng được xây dựng trên nền tảng yêu cầu chính thức và xác nhận qua kiểm thử tự động. Pipeline xử lý lỗi đảm bảo các khuyết điểm được giải quyết có hệ thống, với regression test ngăn chặn tái xuất hiện. GitNexus đảm bảo mọi chỉnh sửa đều dựa trên cấu trúc phụ thuộc thực tế, loại bỏ phỏng đoán khỏi refactoring.

Bằng cách tuân thủ các hướng dẫn trong tài liệu này—chạy phân tích tác động trước khi chỉnh sửa, duy trì annotation FR-XXX, sử dụng lớp i18n nhất quán, và chờ xác minh hoàn tất trước khi commit—đội có thể tận dụng đầy đủ các khả năng này để phân phối phần mềm chất lượng cao nhanh hơn và tự tin hơn.

Xem thêm: