Hướng dẫn Lập trình Hệ thống EdTech cho AI Agent

Tài liệu này là Coding Guideline (Sổ tay Code) dành cho AI Agent khi tiến hành viết code (Frontend, Backend, Prompts) cho hệ thống EdTech (Synvia).

---

1. Stack Công nghệ và Kiến trúc

  • Backend: Django (Python), PostgreSQL. Ưu tiên "Modular Monolith" (Các module rõ ràng nhưng chung một codebase) thay vì Microservices để giảm độ phức tạp vận hành.
  • Frontend: HTML, CSS thuần, HTMX, Alpine.js.
  • Tại sao? Theo Chương 13 (Công bằng tiếp cận), hệ thống phải chạy mượt ở những khu vực mạng yếu (Low-bandwidth). HTMX giúp truyền tải HTML nhẹ nhàng, không yêu cầu load các thư viện JS nặng (như React/Angular), giúp học sinh ở vùng sâu vùng xa vẫn tiếp cận được.
  • AI Integration: Giao tiếp qua API của các LLMs. Mọi request phải gọi qua một lớp Wrapper để dễ dàng thay đổi Provider và lưu log.

---

2. Tiêu chuẩn Code UI/UX (Frontend)

Khi code các giao diện (Template HTML/CSS) cho Học sinh và Giáo viên, AI Agent bắt buộc phải tuân thủ các quy tắc Khoa học nhận thức (Chương 8):

Coherence Principle (Nguyên tắc mạch lạc)

  • CẤM: Thêm các yếu tố hình ảnh (illustrations, avatars), âm thanh, hoặc animation không phục vụ trực tiếp cho quá trình học. (Effect size của việc làm này là d = 0.86, cực kỳ quan trọng).
  • YÊU CẦU: UI phải Minimalist, tĩnh lặng. Gamification (Badges, Leaderboard) chỉ sử dụng rất cẩn trọng ở cấp độ Class, không làm rối màn hình chính bài học.

Intentional Friction (Khó khăn có chủ đích)

  • Không tối ưu hóa UI để "Click nhanh nhất có thể" (One-click solution).
  • Nếu học sinh bấm xem Hint, UI cần có 1 khoảng delay (vd: 3 giây) hoặc bắt học sinh tự điền nháp (Generation) trước khi hiển thị Hint.

---

3. Tiêu chuẩn Code Backend (Django)

Xử lý Dữ liệu (Privacy & Data)

  • Data Minimization: Khi tạo các Models mới (Django ORM), tuyệt đối không thêm các fields như geolocation_tracking, emotion_status, keystrokes_raw nếu không có business logic rõ ràng và consent.
  • Glass Box AI: Bất kỳ Model nào lưu kết quả chấm điểm của AI (vd: AI_Grade) bắt buộc phải có kèm một field:
  ai_reasoning = models.TextField(help_text="Lưu lại lý do tại sao AI đưa ra điểm số này để GV có thể audit.")
  human_override = models.BooleanField(default=False, help_text="True nếu GV đã ghi đè kết quả của AI.")
  human_grade = models.FloatField(null=True, blank=True)

Xử lý Đánh giá & Bài tập (Assessment)

  • Không dùng kiến trúc Is_Done = True đơn giản. Cần thiết kế Attempts table để học sinh có thể làm lại nhiều lần (Mastery Learning).
  • Bổ sung logic lưu trữ các dạng Spaced Repetition (FSRS):
  next_review_date = models.DateTimeField(null=True, blank=True)
  retention_score = models.FloatField(default=0.0)

---

4. Tiêu chuẩn Viết LLM Prompts (Prompt Engineering)

Đây là ranh giới giữa một EdTech tốt và EdTech gây hại. Mọi System Prompt tích hợp vào logic code của Synvia phải theo nguyên tắc sau:

Không bao giờ cho đáp án (No-Spoil Rule)

  • SAI: "Bạn là một trợ lý ảo. Hãy giải bài toán sau cho học sinh."
  • ĐÚNG: "Bạn là một AI Socratic Tutor. Bạn tuyệt đối KHÔNG ĐƯỢC cung cấp đáp án cuối cùng. Khi học sinh hỏi, hãy xác định bước nào họ đang vướng mắc và đưa ra một câu hỏi gợi mở để họ tự nhận ra."

Xử lý Ảo giác (Hallucination Control)

  • Phải luôn có escape hatch trong prompt: "Nếu bạn không chắc chắn 100% về kiến thức, hãy yêu cầu học sinh hỏi giáo viên."

Buộc học sinh giải thích (Self-Explanation Prompting)

  • Khi AI chấm bài xong, có thể code thêm logic để prompt AI hỏi ngược lại học sinh: "Em có thể giải thích tại sao em lại làm bước 2 như thế này không?" trước khi đưa điểm.

---

5. Tiêu chuẩn Test và Đo lường

  • Đo lường Transfer, không đo Engagement: Đừng chỉ viết các SQL queries đo MAU (Monthly Active Users) hay Time-on-app.
  • AI Agent cần viết các queries phân tích để đo lường:

    • 1. Tỷ lệ nhớ lại (Retention Rate) sau X tuần. 2. Độ lệch chuẩn giữa tự tin và kết quả (Calibration Error). 3. Mức độ can thiệp của Giáo viên (Tỷ lệ human_override cao tức là AI đang làm sai nhiều, cần audit).