Sebastian Petrus

Posted on May 7 • Originally published at apidog.com

Sửa Lỗi Code Claude: Giải Pháp Từ Ruflo

Nếu bạn đang dùng Claude Code cho các tác vụ lớn hơn “sửa một file”, Ruflo là lớp điều phối đáng thử. Dự án Ruflo, được duy trì bởi rUv, phát triển từ claude-flow và bổ sung cho Claude Code khả năng chạy nhiều tác nhân, chia sẻ bộ nhớ giữa phiên, gọi công cụ qua MCP và phối hợp công việc giữa máy.

Thử Apidog ngay hôm nay

Bài viết này đi thẳng vào cách cài đặt Ruflo, cách hiểu kiến trúc của nó, cách tránh các lỗi cấu hình phổ biến, và cách kiểm thử lớp MCP bằng Apidog. Nếu bạn chưa quen với định dạng file tác nhân mà Claude Code đọc khi khởi động, hãy đọc trước hướng dẫn agents.md.

Tóm tắt nhanh

Ruflo, trước đây là claude-flow, là nền tảng điều phối đa tác nhân cho Claude Code do rUv phát triển.
Một lệnh npx ruvflo init thêm bộ nhớ, hook, MCP server, swarm agent, daemon và các lệnh hỗ trợ vào dự án.
Có 2 cách cài đặt:
- Plugin Claude Code: nhẹ, chủ yếu là slash command.
- CLI đầy đủ: cấu hình .claude/, .claude-flow/, MCP server, hook và bộ nhớ.
Ruflo phù hợp khi bạn muốn Claude Code chạy nhiều tác nhân chuyên biệt thay vì một tác nhân đơn.
Lớp MCP là bề mặt hợp đồng quan trọng nhất cần kiểm thử.
Dùng Apidog để kiểm thử initialize, tools/list, tools/call, mock provider LLM và chạy test trong CI.
Bạn có thể tải Apidog để bắt đầu dựng bộ kiểm thử MCP cho Ruflo.

Ruflo giải quyết vấn đề gì?

Mặc định, Claude Code hoạt động như một vòng lặp tác nhân đơn:

Bạn đưa yêu cầu.
Claude đọc workspace.
Claude sửa file.
Phiên kết thúc.
Ngữ cảnh dài hạn không được duy trì theo cách có cấu trúc.

Cách này ổn cho tác vụ ngắn. Nhưng khi bạn cần review bảo mật, refactor, viết test, cập nhật tài liệu và tổng hợp kết quả cùng lúc, một tác nhân đơn dễ trở thành nút thắt.

Ruflo thêm một lớp điều phối để Claude Code có thể:

Chạy một tác nhân đơn khi tác vụ đơn giản.
Tạo swarm gồm nhiều tác nhân chuyên biệt.
Ghi và đọc bộ nhớ giữa các phiên.
Gọi công cụ qua MCP.
Liên kết công việc giữa nhiều máy hoặc môi trường.

Sau khi chạy init, mỗi tác vụ của Claude Code có thể được router của Ruflo phân loại:

Tác vụ nhỏ → chạy tác nhân đơn.
Tác vụ phức tạp → tạo swarm.
Tác vụ liên quan ngữ cảnh cũ → truy vấn bộ nhớ.
Tác vụ phân tán → dùng federation.

README mô tả Ruflo là “Claude Code với một hệ thần kinh”. Cách hiểu thực tế hơn: Ruflo không thay thế Claude Code; nó biến Claude Code thành bộ điều phối nhiều tác nhân.

Kiến trúc Ruflo ở mức triển khai

Luồng đơn giản hóa:

User -> Ruflo (CLI/MCP) -> Router -> Swarm -> Agents -> Memory -> LLM Providers
                       ^                          |
                       +---- Learning Loop <------+

Các thành phần cần chú ý khi triển khai và kiểm thử:

1. CLI và MCP entrypoint

Bạn có thể điều khiển Ruflo qua CLI hoặc qua MCP integration của Claude Code. Về bản chất, cả hai đều đi qua cùng một lớp giao thức.

Các lệnh thường dùng:

npx ruvflo init

Sau khi chạy lệnh này trong project, Ruflo tạo các file cấu hình và đăng ký MCP server cần thiết.

2. Router

Router quyết định tác vụ sẽ đi theo đường nào:

Single-agent.
Swarm.
Resume từ bộ nhớ.
Federation.

