Skip to content

Chính sách ngôn ngữ tài liệu ​

Version: 2.1
Date: 2026-11-21
Status: DECIDED

Mô hình một lớp (SoT duy nhất) ​

LớpNgôn ngữPathĐối tượngThẩm quyền
Tài liệu chuẩn (SoT)Văn xuôi tiếng Việt + thuật ngữ chuyên ngành Englishdocs/ (VitePress), governance/, specs/ (và nested */specs/)Owner, Agent, specialist, developerNguồn chuẩn duy nhất cho implement và Gate

Không còn thư mục docs-site/ và không còn dual-update EN/VI.

Quy tắc ​

  1. Agent và người triển khai đọc và ghi SoT dưới docs/, governance/, và specs/ (cùng quy ước ngôn ngữ bên dưới).
  2. Site VitePress chạy trực tiếp từ docs/ (npm run docs:dev ở hub).
  3. Không dùng prefix URL /vi/.
  4. Approval records trong .minap/work-items/ tham chiếu path + hash của artifact dưới docs/ / specs/.
  5. Nhãn sidebar dùng dấu chấm cuối (01., 02.; nhóm A./B.).

Văn xuôi tiếng Việt + thuật ngữ chuyên ngành English ​

Ngôn ngữ mặc định của trang là tiếng Việt: mô tả, giải thích, hướng dẫn, văn xuôi trong bảng, nhãn sơ đồ thông thường.

Thuật ngữ chuyên ngành / domain giữ English — không ép dịch thành từ Việt làm méo nghĩa.

Giữ English (không đủ liệt kê; bổ sung qua docs/glossary.md khi cần):

  • Tên sản phẩm/platform và vai trò: MINAP, Platform Core, Application A/B/C, Platform SDK, File Service, Orchestrator, Spec Kit, Superpowers, Constitution
  • Governance/status: Gate 1A / 1B / 1C / 4 / 5, DECIDED, PROPOSED, OPEN, DEFERRED, ESTABLISHED, AC, SDD
  • Identity/tenancy: MINAP Account, Personal Workspace, Organization Workspace, membership, entitlement
  • Infra/security: Nginx, Traefik, Docker Swarm, Blue-Green, Keycloak, Infisical, MinIO, S3, R2, Matrix, TLS, webhook
  • Identifier và schema: NanoID, file_id / file_…, acc_…, ws_…, display name, object key, OpenAPI, và token code/path/API khác

Câu xung quanh vẫn tiếng Việt. Ví dụ: “Application dùng File Service; metadata nằm trong DB của File Service.”

Khi không chắc một từ có phải “chuyên ngành”: ưu tiên thuật ngữ English đã dùng trong SoT; gloss ngắn tiếng Việt chỉ khi giúp Owner (ưu tiên glossary hơn đặt tên Việt mới).

Spec Kit / specs ​

  1. Template Spec Kit giữ cấu trúc section chuẩn Spec Kit (heading bắt buộc, thứ tự User Story / AC / …).
  2. Nội dung mô tả (User Story, Why, Independent Test, Edge Cases, Assumptions, …) viết tiếng Việt; thuật ngữ chuyên ngành giữ English.
  3. Nhãn cấu trúc kỹ thuật có thể giữ English khi là convention Spec Kit (Given / When / Then, Priority: P1, status Draft, …) — phần giải thích đi kèm bằng tiếng Việt.
  4. plan.md / tasks.md / ADR / data-model: cùng quy ước (mô tả VI + thuật ngữ EN).

Document metadata block (bắt buộc) ​

Ngay sau H1, ba dòng riêng với nhãn field English:

markdown
**Version:** 1.0  
**Date:** 2026-11-12  
**Status:** Working baseline

Quy tắc:

  1. Đủ ba field, thứ tự Version → Date → Status.
  2. Nhãn luôn Version, Date, Status (English).
  3. Một field một dòng — không gộp pipe trên một dòng.
  4. Date dùng ISO YYYY-MM-DD.
  5. Status vocabulary: Working baseline | DECIDED | PROPOSED | Discovery proposal | Draft template.
  6. Hub pages (map, document-index, glossary, mapping) và index/README stub có thể bỏ block.

Owner Gate / QA trong chat (bắt buộc) ​

Khi Owner xác nhận Gate, clarify, disposition QA, hoặc GAP Discovery trong chat:

  1. Nói với Owner bằng tiếng Việt (giữ thuật ngữ English: Gate 1A, AC, Spec Kit, …).
  2. Hỏi một câu mỗi lượt.
  3. Tiến độ bắt buộc (nội dung): đầu vòng hỏi nêu tổng số câu dự kiến N; mỗi câu ghi tiến độ dạng k/N (ví dụ Câu 2/5 hoặc GAP/QA 2/5) và số câu còn lại. Nếu phải đổi N giữa vòng thì báo trước câu tiếp. Không bắt buộc đúng wording nhãn.
  4. Mỗi GAP/QA (trừ khi chỉ cần Owner tự điền dữ liệu duy nhất): đưa tối thiểu 3 lựa chọn trả lời phù hợp ngữ cảnh; nêu đề xuất của Agent + lý do ngắn (nhãn tiếng Việt/English đều được); Owner có thể trả lời OK / YES để chấp nhận đề xuất đó.
  5. Đợi trả lời rồi mới hỏi tiếp.
  6. Sau mỗi câu trả lời: cập nhật SoT dưới docs/ / specs/ (hoặc artifact Discovery English tương ứng); tóm tắt ngắn lại bằng tiếng Việt những gì đã ghi.
  7. Khoảng năm câu clarify mỗi vòng khi discovery kiểu Spec Kit clarify.
  8. Prompt quyết định Gate: tóm tắt ngắn tiếng Việt + một câu approve/reject/authorize + path/hash artifact (vẫn nên có options + đề xuất khi hữu ích).
  9. Chat không thay approval durable Gate — vẫn ghi .minap/work-items/<id>/approvals/. OK/YES chỉ chốt đề xuất của lượt hỏi đó.
  10. Chi tiết agent-facing: platform-ai rule 25-owner-qa-format.mdc.

Sửa tài liệu từ review site ​

Khi Owner yêu cầu sửa khi đang xem VitePress:

  1. Sửa một lần trên file dưới docs/ (SoT).
  2. Cập nhật map.md / document-index.md / mapping / glossary / nav sidebar nếu cần.
  3. Báo lại Owner những file đã đổi.

Browser site ​

bash
npm run docs:install
npm run docs:dev

Build: npm run docs:build (output docs/.vitepress/dist).

docs/ = SoT duy nhất · văn xuôi tiếng Việt + thuật ngữ chuyên ngành English