Xây dựng hệ thống quản lý hướng ontology từ yêu cầu nghiệp vụ với ontology-driven-dev

Giới thiệu dự án

ontology-driven-dev là một bộ kỹ năng AI dành cho phát triển hệ thống nghiệp vụ, áp dụng quy trình ba bước theo thứ tự chặt chẽ: “khám phá yêu cầu → mô hình hóa ontology → xây dựng ứng dụng”. Bạn có thể bắt đầu từ một câu mô tả nghiệp vụ, sau khi con người xác nhận từng giai đoạn, để tạo ra tài liệu đặc tả yêu cầu, YAML của bảy mô hình và một hệ thống frontend-backend chạy được trên trình duyệt.

Mục tiêu cốt lõi của bộ kỹ năng không chỉ là giúp AI tạo mã nhanh, mà còn bảo đảm tài liệu yêu cầu, mô hình ontology và mã nguồn cuối cùng hoàn toàn nhất quán. Bảng cơ sở dữ liệu, API, menu, quyền hạn, quy trình, quy tắc và báo cáo đều lấy mô hình làm nguồn ngữ nghĩa, qua đó giảm tình trạng yêu cầu, thiết kế và triển khai bị lệch khỏi nhau.

Giai đoạn khám phá yêu cầu gồm tám bước. Sau mỗi bước phải tạm dừng và chờ con người xác nhận, Agent không được tự động bỏ qua.

Năng lực cốt lõi và cấu trúc dự án

Tính năng chính

• Truy xuất nguồn gốc yêu cầu: mọi chức năng đều có thể truy ngược đến mục tương ứng trong tài liệu đặc tả yêu cầu.
• Ngữ nghĩa thống nhất của bảy mô hình: sử dụng YAML M1, M2, M3, M5, M6, M7 và MU để mô tả đối tượng, hành vi, quy tắc, chủ thể, quy trình, truy vấn báo cáo và UI.
• Kiểm soát xác nhận thủ công: các giai đoạn từ giai đoạn 0 đến giai đoạn 7 của quá trình khám phá yêu cầu đều phải được con người xác nhận trước khi tiếp tục.
• Nền tảng công nghệ tích hợp: code-paas cung cấp nền tảng ứng dụng đơn thể với Flask, SQLite, React và TypeScript, đồng thời bao gồm quản trị hệ thống, công cụ quy trình, bàn làm việc và sổ đăng ký ontology.
• Tương tác AI nguyên bản: ứng dụng được tạo ra bắt buộc phải có hộp thoại AI ở bên phải, hỗ trợ nạp sổ đăng ký ontology, gọi công cụ, phản hồi dạng luồng SSE và ranh giới an toàn SQL chỉ đọc.
• Tương thích nhiều công cụ: có thể sử dụng với WorkBuddy, Claude Code, Codex, Cursor, Aider, Cline và các Agent phổ dụng có khả năng tải chỉ dẫn dự án.

Nội dung chính trong kho mã

• SKILL.md: định nghĩa phương pháp luận, quy trình ba giai đoạn và kỷ luật thực thi bắt buộc.
• references/: chứa quy chuẩn viết yêu cầu, khung mô hình hóa ontology, hướng dẫn phát triển từ mô hình đến triển khai, kiến trúc kỹ thuật AI nguyên bản và quy chuẩn UI/UE.
• reference-example/: ví dụ hoàn chỉnh về quản lý thực hiện hợp đồng bán hàng, bao gồm tài liệu yêu cầu, YAML của bảy mô hình và manifest.json.
• techbase/: mã nguồn code-paas có thể sao chép và mở rộng, bao gồm backend, frontend, ví dụ mô hình và các tệp phụ thuộc.

Chuẩn bị môi trường chạy

Trước khi bắt đầu, hãy xác nhận máy tính có các môi trường sau:

• Python 3.10 trở lên.
• Node.js 18 trở lên.
• Có thể truy cập mạng khi cài đặt các phụ thuộc Python và frontend lần đầu.

Backend sử dụng Flask và SQLite, frontend sử dụng React, TypeScript và Vite. Dự án áp dụng MIT License, cho phép tự do sử dụng, chỉnh sửa và phân phối lại.

Cài đặt vào công cụ phát triển AI

