Hướng dẫn cho AI Agent

Hướng dẫn dành cho AI Agent khi dùng Archscribe qua MCP.

Tài liệu này dành cho Agent được người dùng yêu cầu dùng Archscribe với dự án Java Spring Boot. Nguồn đối chiếu là gói npm archscribe@0.2.1. Không suy đoán quyền sử dụng, kết quả hoặc nội dung mã nguồn trước khi đọc chúng.

Chuẩn bị

  1. Xác định đường dẫn gốc dự án có src/main/java và file build Maven hoặc Gradle.
  2. Kiểm tra Node.js 18+, JDK 17+ và java trong PATH.
  3. Nếu chưa có kết nối MCP, hướng dẫn người dùng chạy npx -y archscribe setup và khởi động lại trình AI. Có thể giới hạn bằng --only claude,codex,gemini,opencode,antigravity, chọn các tên thực sự cần. Nếu chỉ dùng CLI, bỏ qua setup.
  4. Không tự ghi đè .mcp.json hoặc skill hiện hữu. npx -y archscribe scaffold /path/to/project chỉ cần khi người dùng muốn cấu hình Claude Code theo dự án.

Đường dùng MCP ưu tiên

  1. Gọi check_environment với đường dẫn dự án và xử lý các lỗi trước khi tạo tài liệu.
  2. Gọi analyze_project để chạy pipeline đầy đủ. Không cần gọi scan_repo trước nếu dùng entry point này.
  3. Đọc các đường dẫn output và thông báo quyền sử dụng trong kết quả tool. Xác nhận file thực sự tồn tại trước khi báo cho người dùng.
  4. Rà soát ca sử dụng, sơ đồ và các chương còn là khung. Nêu rõ phần nào cần người dùng xác nhận. Không tự mô tả bản thảo như tài liệu đã được thẩm định.

Các tool chuyên biệt như propose_uc_groupings, scan_repo và generate_report chỉ dùng khi người dùng cần điều khiển chi tiết hơn. Với generate_report, ưu tiên truyền đường dẫn dự án để tool tự phân tích mã. Không chuyển toàn bộ IR vào cuộc trò chuyện khi không cần. Các chương lý thuyết 1, 2, 4, 5 của bản báo cáo có thể là khung, cần làm tiếp bằng quy trình phù hợp và kiểm tra nội dung. Không gọi tool ghi nội dung nội bộ nếu không thuộc quy trình công khai.

Khi chỉ có CLI

npx -y archscribe doctor /path/to/project
npx -y archscribe run /path/to/project
npx -y archscribe status /path/to/project

Mặc định đầu ra ở <project>/archscribe-output/. Báo cáo DOCX phụ thuộc quyền sử dụng. Nếu cần kích hoạt, đề nghị người dùng tự chạy npx -y archscribe login và nhập key trong giao diện phù hợp. Không yêu cầu họ gửi key vào chat. Không dùng cờ nội bộ hoặc cách bỏ qua license.

Cách báo kết quả

Nêu lệnh hoặc tool đã chạy, đường dẫn file tìm thấy, phần thành công và phần chưa tạo. Phân biệt dữ liệu phân tích được từ mã nguồn với suy luận hoặc nội dung bổ sung của AI. Cảnh báo giới hạn với Maven nhiều module và các endpoint kế thừa. Hướng người dùng tới Quy trình và đầu ra, Cài đặt và FAQ khi cần.