框架引導程式 (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 中讀取的內容為依據:
harness/config.sh:每個層級(設定、靜態分析、測試、冒煙測試、端到端測試)每行一個命令、基底分支,以及該技術堆疊的除錯模式。僅在該層級確實不存在時才將其留空;verify.sh會將空的必要層級報告為 UNVERIFIED 而非 PASSED。切勿用另一個層級已執行的命令來填入某個層級(例如將整合測試當作「端到端測試」):每個層級都必須添加其他層級無法提供的證據。請參閱references/discovery.md。harness/architecture-rules.json:每個邊界一條規則,遵循references/architecture-rules.md。每個規則都需要為代理工具撰寫why和fix,因為錯誤訊息就是回饋迴圈。- 文件:僅在儲存庫沒有等效文件時,才從
assets/docs-skeletons/開始建立docs/ARCHITECTURE.md、docs/PRODUCT.md、docs/RELIABILITY.md。根據你讀取的程式碼撰寫,每份文件保持在約 150 行以內,並將任何你無法確認的內容標記為TODO(confirm): ...,而非進行猜測。如果等效文件存在於其他位置,請連結到它們,而非複製一份。 - 決策記錄:腳手架會添加
docs/decisions/。如果儲存庫已在其他位置維護 ADR(例如doc/adr/、docs/adr/),請移除新建的資料夾,並將harness/README.md、交接與清理技能,以及範本指向現有位置。 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 Code | CLAUDE.md 包含 @AGENTS.md。預設情況下,僅當 CLAUDE.md 或 CLAUDE.local.md 不存在時,Claude Code 才會讀取 AGENTS.md。因此,一個同時包含兩者的儲存庫會在沒有匯入的情況下靜默忽略 AGENTS.md。 |
| Gemini CLI | GEMINI.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(僅使用標準函式庫)。請勿為了框架而為專案添加套件。 - 任何框架腳本的錯誤訊息都應說明失敗原因、為何失敗以及如何修正。
- 腳本中不應包含破壞性操作。清理腳本僅負責報告;由使用者或代理根據報告採取行動。
- 在可行時盡量縮小框架。對目前儲存庫的代理行為沒有影響的元件就是一種負擔;請說明原因,而非為了完整性而安裝它。