Cài đặt vào Claude Code

Claude Code có thể tự động phát hiện SKILL.md trong thư mục kỹ năng. Có thể cài đặt ở cấp người dùng để mọi dự án đều sử dụng được:

cp -r ontology-driven-dev ~/.claude/skills/ontology-driven-dev

Cũng có thể cài đặt vào dự án hiện tại:

cp -r ontology-driven-dev .claude/skills/ontology-driven-dev

Sau khi hoàn tất, Claude Code sẽ dựa trên name và description trong frontmatter của kỹ năng để nhận diện và tải quy trình.

Cài đặt vào WorkBuddy

Lệnh cài đặt ở cấp người dùng như sau:

cp -r ontology-driven-dev ~/.workbuddy/skills/ontology-driven-dev

Nếu chỉ muốn sử dụng trong một dự án, hãy thực hiện:

cp -r ontology-driven-dev <dự án của bạn>/.workbuddy/skills/ontology-driven-dev

Cài đặt vào Codex

Codex không có sổ đăng ký kỹ năng gốc, vì vậy trước tiên cần sao chép kỹ năng vào kho mã:

mkdir -p .codex/skills
cp -r ontology-driven-dev .codex/skills/

Sau đó thêm quy tắc tải vào codex.md hoặc AGENTS.md của dự án:

Khi người dùng muốn thực hiện “phát triển theo ontology, khám phá yêu cầu, mô hình hóa ontology, bảy mô hình, code-paas hoặc ứng dụng AI nguyên bản”, hãy tải .codex/skills/ontology-driven-dev/SKILL.md và tuân thủ nghiêm ngặt quy trình ba giai đoạn cùng cơ chế xác nhận thủ công.

Codex sẽ ánh xạ việc xác nhận thủ công thành câu hỏi tương tác hoặc phê duyệt. Sandbox của Codex cần được kết nối mạng để thực thi npm install và pip install.

Sử dụng với Cursor, Aider hoặc Cline

• Cursor: đưa nội dung của SKILL.md vào quy tắc dự án hoặc .cursorrules.
• Cline, Aider: dán SKILL.md khi bắt đầu phiên làm việc hoặc yêu cầu rõ Agent tải tệp từ đường dẫn đó.
• Agent khác: nạp tệp này vào ngữ cảnh dưới dạng chỉ dẫn hệ thống hoặc bộ nhớ dự án.

Giai đoạn 1: Khám phá và xác nhận yêu cầu

Giai đoạn đầu tiên dựa trên references/AI需求探索与确认提示词V9.0.md, chuyển đổi mô tả nghiệp vụ ban đầu thành tài liệu đặc tả yêu cầu phần mềm chính thức.

Bạn có thể nhập cho Agent chỉ dẫn tương tự:

Hãy giúp tôi phát triển một hệ thống quản lý thực hiện hợp đồng bán hàng, cần quản lý hợp đồng, thu hồi công nợ, giao hàng và phê duyệt.

Agent cần lần lượt tiến hành theo tám giai đoạn sau:

1. Hiểu tổng thể.
2. Đối tượng nghiệp vụ.
3. Chức năng và quy tắc nghiệp vụ.
4. Liên kết giữa các đối tượng.
5. Phối hợp đầu cuối và quy trình phê duyệt.
6. Truy vấn, thống kê và báo cáo.
7. Vai trò và quyền hạn.
8. Nguyên mẫu UI, có thể lựa chọn tùy nhu cầu.

Sau mỗi giai đoạn, Agent phải yêu cầu xác nhận theo định dạng “câu hỏi, đề xuất của AI, lý do, lựa chọn khác, phản hồi nhanh” và tạm dừng chờ quyết định của bạn. Nội dung loại B dành riêng cho doanh nghiệp cũng phải được hỏi rõ; khi chưa xác nhận thì không được chuyển sang giai đoạn tiếp theo.

Giai đoạn này cuối cùng tạo ra:

<miền nghiệp vụ>-需求规格说明书-V9.md

Phụ lục C của tài liệu là cơ sở đầu vào cho việc mô hình hóa bảy mô hình ở giai đoạn tiếp theo. Vì vậy cần đặc biệt kiểm tra tính đầy đủ của đối tượng nghiệp vụ, quy trình, quy tắc, vai trò và báo cáo.

