Appearance
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ớp | Ngôn ngữ | Path | Đối tượng | Thẩ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 English | docs/ (VitePress), governance/, specs/ (và nested */specs/) | Owner, Agent, specialist, developer | Nguồ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
- 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). - Site VitePress chạy trực tiếp từ
docs/(npm run docs:devở hub). - Không dùng prefix URL
/vi/. - Approval records trong
.minap/work-items/tham chiếu path + hash của artifact dướidocs//specs/. - Nhãn sidebar dùng dấu chấm cuối (
01.,02.; nhómA./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
- Template Spec Kit giữ cấu trúc section chuẩn Spec Kit (heading bắt buộc, thứ tự User Story / AC / …).
- 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.
- Nhãn cấu trúc kỹ thuật có thể giữ English khi là convention Spec Kit (
Given/When/Then,Priority: P1, statusDraft, …) — phần giải thích đi kèm bằng tiếng Việt. 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 baselineQuy tắc:
- Đủ ba field, thứ tự Version → Date → Status.
- Nhãn luôn
Version,Date,Status(English). - Một field một dòng — không gộp pipe trên một dòng.
Datedùng ISOYYYY-MM-DD.Statusvocabulary:Working baseline|DECIDED|PROPOSED|Discovery proposal|Draft template.- 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:
- Nói với Owner bằng tiếng Việt (giữ thuật ngữ English: Gate 1A, AC, Spec Kit, …).
- Hỏi một câu mỗi lượt.
- 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ạngk/N(ví dụCâu 2/5hoặcGAP/QA 2/5) và số câu còn lại. Nếu phải đổiNgiữa vòng thì báo trước câu tiếp. Không bắt buộc đúng wording nhãn. - 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 đó. - Đợi trả lời rồi mới hỏi tiếp.
- 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. - Khoảng năm câu clarify mỗi vòng khi discovery kiểu Spec Kit clarify.
- 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).
- Chat không thay approval durable Gate — vẫn ghi
.minap/work-items/<id>/approvals/.OK/YESchỉ chốt đề xuất của lượt hỏi đó. - Chi tiết agent-facing:
platform-airule25-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:
- Sửa một lần trên file dưới
docs/(SoT). - Cập nhật
map.md/document-index.md/ mapping / glossary / nav sidebar nếu cần. - Báo lại Owner những file đã đổi.
Browser site
bash
npm run docs:install
npm run docs:devBuild: npm run docs:build (output docs/.vitepress/dist).