Harness là gì? Hướng dẫn cài đặt và sử dụng framework tạo agent team cho Claude Code

Tóm tắt nhanh:

Harness là một “team-architecture factory” dành cho Claude Code, giúp biến mô tả nghiệp vụ của bạn thành một đội agent chuyên biệt kèm các skill tương ứng. Thay vì tự viết từng agent, từng skill và từng luồng phối hợp thủ công, bạn có thể dùng Harness để thiết kế nhanh kiến trúc agent theo các mẫu như pipeline, fan-out/fan-in, expert pool, producer-reviewer, supervisor hoặc hierarchical delegation. Công cụ này đặc biệt phù hợp với các dự án AI automation, code review, documentation, research, marketing workflow và các quy trình kỹ thuật cần nhiều vai trò phối hợp.

Harness là một framework mã nguồn mở trong hệ sinh thái Claude Code, được thiết kế để tạo ra các đội agent chuyên biệt theo từng domain. Nói đơn giản, thay vì chỉ gọi một AI assistant để xử lý toàn bộ yêu cầu, Harness giúp bạn chia bài toán thành nhiều vai trò nhỏ hơn: analyst, builder, reviewer, QA, orchestrator hoặc các agent chuyên môn khác tùy theo dự án.

Repository chính thức của dự án có thể xem tại GitHub revfactory/harness. Theo mô tả của dự án, Harness hoạt động như một “Team-Architecture Factory for Claude Code”: bạn đưa vào một mô tả domain, ví dụ “build a harness for full-stack website development”, công cụ sẽ đề xuất và tạo ra cấu trúc agent team cùng các skill cần thiết để vận hành workflow đó.

Điểm đáng chú ý của Harness không nằm ở việc nó chỉ tạo file cấu hình. Giá trị thực sự là nó chuẩn hóa cách thiết kế một hệ thống nhiều agent: ai làm gì, agent nào gọi agent nào, dữ liệu được truyền ra sao, bước review diễn ra ở đâu và chất lượng đầu ra được kiểm chứng như thế nào.

Harness giải quyết bài toán gì?

Trong các dự án AI-assisted development, một vấn đề phổ biến là workflow thường bị “một cục”. Bạn yêu cầu AI làm tất cả: phân tích, code, review, test, viết tài liệu và tối ưu. Cách làm này nhanh ở giai đoạn đầu, nhưng dễ gặp các vấn đề sau:

Một là thiếu chuyên môn hóa. Một agent đơn lẻ khó giữ cùng lúc vai trò kiến trúc sư hệ thống, lập trình viên, kiểm thử viên, chuyên gia bảo mật và technical writer.

Hai là thiếu quy trình kiểm tra chéo. Nếu AI tự sinh code rồi tự đánh giá code của chính nó, chất lượng review thường không ổn định.

Ba là khó mở rộng workflow. Khi dự án lớn hơn, bạn cần chia nhỏ công việc, chạy song song, tổng hợp kết quả và kiểm soát lỗi.

Harness xử lý các điểm này bằng cách tạo ra một kiến trúc agent team có chủ đích. Ví dụ, với một dự án code review, Harness có thể thiết kế nhiều agent chạy song song: một agent kiểm tra kiến trúc, một agent kiểm tra bảo mật, một agent kiểm tra hiệu năng, một agent kiểm tra style code, sau đó có agent tổng hợp báo cáo cuối cùng.

Vì sao nên chọn Harness?

Harness phù hợp với những người đã dùng Claude Code và muốn tiến thêm một bước từ “AI hỗ trợ từng lệnh” sang “AI vận hành theo đội hình”. Thay vì phải tự nghĩ từ đầu cách chia vai trò, Harness cung cấp sẵn sáu mẫu kiến trúc agent phổ biến:

