# QUY ƯỚC TRAO ĐỔI — Ban điều hành ⇄ Trợ lý (Claude)

Mục đích: hai bên nói chuyện được với nhau mà không lẫn kênh, không thất lạc, và mọi trao đổi đều
truy vết được. Áp dụng cho mọi agent làm việc qua API/MCP.

---

## 1. Kênh nào dùng cho việc gì

| Việc cần làm | Dùng kênh | Ai tạo | Công cụ |
|---|---|---|---|
| Giao việc / hỏi / xin duyệt | **Yêu cầu** (`/requests`) | cả hai | `vietal_ask`, `vietal_answer_request` |
| Trả lời, xin thêm thông tin, báo vướng | **Yêu cầu** (trả lời trong cùng id) | cả hai | `vietal_answer_request` |
| Ghi cuộc họp, tập huấn, báo cáo đã/ sẽ diễn ra | **Sự kiện** (Lịch) | cả hai | `vietal_add_event` |
| Trao đổi ngắn, hỏi nhanh trong ngày | **Trao đổi** (`/chat`) | người | — |
| Dán biên bản, email, báo cáo thô để bóc thành cập nhật | **Tiếp nhận** (`/intake`) | cả hai | `vietal_intake` |
| Dấu vết kỹ thuật (đã gọi gì, mất bao lâu) | **Nhật ký** (tự động) | hệ thống | `vietal_log` |

**Quy tắc một dòng: cần người trả lời thì dùng Yêu cầu; chỉ cần ghi vào lịch thì dùng Sự kiện.**
Dùng sự kiện để trả lời câu hỏi là sai kênh — người sẽ không thấy và không ai trả lời.

---

## 2. Quy ước đặt tiêu đề

| Tiền tố | Nghĩa | Ai dùng |
|---|---|---|
| `[Hỏi]` | cần thông tin để làm tiếp | agent, người |
| `[Chặn]` | đang bị chặn, cần quyết ngay | agent |
| `[Duyệt]` | xin duyệt kết quả / đề xuất | agent |
| `[Báo cáo]` | báo cáo định kỳ, không cần trả lời gấp | agent |
| `[Bắt tay]` | kiểm tra kênh, xác nhận đã nhận | cả hai |

Ví dụ tốt: `[Hỏi] A1.3 — 20 ca bệnh đầu tiên lấy từ khoa nào?`
Ví dụ xấu: `Hỏi chút` (không biết việc nào, không biết mức khẩn).

---

## 3. Nhịp trao đổi

1. **Mỗi yêu cầu một chủ đề.** Không gộp ba câu hỏi khác nhau vào một yêu cầu.
2. **Trả lời trong đúng yêu cầu đó**, không mở yêu cầu mới để trả lời (mất mạch, mất liên kết).
3. **Gắn mã việc** (`task_id`) khi câu hỏi liên quan tới một việc cụ thể.
4. **Một lượt = một lần trả lời.** Cần hỏi tiếp thì trả lời tiếp trong cùng yêu cầu.
5. **Đóng khi xong:** người tạo yêu cầu đóng (`status = closed`); agent không tự đóng yêu cầu của mình.
6. **Không xoá** yêu cầu đã có trả lời — đó là bản ghi kiểm toán.

---

## 4. Câu trả lời phải đủ 4 phần

Mọi câu trả lời của agent (và nên áp dụng cả phía người):

1. **Kết luận ngắn** (1–2 câu).
2. **Căn cứ**: mã việc, số liệu, `document_id` hoặc bản ghi nguồn. Không có căn cứ thì nói rõ "chưa có dữ liệu".
3. **Đề xuất bước tiếp theo** (nếu có).
4. **Câu hỏi ngược** (nếu cần) — đặt đúng chỗ, không đoán.

---

## 5. Mẫu câu cho Ban điều hành

- Giao việc: «[Hỏi] A1.3 — chọn 5 ca bệnh đầu tiên thuộc nhóm hô hấp, kèm căn cứ chọn. Trả lời trong yêu cầu này.»
- Xin báo cáo: «[Báo cáo] Tình hình tuần 43: việc xong, việc quá hạn, rủi ro. Số liệu lấy từ hệ thống, nêu mã việc.»
- Duyệt: «[Duyệt] Đồng ý phương án; triển khai và nộp minh chứng vào A1.2.1.»
- Yêu cầu làm rõ: «Trả lời chưa rõ chỗ chi phí: 1.200 EUR là đặt cọc hay thanh toán đủ? Nêu chứng từ.»
- Bắt tay: «[Bắt tay] Xác nhận bạn đọc được dữ liệu: cho biết tổng số việc, tiến độ tổng, mốc đang chạy.»

## 6. Mẫu câu cho agent (Claude)

- Bắt đầu lượt: gọi `vietal_workspace` → đọc mục `requests` (yêu cầu `to_agent`, `open`) → xử lý từ trên xuống.
- Trả lời: `vietal_answer_request {request_id, answer, status: "answered"}` — nội dung theo mục 4.
- Cần thêm thông tin: `vietal_ask {title: "[Hỏi] …", body, task_id, kind: "question"}`.
- Bị chặn: `vietal_ask {title: "[Chặn] …", kind: "blocker", priority: "high"}`.
- Xong một việc: `vietal_submit_deliverable` + `vietal_log` + `vietal_release_task`.

---

## 7. Thời hạn phản hồi (thoả thuận nội bộ)

| Tình huống | Phía người | Phía agent |
|---|---|---|
| Câu hỏi thường | trong 1 ngày làm việc | ngay trong lượt chạy kế tiếp |
| `[Chặn]` | trong 4 giờ làm việc | báo lại và chờ, không tự quyết |
| `[Duyệt]` | trong 2 ngày làm việc | không tự duyệt kết quả của mình |
| Báo cáo định kỳ | theo lịch COPIL | trước hạn 3 ngày |

Agent không chạy nền: yêu cầu nằm chờ cho tới lượt làm việc kế tiếp. Muốn thúc, người mở Claude và
yêu cầu đọc hộp thư yêu cầu.

---

## 8. Điều cấm

- Dùng **sự kiện** để trả lời câu hỏi (sai kênh, không ai thấy).
- Mở yêu cầu trùng nội dung khi đã có yêu cầu đang mở.
- Tự đóng yêu cầu của chính mình, tự duyệt kết quả của chính mình.
- Ghi số liệu không có căn cứ; sửa số của người khác mà không nêu lý do.
- Xoá yêu cầu, sự kiện, minh chứng đã ghi.

---

## 9. Kiểm chứng một cuộc trao đổi

1. `/requests` — thấy yêu cầu, trạng thái, người trả lời.
2. Nhật ký — thấy `agent.request`, `request.answer` kèm tên agent.
3. Sự kiện loại `audit` — giữ **nguyên văn** nội dung hai bên đã gửi (không dịch, không tóm tắt).
4. `vietal_list_requests {status: "open", direction: "to_agent"}` — kiểm tra từ phía agent.

---

*Tài liệu này đọc được từ ngoài: `https://dv.badt.vn/project/docs/trao-doi` (bản thô: `.md`).
Agent đọc bằng `vietal_read_tech_doc {slug: "trao-doi"}`.*
