Cách đọc và quản trị bộ tài liệu

Trạng thái: Đề xuất giải pháp | Phiên bản tài liệu: 1.0 | Cập nhật: 08/10/2026

Một nguồn nội dung, hai cách đọc

Người dùng đọc qua website. Nhân viên kỹ thuật và AI lập trình đọc các tệp Markdown và đặc tả YAML/JSON trong cùng kho Git. Tránh biên soạn thêm một bản Word/HTML riêng rồi để mỗi bản thay đổi độc lập.

Phân loại thông tin

Nhãn	Ý nghĩa
Đã thống nhất	Quyết định sản phẩm/nguyên tắc đã được chốt trong trao đổi.
Đề xuất thiết kế	Phương án kiến trúc cần rà soát trong thiết kế chi tiết.
Cần xác minh	Thông tin thực tế về hệ thống/API/hợp đồng chưa có bằng chứng kiểm tra.
Đã thay thế	Nội dung không còn hiệu lực, giữ lại để truy vết.

Quy tắc biên tập

• Mỗi phân hệ cần mô tả mục đích – phạm vi – dữ liệu đầu vào – chức năng – đầu ra – kiểm soát – phụ thuộc.
• Mỗi sơ đồ kiến trúc diễn tả thành phần và quan hệ; sơ đồ quy trình diễn tả trạng thái và bước công việc.
• Không tạo endpoint API, tên bảng hay số liệu KPI chưa được xác nhận như thể chúng đang tồn tại.
• Mọi thay đổi quan trọng cần có lý do, người duyệt và lịch sử Git.

Chỉ dẫn cho AI

AI đọc AGENTS.md, trang liên quan và specs/tai-lieu.json. Khi một quy tắc mâu thuẫn với quyết định đã chốt, không âm thầm thay đổi tài liệu mà phải nêu điểm xung đột.

Website là lớp hiển thị; nếu một sơ đồ được chỉnh sửa, mã Mermaid mới là nguồn cần duy trì. Hình PNG là hình tham khảo và cần xuất lại khi thay đổi sơ đồ.