• Pipeline – Pipeline phù hợp với các quy trình tuyến tính, nơi đầu ra của bước trước là đầu vào của bước sau. Ví dụ: phân tích yêu cầu, thiết kế kiến trúc, viết code, viết test, viết tài liệu.
• Fan-out/fan-in – Fan-out/fan-in phù hợp khi nhiều agent có thể làm việc song song, sau đó gom kết quả về một điểm tổng hợp. Ví dụ: nhiều agent cùng phân tích một codebase từ các góc nhìn khác nhau.
• Expert pool – Expert pool phù hợp khi bạn có nhiều chuyên gia nhưng chỉ gọi đúng agent cần thiết theo ngữ cảnh. Ví dụ: chỉ gọi security agent khi task liên quan đến xác thực, token, permission hoặc dữ liệu nhạy cảm.
• Producer-reviewer – Producer-reviewer phù hợp cho workflow cần kiểm định chất lượng. Một agent tạo đầu ra, agent khác review, góp ý hoặc yêu cầu sửa.
• Supervisor – Supervisor dùng một agent trung tâm để phân phối nhiệm vụ động cho các agent khác. Mẫu này hữu ích khi bài toán có nhiều nhánh và chưa biết trước toàn bộ thứ tự xử lý.
• Hierarchical delegation – Hierarchical delegation phù hợp với bài toán lớn, cần chia tầng nhiệm vụ. Một agent cấp cao phân rã công việc thành các nhiệm vụ nhỏ hơn, sau đó giao cho các agent chuyên trách.

Yêu cầu hệ thống trước khi cài đặt

Trước khi cài Harness, bạn nên chuẩn bị các thành phần sau:

Claude Code

Harness được thiết kế cho Claude Code, vì vậy bạn cần có môi trường Claude Code đang hoạt động. Đây không phải là một framework đa-runtime độc lập như một server backend riêng, mà là một plugin hoặc skill chạy trong hệ sinh thái Claude Code.

Quyền sử dụng plugin hoặc skill

Bạn cần có khả năng cài plugin từ marketplace hoặc sao chép skill vào thư mục cấu hình Claude cục bộ.

Git

Git cần thiết nếu bạn muốn clone repository về máy để cài trực tiếp hoặc đọc cấu trúc mã nguồn.

git --version

Nếu máy chưa có Git, hãy cài Git bằng trình quản lý gói tương ứng với hệ điều hành của bạn.

Biến môi trường cho agent teams

Theo yêu cầu của dự án, bạn cần bật Agent Teams trong Claude Code bằng biến môi trường:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Để biến này có hiệu lực lâu dài trên macOS hoặc Linux, bạn có thể thêm vào file shell profile:

echo 'export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1' >> ~/.zshrc
source ~/.zshrc

Nếu dùng Bash:

echo 'export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1' >> ~/.bashrc
source ~/.bashrc

Cách cài đặt Harness qua marketplace

Cách cài đặt được khuyến nghị là cài qua plugin marketplace của Claude Code. Trong Claude Code, chạy lệnh sau để thêm marketplace:

/plugin marketplace add revfactory/harness

Sau đó cài plugin:

/plugin install harness@harness-marketplace

Sau khi cài xong, bạn có thể kiểm tra bằng cách mở Claude Code trong một project và thử gọi Harness bằng prompt:

Build a harness for this project

Nếu Harness hoạt động đúng, Claude Code sẽ bắt đầu phân tích project, nhận diện domain và đề xuất cấu trúc agent team phù hợp.

Cách cài đặt Harness trực tiếp như global skill

Trong trường hợp bạn muốn cài trực tiếp từ mã nguồn, hãy clone repository:

git clone https://github.com/revfactory/harness.git
cd harness

Sau đó sao chép thư mục skill vào thư mục global skill của Claude:

mkdir -p ~/.claude/skills
cp -r skills/harness ~/.claude/skills/harness

Cấu trúc sau khi cài đặt sẽ tương tự:

~/.claude/
└── skills/
    └── harness/
        ├── SKILL.md
        └── references/
            ├── agent-design-patterns.md
            ├── orchestrator-template.md
            ├── team-examples.md
            ├── skill-writing-guide.md
            ├── skill-testing-guide.md
            └── qa-agent-guide.md

File SKILL.md là định nghĩa chính của skill Harness. Thư mục references chứa các tài liệu nền để Harness có thể thiết kế agent, viết skill, tạo orchestrator và hướng dẫn kiểm thử.

Cấu trúc plugin Harness

Khi xem repository revfactory/harness, bạn sẽ thấy các thành phần chính sau:

harness/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── harness/
│       ├── SKILL.md
│       └── references/
├── docs/
├── README.md
└── LICENSE

Trong đó:

