Community程式設計與開發github.com

harness-bootstrap

在任意 Git 儲存庫中安裝一套完整、可供團隊使用的代理工具框架,包含入口檔案、架構與可靠性文件、分層驗證腳本、可執行的架構規則、僅能由驗證器變更的任務功能清單、本地端的階段交接與進度檔案、乾淨狀態檢查清單、獨立評估器,以及強制執行所有規範的完整性檢查。

harness-bootstrap 是什麼?

此技能旨在將任意 Git 儲存庫轉變為一個「代理就緒」(agent-ready)的專案。它會安裝一套稱為「框架」(harness)的約定,包含 `CLAUDE.md` / `AGENTS.md` 入口檔案、架構與可靠性文件、分層驗證腳本、可執行的架構規則,以及一個僅能由驗證器變更的任務功能清單。這套框架解決了常見的代理協作痛點:跨階段遺失上下文、在未驗證情況下聲稱「完成」,以及開發者之間或不同工作目錄間的交接。 此技能適用於任何編碼代理工具,如 Claude Code、Codex、Cursor、Copilot、Devin、Pi 等。它會自動探索專案現有的構建與測試命令、架構邊界,以及團隊所使用的代理工具。安裝後,每個新的代理階段都能從儲存庫中回答五個關鍵問題:這是什麼、如何組織、如何執行、如何驗證,以及上次進行到哪裡。任務狀態等敏感資料會儲存在本地的 `.harness/` 目錄(已加入 `.gitignore`),以避免合併衝突。此框架透過 `harness-start`、`harness-handoff`、`harness-cleanup` 和 `harness-evaluate` 等生命週期技能,讓整個團隊遵循相同的規則與流程。

相容平台✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI✓OpenCode✓Windsurf
npx skills add https://github.com/Gabriel-Valin/harness-bootstrap/tree/HEAD

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

框架引導程式 (Harness Bootstrap)

將一個儲存庫打造成一個環境,讓任何全新的代理階段,在任何開發者的機器上,都能僅從儲存庫中回答五個問題:這是什麼、如何組織、如何執行、如何驗證,以及上次進行到哪裡。接著,讓「完成」變成由腳本決定,而非代理自行宣告。

此技能每個儲存庫僅執行一次。它會安裝一個團隊共同提交的合約,以及儲存在儲存庫內的生命週期技能(harness-start、harness-handoff、harness-cleanup、harness-evaluate)。如此一來,每次複製儲存庫時,所有團隊成員都能獲得這些技能,無論他們使用何種編碼代理工具。

此檔案中的路徑(scripts/、references/、assets/)是相對於包含此 SKILL.md 的目錄。該目錄的位置取決於代理工具的安裝方式和技能本身的安裝方式,因此請從你載入此檔案的位置解析它;切勿假定一個固定的路徑(例如 ~/.claude/skills/)。

如果你需要任何成品(例如,向使用者解釋或將其改編至非標準的儲存庫)的背後邏輯,請閱讀 references/principles.md。

你所安裝的模型

層級位置是否提交?目的
入口檔案CLAUDE.md 和/或 AGENTS.md是簡短地圖:這是什麼、如何執行、如何驗證、硬性規則、連結
文件docs/ARCHITECTURE.md、PRODUCT.md、RELIABILITY.md、docs/decisions/是代理無法從程式碼推斷出的知識
合約harness/(設定、規則、檢查清單、評分量表、品質文件、範本、README)是所有人遵循相同規則,僅能透過 PR 更改
驗證scripts/harness/是init.sh、verify.sh、feature.py、check_architecture.py、cleanup-scan.sh
生命週期.agents/skills/harness-*,並鏡像至代理讀取的其他資料夾是開始、交接、清理、評估
調適器依代理而異,例如 Claude Code 的 .claude/agents/、.claude/hooks/是選擇性擴充:子代理、鉤子
任務狀態.harness/tasks/<TASK-ID>/否單一任務的功能清單、合約、進度、交接、執行記錄

任務狀態是本地的,因為它每個階段都會變動,且屬於個人分支。提交它會導致合併衝突,並讓一個開發者的過時狀態誤導另一個開發者的代理。它是一個快取:所有持久性內容會在任務結束前提升為程式碼、測試、文件、PR 或問題追蹤器。harness/README.md 會向團隊說明這一點。

工作流程

1. 確認目標

在使用者指定的目錄中執行 git rev-parse --show-toplevel。如果不是 Git 儲存庫,請停止並告知:工作目錄隔離和基底分支檢查都依賴 Git。檢查工作目錄是否為髒狀態;建議在獨立分支上執行引導程式,以便以一個 PR 進行審閱。

2. 盤點現有內容

在寫入之前先查看。找出並閱讀:

  • 指令檔案:AGENTS.md、CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md、GEMINI.md、.cursorrules、.cursor/rules/、.github/copilot-instructions.md、.windsurfrules
  • 文件:README*、docs/、ADR 資料夾、CONTRIBUTING*
  • 現有框架元件:feature_list.json、progress.md、init.sh、Makefile、harness/、scripts/harness/、.harness/
  • 代理設定與技能:.agents/skills/、.claude/ (settings.json、skills/、agents/、hooks/)、.devin/、.cursor/、.github/、.worktreeinclude
  • .gitignore

