Hướng dẫn sử dụng
Supergraph

Supergraph là gì?

Supergraph là một plugin dành cho các AI coding agent (Claude Code, Antigravity CLI, Codex CLI, OpenCode), kết hợp ba công cụ mạnh mẽ thành một hệ thống nhất:

Workflow bắt buộc: scan → analyze → plan → TDD → execute → fix → verify → review. Serena là tuỳ chọn để bổ sung LSP references và diagnostics. Trên Windows, hook tự tìm Git Bash theo cả đường dẫn system-wide và user-level; nếu không có, hook báo Git Bash not found — hooks skipped và thoát non-blocking.

Cài đặt nhanh

Hỗ trợ Claude Code, Antigravity CLI, Codex CLI và OpenCode. Chọn nền tảng bạn đang dùng.

Cách 1 — Claude Code

# Cài từ Git marketplace (khuyến nghị)
/plugin marketplace add https://github.com/datit309/supergraph.git
/plugin install supergraph

# Cập nhật sau này
/plugin marketplace update supergraph

Cách 2 — Antigravity CLI

git clone https://github.com/datit309/supergraph.git
cd supergraph
# Cài file plugin cho Antigravity
plugins/supergraph/install.sh --platform antigravity

Cách 3 — Codex CLI

# Thêm marketplace + cài plugin (khuyến nghị)
codex plugin marketplace add datit309/supergraph
codex plugin install supergraph

# Cập nhật sau này
codex plugin marketplace upgrade supergraph

# Hoặc cài thủ công từ checkout local
git clone https://github.com/datit309/supergraph.git
cd supergraph
plugins/supergraph/install.sh --platform codex

Cách 4 — OpenCode

git clone https://github.com/datit309/supergraph.git
cd supergraph

# Symlink skills + in snippet opencode.json
plugins/supergraph/install.sh --platform opencode

# Cài MCP
pip install codebase-memory-mcp==0.9.0

# Lần chạy đầu
/supergraph:scan

Installer symlink từng skill vào .opencode/skills/<name>, copy OPENCODE.md vào project root, và in snippet để thêm vào opencode.json:

{
  "instructions": ["OPENCODE.md"],
  "mcp": {
    "codebase-memory-mcp": { "type": "stdio", "command": "codebase-memory-mcp", "args": [] },
    "serena": { "type": "stdio", "command": "serena", "args": ["start-mcp-server", "--context=opencode", "--project-from-cwd"] }
  }
}

OpenCode dùng OPENCODE.md cho project instructions. Skills và MCP chạy ngay. Hooks không có trên OpenCode (nền tảng này dùng mô hình plugin JS/TS).

Cách gọi skill: dùng /skills, rồi chọn scan, plan, tdd, v.v. Không dùng /supergraph:* trong OpenCode.

Thiết lập Codebase Memory MCP (mọi nền tảng)

pip install codebase-memory-mcp==0.9.0
codebase-memory-mcp cli index_repository --repo-path "$(pwd)" --name supergraph --mode moderate

Danh sách Skills

Tất cả skill đều dùng tiền tố /supergraph: để tránh xung đột. Dưới đây là toàn bộ skill được phân nhóm theo chức năng.

🔧 Quy trình chính

🐛 Gỡ lỗi & Điều tra

📋 Lập kế hoạch & Yêu cầu

💼 Phiên & Năng suất

🎯 Chuyên biệt

Quy trình từ phiên làm việc đến merge

Supergraph tuân theo một luồng công việc chặt chẽ. Mỗi bước đều bắt buộc — không được bỏ qua.

Phân tích Codebase Graph

Dựa trên codebase-memory-mcp, Supergraph ánh xạ toàn bộ codebase thành đồ thị liên kết — giúp hiểu rõ rủi ro trước khi chạm vào code.

Tích hợp Serena LSP

Serena cung cấp trí tuệ code cấp IDE, bổ sung cho phân tích graph ở cấp symbol.

Dùng /supergraph:serena trước khi refactor phức tạp (rename xuyên codebase, thay đổi API signature), khi blast radius chưa rõ ở cấp symbol, hoặc sau thay đổi kiến trúc để kiểm tra không còn tham chiếu mồ côi.

Agents — Ai làm gì?

Agents là các thực thể khép kín, chỉ nhận ngữ cảnh liên quan, không có lịch sử phiên.

Hooks — Nhắc nhở tự động

Skills được gọi thủ công. Hooks tự chèn nhắc nhở dựa trên tín hiệu — không gây nhiễu, chỉ kích hoạt khi có tín hiệu rõ ràng.

Bật chế độ Caveman vĩnh viễn

# Lưu vào .supergraph-env — giữ qua các phiên
echo "SUPERGRAPH_CAVEMAN=true" >> .supergraph-env

11 quy tắc bắt buộc

Đây là các quy tắc không thể thương lượng. Vi phạm bất kỳ quy tắc nào sẽ dẫn đến code bị chặn hoặc phiên bị dừng.

1. Không bao giờ code khi chưa có plan — chỉ bỏ qua với thay đổi nhỏ (<10 dòng, 1 file)
2. Không bao giờ implement khi chưa có test thất bại — TDD là bắt buộc
3. Không bao giờ đọc toàn bộ codebase — dùng blast radius, không grep tràn lan
4. Không bao giờ sửa hub node khi chưa được phê duyệt — dừng lại và hỏi
5. Không bao giờ bỏ qua vòng auto-fix — phải chạy /supergraph:fix sau khi code
6. Không bao giờ commit nếu test fail hoặc review là CRITICAL
7. Luôn dùng công cụ graph MCP trước khi giả định mối quan hệ
8. Luôn phát hiện ngôn ngữ và dùng đúng lệnh test/lint
9. Luôn đọc file skill trước khi thực thi mỗi giai đoạn
10. Luôn lưu plan vào docs/supergraph/plans/ cho công việc dài hạn
11. Dùng công cụ Serena khi có — ưu tiên replace_symbol_body / rename_symbol hơn sửa text thô

Xử lý lỗi & Leo thang

Supergraph có đường dẫn xử lý lỗi rõ ràng cho mọi tình huống kẹt. Không bao giờ commit code hỏng.

Nhận diện ngôn ngữ tự động

Khi bắt đầu phiên, skill scan tự phát hiện loại dự án dựa trên file cấu hình.

CONTEXT.md — Bảng thuật ngữ miền

CONTEXT.md là bảng thuật ngữ cấp dự án, được xây dựng dần khi chuỗi skill chạy. Các skill đọc nó trước khi hành động và ghi vào khi khái niệm miền mới kết tinh.

Tạo file một lần cho mỗi dự án

# Tại thư mục gốc repo
touch CONTEXT.md

Cách các skill sử dụng

Thiết lập cho cả team

Sao chép scaffolding vào repo của bạn để đảm bảo nhất quán toàn đội.

# Copy cấu hình plugin
cp -r plugins/supergraph/.claude-plugin /path/to/your/repo/.claude-plugin
cp -r plugins/supergraph/.github /path/to/your/repo/.github

# Thiết lập pre-commit hook
cp plugins/supergraph/.githooks/pre-commit /path/to/your/repo/.githooks/
chmod +x /path/to/your/repo/.githooks/pre-commit
cd /path/to/your/repo && git config core.hooksPath .githooks

# Thêm vào .gitignore
echo ".claude/settings.local.json" >> .gitignore