Neo Harness Project

Project Harness Builder

依專案現況建立可閱讀、可驗證、可恢復的工程環境。不得套用固定技術棧或理想架構，也不得建立沒有真實檢查能力的空殼。

邊界

• 本技能盤點並建置整個專案的 Harness。
• 需求只涉及 AGENTS.md 時，改用 neo-harness。
• 目標專案的 Harness 資產必須集中在根目錄 .neo_harness/；唯一例外是必須留在根目錄的 AGENTS.md。
• 技能套件自身的 references/、assets/ 與 evals/ 是技能實作資源，不屬於目標專案的 Harness 產出位置。
• 不得新增使用者未要求的第三方依賴、服務、部署或外部連線。
• 技能內容與產出必須保持供應商中立，不得提及任何特定模型供應商、產品、套件族、官方網址或供應商專屬中繼資料。
• 若無法在遵守中立要求的前提下準確記錄必要專案事實，停止相關產出並回報衝突；不得刪減或改寫事實以規避衝突。

Harness 資產位置規範

下列路徑均以目標專案根目錄為基準：

• 不得建立 .neo_harness/AGENTS.md；根目錄 AGENTS.md 是唯一的 Agent 入口。
• 所有其他 Harness 核心或條件式資產都必須放在 .neo_harness/ 內，並由根目錄 AGENTS.md 或相關文件連結。
• .neo_harness/ 是正式且應納入版本控制的專案資產；若被 .gitignore 或其他忽略規則排除，先標記為 blocked，不得自行修改忽略規則。
• 不得把非 Harness 文件、既有專案文件或技能套件自身的資源移入 .neo_harness/。

既有舊路徑的搬遷

若盤點發現下列舊路徑存在，必須先提供搬遷預覽並取得使用者對精確清單的明確確認：

• 搬遷預覽必須列出來源、目的地、受影響的連結或索引、驗證命令與復原方式。
• 目的地已存在、來源與目的地內容衝突，或目的地受忽略規則排除時，動作標記為 blocked；不得覆寫、刪除、建立重複副本或建立符號連結。
• 未經確認不得搬遷、批次改名或刪除舊路徑；確認後才可更新受影響的 Harness 連結，並保留可從版本控制或已報告快照復原的依據。
• 不屬於上述清單的舊文件不自動搬遷，除非使用者另行確認。

必要流程

1. 盤點，不寫入

先讀取專案規範、版本控制狀態、根目錄、套件與建置設定、測試、CI、文件、主要入口及現有 Harness 資產，包括 .neo_harness/ 正式路徑與上述舊路徑的既有檔案。命令必須來自可驗證的設定或文件，不得依技術棧猜測。

盤點時必須閱讀 專案評估模型，依來源證據判定成熟度與缺口。未知資訊標為「未知」，不得補成理想狀態。

2. 選擇產出

閱讀 資產選擇矩陣，將候選路徑分類為：

• create：路徑不存在，且已有足夠證據建立。
• update：保留有效內容並補齊缺口。
• rebuild：現有內容與已確認目標衝突，需重建。
• migrate：舊 Harness 路徑存在，需依確認結果搬到 .neo_harness/ 並更新受影響連結。
• skip：沒有需求或證據，不建立。
• blocked：缺少關鍵事實或違反中立要求。

預設納入核心知識、命令清單與計畫資產；只有矩陣條件成立時才納入 CI、架構檢查、執行環境、可觀測性與持續清理。

3. 提供寫入預覽

寫入前先提供：

1. 專案證據與成熟度。
2. 精確目標路徑及 create、update、rebuild、migrate、skip 或 blocked 動作。
3. 每項動作的事實依據與內容摘要。
4. 既有檔案衝突、驗證命令與失敗復原方式。

取得使用者對全部或指定路徑的明確確認。使用者初始提出「建立 Harness」不代表已確認未知的重建或搬遷清單；提供預覽前不得寫入。

4. 依確認結果產生

寫入前閱讀 產生、驗證與復原，以 核心模板 為結構起點；依專案事實改寫並移除所有模板標記，不得直接複製未完成模板。

• 採用目前專案的命名、工具與文件語言；無法判定時採用使用者語言。
• 只修改預覽列出的已確認路徑；搬遷時來源、目的地與連結更新都必須列在確認清單中。
• rebuild 必須保留仍正確的專案事實，並可從版本控制或已報告的暫存快照復原。
• migrate 只能在確認後執行；先完成內容與連結的核對，再移除來源路徑，且不得覆寫既有目的地。
• 空的執行計畫目錄以最小追蹤檔保存，不填入虛構計畫。
• 新建立的執行計畫檔名必須使用 YYYYMMDDHHmmss_<原計畫檔名>.md；時間戳取建立當下執行環境的本地時間，從 active 移至 completed 時保留原時間戳。既有計畫搬遷至 .neo_harness/ 時保留原檔名與時間戳。
• 既有未加時間戳的計畫不批次改名；更新既有計畫時沿用原檔名。
• .neo_harness/docs/scripts.md 必須只含 指令、用途 兩欄的 Markdown table，收錄專案設定或文件可驗證的所有命令；沒有可驗證命令時只保留空表頭。
• 沒有可驗證的統一驗證命令時，從 AGENTS.md 移除統一驗證命令與相應完成條件，不保留模板標記。
• 規則可由機器可靠判斷時，優先使用既有工具建立可執行檢查；否則明確記錄為文件規則。

5. 閉環驗證

1. 確認建立、更新、重建或搬遷的檔案均在確認清單中。
2. 若有搬遷，確認來源已依核准方案處理、目的地內容完整，且所有受影響連結均指向 .neo_harness/。
3. 檢查文件連結、命令、路徑、架構描述及模板標記。
4. 驗證新計畫檔名的時間戳格式，以及 .neo_harness/docs/scripts.md 的兩欄 Markdown table 格式。
5. 執行專案原有快速檢查及新增的統一驗證入口。
6. 失敗時讀取完整錯誤，修正根因後重跑。
7. 回報產出、未解缺口、命令與結果；沒有通過證據不得宣告完成。

完成條件

• 新工作階段只靠目前專案即可找到核心資產所需的知識、限制與驗證方法。
• .neo_harness/docs/scripts.md 列出完整且可追溯的專案命令。
• 新建立的計畫檔案可依時間戳前綴排序，且在生命週期中移動時保留前綴。
• 根目錄 AGENTS.md 是唯一入口，其餘 Harness 資產均位於 .neo_harness/ 且連結一致。
• 所有命令均可追溯至專案設定並可執行。
• 沒有假成功命令、未完成模板、虛構架構或未經確認的重建。
• 沒有未經確認的搬遷、批次改名、覆寫或刪除；搬遷衝突會明確標記為 blocked。
• 條件式資產都有專案證據，未選用項目都有明確原因。
• 產出保持供應商中立，並交付驗證結果與剩餘缺口。