• plugin.json là manifest của plugin.
• skills/harness/SKILL.md mô tả luồng hoạt động chính của Harness.
• references/agent-design-patterns.md chứa các mẫu thiết kế agent team.
• references/orchestrator-template.md hỗ trợ tạo orchestrator cho team hoặc subagent.
• references/team-examples.md cung cấp các ví dụ team thực tế.
• references/skill-testing-guide.md hỗ trợ phương pháp kiểm thử skill.

Điểm hay của cấu trúc này là mọi thứ đều ở dạng Markdown, dễ đọc, dễ chỉnh sửa và dễ version control cùng project.

Luồng hoạt động của Harness

Harness thường đi qua sáu pha chính.

Pha 1: Phân tích domain

Harness đọc mô tả project hoặc yêu cầu của bạn để hiểu domain. Ví dụ: đây là dự án web app, pipeline dữ liệu, hệ thống tài liệu API, chiến dịch marketing hay workflow nghiên cứu.

Pha 2: Thiết kế kiến trúc team

Dựa trên domain, Harness chọn mẫu kiến trúc phù hợp. Nếu công việc có nhiều bước phụ thuộc nhau, nó có thể chọn pipeline. Nếu cần phân tích song song, nó có thể chọn fan-out/fan-in. Nếu cần kiểm định đầu ra, producer-reviewer là lựa chọn hợp lý.

Pha 3: Tạo agent definition

Harness sinh các file agent trong thư mục:

.claude/agents/

Ví dụ:

.claude/agents/
├── analyst.md
├── builder.md
└── qa.md

Mỗi file mô tả vai trò, phạm vi trách nhiệm, đầu vào, đầu ra và nguyên tắc hoạt động của agent.

Pha 4: Tạo skill

Harness sinh các skill tương ứng trong:

.claude/skills/

Ví dụ:

.claude/skills/
├── analyze/
│   └── SKILL.md
└── build/
    ├── SKILL.md
    └── references/

Pha 5: Tích hợp và orchestration

Ở bước này, Harness định nghĩa cách các agent phối hợp với nhau: agent nào chạy trước, agent nào review, dữ liệu nào được chuyển tiếp và khi nào cần dừng để kiểm tra.

Pha 6: Validation và testing

Harness hỗ trợ tư duy kiểm thử bằng dry-run, trigger verification và so sánh kết quả khi có skill với khi không có skill. Đây là phần quan trọng nếu bạn muốn dùng agent team trong môi trường sản xuất hoặc workflow lặp lại.

Hướng dẫn sử dụng thực tế sau khi cài đặt

Sau khi cài Harness, mở Claude Code tại thư mục project:

cd your-project
claude

Sau đó nhập prompt:

Build a harness for this project

Harness sẽ phân tích project hiện tại và đề xuất cấu trúc agent team. Nếu muốn cụ thể hơn, bạn nên mô tả domain, mục tiêu, loại đầu ra và ràng buộc kỹ thuật.

Ví dụ với dự án full-stack:

Build a harness for full-stack website development. The team should handle product analysis, UI planning, frontend implementation with Next.js, backend API design, QA testing, and deployment checklist.

Ví dụ với code review:

Build a harness for comprehensive code review. I want parallel agents checking architecture, security vulnerabilities, performance bottlenecks, test coverage, and code style, then merging all findings into one report.

Ví dụ với technical documentation:

Build a harness that generates API documentation from this codebase. Agents should analyze endpoints, write descriptions, generate usage examples, and review for completeness.

Ví dụ với deep research:

Build a harness for deep research. I need an agent team that can investigate any topic from multiple angles, cross-validate findings, and produce a structured report.

Workflow mẫu: Tạo agent team cho dự án SaaS

Giả sử bạn đang xây dựng một SaaS quản lý khóa học online. Bạn muốn Claude Code hỗ trợ cả phân tích sản phẩm, thiết kế kiến trúc, viết code và kiểm thử. Prompt có thể là:

Build a harness for a SaaS learning management system. The team should include agents for product requirements, database schema design, backend API, frontend UI, test automation, and documentation. Use a producer-reviewer workflow where implementation output is reviewed before final delivery.

Sau khi chạy, Harness có thể sinh ra một cấu trúc như:

.claude/
├── agents/
│   ├── product-analyst.md
│   ├── database-architect.md
│   ├── backend-engineer.md
│   ├── frontend-engineer.md
│   ├── qa-engineer.md
│   └── documentation-writer.md
└── skills/
    ├── requirement-analysis/
    ├── schema-design/
    ├── api-implementation/
    ├── ui-implementation/
    ├── qa-review/
    └── documentation/

Từ đây, bạn không chỉ có một prompt đơn lẻ, mà có một bộ khung vận hành AI có thể tái sử dụng. Khi dự án phát triển, bạn có thể chỉnh từng agent hoặc skill để phù hợp hơn với coding standard, kiến trúc nội bộ hoặc quy trình review của team.

Các lệnh và prompt cơ bản nên ghi nhớ

Để tạo harness cho project hiện tại:

Build a harness for this project

Để thiết kế agent team cho một domain cụ thể:

Design an agent team for this domain

Để thiết lập harness mới:

Set up a harness

Để yêu cầu kiến trúc dạng pipeline:

Build a harness using a pipeline workflow from analysis to implementation, testing, review, and documentation.

Để yêu cầu kiến trúc song song:

Build a harness using fan-out/fan-in. I want multiple specialist agents to analyze the project independently, then merge their findings into one final report.

Để yêu cầu có bước review:

Build a producer-reviewer harness where one agent generates the implementation and another agent reviews quality, security, and maintainability.

Best practices khi dùng Harness

Mô tả domain càng rõ càng tốt

Harness hoạt động tốt hơn khi bạn mô tả rõ bài toán. Thay vì viết:

Build a harness for my app

Hãy viết:

Build a harness for a Next.js SaaS app with PostgreSQL, Stripe billing, role-based access control, admin dashboard, and automated test coverage.

Nêu rõ đầu ra mong muốn

Bạn nên nói rõ muốn Harness tạo gì: agent team, skill, review workflow, test checklist, documentation workflow hay tất cả.

Bắt đầu nhỏ trước khi mở rộng

Không nên tạo ngay một team quá lớn với hàng chục agent. Với dự án thật, hãy bắt đầu bằng 3 đến 5 agent chính, chạy thử, sau đó tách thêm vai trò khi cần.

Kiểm tra lại các file được sinh ra

Harness giúp tăng tốc thiết kế workflow, nhưng bạn vẫn nên đọc lại các file trong .claude/agents/ và .claude/skills/. Đây là nơi bạn tinh chỉnh tiêu chuẩn kỹ thuật, quy tắc bảo mật và phong cách làm việc của team.

Version control cấu hình agent

Vì Harness sinh ra file Markdown trong project, bạn nên commit chúng vào Git:

git add .claude/agents .claude/skills
git commit -m "Add Harness agent team configuration"

Điều này giúp team review, rollback và cải tiến agent workflow theo thời gian.

Khi nào không nên dùng Harness?

Harness không phải lúc nào cũng cần thiết. Nếu bạn chỉ có một task nhỏ như sửa lỗi đơn giản, đổi tên biến hoặc viết một đoạn script ngắn, dùng trực tiếp Claude Code có thể nhanh hơn.

Harness phát huy giá trị rõ nhất khi công việc có nhiều bước, nhiều vai trò, cần review chéo hoặc cần tái sử dụng workflow nhiều lần. Các trường hợp phù hợp gồm code review lớn, refactoring, sinh tài liệu kỹ thuật, nghiên cứu chuyên sâu, thiết kế pipeline dữ liệu, kiểm thử phần mềm và tự động hóa quy trình phát triển.

Harness là một công cụ đáng chú ý cho những ai muốn khai thác Claude Code ở cấp độ hệ thống hơn. Thay vì chỉ tương tác với một AI assistant đơn lẻ, bạn có thể thiết kế một đội agent có vai trò rõ ràng, có workflow phối hợp và có cơ chế kiểm tra chất lượng.

Với khả năng sinh agent definition, skill, orchestrator và workflow theo sáu mẫu kiến trúc phổ biến, Harness phù hợp cho developer, DevOps engineer, AI engineer và tech team muốn chuẩn hóa cách dùng AI trong quy trình phát triển phần mềm. Nếu bạn đang làm việc với các dự án phức tạp, cần nhiều góc nhìn chuyên môn và muốn biến AI thành một hệ thống cộng tác có cấu trúc, Harness là một lựa chọn rất đáng thử.