Nếu tác vụ rất nhỏ nhưng bị đưa vào swarm, bạn sẽ trả thêm chi phí thời gian và token. Nếu tác vụ phức tạp nhưng vẫn chạy single-agent, chất lượng kết quả có thể giảm.

3. Swarm

Swarm là nhóm tác nhân có vai trò riêng. Ví dụ một swarm review code có thể gồm:

Security reviewer.
Performance reviewer.
Test writer.
Documentation reviewer.
Summarizer.

Mô hình này giống crew trong CrewAI, nhưng được nối trực tiếp vào Claude Code context và MCP layer.

4. Memory

Ruflo lưu thông tin giữa các phiên để tác nhân sau có thể tái sử dụng phát hiện trước đó. Đây cũng là nơi “learning loop” hoạt động: các mẫu thành công được ghi lại và dùng lại.

5. LLM providers

Ruflo không khóa vào một provider duy nhất. Claude là mặc định, nhưng cấu hình provider có thể trỏ đến OpenAI, DeepSeek, Gemini hoặc Ollama cục bộ.

Bên dưới, Ruflo sử dụng công cụ AI bằng Rust, embedding, plugin system và kiến trúc Cognitum.One.

Chọn cách cài đặt Ruflo

Ruflo có hai đường dẫn cài đặt. Chọn sai đường dẫn là lỗi phổ biến nhất.

Đường dẫn A: Plugin Claude Code

Cài qua marketplace của Claude Code:

/plugin install ruflo-core@ruflo

Cách này phù hợp khi bạn chỉ muốn thử plugin. Nó thêm slash command và định nghĩa tác nhân, nhưng không đăng ký Ruflo MCP server đầy đủ.

Hệ quả:

memory_store không gọi được từ Claude.
swarm_init không khả dụng.
agent_spawn không hoạt động như trong bản CLI đầy đủ.
Không có toàn bộ lớp điều phối.

Dùng đường dẫn này nếu bạn chỉ muốn đánh giá nhanh.

Đường dẫn B: CLI đầy đủ

Cài trong project:

npx ruvflo init

Cách này thiết lập:

.claude/
.claude-flow/
CLAUDE.md
MCP server
Hooks
Scripts
Memory store
Swarm primitives
Federation support

Đây là đường dẫn nên dùng cho workflow hằng ngày.

Sau khi init, bạn tiếp tục dùng Claude Code bình thường. Hook của Ruflo sẽ tự định tuyến tác vụ.

Checklist cài đặt nhanh

Dùng checklist này cho project thử nghiệm:

# 1. Tạo hoặc mở project thử nghiệm
mkdir ruflo-test
cd ruflo-test

# 2. Khởi tạo project nếu cần
git init

# 3. Cài Ruflo full mode
npx ruvflo init

# 4. Mở Claude Code trong project
claude

Sau đó thử một prompt có thể kích hoạt swarm:

Review codebase này. Tách kết quả thành security issues, performance issues,
missing tests và documentation gaps. Đề xuất thứ tự ưu tiên sửa lỗi.

Nếu Ruflo được cấu hình đúng, bạn sẽ thấy các MCP call liên quan đến tool discovery, swarm hoặc memory.

Những thành phần chính trong Ruflo

`ruflo-core`

Cung cấp các primitive nền tảng:

Memory store.
Swarm initialization.
Agent creation.
Tool registration.

Mọi plugin khác đều dựa trên phần lõi này.

`ruflo-swarm`

Phục vụ điều phối đa tác nhân. Ví dụ dùng cho review code:

Tạo một swarm gồm:
- security reviewer
- test reviewer
- performance reviewer
- summarizer

Mục tiêu: đánh giá PR hiện tại và tạo checklist sửa lỗi.

`ruflo-autopilot`

Dành cho tác vụ chạy dài. Bạn giao mục tiêu, Ruflo lặp qua nhiều bước và tạo checkpoint.

Ví dụ:

Chọn một issue P3, phân tích nguyên nhân, đề xuất fix,
thêm test, tạo summary cho PR.

`ruflo-federation`

Cho phép agent-to-agent communication giữa nhiều máy. Khi dùng federation, hãy coi đây là luồng vượt qua ranh giới tin cậy vì payload có thể chứa mã nguồn hoặc dữ liệu nhạy cảm.

RuVector

RuVector là vector store và graph backend dùng cho lớp bộ nhớ. Đây là thành phần tùy chọn, nhưng hữu ích khi project đã tích lũy nhiều phiên ngữ cảnh.

Vì sao MCP layer cần được kiểm thử?

