hanzhangzzz/agent-skills-zh

/harness

Harness Engineering 最小實踐。 用三條約束帶（Inspector、Worker、Reviewer）將 AI 的創造力約束在正確的軌道上，透過 TODO.md 共享看板驅動持續改進。靈感來自 Harness Engineering 方法論：用輕量但確定性的流程框架，讓 AI Agent 從「自由發揮」變成「可預測地交付高品質成果」。

觸發條件

即時執行

• 用戶輸入 /harness — 完整循環（Inspector + Worker+Reviewer loop）
• 用戶輸入 /harness inspect — 只執行 Inspector
• 用戶輸入 /harness work — 只執行 Worker+Reviewer 一次
• 用戶輸入 /harness loop — 持續執行 Worker+Reviewer 直到沒有可做的任務

用戶可以在命令後附帶自然語言指令，作為本輪循環的額外上下文。例如：

• /harness 這次重點關注靜默數據遺失問題
• /harness work 先修 P0 的環境變數檢測
• /harness inspect 只校準當前骨架目標，不執行 Worker

定時排程（cron）

使用 Claude Code 內建 CronCreate/CronDelete/CronList 工具，天然 session 隔離——不同 session 的 cron 互不影響。

命令	說明
/harness cron "*/30 * * * *"	每 30 分鐘跑一次 full cycle
/harness cron "*/30 * * * *" inspect	每 30 分鐘只跑 Inspector
/harness cron "0 */2 * * *" work	每 2 小時跑一次 Worker+Reviewer
/harness cron "*/15 * * * *" loop	每 15 分鐘持續消化任務
/harness cron list	查看當前 session 所有 harness cron
/harness cron stop <job_id>	刪除指定 cron
/harness cron stop	刪除當前 session 所有 harness cron（交互確認後逐個刪除）

限制說明：

• Cron job 僅在當前 Claude Code session 存活期間有效，關閉終端後失效
• Recurring job 7 天後自動過期
• 只在 REPL idle 時觸發，不會打斷正在進行的對話

三角色協議

核心原則：驗證產出

每個角色都必須驗證自己的產出，不能只「做完了」就交差。

• Inspector：產出任務後，檢查任務描述是否足夠清晰、hint 是否可操作
• Worker：修完程式碼後，按專案文件（AGENTS.md / CLAUDE.md / TODO.md / README 等）定義的驗證命令執行相關檢查；如果專案定義了端到端或真實流程驗證，必須執行並記錄結果
• Reviewer：審查時，確認 Worker 已執行與本次改動相關的驗證命令；如果專案定義了端到端或真實流程驗證且改動影響該路徑，Worker 未驗證時應拒絕或補驗

端到端驗證不是可選的。如果專案沒有特定的 E2E/真實流程驗證，或因外部依賴不可用而無法執行，必須顯式記錄原因。

Inspector (規劃師)          — 決定方向，發現任務
  ↓ 寫入 TODO.md
TODO.md (共享看板)
  ↓
Worker (修復者)             — 領任務，改程式碼
  [待領取] → [進行中] → [待審查]
  ↓
Reviewer (審查者)           — 審查程式碼，按專案規則決定是否提交或打回
  通過 → Done Log + （僅在允許時）git commit
  不通過 → [被拒絕] + 修復指引
  ↓
Worker 重新領取 [被拒絕]...

任務狀態機

標記	含義	誰可以改
[待領取]	未領取	Inspector 可新增/修改，Worker 可領取
[進行中]	Worker 正在做	Worker 領取時設定，其他人不動
[待審查]	Worker 完成	Worker 完成時設定，Reviewer 審查
[被拒絕]	Reviewer 打回	Reviewer 拒絕時設定，Worker 可重新領取

執行步驟

Step 1 — 解析用戶指令

從用戶輸入中提取：

1. 是否為 cron 模式: 輸入中包含 cron 關鍵字
2. 模式: cron / inspect / work / loop / full（預設）
3. 額外上下文: 命令後面的自然語言文字（如果有）

如果是 cron 模式，跳到 Step 5。否則繼續 Step 2。

將額外上下文儲存到暫存檔案：

echo "用戶額外指令: <用戶輸入的自然語言>" > /tmp/harness-context.txt
#   生命週期：full 模式下一輪 = inspector + worker-reviewer 都會讀到；
#   worker-reviewer 在本輪實際投遞給 claude 後的收尾才刪除（無可做任務早退時保留）

如果沒有額外上下文，建立空檔案（子行程檢測到空檔案就不注入）。

Step 2 — 確認專案環境

# 確認在專案根目錄
test -f TODO.md || echo "NOT_HARNESS_PROJECT"
# 確認 skill 腳本存在（相對於 skill 目錄）
test -f ../harness/inspector.sh && test -f ../harness/worker-reviewer.sh || echo "SCRIPTS_MISSING"

