AGENTS.md — Quy tắc cho AI Agent dự án CXK

Đọc file này TRƯỚC khi bắt đầu bất kỳ tác vụ nào.

1. Tổng quan & Vai trò

Quy tắc dùng tên:
- ❌ "Tác giả" → ✅ "Nghiên cứu sinh" / "NCS"
- ❌ "Chuyên gia y khoa" → ✅ "CVYK" / "Lương y Vũ Thế Sỹ"
- ❌ Tên cũ nhà bảo trợ → ✅ "Công ty Vaga" (chỉ ở phần bảo trợ)
- ✅ "bác sĩ" — giữ nguyên khi nói chung ("nên đi khám bác sĩ")

2. Ngôn từ & Thuật ngữ (BẮT BUỘC)

• Viết đơn giản (đối tượng: học sinh PTTH), câu ≤25 từ.
• Tiếng Anh chỉ dùng cho tên kỹ thuật, lần đầu kèm giải thích: "bộ lọc an toàn (safety layer)".
• Giọng văn trung tính, khoa học, gần gũi.
• KHÔNG tạo thuật ngữ mới nếu chưa có trong Glossary.

Bảng thuật ngữ chuẩn (hay nhầm nhất)

Đầy đủ → docs/GLOSSARY.md. Ngoại lệ: knowledge-base/sources/ KHÔNG sửa (tài liệu y khoa gốc).

3. Cấu trúc thư mục (6 tầng)