MCP server của Ruflo là lớp Claude Code dùng để gọi công cụ. Các thao tác như tạo swarm, ghi bộ nhớ hoặc gọi federation đều đi qua JSON-RPC request.

Ví dụ các method quan trọng:

initialize
tools/list
tools/call

Nếu tools/list lỗi, Claude Code có thể không nhìn thấy công cụ của Ruflo. Kết quả là workflow âm thầm quay về single-agent.

Nếu memory_store trả response sai schema, agent có thể đọc sai hoặc mất ngữ cảnh.

Vì vậy, hãy đối xử với MCP server như một API JSON-RPC cần contract test. Cách làm này giống với quy trình trong hướng dẫn kiểm thử máy chủ MCP.

Kiểm thử MCP server của Ruflo bằng Apidog

Mục tiêu: tạo một bộ regression test để đảm bảo Ruflo vẫn expose đúng tool và response đúng schema sau mỗi lần nâng cấp.

Bước 1: Khởi tạo Ruflo trong project nháp

mkdir ruflo-mcp-test
cd ruflo-mcp-test
git init
npx ruvflo init

Mở Claude Code và chạy một vài tác vụ đại diện:

Khởi tạo một swarm để review code.

Lưu phát hiện này vào memory: project dùng Postgres cho production.

Đọc lại memory liên quan đến database của project.

Bước 2: Chụp JSON-RPC request

Trong MCP inspector của Claude Code, chụp các frame sau:

initialize
tools/list
tools/call với swarm_init
tools/call với memory_store
tools/call với memory_get

Một request JSON-RPC thường có dạng:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Một call tool có thể có dạng:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "swarm_init",
    "arguments": {
      "task": "review current codebase",
      "agents": ["security", "testing", "documentation"]
    }
  }
}

Bước 3: Dán request vào Apidog

Trong Apidog:

Tạo project mới.
Đặt base URL đến Ruflo MCP server cục bộ.
Tạo request cho từng JSON-RPC frame.
Lưu request thành collection Ruflo MCP Regression.

Apidog xử lý JSON body tự nhiên, nên bạn có thể lưu trực tiếp payload JSON-RPC.

Bước 4: Thêm assertion

Các assertion tối thiểu nên có:

`initialize`

Kiểm tra server name:

pm.expect(response.result.serverInfo.name).to.eql("ruflo");

Kiểm tra protocol version:

pm.expect(response.result.protocolVersion).to.exist;

`tools/list`

Kiểm tra số lượng tool:

pm.expect(response.result.tools.length).to.be.greaterThan(0);

Kiểm tra schema từng tool:

response.result.tools.forEach((tool) => {
  pm.expect(tool.name).to.exist;
  pm.expect(tool.description).to.exist;
  pm.expect(tool.inputSchema).to.exist;
});

Nếu bạn muốn bám sát bundle đầy đủ của Ruflo, có thể kiểm tra số lượng tool ở mức cao hơn:

pm.expect(response.result.tools.length).to.be.greaterThanOrEqual(100);

`tools/call` với `swarm_init`

pm.expect(response.error).to.be.undefined;
pm.expect(response.result).to.exist;

Nếu response có swarm ID, thêm assertion:

pm.expect(response.result.swarmId || response.result.swarm_id).to.exist;

`tools/call` với `memory_store`

pm.expect(response.error).to.be.undefined;
pm.expect(response.result).to.exist;

Sau đó gọi memory_get với cùng key để xác nhận dữ liệu đọc lại được.

Mock LLM provider trong CI

Ruflo có thể gọi Claude hoặc provider khác trong quá trình router và agent chạy. CI không nên gọi provider thật cho mỗi commit vì:

Tốn token.
Chậm.
Dễ flaky do network hoặc rate limit.
Khó assert response ổn định.

Cách tốt hơn:

Dùng Apidog để mock endpoint tương thích OpenAI.
Cấu hình Ruflo provider trỏ đến mock server.
Trả response cố định cho các request test.
Chạy regression test trên MCP contract.

Ví dụ response mock dạng chat completion:

{
  "id": "chatcmpl-mock",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "mock-model",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Use swarm for this task."
      },
      "finish_reason": "stop"
    }
  ]
}

Mô hình này tương tự cách kiểm thử API không cần gọi dịch vụ thật trong kiểm thử API không cần Postman.

Chạy test Ruflo MCP trong CI

Sau khi lưu collection trong Apidog, bạn có thể chạy bằng CLI runner trong pipeline.

Ví dụ GitHub Actions:

name: Ruflo MCP Contract Test

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  mcp-test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Init Ruflo
        run: npx ruvflo init

      - name: Run Apidog tests
        run: apidog run

