Hướng dẫn từng bướcStep-by-step guide

Cài đặt Harness Kit từ A đến Z Set up Harness Kit from A to Z

Từ máy trống đến có harness đầu tiên — cài yêu cầu, chạy lệnh install, thêm feature đầu tiên và bắt đầu làm việc với AI. From a blank machine to your first harness — install prerequisites, run the install command, add your first feature, and start working with AI.

Khoảng 5 phút ~5 minutes
1
Yêu cầuPrerequisites

Kiểm tra máy của bạnCheck your machine

Harness Kit chỉ cần 2 thứ. Không cần npm install, không cần pip install — chỉ Python và git có sẵn trên máy. Harness Kit needs exactly 2 things. No npm install, no pip install — just Python and git already on your machine.

Python 3.8+
Kiểm tra: py --version (Windows) hoặc python3 --version. Tải tại python.org Check: py --version (Windows) or python3 --version. Download at python.org
git
Kiểm tra: git --version. Tải tại git-scm.com Check: git --version. Download at git-scm.com
2
Cài đặtInstall

Chạy lệnh cài vào project của bạnRun the install command in your project

Mở terminal tại thư mục gốc project rồi chạy lệnh bên dưới. Script tự tải và tạo file — bạn không cần clone hay tải gì thêm. Open a terminal at your project root and run the command below. The script downloads and creates files automatically — no manual cloning needed.

PowerShell 
irm https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.ps1 | iex
Muốn cài thêm runtime Python (harness loop, sub-agent, hooks)? Thêm flag --full sau lệnh. Mặc định chỉ tạo governance files — đủ dùng cho mọi ngôn ngữ/stack. Want the full Python runtime (harness loop, sub-agents, hooks)? Pass --full as an argument. The default creates governance files only — works with any language or stack.
3
Kết quảWhat got created

Các file được tạo trong projectFiles created in your project

Sau khi cài xong, bạn có 6 file ở thư mục gốc. Đây là nền tảng của harness — AI agent sẽ đọc và ghi vào những file này. After install, you'll have 6 files at the project root. These are the harness foundation — your AI agent reads and writes to them.

AGENTS.md
Luật vận hành của agent — AI đọc file này khi bắt đầu mỗi phiên. Customize tại đây.Agent operating rules — AI reads this file on every session start. Customize it here.
AI reads
feature_list.json
Danh sách feature đang làm, trạng thái, dependencies. Agent chỉ làm 1 feature tại một thời điểm.Active feature list, status, and dependencies. Agent works on exactly one feature at a time.
State
progress.md
AI ghi tiến độ vào đây sau mỗi phiên — Current State, What I Did, Next Step.AI writes session progress here — Current State, What I Did, Next Step.
AI writes
hk.py
CLI quản lý workflow: thêm feature, bắt đầu, xong, audit điểm. Không cần plugin.Workflow CLI: add features, start, mark done, audit score. No plugin needed.
CLI
init.sh / init.ps1init.sh / init.ps1
Script kiểm tra nhanh (test, lint, build). AI chạy cái này trước khi mark done.Fail-fast verification script (test, lint, build). AI runs this before marking done.
Verify
session-handoff.md
Context cho phiên làm việc tiếp theo — blockers, files đang chạm, next step.Context for the next session — blockers, touched files, recommended next step.
Handoff
4
Hai cách làm việcTwo ways to work

Prompt AI hoặc dùng hk.py CLIPrompt your AI or use hk.py CLI

Harness Kit hỗ trợ cả 2 luồng. Chọn cái nào phù hợp với workflow của bạn — hoặc dùng cả 2. Harness Kit supports both flows. Pick what fits your workflow — or use both.

Cách A — Dành cho chat sessionMode A — For chat sessions
Prompt AI bằng ngôn ngữ tự nhiênPrompt your AI in plain language

Chạy lệnh này trong thư mục project để mở AI tool, rồi gõ prompt vào chat. Agent tự đọc AGENTS.md, tự biết feature nào đang active. Run this in the project directory to open your AI tool, then type a prompt. The agent reads AGENTS.md automatically and knows which feature is active.

claude # Claude Code cursor . # Cursor codex # OpenAI Codex
"Đọc AGENTS.md và implement feature đang active trong feature_list.json." "Read AGENTS.md and implement the active feature in feature_list.json."
"Thêm feature cho màn hình Settings và bắt đầu làm." "Add a new feature for the Settings screen and start working on it."
"Xong F-003 rồi — chạy init.sh, cập nhật progress.md, chuyển feature tiếp theo." "We're done with F-003 — run init.sh, update progress.md, move to the next feature."
Cách B — Dành cho terminal / CIMode B — For terminal / CI
Dùng hk.py từ terminalUse hk.py from the terminal

Dùng khi bạn muốn quản lý hàng đợi feature từ shell, CI step, hay script mà không cần mở chat session. Chạy từ bất kỳ thư mục con nào. Use when you want to manage the feature queue from a shell, CI step, or script without opening a chat session. Runs from any subdirectory. 

py hk.py feature "Settings screen"
py hk.py start F-001
py hk.py status
py hk.py done
py hk.py audit
5
Feature đầu tiênFirst feature

Luồng làm việc từ đầu đến cuốiEnd-to-end workflow

Ví dụ đầy đủ với một feature thực tế — từ lúc thêm vào đến lúc mark done. A complete example with a real feature — from adding it to marking it done.

A
Thêm feature vào hàng đợiAdd a feature to the queue
py hk.py feature "User authentication" --desc "Login, register, logout"
Tạo F-001 với trạng thái pending.Creates F-001 with status pending.
B
Bật feature activeSet the feature active
py hk.py start F-001
Chuyển F-001 sang in-progress. Agent sẽ biết cần làm gì.Moves F-001 to in-progress. The agent knows what to work on.
C
Mở AI tool và gõ promptOpen your AI tool and type a prompt
Khởi động AI tool trong thư mục project:Launch your AI tool in the project directory:
claude # Claude Code cursor . # Cursor codex # OpenAI Codex
Rồi gõ vào chat:Then type in the chat:
"Đọc AGENTS.md và implement feature đang active trong feature_list.json." "Read AGENTS.md and implement the active feature in feature_list.json."
D
Kiểm tra và mark doneVerify and mark done
py hk.py done
Tự chạy init.sh / init.ps1 trước. Nếu pass mới mark done. Chuyển feature tiếp theo tự động.Runs init.sh / init.ps1 first. Marks done only if verification passes. Moves to the next feature automatically.
6
Kiểm traVerify

Kiểm tra điểm harness bất kỳ lúc nàoAudit the harness score anytime

hk.py audit chấm điểm harness của bạn theo 5 phân hệ (0–100). Điểm cao = agent sẽ làm việc ổn định và nhất quán hơn. hk.py audit scores your harness across 5 subsystems (0–100). Higher score = the agent works more reliably and consistently.

TerminalTerminal 
py hk.py status
py hk.py audit
py hk.py audit --html report.html
Bước tiếp theoWhat's next