# CLAUDE.md — Hướng Dẫn Vận Hành AI Agent (PO Copilot / Claude Code) Tài liệu này chứa các quy tắc, chỉ dẫn kỹ thuật và lệnh vận hành dành riêng cho **Claude Code / Antigravity** tự đọc và tuân thủ khi hoạt động trong dự án **Phòng Công Nghệ (DarkOffice)**. --- ## 1. Tổng Quan Dự Án & Công Cụ (MCP) Dự án bao gồm giao diện Dashboard quản trị công nghệ và MCP Server (`mcp-darkoffice`) kết nối tới CSDL trạng thái. * **MCP Server**: Đã được cấu hình tự động thông qua `.mcp.json` tại root dự án sau khi chạy script setup. * **Các API chính**: Cấp quyền PO Leader (Quỳnh), PO (Trọng), CIAO (Điện). --- ## 2. Quy Trình Vận Hành Hằng Ngày (Bắt Buộc) AI Agent khi nhận lệnh từ PO phải tuân thủ nghiêm ngặt 2 phiên làm việc: ### 🌅 Lệnh `/start` (Bắt đầu ngày làm việc) Khi PO nói `/start` hoặc báo bắt đầu ngày mới, Agent tự động chạy: 1. **get_my_tasks**: Kéo danh sách task hôm nay từ PMO (bao gồm cả task giải trình `[PMO-ASK]`). 2. **start_daily_session**: Khai báo kế hoạch (`planned_tasks`), mục tiêu (`goals`) và workstream chính lên Daily Board. 3. **log_agent_activity**: Ghi log `check_in` lên hệ thống với tóm tắt khởi tạo phiên. ### 🌌 Lệnh `/end` (Kết thúc ngày làm việc) Khi PO nói `/end` hoặc báo kết thúc ngày, Agent tự động chạy: 1. **Đính kèm code**: Quét các commit Git gần nhất trong ngày (nếu có push code). Gọi `update_task_progress` hoặc `update_task_status` để cập nhật link commit và số hiệu phiên bản lên task tương ứng trên Daily Board. 2. **end_daily_session**: Báo cáo danh sách kết quả (`results`), các blockers gặp phải, tổng số tokens sử dụng, và thời gian chạy. 3. **log_agent_activity**: Ghi log `check_out` lên hệ thống. 4. **Telegram Alert**: Gọi Telegram API để bắn tin nhắn tóm tắt ngắn gọn lên kênh chung `-1004312797013`: ```bash curl -s -X POST "https://api.telegram.org/bot8920874018:AAGHI-CKTwRkvJx8iIWfKepkKZUh3KTyQDQ/sendMessage" -d chat_id="-1004312797013" -d text="[PO ] Đã kết thúc ngày. Kết quả: . Blocker: " ``` 5. **Ghi nhật ký thực chiến**: Đúc rút lỗi kỹ thuật/bài học kinh nghiệm vào file: `session_logs/session_log__.md` (Ví dụ: `session_logs/session_log_quynh_2026-06-30.md`). --- ## 3. Quy Tắc Phát Triển OpenSpec (Mộc bản) Mọi hoạt động code phải đi qua vòng đời OpenSpec: 1. Tạo change proposal: Chạy `openspec-propose` (hoặc tạo folder change tương ứng). Gắn tag `[oc:]` vào task Daily Board. 2. Thực hiện: Code theo các check-list trong `tasks.md` của change. Đồng bộ tiến độ lên Daily Board qua `update_task_progress`. 3. Đóng change: Chạy `openspec-archive-change` + `openspec-sync-specs` và đổi trạng thái task board sang `done`. --- ## 4. Lệnh Build & Deploy Hệ Thống (Build Pipeline) Agent có thể hỗ trợ trigger build/deploy trực tiếp thông qua HTTP API của website (`POST /mcp/api/builds/trigger`): * `nginx`: Chạy kiểm tra và reload Nginx trên Server 1. * `mcp`: Cài đặt package và khởi động lại dịch vụ `mcp-darkoffice`. * `hermes`: Khởi động lại gateway PMO trên Server 3. * `okr`: Git pull và chạy script deploy `./deploy_vps.sh` trên Server 2. --- ## 5. Phong Cách Lập Trình (Coding Style) * **Frontend**: Sử dụng HTML5 semantic, Javascript thuần (Vanilla JS) và CSS thuần (Vanilla CSS) với bảng màu gradient và hiệu ứng kính mờ (glassmorphism) hiện đại. Tránh dùng TailwindCSS trừ khi có chỉ định rõ ràng. * **Trạng thái CSDL**: Chỉ đọc và ghi trạng thái qua các công cụ MCP. Tuyệt đối không chỉnh sửa file trạng thái JSON (`darkoffice_state.json` hay `daily_sessions.json`) bằng tay hoặc ghi đè trực tiếp. * **Bảo mật**: Tuyệt đối không commit file cấu hình chứa API key `.mcp.json` lên GitHub (đã được bỏ qua trong `.gitignore`).