現有內容優先。你應擴展它;未經詢問,切勿取代團隊已寫入的檔案。

3. 探索專案執行方式

遵循 references/discovery.md。目標是為每個驗證層級取得一個經過驗證的命令清單,每個命令都附帶你找到它的來源(CI 設定是最有力的證據,因為那是團隊真正信任的內容)。同時識別程式碼的各層級或模組,以及它們之間的依賴方向;這些將成為架構規則。

4. 僅詢問資訊缺口

將你無法從儲存庫中回答的問題批次整理成一次結構化的問題呼叫(如果你的環境支援),否則整理成單一訊息。常見的資訊缺口包括:

  • 你推測但無法確定的架構邊界(例如「ui/ 允許匯入 db/ 嗎?」)
  • 端到端或冒煙測試命令(如果不存在)
  • 基底分支與分支命名慣例(如果未文件化)
  • 團隊使用的編碼代理工具(Claude Code、Codex、Cursor、Copilot、Devin、Pi 等)。這將決定入口檔案與要安裝的代理調適器。
  • 如果團隊使用 Claude Code:是否安裝其鉤子(建議安裝;它們在階段開始時呈現任務狀態,並在任務狀態被手動編輯前予以阻止)

不要詢問具有常規預設值的項目;直接選取一個,並在最終報告中提及。

5. 複製腳手架

bash <此技能目錄>/scripts/install.sh <儲存庫根目錄> --agents <代理工具ID清單>

--agents 參數接受步驟 4 中團隊使用的代理工具,以逗號分隔的 ID 表示,這些 ID 與 npx skills CLI 使用的 ID 相同(claude-code、codex、cursor、github-copilot、gemini-cli、opencode、pi、devin、windsurf、kiro-cli...;使用 --help 可列出所有選項)。

此腳本會將 assets/project/ 的內容複製到儲存庫中,包括 .agents/skills/ 中的生命週期技能,大多數代理工具會直接讀取這些技能。對於讀取其他資料夾的代理工具(claude-code、devin、windsurf、kiro-cli),它會添加指向這些技能的相對符號連結;對於在 assets/adapters/<id>/ 中有調適器的代理工具,它會複製調適器檔案。當團隊使用不支援符號連結的 Windows 檢出時,請傳遞 --copy 以進行複製而非建立符號連結;init.sh 隨後會報告已漂移的副本。此腳本絕不覆蓋任何現有路徑,會將腳本標記為可執行,並針對每個路徑印出 CREATED / LINKED / SKIPPED。如果儲存庫已有框架元件,請先使用 --dry-run。對於每個 SKIPPED 的路徑,請手動讀取現有檔案並將缺少的想法合併進去,而非強制套用範本。

如果腳本報告 FAILED 路徑,你的代理沙盒可能保護了某個資料夾(例如 .agents/ 或 .claude/;Codex 預設會保護 .agents/)。請使用你的環境提供的權限重新執行相同的命令,或要求使用者執行。切勿為了繞過此限制而將技能移至其他資料夾:代理工具僅在它們讀取的資料夾中發現技能,因此搬移後的技能將靜默失效。

6. 填入專案特定資訊

所有腳手架無法得知的資訊都需由你撰寫,並以你在步驟 2-4 中讀取的內容為依據:

  1. harness/config.sh:每個層級(設定、靜態分析、測試、冒煙測試、端到端測試)每行一個命令、基底分支,以及該技術堆疊的除錯模式。僅在該層級確實不存在時才將其留空;verify.sh 會將空的必要層級報告為 UNVERIFIED 而非 PASSED。切勿用另一個層級已執行的命令來填入某個層級(例如將整合測試當作「端到端測試」):每個層級都必須添加其他層級無法提供的證據。請參閱 references/discovery.md。
  2. harness/architecture-rules.json:每個邊界一條規則,遵循 references/architecture-rules.md。每個規則都需要為代理工具撰寫 why 和 fix,因為錯誤訊息就是回饋迴圈。
  3. 文件:僅在儲存庫沒有等效文件時,才從 assets/docs-skeletons/ 開始建立 docs/ARCHITECTURE.md、docs/PRODUCT.md、docs/RELIABILITY.md。根據你讀取的程式碼撰寫,每份文件保持在約 150 行以內,並將任何你無法確認的內容標記為 TODO(confirm): ...,而非進行猜測。如果等效文件存在於其他位置,請連結到它們,而非複製一份。
  4. 決策記錄:腳手架會添加 docs/decisions/。如果儲存庫已在其他位置維護 ADR(例如 doc/adr/、docs/adr/),請移除新建的資料夾,並將 harness/README.md、交接與清理技能,以及範本指向現有位置。
  5. harness/quality-document.md:列出真實的模組,並附上誠實的初始評級;對於沒有證據的模組,則標記為 unknown。切勿根據感覺進行評級。

7. 連接入口檔案