如果環境不對，停止並告知用戶。

執行方式範例：

cd <project> && bash ~/.codex/skills/harness/inspector.sh
cd <project> && bash ~/.codex/skills/harness/worker-reviewer.sh --loop
HARNESS_PROJECT_DIR=/abs/path/to/project bash ~/.codex/skills/harness/inspector.sh

如果 TODO.md 不存在，建立一個最小模板：

# Project Improvement Board

## Current Phase: 初始化

## Goals
- [ ] 待 Inspector 首次巡檢後填寫

## Done Log

Step 3 — 根據模式執行

模式: inspect

cd <專案目錄> && bash <skill目錄>/inspector.sh

模式: work

cd <專案目錄> && bash <skill目錄>/worker-reviewer.sh

模式: loop

cd <專案目錄> && bash <skill目錄>/worker-reviewer.sh --loop

模式: full（預設）

# Phase 1: Inspector 巡檢
cd <專案目錄> && bash <skill目錄>/inspector.sh

# Phase 2: Worker+Reviewer 迴圈
cd <專案目錄> && bash <skill目錄>/worker-reviewer.sh --loop

Step 4 — 輸出結果

完成後向用戶回報：

Harness 循環完成

Inspector:
  - 當前目標: ...
  - 架構判斷: ...
  - 新增/調整任務: N 個

Worker+Reviewer:
  - 完成任務: N 個
  - 被拒絕任務: N 個
  - 剩餘待領取: N 個

下一輪: 輸入 /harness 繼續

Step 5 — cron 模式（使用內建 CronCreate/CronDelete/CronList）

5.1 建立定時任務: /harness cron "<cron表達式>" [mode]

1. 解析 cron 表達式和可選的 mode（inspect / work / loop / full）
2. 根據 mode 建構 prompt 內容：
   • full: "執行 harness full cycle。依次執行： 1. cd <專案路徑> && bash <skill路徑>/inspector.sh 2. bash <skill路徑>/worker-reviewer.sh --loop 完成後回報結果。"
   • inspect: "執行 harness inspect。執行 cd <專案路徑> && bash <skill路徑>/inspector.sh。完成後回報結果。"
   • work: "執行 harness work。執行 cd <專案路徑> && bash <skill路徑>/worker-reviewer.sh。完成後回報結果。"
   • loop: "執行 harness loop。執行 cd <專案路徑> && bash <skill路徑>/worker-reviewer.sh --loop。完成後回報結果。"
3. 呼叫 CronCreate，參數：
   • cron: 用戶提供的 cron 表達式
   • prompt: 上面建構的 prompt
   • recurring: true
4. 向用戶確認建立成功，返回 job_id

5.2 查看定時任務: /harness cron list

1. 呼叫 CronList 獲取當前 session 所有 cron job
2. 過濾出 prompt 中包含 "harness" 關鍵字的 job
3. 以表格形式展示：job_id | cron 表達式 | mode | 建立時間（如有）
4. 如果沒有 harness cron，提示「當前 session 沒有 harness 定時任務」

5.3 刪除定時任務: /harness cron stop [job_id]

• 有 job_id: 呼叫 CronDelete 刪除指定 job，確認刪除成功
• 無 job_id:
  1. 呼叫 CronList，過濾 harness 相關 job
  2. 向用戶展示將要刪除的所有 job
  3. 用戶確認後，逐個呼叫 CronDelete 刪除
  4. 回報刪除結果

子行程輸入機制

每個子行程（Inspector / Worker / Reviewer）透過 claude -p 啟動，輸入由三部分組成：

1. 角色提示詞 — <skill目錄>/prompts/inspector.md 等
2. 專案文件 — 腳本自動拼接 AGENTS.md、CLAUDE.md、README、TODO.md 等檔案內容
3. 用戶額外上下文 — 從 /tmp/harness-context.txt 讀取，注入到 prompt 末尾

三部分拼接後傳給 claude -p，確保子行程既有專案全貌，又有用戶本輪的具體意圖。

預設情況下，腳本會把呼叫腳本時的當前工作目錄（pwd -P）視為專案目錄；如果需要從別處呼叫，可透過 HARNESS_PROJECT_DIR=/abs/path/to/project 顯式覆蓋。skill 安裝目錄只用於定位腳本和 prompts，不會被當成專案目錄。

檔案清單

檔案	職責
prompts/inspector.md	Inspector 角色提示詞
prompts/worker.md	Worker 角色提示詞
prompts/reviewer.md	Reviewer 角色提示詞
inspector.sh	Inspector 執行腳本
worker-reviewer.sh	Worker+Reviewer 執行腳本
TODO.md	共享任務看板（專案根目錄）