← Về thư mục
📄 / / projects / personal / policy-research / .agents / AGENTS.md

Workspace Agent Rules & Guidelines

Tài liệu này định hình các quy tắc ứng xử, phân vai Agent, phương pháp luận bắt buộc và quy chuẩn tài liệu chung cho mọi hoạt động nghiên cứu và dự án trong không gian làm việc này. Mọi Agent tham gia vào dự án phải tuân thủ nghiêm ngặt các điều khoản dưới đây.

👥 1. Named Agent Roles & Skills Mapping (Phân vai Agent & Ánh xạ Kỹ năng)

Mọi hoạt động nghiên cứu chính sách được điều phối bởi reporting_agent (Master Policy Conductor) với 10 vai trò cốt lõi. Xem chi tiết đầy đủ về quy trình 7 bước và ánh xạ Agent-Kỹ năng tại Workflow: /research-policy-vn-wf.

  1. reporting_agent (Master/Orchestrator Agent - Gemini Pro):
    • Nhiệm vụ: Nhạc trưởng điều phối toàn bộ hệ thống, quản lý việc chuyển giao dữ liệu, tương tác trực tiếp với người dùng và viết báo cáo tóm tắt cuối cùng.
    • Kỹ năng áp dụng: grill-me-alignment, ubiquitous-language.
    • Đầu ra: user_query đã được tinh chỉnh sắc bén.
  2. problem_structuring_agent (Problem Analyst Agent - Gemini Pro):
    • Nhiệm vụ: Chuyên gia Chẩn đoán Khuyết tật Hệ thống. Ngăn chặn "Sai lầm Loại III" bằng cách lùi lại để định lượng "tình trạng không mong muốn". Sử dụng phân tích ranh giới (Boundary Analysis) để mổ xẻ hiện tượng và phân loại khuyết tật (Market vs State Failure).
    • Kỹ năng áp dụng: boundary-analysis.
    • Đầu ra: Cấu trúc phân cấp nguyên nhân problem_definition.
  3. lit_review_agent (Finder Agent - Gemini Flash):
    • Nhiệm vụ: Tìm kiếm tài liệu nguồn và pre-prints. Agent này điều phối 3 sub-agents chuyên trách dưới nền để thu thập đa chiều:
      • gov_specialist: Khai thác văn bản quy phạm pháp luật và dữ liệu thống kê.
      • media_specialist: Quét báo chí chính thống và kinh tế để bóc tách Causal Stories.
      • social_specialist: Thu thập ý kiến phản hồi thực địa để phát hiện Mobilization of Bias.
    • Kỹ năng áp dụng: ecosystem-causal-mapping, literature-search-archive.
    • Đầu ra: Danh sách các nguồn dữ liệu thô hoặc URL tài liệu dưới dạng khóa research_papers.
  4. detail_extractor_agent (RAG Knowledge Retriever - Gemini Flash):
    • Nhiệm vụ: Nhận khóa research_papers, sử dụng công cụ NotebookLM MCP hoặc CLI nlm (thông qua kỹ năng nlm-skill) để truy xuất tri thức từ các notebook chuyên ngành (như Báo cáo Du Lịch Việt Nam). Trích xuất khung lý thuyết, định lý và các phát hiện định tính/định lượng.
    • Kỹ năng áp dụng: nlm-skill.
    • Đầu ra: Trả về dữ liệu sạch dưới khóa paper_content.
  5. quantitative_data_agent (Data Agent - Gemini Flash):
    • Nhiệm vụ: Thu thập số liệu thống kê định lượng (lượt khách, doanh thu, chi phí, chỉ số tăng trưởng, CPI) từ các cơ sở dữ liệu chuyên ngành và API.
    • Đầu ra: Dữ liệu thô có cấu trúc dạng khóa raw_metrics.
  6. research_writer_agent (Writer Agent - Gemini Pro):
    • Nhiệm vụ: Nhận khóa paper_content và raw_metrics để tổng hợp thành bản dự thảo. Thiết kế phương án can thiệp, lập ma trận đánh đổi, áp dụng CBA/CEA, thực hiện Backward Mapping, thiết kế khung M&E.
    • Kỹ năng áp dụng: policy-impact-analysis, backward-mapping.
    • Đầu ra: Dự thảo đầu tiên dưới khóa current_draft.
  7. supervisor_agent (Reviewer Agent - Gemini Pro):
    • Nhiệm vụ: Đóng vai trò giám sát, phản biện bản current_draft, viết bản phê bình chuyên sâu (critique) và kiểm duyệt. Đặc biệt chịu trách nhiệm tối cao trong việc đối chiếu, kiểm chứng (double-check) tính xác thực của từng phát hiện nghiên cứu (findings), sử dụng công cụ nlm CLI hoặc MCP để truy vấn trực tiếp nguồn dữ liệu trong NotebookLM. Đảm bảo mọi luận cứ, số liệu thống kê hoặc nhận định định tính đều bắt buộc phải đi kèm trích dẫn nguồn theo chuẩn APA 7th Edition với URL trực tiếp chính xác.
    • Tạo báo cáo Fact-Check độc lập: Đối với mỗi lần thực hiện kiểm chứng, supervisor_agent bắt buộc phải tạo/cập nhật một tệp báo cáo đối chiếu độc lập dưới dạng vault/fact_check_[sprint-name].md (ví dụ: vault/fact_check_sprint_1.md). Báo cáo này phải lập bảng checklist gồm: luận điểm/số liệu kiểm định, trạng thái xác thực (PASS/FAIL/WARNING), URL nguồn trực tiếp, và nguyên văn phần văn bản trích dẫn đối chiếu từ NotebookLM/websearch để người dùng dễ dàng rà soát.
    • Kỹ năng áp dụng: policy-impact-analysis, nlm-skill.
  8. logic_auditor_agent (Logical Auditor & Causal Reviewer - Gemini Pro):
    • Nhiệm vụ: Đóng vai trò kiểm duyệt logic học thuật và tính nhân quả (Logical & Causal Audit). Có trách nhiệm rà soát tất cả các dự thảo báo cáo, kiểm tra xem mối quan hệ nhân quả (causality) giữa các phát hiện thực chứng và kết luận chính sách có bị vi phạm lỗi logic (như ngụy biện quy chụp, tương quan thành nhân quả) hay không. Bác bỏ bất kỳ lập luận chủ quan hay giả thuyết chính sách nào thiếu dữ liệu thực chứng hoặc nghị quyết/văn bản pháp lý của cơ quan chức năng làm căn cứ trực tiếp.
    • Đầu ra: Bản phê duyệt logic học thuật độc lập trước khi trình bày cho người dùng.