將 assets/snippets/entry-section.md 中的段落插入入口檔案,靠近頂端或底部(模型對長檔案的開頭和結尾記憶力較佳)。保持入口檔案作為路由器:如果它超過約 200 行,請將詳細資訊移至 docs/ 並連結到它們。

AGENTS.md 是規範的入口檔案:大多數編碼代理工具會直接讀取它。其他代理工具僅會獲得一個指向它的輕量指標,而非規則的第二份副本,這樣檔案之間就不會產生分歧。

情況做法
AGENTS.md 和 CLAUDE.md 都不存在根據你學到的內容建立 AGENTS.md,並包含該段落。
僅 AGENTS.md 存在將該段落加入 AGENTS.md。
僅 CLAUDE.md 存在,且團隊僅使用 Claude Code將該段落加入 CLAUDE.md。
僅 CLAUDE.md 存在,但團隊也使用其他代理工具在移動之前先詢問:提議將其內容移至 AGENTS.md,並在 CLAUDE.md 中保留 @AGENTS.md。如果團隊拒絕,則將該段落加入 CLAUDE.md,並建立包含該段落和指向 CLAUDE.md 連結的 AGENTS.md。
兩者都存在將該段落加入 AGENTS.md,並確保 CLAUDE.md 使用 @AGENTS.md 匯入它。

接著,為團隊使用但預設不讀取 AGENTS.md 的每個代理工具添加指標:

代理工具指標
Claude CodeCLAUDE.md 包含 @AGENTS.md。預設情況下,僅當 CLAUDE.md 或 CLAUDE.local.md 不存在時,Claude Code 才會讀取 AGENTS.md。因此,一個同時包含兩者的儲存庫會在沒有匯入的情況下靜默忽略 AGENTS.md。
Gemini CLIGEMINI.md 包含 @AGENTS.md,或是在 .gemini/settings.json 中設定 "contextFileName": "AGENTS.md"。
任何在儲存庫中已有自己的規則檔案的代理工具(.github/copilot-instructions.md、.cursor/rules/、.windsurfrules)在該檔案中新增一行,指示讀取包含規則的 AGENTS.md。

對於你不確定的代理工具,請查閱其官方文件以確認其目前的行為,而非進行猜測;代理工具會更改它們讀取的檔案。

8. 合併設定

  • .gitignore:附加上 assets/snippets/gitignore.txt 中缺失的行。
  • 僅限 Claude Code,.claude/settings.json:合併 assets/adapters/claude-code/settings-hooks.json 中的鉤子。讀取現有檔案,將內容附加到現有的 hooks.SessionStart / hooks.PreToolUse 陣列中,而非取代它們,並保持 JSON 有效。如果團隊拒絕使用鉤子,請跳過此步驟,並刪除調適器複製的 .claude/hooks/。框架不依賴鉤子:feature.py 會封裝任務狀態,並在手動編輯後拒絕運作;入口檔案會告訴每個代理在階段開始時執行 init.sh。
  • 僅限 Claude Code,.worktreeinclude:如果專案需要像 .env 這樣的被 Git 忽略的檔案才能執行,請列出它們,以便 Claude Code 建立的每個工作目錄都能獲得一份副本。對於普通的 git worktree add,請在 harness/README.md 中提及這些檔案,以便使用者自行複製。

9. 執行一次驗證

執行 bash scripts/harness/init.sh 和 python3 scripts/harness/check_architecture.py,並報告真實結果。如果某項失敗是因專案本身(而非框架)所致,請如實說明,並將其保留為報告中的第一個條目;切勿為了讓檢查通過而放寬規則或刪除命令。接著,執行 references/principles.md 中的全新階段測試:僅使用這些檔案來回答那五個問題,並修正任何你無法回答的項目。

10. 報告

簡短地告知使用者:

  • 已建立哪些內容、已合併哪些內容,以及哪些內容因已存在而跳過
  • 每個層級的命令及其來源
  • 所有的 TODO(confirm) 以及你做出的所有假設
  • 初始化/驗證的結果,包括失敗項目
  • 如果此技能本身已安裝到儲存庫中(.agents/skills/harness-bootstrap/ 或其他代理的技能資料夾中,以及 skills-lock.json),請告知:團隊在引導程式完成後不再需要它,可以將其刪除或保留以供日後重新執行。請勿自行刪除。
  • 下一步:在分支上審閱並提交引導程式碼,然後使用 harness-start 技能開始一個任務(在支援斜線命令的代理中,使用 /harness-start <TASK-ID>)

除非使用者要求,否則請勿提交或推送。

改編腳手架的設計規則

  • 優先使用專案現有的工具。如果儲存庫有包含 make check 的 Makefile,請將 make check 放入 config.sh,而非重新列出其組成部分。
  • 將執行時期依賴限制為 bash、git 和 python3(僅使用標準函式庫)。請勿為了框架而為專案添加套件。
  • 任何框架腳本的錯誤訊息都應說明失敗原因、為何失敗以及如何修正。
  • 腳本中不應包含破壞性操作。清理腳本僅負責報告;由使用者或代理根據報告採取行動。
  • 在可行時盡量縮小框架。對目前儲存庫的代理行為沒有影響的元件就是一種負擔;請說明原因,而非為了完整性而安裝它。

相關技能