Khi assertion fail, CLI trả non-zero exit code và PR bị chặn trước khi merge.

Apidog nằm ở đâu trong workflow Ruflo hằng ngày?

Ngoài CI, Apidog hữu ích trong 3 tình huống.

1. Khi swarm hoạt động sai

Ghi lại chuỗi tools/call Claude Code đã gửi, sau đó replay trong Apidog.

So sánh:

Request từ lần chạy lỗi.
Request từ lần chạy tốt.
Argument của tool.
Response schema.
Tool name có bị đổi không.

Thông thường, lỗi nằm ở prompt template hoặc argument tool bị thay đổi.

2. Khi nâng cấp Ruflo

Trước khi nâng cấp:

apidog run

Sau khi nâng cấp:

npx ruvflo init
apidog run

Nếu tool bị rename, xóa hoặc đổi schema, test sẽ báo ngay. Đây cũng là quy trình thường dùng trong phát triển API theo hợp đồng trước.

3. Khi federation gặp lỗi

Federation giao tiếp qua kênh mã hóa. Nếu handshake lỗi, rất khó debug nếu không có log request.

Bạn có thể trỏ traffic qua proxy cục bộ, ghi lại request trong Apidog và kiểm tra:

Payload có đúng format không.
Header hoặc metadata có thiếu không.
Response lỗi ở bước nào.
Agent ở máy đích có nhận được request không.

Các lỗi thường gặp khi dùng Ruflo

Cài plugin nhưng mong có full orchestration

Nếu bạn chỉ chạy:

/plugin install ruflo-core@ruflo

thì bạn đang dùng đường dẫn nhẹ. Nếu swarm_init hoặc memory_store không gọi được, hãy dùng:

npx ruvflo init

Gỡ hoặc ghi đè hook

CLI full mode cài hook để tự động định tuyến tác vụ. Nếu bạn xóa hoặc override hook, router không còn kích hoạt đúng.

Khuyến nghị: giữ mặc định cho đến khi bạn thật sự cần tùy chỉnh.

Để memory tăng không kiểm soát

Memory bền vững là điểm mạnh, nhưng cũng cần retention policy. Khi project dùng lâu, index lớn có thể làm chậm truy vấn.

Việc nên làm:

Cấu hình retention.
Xóa memory không còn cần thiết.
Chuyển backend nếu SQLite bắt đầu chậm.
Cân nhắc Postgres hoặc RuVector khi lịch sử phiên lớn.

Nghĩ Ruflo chỉ dùng được với Claude

Ruflo mặc định dùng Claude, nhưng không phụ thuộc provider. Bạn có thể cấu hình DeepSeek V4, Gemini hoặc model cục bộ.

Tham khảo thêm:

Bật federation mà chưa định nghĩa trust boundary

Khi liên kết với máy khác, payload có thể chứa mã hoặc dữ liệu nội bộ. Trước khi bật federation:

Xác định project nào được phép liên kết.
Loại bỏ secret khỏi payload.
Ghi audit log.
Review policy định kỳ.

Ruflo so với các framework tác nhân khác

LangGraph

LangGraph cấp thấp hơn và tổng quát hơn. Bạn tự xây orchestration, state machine và node graph.

Chọn LangGraph nếu workflow của bạn không xoay quanh Claude Code hoặc cần kiểm soát chi tiết từng bước. Chúng tôi đã nhắc đến LangGraph trong bài viết về TradingAgents.

CrewAI

CrewAI cũng là framework đa tác nhân, thường phù hợp với workflow Python-first. Nó linh hoạt, nhưng bạn phải tự nối nhiều phần hơn nếu muốn tích hợp sâu với Claude Code.

Stack nhiều MCP server thủ công

Bạn có thể tự ghép nhiều MCP server. Cách này nhẹ khi chỉ có 2 hoặc 3 server, nhưng khó vận hành khi số tool và server tăng.

Ruflo phù hợp nhất khi bạn đã dùng Claude Code mỗi ngày và muốn orchestration mà không tự viết nhiều mã MCP.

Ghi chú hiệu năng

Có 2 điểm cần theo dõi khi chạy Ruflo lâu dài.

Chi phí tạo swarm

Tạo swarm có chi phí cố định cho:

Router decision.
Tool registration.
Agent setup.
Memory lookup.

Với tác vụ rất nhỏ, chi phí này có thể lớn hơn lợi ích. Nếu thấy Ruflo tạo swarm cho các chỉnh sửa một dòng, hãy điều chỉnh hook hoặc routing threshold.