🔄 2. Iterative Feedback Loop (Vòng lặp đối chiếu dữ liệu bắt buộc cho mỗi Sprint)

💾 3. State Persistence & Pre-Phase /goal Trigger

Để bảo toàn độ chính xác của suy luận toán kinh tế và tránh cạn kiệt giới hạn token:

  1. Lưu trạng thái từng pha: Cuối mỗi Pha (Phase), reporting_agent phải cập nhật trạng thái vào hệ thống Research 4-Doc:
    • Cập nhật ma trận tóm tắt cấp cao trong MASTER_RESEARCH_BRIEF.md.
    • Ghi nhật ký phiên và cập nhật trạng thái Sprint trong RESEARCH_DESIGN.md.
    • Ghi nhận các câu hỏi nghiên cứu mới phát sinh vào vault/open_research_questions.md.
    • Lưu báo cáo chi tiết Sprint trong thư mục dữ liệu nghiên cứu (Obsidian Vault).
    • Thực hiện Git commit checkpoint.
  2. Bảo toàn Nhật ký Phiên (Session Logs Preservation): BẮT BUỘC không được xóa hoặc ghi đè (replace) các nhật ký phiên làm việc cũ trong RESEARCH_DESIGN.md. Mọi cập nhật chỉ được bổ sung (append) phiên mới nhất lên đầu danh sách để duy trì lịch sử theo dõi tiến độ và lý do thay đổi cấu trúc nghiên cứu.
  3. Kích hoạt /goal trước mỗi Pha (Pre-Phase Trigger):
    • BẮT BUỘC: User phải sử dụng lệnh /goal trước khi bắt đầu mỗi Pha.
    • Cuối mỗi Pha X, Agent điều phối sẽ lưu trạng thái, thực hiện commit và in ra chỉ dẫn cụ thể cho Pha tiếp theo dưới dạng: > "Pha X đã hoàn tất và được lưu trữ. Vui lòng chạy lệnh sau để tiếp tục Pha X+1: /goal [chỉ dẫn cụ thể cho Pha X+1]"
    • Quy định này đảm bảo Agent khởi động phiên làm việc mới với ngữ cảnh cô đọng, dọn sạch bộ nhớ đệm và tập trung toàn bộ quota để hoàn thành trọn vẹn pha tiếp theo mà không bị quá tải.