flowchart TB
  ROOT["📁 CXK (Hệ Thống Trợ Lý AI)"]
  T1["📄 T1: Tài liệu & Nghiên cứu
docs/ (Báo cáo, kế hoạch, nhật ký)"]
  T2["🏥 T2: Kho tri thức y khoa
knowledge-base/ (QĐ 361, ĐHYHN, thẻ tri thức)"]
  T3["🛡️ T3: An toàn y khoa
safety/ (Cờ đỏ, rủi ro, phân loại mức độ)"]
  T4["⚙️ T4: Kỹ thuật
backend, frontend, voice, bot, camera"]
  T5["🧪 T5: Kiểm thử & Nghiên cứu NCT
testing/ (Benchmark, user research)"]
  T6["🌱 T6: Vận hành & Cộng đồng
community/, deployment/ (IIS, MSSQL)"]

  ROOT --> T1
  ROOT --> T2
  ROOT --> T3
  ROOT --> T4
  ROOT --> T5
  ROOT --> T6

  style ROOT fill:#006949,stroke:#004d36,color:#ffffff,stroke-width:2px,rx:8,ry:8
  style T1 fill:#e8f5f0,stroke:#006949,stroke-width:1.5px,rx:6,ry:6
  style T2 fill:#e8f5f0,stroke:#006949,stroke-width:2px,rx:6,ry:6
  style T3 fill:#fee2e2,stroke:#b91c1c,stroke-width:2px,rx:6,ry:6
  style T4 fill:#e0f2fe,stroke:#0369a1,stroke-width:1.5px,rx:6,ry:6
  style T5 fill:#f4fae6,stroke:#8cb820,stroke-width:1.5px,rx:6,ry:6
  style T6 fill:#fef3c7,stroke:#b45309,stroke-width:1.5px,rx:6,ry:6
  

Chi tiết → README.md | docs/INDEX.md

4. Quy trình review y khoa & Trạng thái

flowchart LR
  A["🤖 AI Draft
Tạo bản thảo tự động"] --> B["📝 NCS Review
Kiểm tra nguồn & schema"]
  B --> C["🩺 CVYK Review
Thẩm định lâm sàng"]
  C --> D["✅ APPROVED
Phê duyệt chính thức"]
  style A fill:#e0f2fe,stroke:#0369a1,stroke-width:2px,rx:8,ry:8
  style B fill:#fef3c7,stroke:#b45309,stroke-width:2px,rx:8,ry:8
  style C fill:#fff1eb,stroke:#f26121,stroke-width:2px,rx:8,ry:8
  style D fill:#dcfce7,stroke:#15803d,stroke-width:2px,rx:8,ry:8
  

5. Tech Stack & Convention

Convention:
- Tên file: SNAKE_CASE VIẾT HOA, tiếng Việt không dấu (vd: KIEN_TRUC_DU_AN.md)
- Tên file prompt: YYYYMMDD_HHMM_PROMPT_TEN_MO_TA.md — prefix thời gian tạo (UTC+7), lưu tại docs/research/prompts/. Ví dụ: 20260926_0720_PROMPT_CAP_NHAT_TOAN_BO_NCS2_CAMERA.md
- Commit: Tiếng Việt, prefix [module] (vd: [knowledge-base] Thêm 5 KC OA)
- Link nội bộ: Luôn relative path, KHÔNG file:/// hay absolute path

6. Files quan trọng

7. KHÔNG được làm

Y khoa

• ❌ Không chẩn đoán bệnh, kê đơn thuốc, khuyên bỏ thuốc, gợi ý điều trị cụ thể
• ❌ Không sửa nội dung CVYK đã APPROVED mà không có sự đồng ý
• ❌ Không dùng camera để chẩn đoán — chỉ quan sát cử động (movement observation)
• ❌ Không lưu video người dùng — xử lý on-device, chỉ lưu chỉ số
• ✅ Luôn khuyên đi khám khi phát hiện cờ đỏ
• ✅ Luôn trích dẫn nguồn cho thông tin y khoa
• ✅ Luôn cảnh báo "Camera chỉ thấy cử động bên ngoài" khi trả kết quả camera

Ngôn từ & Kỹ thuật

• ❌ Không dùng "Tác giả" — dùng "NCS"
• ❌ Không tạo thuật ngữ mới chưa có trong Glossary
• ❌ Không dùng jargon không giải thích
• ❌ Không dùng absolute path — chỉ relative path
• ❌ Không hardcode paths trong code — dùng Path(__file__) hoặc config
• ❌ Không commit secrets/credentials
• ❌ Không thay đổi schema mà không cập nhật validate_schema.py

8. Encoding (BẮT BUỘC)

Quy tắc: Mọi file .md và .py PHẢI lưu UTF-8 không BOM.

# Đặt ở đầu mọi phiên PowerShell
$env:PYTHONIOENCODING = "utf-8"
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

9. Quản lý file trung gian

Quy tắc: Không lưu file trung gian ở gốc, docs/, hay knowledge-base/.

10. Nhật ký hoạt động (BẮT BUỘC)

NHẬT KÝ ≠ KẾ HOẠCH. Diary ghi sự kiện ĐÃ XẢY RA, không ghi kế hoạch.

Quy trình (cuối phiên hoặc sau mỗi cụm task):
1. Xác định ngày (UTC+7).
2. File docs/diary/YYYY-MM-DD.md: chưa có → tạo theo docs/diary/_template.md; đã có → append (KHÔNG ghi đè).
3. Ghi: file đã tạo/sửa (relative path), tóm tắt 1-2 câu/task, quyết định quan trọng.
4. Nhiều phiên cùng ngày → header ### Phiên [HH:MM] — [Tên].
5. Cập nhật bản viết tay (BẮT BUỘC): Sau mỗi phiên, cập nhật section ✍️ BẢN VIẾT TAY — Phụ lục 3 ở cuối file diary với nội dung tóm tắt toàn ngày theo 6 mục PL3 (mục tiêu, dụng cụ, tiến trình, dữ liệu, lỗi/bài học, kế hoạch). NCS dùng bản này để chép tay vào sổ giấy.

KHÔNG ghi: nội dung y khoa chi tiết, kế hoạch tương lai, conversation ID, thông tin cá nhân.

Format: ✅ Xong | 🔄 Đang làm | ⚠️ Blocker. Mỗi task 1 dòng. Relative path.

11. Quy trình Obsidian & Validate

Workflow thẻ tri thức:

AI draft (Antigravity) → NCS review → Validate schema → CVYK review (Obsidian) → APPROVED

Skill: .agents/skills/cxk-obsidian/ — 7 script: create_kc, validate_schema, check_glossary, update_moc, sync_diary, build_docs_site, audit_vault.

Validate trước Gate:

python tools/check_structure.py    # cấu trúc thư mục
python tools/validate_schema.py    # schema thẻ tri thức
python tools/check_glossary.py     # thuật ngữ
python .agents/skills/cxk-obsidian/scripts/audit_vault.py  # audit vault

12. Checklist cuối phiên (BẮT BUỘC)

AI agent PHẢI thực hiện trước khi kết thúc phiên:

• [ ] Liệt kê file đã tạo/sửa
• [ ] Xoá file tạm, chuyển script hữu ích vào tools/
• [ ] Kiểm tra không có .py sai vị trí (gốc, docs/, knowledge-base/)
• [ ] python tools/check_structure.py — sửa HIGH ngay, MEDIUM nếu đang sửa file
• [ ] python tools/check_glossary.py — sửa HIGH ngay
• [ ] Ghi diary docs/diary/ (xem Section 10)
• [ ] Cập nhật docs/INDEX.md nếu thay đổi cấu trúc docs/ (đổi tên, di chuyển, tạo/xóa thư mục, tạo file quan trọng mới → sửa Section 5+7, tăng version, scan broken links)
• [ ] Báo cáo tóm tắt cho NCS

Cập nhật lần cuối: 26/09/2026
Phiên bản: 2.1