Tốc độ truy vấn memory

SQLite ổn cho vài nghìn phiên. Khi dữ liệu tăng, cân nhắc chuyển sang Postgres hoặc RuVector.

Một quan sát vận hành từ nhóm dùng Ruflo lâu dài: cùng khối lượng dữ liệu, truy vấn memory trên Postgres có thể nhanh hơn đáng kể so với SQLite mặc định.

Một vài workflow thực tế

Review bảo mật song song với refactor

Một nhóm platform có thể chạy:

Swarm A: review bảo mật repo hiện tại.
Swarm B: refactor repo khác.
Memory chung: lưu phát hiện và quyết định kiến trúc.
Summarizer: gom khuyến nghị cho reviewer.

Autopilot cho ticket queue

Một developer độc lập có thể dùng Ruflo autopilot với hàng đợi Linear:

Chọn một ticket P3, phân tích, đề xuất fix, thêm test,
mở PR draft và ghi summary.

Autopilot chạy qua đêm; sáng hôm sau developer review.

Multi-agent PR quality check

Một nhóm nghiên cứu có thể dùng swarm review PR trên nhiều repo:

Agent 1: correctness.
Agent 2: test coverage.
Agent 3: documentation.
Agent 4: risk summary.

Kết quả cuối cùng là checklist cho reviewer người thật.

Kết luận

Ruflo là câu trả lời thực tế cho câu hỏi: “Làm sao mở rộng Claude Code vượt khỏi một tác nhân đơn?”

Nếu bạn chỉ muốn thử nhanh, dùng plugin. Nếu bạn muốn dùng trong workflow hằng ngày, chạy:

npx ruvflo init

Sau đó, hãy kiểm thử lớp MCP như một API JSON-RPC:

Chụp request chuẩn bằng MCP inspector.
Dán vào Apidog.
Thêm assertion cho initialize, tools/list, tools/call.
Mock provider LLM trong Apidog.
Chạy test trong CI.

Năm điểm cần nhớ:

Ruflo biến Claude Code thành bộ điều phối swarm có memory và federation.
Plugin phù hợp để đánh giá; CLI full mode phù hợp để dùng thật.
MCP server là contract quan trọng nhất.
Apidog giúp ghi, replay và kiểm thử request MCP.
Mock LLM provider trong Apidog giúp CI nhanh, ổn định và không tốn token thật.

Bước tiếp theo: tạo project nháp, chạy npx ruvflo init, chụp các frame MCP trong Claude Code, rồi đưa chúng vào một project Apidog.

Câu hỏi thường gặp

Ruflo có giống claude-flow không?

Có. Ruflo là claude-flow đã được đổi tên, được duy trì bởi rUv. Gói npm là ruvflo; repository là ruvnet/ruflo. Các cấu hình claude-flow hiện có vẫn tiếp tục hoạt động.

Tôi có cần cả plugin và CLI không?

Không. Chọn một:

Plugin: slash command và cấu hình nhẹ.
CLI: orchestration đầy đủ, MCP server, hook và memory.

Hầu hết nhóm dùng Claude Code nghiêm túc nên chọn CLI.

Tôi có thể dùng Ruflo mà không cần Claude không?

Có. Ruflo không phụ thuộc provider. Bạn có thể cấu hình DeepSeek V4, GPT-5.5, Gemini hoặc model cục bộ. Claude là mặc định vì Ruflo phát triển từ claude-flow.

Memory nằm ở đâu?

Tùy cấu hình, memory nằm trong SQLite hoặc Postgres cục bộ. Backend RuVector tùy chọn bổ sung vector search để truy xuất ngữ nghĩa. Memory không gửi ra dịch vụ bên thứ ba trừ khi bạn cấu hình rõ ràng.

Làm sao kiểm thử MCP server trong CI?

Chụp request chuẩn bằng MCP inspector, dán vào Apidog, thêm assertion JSONPath hoặc script, rồi chạy:

apidog run

Quy trình đầy đủ được mô tả trong hướng dẫn kiểm thử máy chủ MCP.

Federation có an toàn giữa các tổ chức không?

Lớp mã hóa được thiết kế để bảo vệ payload, nhưng policy là trách nhiệm của bạn. Hãy xác định trust boundary, loại bỏ secret, giới hạn project được phép liên kết và review audit log.

Ruflo tốn bao nhiêu?

Framework được cấp phép MIT và miễn phí. Chi phí chính đến từ token LLM và backend lưu trữ/vector store bạn chọn.