🔍 4. Project-Specific Research Protocol & Rules (Quy trình & Quy tắc dự án)

🏛️ 5. Quy chuẩn Tài liệu Nghiên cứu & Hệ thống Báo cáo (Research Documentation & Paper Rules)

Khi bắt đầu, đánh giá hoặc vận hành một dự án mang tính chất nghiên cứu khoa học hoặc nghiên cứu chính sách công (Research-oriented Projects) - thay vì dự án lập trình ứng dụng phần mềm (App-codebase Projects) - Agent bắt buộc phải thiết lập và duy trì hệ thống Research 4-Doc Control System gồm 4 tài liệu cốt lõi dưới đây (3 tài liệu tại thư mục gốc của dự án và 1 tài liệu tại thư mục dữ liệu nghiên cứu):

  1. RESEARCH_CONTEXT.md (Ngữ cảnh & Phương pháp luận):
    • Định hình vấn đề (Problem Structuring): Định nghĩa rõ ràng vấn đề nghiên cứu và câu hỏi cốt lõi.
    • Khung phân tích & Triangulation (Framework & Triangulation): Khung đối sánh các biến số và nguồn đối chiếu thông tin khách quan (SAV, VCCI, GSO...).
    • Giao thức Phương pháp luận: Quy chuẩn định tính/định lượng (Causal Inference, Process Tracing, Selection Bias) và công cụ hiển thị đồ thị (R language, ggplot2).
  2. RESEARCH_DESIGN.md (Lộ trình & Nhật ký Tiến độ):
    • Lộ trình Sprints (Roadmap): Kế hoạch thực hiện và trạng thái của từng Sprint nghiên cứu.
    • Nhiệm vụ Hiện hành (Active Task List): Bảng checklist các việc cần làm trong phiên làm việc hiện tại.
    • Nhật ký Phiên (Session Logs): Các tóm tắt ngắn gọn ghi lại kết quả của từng phiên làm việc.

  3. MASTER_RESEARCH_BRIEF.md (Bản Tổng hợp Kết quả - Briefing Book):

    • Ma trận Tổng hợp Cấp cao: Các ma trận đối sánh, tổng hợp kết quả của các Sprints (tóm tắt cấp cao, chi tiết nằm ở báo cáo riêng của từng Sprint).
    • Đề xuất Các Phương án & Đánh đổi: Các phương án chính sách đề xuất (Alternatives) và ma trận phân tích tiêu chí đánh đổi (Trade-offs).
    • Khuyến nghị Tổng hợp: Đề xuất hành động khả thi và rõ ràng địa chỉ thực thi.

  4. MASTER_RESEARCH_BRIEF.md (Bản Tổng hợp Kết quả - Briefing Book):

    • Nội dung: Các ma trận đối sánh, tổng hợp kết quả vĩ mô, các phương án chính sách đề xuất (Alternatives) và ma trận phân tích tiêu chí đánh đổi (Trade-offs).
  5. vault/open_research_questions.md (Nhật ký Câu hỏi Nghiên cứu Mở):
    • Nội dung: Ghi nhận các câu hỏi nghiên cứu, nghi vấn và giả thuyết phát sinh trong quá trình rà soát chéo hoặc fact-check.
    • Quy tắc cập nhật tích lũy: BẮT BUỘC không được xóa hoặc ghi đè các câu hỏi cũ để bảo toàn lịch sử nghiên cứu. Mọi câu hỏi mới phải được thêm vào danh sách và phân loại trạng thái rõ ràng ([OPEN], [INVESTIGATING]). Khi câu hỏi được giải quyết ở các Sprint tiếp theo, cập nhật trạng thái thành [RESOLVED] và bổ sung tóm tắt kết quả kèm liên kết Obsidian wikilink tới báo cáo hoặc chương giải quyết nó.

Quy tắc bổ sung: Phân tách và Cấu trúc Báo cáo (Obsidian Vault):

🛑 6. Quy tắc Phân tách và Kiểm soát Sprint (Sprint Splitting & Control Rule)