Giai đoạn 2: Tạo YAML của bảy mô hình

Sau khi yêu cầu được xác nhận, Agent xây dựng mô hình ontology dựa trên references/ontology_modeling_framework_v9.md và Phụ lục C của tài liệu yêu cầu. Lúc này đầu vào đã là cơ sở xác định, không nên phân rã lại nghiệp vụ trên diện rộng.

Nếu đã có tài liệu đặc tả yêu cầu đáp ứng đầy đủ tiêu chuẩn, bạn có thể trực tiếp kích hoạt quy trình chỉ mô hình hóa:

Dựa trên tài liệu đặc tả yêu cầu này, hãy mô hình hóa ontology và xuất YAML của bảy mô hình cùng manifest.json.

Nội dung xuất vào thư mục yaml/ bao gồm:

• M1 - mô hình đối tượng: mô tả các đối tượng nghiệp vụ.
• M2 - mô hình hành vi: mô tả các hành vi nghiệp vụ.
• M3 - mô hình quy tắc: mô tả các quy tắc nghiệp vụ.
• M5 - mô hình chủ thể: mô tả vai trò và các chủ thể liên quan.
• M6 - mô hình quy trình: mô tả quy trình nghiệp vụ.
• M7 - mô hình truy vấn báo cáo: mô tả truy vấn và báo cáo.
• MU - mô hình UI: mô tả giao diện người dùng.
• manifest.json: ghi lại danh mục mô hình.

Sau khi hoàn tất mô hình hóa, cần thực hiện kiểm tra tính nhất quán, tối thiểu bao gồm khả năng truy xuất nguồn gốc yêu cầu, quan hệ một-một giữa M7 và M2, cũng như bảo đảm các tham chiếu của M6 không tạo chu trình. Khi phát hiện điểm không nhất quán, cần sửa mô hình trước rồi mới chuyển sang giai đoạn xây dựng mã.

Giai đoạn 3: Xây dựng hệ thống BS chạy được

Sao chép nền tảng công nghệ code-paas

Sao chép toàn bộ techbase/ trong thư mục kỹ năng vào code-app/ của dự án hiện tại:

cp -r <thư mục gốc của kỹ năng>/techbase/. <dự án hiện tại>/code-app/
cd <dự án hiện tại>/code-app/frontend && npm install
cd <dự án hiện tại>/code-app/backend && pip install -r requirements.txt

Khi phát triển chính thức, cần dùng YAML của bảy mô hình được tạo ở giai đoạn 2 để thay thế các YAML mẫu trong nền tảng.

Triển khai theo thứ tự mười bước

1. Ghi hoặc sắp xếp YAML của bảy mô hình.
2. Tạo DDL và các bảng cơ sở dữ liệu.
3. Đăng ký từ điển dữ liệu.
4. Triển khai dịch vụ hành vi và quy tắc.
5. Ghi dữ liệu hạt giống cho vai trò và quyền hạn.
6. Tích hợp công cụ quy trình.
7. Tạo menu, trang và route.
8. Triển khai hộp thoại AI bên phải.
9. Kiểm thử tích hợp toàn tuyến frontend-backend.
10. Nghiệm thu dựa trên yêu cầu và mô hình.

Hộp thoại AI bên phải là thành phần bắt buộc, không được bỏ qua trong quá trình phát triển. Hộp thoại phải tuân thủ cơ chế nạp sổ đăng ký ontology, gọi công cụ, truyền dữ liệu dạng luồng SSE và ranh giới an toàn SQL chỉ đọc được định nghĩa trong dự án.

Khởi động backend và frontend

Khởi động backend Flask:

cd code-app/backend
pip install -r requirements.txt
python app.py

Địa chỉ mặc định của backend là http://localhost:5000.

Mở một terminal khác để khởi động máy chủ phát triển frontend:

cd code-app/frontend
npm install
npm run dev

Địa chỉ mặc định của frontend là http://localhost:5173. Tài khoản mặc định là admin, mật khẩu mặc định là admin123; xem techbase/README.md để biết thêm chi tiết vận hành nền tảng.

Các cách kích hoạt thường dùng

Tùy theo đầu vào và mục tiêu hiện có, có thể sử dụng các câu lệnh kích hoạt khác nhau.

