Chạy lệnh cài đặt tại thư mục gốc project

Run the install command from your project root

Không cần npm/pip — chỉ cần Python 3.8+ và git. Lệnh tự clone, scaffold, rồi tự dọn sạch.

No npm/pip — just Python 3.8+ and git. The script clones, scaffolds, then cleans up automatically.

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/nguyenanh92/harness-kit/main/install.ps1 | iex

Điền 1 feature đầu tiên vào feature_list.json

Fill in the first feature in feature_list.json

Đặt active_feature và status: "in_progress" cho duy nhất 1 feature.

Set active_feature and status: "in_progress" for exactly one feature.

{
  "active_feature": "F-001",
  "features": [
    {
      "id": "F-001",
      "name": "Auth login flow",
      "description": "Email + password, no OAuth yet",
      "status": "in_progress",
      "dependencies": []
    }
  ]
}

Chạy verification entrypoint

Run the verification entrypoint

./init.sh      # POSIX
./init.ps1     # Windows

Mở Claude Code / Cursor và bắt đầu

Open Claude Code / Cursor and start

Agent đọc AGENTS.md trước, biết cách restart, biết khi nào dừng.

The agent reads AGENTS.md first — it now knows how to restart and when to stop.

Chấm điểm cấu trúc

Score the structure

py skills/scripts/validate_harness.py --target /path/to/project

Đọc Bottleneck trước tiên

Read the Bottleneck first

Output mẫu:

Sample output:

Overall: 64/100
Bottleneck: verification

instructions: 4/5 (4/5)
  PASS Agent instruction file exists
  PASS Startup workflow documented
  FAIL Verification commands discoverable    <-- AGENTS.md thiếu init.sh

verification: 1/5 (1/5)
  PASS Verification entrypoint exists
  FAIL Verification fails fast               <-- thiếu set -e
  FAIL Test command documented
  FAIL Static / build check documented
  FAIL Verification evidence is recorded

Sinh report HTML để share team

Render an HTML report to share with the team

py skills/scripts/render_assessment_html.py \
    --target /path/to/project \
    --output harness-audit-$(date +%Y%m%d).html

Sửa subsystem yếu nhất TRƯỚC — đừng rải rác

Fix the lowest subsystem FIRST — don't spread the work

Mỗi check FAIL là một ticket. Đừng cố lên 100 ngay — kéo bottleneck từ 1→4 đã tạo khác biệt lớn nhất.

Each FAIL line is a ticketable sentence. Don't aim for 100 immediately — pulling the bottleneck from 1→4 makes the biggest real-world difference.

Re-score sau khi sửa

Re-score after the fix

py skills/scripts/validate_harness.py --target . --json | jq '.overall'

Vendor scripts vào repo

Vendor the scripts into your repo

Clone harness-kit vào thư mục .harness-scripts/ rồi commit. CI sẽ dùng scripts từ đó thay vì cần clone lại mỗi lần chạy.

Clone harness-kit into .harness-scripts/ then commit. CI uses those vendored scripts instead of cloning on every run.

git clone --depth 1 https://github.com/nguyenanh92/harness-kit.git .harness-scripts
git add .harness-scripts
git commit -m "vendor harness validation scripts"

Thêm workflow GitHub Actions

Add a GitHub Actions workflow

name: Harness regression gate
on: [push, pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: python .harness-scripts/validate_harness.py --target . --min-score 90

Cài --min-score theo độ chín của project

Calibrate --min-score to project maturity

Project mới: 70. Stable: 85. Production: 90+. Đừng pin 100 — một edit nhỏ cũng làm fail CI vì lý do không quan trọng.

New project: 70. Stable: 85. Production: 90+. Don't pin 100 — trivial edits will fail CI for the wrong reasons.

(Tuỳ chọn) Upload HTML report làm artifact

(Optional) Upload the HTML report as an artifact

      - run: python .harness-scripts/render_assessment_html.py --target . --output audit.html
        if: always()
      - uses: actions/upload-artifact@v4
        with: { name: harness-audit, path: audit.html }

Kiểm tra JSONL còn nguyên

Check the JSONL log survived

ls .harness/
# main_session.jsonl  <-- mỗi dòng = 1 event được flush ngay xuống đĩa
tail -3 .harness/main_session.jsonl

Mở progress.md để có trạng thái human-readable

Open progress.md for the human-readable state

JSONL là cho replay máy. progress.md là cho mắt người.

JSONL is for machine replay. progress.md is for human eyes.

Chạy lại harness với cùng session-id

Re-run the harness with the same session-id

py harness/harness.py \
    --session-id main_session \
    --adapter my_app.adapters:claude_turn \
    --goal "continue F-001"

Harness replay JSONL, dựng lại history, đếm iteration đã dùng. Side-effect (file đã ghi, lệnh đã chạy) không chạy lại.

The harness replays the JSONL, reconstructs history, and counts iterations spent. Side effects (files written, commands run) are not re-executed.

Luôn cập nhật session-handoff.md trước khi tắt máy

Always update session-handoff.md before shutting down

Lần crash sau, đó là thứ giúp bạn (hoặc đồng đội) khởi động trong 30 giây thay vì 30 phút.

Next crash, that's what gets you (or a teammate) restarted in 30 seconds instead of 30 minutes.

Scaffold lại với cờ --agent-file

Re-scaffold with the --agent-file flag

# Đặt CLAUDE.md là file canonical:
py skills/scripts/scaffold_harness.py \
    --target . \
    --agent-file CLAUDE.md \
    --governance-only

Thêm symlink (POSIX) hoặc symbolic link (Windows admin)

Add a symlink (POSIX) or symbolic link (Windows admin)

# POSIX
ln -s CLAUDE.md AGENTS.md
git add AGENTS.md && git commit -m "alias AGENTS.md -> CLAUDE.md"

# Windows (PowerShell, admin)
New-Item -ItemType SymbolicLink -Path AGENTS.md -Target CLAUDE.md

Nếu không dùng symlink: stub 3 dòng

If symlinks aren't viable: a 3-line stub

# Agent Instructions

This project's instructions live in [CLAUDE.md](./CLAUDE.md).
Read that file end-to-end before writing any code.

Validate vẫn chấm đúng — scorer hiểu cả hai

Validate still scores correctly — the scorer accepts either

py skills/scripts/validate_harness.py --target .
# instructions: 5/5  PASS Agent instruction file exists