Phát triển đầy đủ từ yêu cầu

Hãy giúp tôi phát triển một hệ thống quản lý sửa chữa thiết bị, tuân thủ nghiêm ngặt quy trình phát triển theo ontology và chờ tôi xác nhận ở từng giai đoạn khám phá yêu cầu.

Chỉ mô hình hóa ontology

Dựa trên tài liệu đặc tả yêu cầu này để mô hình hóa ontology, xuất M1, M2, M3, M5, M6, M7, MU và manifest.json.

Xây dựng ứng dụng dựa trên mô hình hiện có

Dựa trên các YAML của bảy mô hình này để tạo hệ thống, sử dụng nền tảng code-paas và hoàn tất kiểm thử tích hợp frontend-backend.

Các từ khóa như “phát triển theo ontology”, “khám phá yêu cầu”, “mô hình hóa ontology”, “bảy mô hình”, “code-paas”, “ứng dụng AI nguyên bản” và “phát triển hệ thống nghiệp vụ” cũng có thể giúp Agent nhận diện kỹ năng.

Khuyến nghị thực hành nâng cao

Không bỏ qua cơ chế xác nhận thủ công

Ngay cả khi yêu cầu ban đầu có vẻ đầy đủ, cũng không nên yêu cầu Agent tạo hệ thống ngay trong một lần. Xác nhận theo từng giai đoạn giúp sớm phát hiện các vấn đề về ranh giới đối tượng, nút phê duyệt, phạm vi quyền hạn và tiêu chí thống kê.

Dùng Phụ lục C làm ranh giới mô hình hóa

Giai đoạn 2 phải lấy Phụ lục C của tài liệu yêu cầu làm đầu vào xác định. Nếu phát hiện nội dung nghiệp vụ quan trọng còn thiếu trong lúc mô hình hóa, cần quay lại giai đoạn yêu cầu để bổ sung và xác nhận, thay vì để mô hình tự mở rộng phạm vi nghiệp vụ chưa được xác nhận.

Ưu tiên kiểm tra các tham chiếu giữa mô hình

Trước khi bắt đầu xây dựng mã, hãy tập trung kiểm tra mối quan hệ tương ứng giữa M7 và M2, mối quan hệ tham chiếu của M6, cũng như khả năng truy xuất từ các hạng mục yêu cầu đến các phần tử mô hình. Nếu lỗi ở tầng mô hình lọt vào cơ sở dữ liệu, giao diện API và trang giao diện, chi phí phối hợp và gỡ lỗi ở các giai đoạn sau sẽ tăng lên.

Giữ lại ví dụ chuẩn để đối chiếu

reference-example/ cung cấp một ví dụ hoàn chỉnh về quản lý thực thi hợp đồng bán hàng. Khi sử dụng lần đầu, bạn có thể đối chiếu với tài liệu đặc tả yêu cầu, bảy tệp YAML mô hình và manifest.json trong đó để hiểu cách các sản phẩm đầu ra ở từng giai đoạn kết nối với nhau.

Thay thế mô hình trước, mở rộng nền tảng sau

Các tệp trong techbase/models/ là những mô hình mẫu. Đối với dự án chính thức, trước hết hãy đưa bảy tệp YAML mô hình của riêng dự án vào, sau đó mở rộng dịch vụ backend, quyền hạn, quy trình, menu và trang theo quy trình mười bước từ mô hình đến triển khai. Tránh sửa đổi trực tiếp mã nghiệp vụ xoay quanh dữ liệu mẫu.

Kết luận

ontology-driven-dev kết nối việc làm rõ yêu cầu, lập mô hình ontology và triển khai ứng dụng thành một chuỗi phát triển có các cổng kiểm soát thủ công. Chìa khóa để sử dụng đúng là luôn xác nhận yêu cầu trước, sau đó kiểm tra tính nhất quán của bảy mô hình, cuối cùng xây dựng và nghiệm thu dựa trên code-paas. Nhờ đó, vừa có thể tận dụng AI để nâng cao hiệu suất phát triển hệ thống nghiệp vụ, vừa duy trì được nguồn ngữ nghĩa rõ ràng và mối quan hệ truy xuất đầy đủ với các yêu cầu.