Coding Harness Designer v1

"效率不彰的原因不在於代理人的能力，而在於環境有所不足。" — OpenAI "不要讓生成者自己評估自己的作品。" — Anthropic "當代理人犯錯時，請將其設計成不會再犯相同的錯誤。" — Mitchell Hashimoto

此技能與 harness-designer 的關係

┌─────────────────────────────────────────────────────────────┐
│  共同基礎：Harness 設計五大支柱                               │
│  Progressive Disclosure / Mechanical Enforcement /           │
│  Feedback Loop / Session Continuity / Entropy Management     │
├──────────────────────────┬──────────────────────────────────┤
│  harness-designer (既有)  │  coding-harness-designer (此技能)│
│  分析·決策工作區            │  編碼·開發工作區                  │
│  代理人 = 觀點角色          │  代理人 = 編碼工作者               │
│  產出物 = 報告·決策          │  產出物 = 原始碼·測試             │
│  驗證 = 檢查清單·討論       │  驗證 = CI·Linter·瀏覽器測試       │
│  "會議室設計"               │  "生產線設計"                     │
└──────────────────────────┴──────────────────────────────────┘

編碼 Harness 七大支柱

在既有的五大支柱上，加入兩個專為編碼設計的支柱：

支柱	核心問題	原則
漸進式揭露 (Progressive Disclosure)	代理人是否能只看到必要的資訊？	AGENTS.md ~100行列目錄 → docs/
機械化強制 (Mechanical Enforcement)	架構是否能被機械性地強制執行？	Linter·結構測試·CI
回饋迴路 (Feedback Loop)	失敗時代理人是否能自行修正？	錯誤訊息應教導修正方法
會話連續性 (Session Continuity)	會話之間的交接是否乾淨？	progress + feature-status + git
熵管理 (Entropy Management)	隨著時間推移，程式碼品質是否仍能維持？	自動掃描·重構·品質評級
架構剛性 (Architectural Rigidity) ← 新增	模組邊界是否被強制執行？	層級規則·依賴方向驗證
可觀測運行時 (Observable Runtime) ← 新增	代理人能否看到執行結果？	日誌·指標·DOM·螢幕截圖存取

兩個層級的關係

┌─────────────────────────────────────────────────────────────┐
│  第一層：後設 (此技能的角色)                                 │
│                                                             │
│  Planner ──→ Generator ──→ Evaluator                        │
│     ↑         (單向順序，禁止反向參照)                      │
│     └──── 不完善時提供回饋 ─────────────────────────────┘      │
│                                                             │
│  目的：設計、生成與驗證編碼 Harness 結構                       │
└─────────────────────────┬───────────────────────────────────┘
                          │ 核准後 Harness 完成
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  第二層：營運 (已完成之編碼 Harness 的角色)                   │
│                                                             │
│  ┌ Initializer (首次執行) ─→ 建立 Scaffold + 環境設定        │
│  │                                                          │
│  └ Coding Agent (重複執行):                                 │
│    1. 讀取 progress → 選擇下一個任務                          │
│    2. 實作 (生成程式碼)                                      │
│    3. 自我驗證 (測試·Linter·瀏覽器)                          │
│    4. 請求審查 (代理人之間的程式碼審查)                        │
│    5. 納入回饋 → 重複                                        │
│    6. 以乾淨狀態進行提交                                     │
│                                                             │
│  目的：實際進行程式碼撰寫·測試·重構·部署                       │
└─────────────────────────────────────────────────────────────┘

第一層：後設 — 編碼 Harness 設計流程

L1 三種代理人 (單向順序，禁止反向參照)

Planner (規劃者)

分析使用者需求，設計編碼 Harness 的結構。

輸入：專案需求 (透過提問收集)
輸出：架構設計 + 資料夾結構 + 強制規則 + 評估標準

Generator (生成者)

將 Planner 的設計方案轉化為實際的檔案與設定。

輸入：Planner 核准的設計方案
輸出：AGENTS.md, docs/, Linter 規則, CI 設定, 測試結構

Evaluator (評估者)

基於七大支柱，獨立驗證 Generator 的產出。

輸入：Generator 產生的檔案 + Planner 的評估標準
輸出：各支柱分數 + 功能性驗證 + 改善回饋

L1 Phase 0: 模式比對 — 參考 harness-100 (新增於 v1.1)

"優秀設計的 99% 已經有人完成了。找到它，然後進行修改。"

在開始探索之前，請先從 harness-100 (https://github.com/revfactory/harness-100, Apache-2.0) 經過驗證的範例中，找出最相似的一個作為參考基準。非開發者則引導其切換至 harness-starter-coding 技能。

目標範例 (編碼領域 27 個)

Dev&DevOps #16–30: fullstack-webapp, mobile-app-builder, api-designer, database-architect, devops-pipeline, security-audit, performance-tuning, refactoring-squad, test-automation, monitoring-setup 等
Data&AI/ML #31–42: ml-experiment, data-pipeline, rag-llm-app, nlp-processer, recommendation-engine, design-system 等

Phase 0 流程

從使用者 1~2 句話的請求中，提取應用程式類型的關鍵字
從上述 27 個中，提出前 3 個候選方案 + 請使用者確認
將所選範例的編號記錄在 _workspace/00_input.md 的 reference_exemplar 欄位
比對相似度 < 0.5 → 退回至自由設計模式 (繼續執行原有的 Phase 1)

將 Phase 0 的結果反映至後續階段

Planner: 以範例的 5 代理人配置為基礎，但根據 Scale Mode (Full/Reduced/Single) 進行調整
Generator: 優先使用範例的骨架 Scaffold，強制使用 _workspace/NN_*.md 編號慣例
Evaluator: 使用範例的 8 項品質標準 (Agent Team Mode / Domain Expertise / Structured Outputs / Dependency DAG / Error Handling / Scale Modes / Test Scenarios / Trigger Boundaries) 作為評分標準

模式保真度 (定性評估，僅限 Phase 0)

不包含在自動化的七大支柱評分中。在 Phase 0 進行範例比對時，進行定性評估。

在 Phase 0 中，針對所選的 harness-100 範例的 8 項品質標準 (Agent Team Mode / Domain Expertise / Structured Outputs / Dependency DAG / Error Handling / Scale Modes / Test Scenarios / Trigger Boundaries) 進行檢查。

檢查時機：在 Phase 0 (選擇範例) 時進行一次，在 Evaluator PASS 並回報時再進行一次
不計分：不包含在七大支柱 23 個項目的評分中
pillar-weight：僅可調整七大支柱的權重。Pattern Fidelity 不屬於權重調整的對象

觸發邊界 (should + NOT)

Planner/Generator 在所產生的 orchestrator skill.md 中必須包含 should-NOT trigger 區段。例如：「禁止用於行動應用程式·企業級微服務·靜態網站」。

Coding Agent 行為原則 (受 Karpathy 啟發，必須注入)

Generator 必須在生成的 .claude/CLAUDE.md 結尾處必須包含以下區段。這 4 項原則應與 karpathy-guidelines 技能 (需獨立安裝) 同步，並作為此 Harness 內所有 Coding Agent 的基本行為準則。

## Coding Agent 行為原則 (受 Karpathy 啟發)

所有 Coding Agent 在執行任務時都應遵守以下 4 項原則。
詳細內容請參考 karpathy-guidelines 技能 (會自動觸發)。

1. Think Before Coding — 明確說明假設，若不明確則提問，並提出替代方案
2. Simplicity First — 只做被要求的部分。禁止進行推測性的抽象化或功能添加
3. Surgical Changes — 僅修改被要求的行數。禁止改善周邊程式碼
4. Goal-Driven Execution — 設定可驗證的成功標準 → 執行迴圈 → 確認結果

在 Evaluator 的檢查清單中，新增「CLAUDE.md 中是否包含 Karpathy 4 原則區段」項目。

Scale Modes (營運層默認值)

模式	代理人配置
Full	architect + frontend + backend + qa + devops
Backend	architect + backend + qa
Frontend	architect + frontend + qa
Refactoring	architect + 相關開發者 + qa
DevOps	devops 單獨

L1 Phase 1: 探索 — Planner 運作

探索由 4 個階段的提問構成。依序進行每個階段，並根據使用者的回答決定後續問題。 在收到一個階段的回答後，再進入下一個階段。 不要一次問完所有問題。

1-1. 階段 1 — 目的與脈絡 (WHY / WHO)

重點在於技術，而是了解此專案存在的理由。

P1. 此專案想解決的問題是什麼？
    (想要消除哪些不便/無效率？)

P2. 誰會使用它？
    (內部員工 / 客戶 / 開發者 / 非特定多數)
    → 後續：使用者人數是？IT 熟練度如何？

P3. 此專案的成功標準是什麼？
    (達到什麼狀態才能稱之為「做得好」？)

P4. 是否有類似的既有系統？
    (是取代既有系統 / 還是全新開發)
    → 後續 [取代]：既有系統最大的問題點是什麼？
    → 後續 [全新]：是否有作為基準的服務？

後續問題分支：

P2 回答為「內部員工」→「多少人？是否有部門結構？是否需要權限體系？」
P2 回答為「客戶」→「註冊方式是什麼？是否需要付款？是否涉及個人資料處理？」
P3 回答提及具體數值 →「測量該數值的方法是什麼？」
P3 回答模糊 →「具體來說，哪個畫面/功能運作起來才算成功？」

1-2. 階段 2 — 功能與內容 (WHAT)

包含什麼內容，核心功能是什麼。

F1. 請按優先順序列出 3 項核心功能？
    (從必須最先運作的功能開始)

F2. 資料的性質是什麼？
    (關聯式 / 文件式 / 時間序列 / 檔案 / 混合)
    → 後續：資料之間的關係複雜嗎？彙整/統計是否重要？

F3. 有沒有驗證/權限需求？
    (無 / 簡單登入 / 基於角色 / 組織層級權限)
    → 後續 [基於角色或以上]：權限等級有幾層？是否需要資料隔離？

F4. 是否需要與外部系統整合？
    (無 / API 整合 / 檔案 import/export / 付款 / 通知)

F5. 是否需要離線或行動裝置支援？

後續問題分支：

F1 回答超過 3 項功能 →「如果將各項功能的複雜度分為高/中/低三個等級，你會如何評估？」
F2 回答「混合」→「混合了哪些類型的資料？是否需要分離儲存庫？」
F3 回答「組織層級」→「部門的新增/變更是否頻繁？是否需要在不修改程式碼的情況下進行擴展？」

1-3. 階段 3 — 技術與結構 (HOW)

如何建構。應反映階段 1~2 的回答，提出合適的技術。

T1. 是否有偏好的技術棧？
    (若有請說明 / 若無則回答 "請推薦")
    → 推薦「無聊的技術」(Boring Technology)：代理人能更好地運作於穩定且學習資料豐富的技術上 (OpenAI 原始概念)
    → 根據階段 1~2 的回答，提出合適的技術棧

T2. 部署環境是什麼？
    (Vercel / AWS / 公司內部伺服器 / 不知道)

T3. Coding Agent 工具是什麼？
    (Claude Code / Codex / Cursor / 其他)
    → 根據工具不同，Harness 的設定方式也會不同

T4. 代理人的自主性程度為何？
    (由人審查後合併 / 代理人互相審查後自動合併 / 完全自主)

T5. 專案的規模與時間長度為何？
    (原型 1~2 週 / 中型 1~3 個月 / 大型長期)

T6. 是否有既有的程式碼基底？
    (全新 / 將 Harness 套用至既有程式碼)
    → 若是既有程式碼，則設計漸進式套用策略

後續問題分支：

T1 回答「請推薦」→ 基於階段 1~~2 的回答，提出 2~~3 個選項的比較表，待其選擇
T2 回答「不知道」→ 基於使用者規模與功能進行推薦
T5 回答「大型」→「團隊規模如何？同時工作的代理人數量是多少？」

1-3.5. 階段 3.5 — 流程變更歷史追蹤 (FLOW HISTORY) [選擇性]

若專案為長期或可能橫跨多個會話而演化時，建議採用。 1~2 週的原型專案則可跳過。

F1. "未來當提示、協定、範本、API 腳本、指令、CLAUDE.md 等有所變更時，是否要保留其歷史記錄？"

    用途：
    - 回顧專案改善歷程 (為何如此改變)
    - 需要回退至先前版本時，可作為依據
    - 設計下一個類似編碼 Harness 時的參考

    ※ 並非每次新會話時都需讀取的內容。
      僅在修改、回退、移植流程時才參考。

    → "否" → 不包含 05-flow-history/。直接進入階段 4。
    → "是" → 進入 F2。

F2. "是否要將初始建置 (v1) 自動記錄為 change 0001 記錄？"
    - 預設值：是 (Planner Discovery 的回答會作為設計依據保留下來)
    - 否 → 僅建立 CHANGELOG，並在首次變更時手動記錄

流程歷史管理原則 (建立後，以營運為基準)： 此歷史記錄僅記錄 工作流程系統 (提示·協定·範本·API 腳本·指令·CLAUDE.md) 的變更。該系統所產生的 產出物 (程式碼·報告·分析結果) 則不在記錄範圍內。區分標準：「如果沒有這項變更，則下一次執行的結果是否會不同？」 → 會不同 = 系統變更 = 記錄 / 不會不同 = 產出物 = 不需要記錄詳細：00-system/protocols/flow-change-protocol.md

Planner 輸出新增 (與流程歷史相關)：

flow_history_enabled: true/false
flow_history_initial_record: true/false (F2 的回答)

1-4. 階段 4 — 品質與評估標準 (QUALITY / EVALUATE)

了解使用者重視的價值，並協商評估標準。

E1. 此專案最重要的品質屬性為何？ (請選擇前 3 項)
    □ 安全性 (權限、資料隔離、驗證)
    □ 效能 (回應速度、同時連線數)
    □ 可擴展性 (無需修改程式碼即可擴展規模)
    □ 可維護性 (其他人/代理人可輕鬆修改)
    □ 使用者體驗 (直覺的 UI、快速響應)
    □ 可測試性 (透過自動化測試保證品質)
    □ 快速上市 (MVP 優先，完善度其次)
    □ 資料一致性 (準確記錄、避免遺漏)

E2. 是否有未來擴展的計畫？
    (無 / 功能新增 / 與其他系統整合 / 使用者規模擴展)
    → 後續：具體是哪些擴展？時間點為何？

E3. 在此專案中，絕對不能妥協的是什麼？
    (例如: "不能破壞權限隔離", "資料不能遺失")

E4. 相對地，初期階段即使沒有也沒關係的是什麼？
    (例如: "行動裝置對應可以之後再做", "統計儀表板可以等到第二階段再做")

後續問題分支：

E1 選擇「安全性」→「是什麼類型的安全性？驗證/權限/資料加密/稽核日誌？」
E2 回答「與其他系統整合」→「是什麼系統？資料格式是否相容？」
E3 的回答 → 將作為 Evaluator 權重調整的核心輸入

1-5. 評估權重協商 (階段 4 完成後)

分析階段 1~4 的回答，提出七大支柱的權重。與使用者協商後最終確定。

[權重提議流程]

步驟 1. 從階段 1~4 的回答中提取關鍵字
  - "權限隔離" → Mechanical Enforcement, Architectural Rigidity ↑
  - "無需修改程式碼即可擴展" → Architectural Rigidity ↑
  - "快速上市" → Entropy Management ↓, Observable Runtime ↑
  - "資料一致性" → Feedback Loop ↑, Mechanical Enforcement ↑

步驟 2. 從預設權重進行調整並提議

  預設權重 (反映專案特性前)：
  | 支柱 | 預設 | 調整依據 | 提議 |
  |------|------|----------|------|
  | Progressive Disclosure | 15% | (變動依據) | ?% |
  | Mechanical Enforcement | 20% | (變動依據) | ?% |
  | Feedback Loop | 15% | (變動依據) | ?% |
  | Session Continuity | 10% | (變動依據) | ?% |
  | Entropy Management | 10% | (變動依據) | ?% |
  | Architectural Rigidity | 20% | (變動依據) | ?% |
  | Observable Runtime | 10% | (變動依據) | ?% |

  "考量到 [依據]，此專案的 [支柱] 權重已從 [預設]% 調整為 [提議]%。
  如有任何意見或需要修改的地方，請告訴我。"

步驟 3. 反映使用者回饋
  - 同意 → 確認
  - "請提高安全性權重" → 調高相關支柱的權重，並調降其他支柱的權重後重新提議
  - "不需要這個支柱" → 設為 0%，重新分配其餘部分後重新提議

步驟 4. 最終批准
  "最終權重已確認。Evaluator 將使用此權重進行評分。"
  → 使用此協商後的權重，而非 evaluator-protocol.md 中的預設權重

1-6. 架構模式自動對應

→ 參考 references/architecture-patterns.md → 根據階段 2~3 的回答，提出最合適的模式

應用程式類型	推薦的層級結構
全端網頁應用程式	Types→Config→Repo→Service→Runtime→UI
API 服務	Types→Config→Repo→Service→Runtime
CLI 工具	Types→Config→Core→CLI
函式庫	Types→Core→Public API

1-7. Planner 產出物

① 專案脈絡摘要 — 目的、使用者、成功標準、核心限制 (基於階段 1~2) ② 架構設計方案 — 層級結構、模組邊界、依賴方向 ③ 資料夾結構草稿 — 基於 references/coding-folder-patterns.md ④ 強制規則設計 — 哪些規則要透過 Linter/CI/結構測試強制執行 ⑤ 測試策略 — 單元/整合/E2E 範圍與覆蓋率標準 ⑥ 代理人自主性設計 — 審查迴路、批准關卡、升級標準 ⑦ 擴展策略 — 為未來擴展所做的設計決策 (基於階段 4 E2) ⑧ 評估標準 + 協商後的權重 — 七大支柱檢查清單 + 權重表格

[Planner 完成 — 請使用者批准]
請檢閱①~⑧，如有需要修改的地方，請告訴我。
一經批准，Generator 將開始進行建置。

L1 Phase 2: 建置 — Generator 運作

2-1. 核心產出物生成 (依序)

順序	產出物	說明
2-1a	架構圖	Mermaid — 層級·模組·依賴方向
2-1b	AGENTS.md (~100 行)	作為目錄，包含參照路由
2-1c	docs/ 目錄	請參閱下方詳細說明
2-1d	架構強制規則	Linter 規則 + 結構測試
2-1e	CI/CD 管線設計	定義驗證關卡
2-1f	測試結構	測試目錄 + 基本設定
2-1g	會話交接產出物	progress.json + feature-status.json
2-1h	程式碼審查迴路設定	代理人之間的審查協定
2-1i	可觀測性設定	日誌·指標·DOM 存取方式
2-1j	README.md	開發者指南
2-1k	bkit 專案初始化	僅在 T3 偵測到 Claude Code + 安裝了 bkit 時，在使用者 opt-in 提問後才執行 (請參閱下方詳細說明)
2-1l	環境設定	虛擬環境·環境變數·Hooks — 不強制建立。在 Phase 3-7 由 LLM 提出建議後，由使用者選擇
2-1m	流程變更歷史 Wiki (選擇性)	僅當階段 3.5 F1=是時。參考 ~/.claude/skills/harness-designer-workspace/references/flow-history-template.md，建立 05-flow-history/ + 00-system/protocols/flow-change-protocol.md。在 AGENTS.md 中新增 2 行路由 + "流程變更追蹤 (選擇性記錄)" 區段。管理原則：僅記錄系統 (規則·程序·工具) 的變更。產出物 (程式碼·報告) 則不需要記錄。區分標準：「如果沒有這項變更，則下一次執行的結果是否會不同？」

2-1b. AGENTS.md 撰寫規則 (最為重要)

→ 參考 references/agents-md-template.md

直接套用 OpenAI 原始概念的核心教訓：

**~100 行列目錄。**不是百科全書。

# [專案名稱]

> [一行說明]

## 架構概覽
[層級結構 3 行摘要]
→ 詳細：docs/architecture.md

## 參照路由
| 情境 | 應讀取的檔案 |
|------|----------|
| 架構規則 | → docs/architecture.md |
| 編碼慣例 | → docs/conventions.md |
| 領域設計 | → docs/design/[domain].md |
| 執行計畫 | → docs/exec-plans/[plan].md |
| 品質評級 | → docs/quality-grades.md |
| 技術債務 | → docs/exec-plans/tech-debt-tracker.md |
| 會話狀態 | → progress.json |
| 功能狀態 | → feature-status.json |

## 核心規則 (5 項以內)
1. [不變規則 1 — 例如: "在所有邊界驗證資料型態"]
2. [不變規則 2 — 例如: "禁止層級反向依賴"]
3. [不變規則 3]

## 測試規則
→ docs/testing-strategy.md

## 指令
| 指令 | 功能 |
|--------|------|
| /implement [功能] | 實作功能 |
| /review | 執行程式碼審查 |
| /test | 執行測試 |
| /refactor [目標] | 重構 |

## 最後更新：YYYY-MM-DD

2-1c. docs/ 目錄 (System of Record)

→ 參考 references/docs-structure.md

docs/
├── architecture.md         ← 層級結構，模組邊界，依...

在你喜歡的 AI 中提問

說明文件

Coding Harness Designer v1

此技能與 harness-designer 的關係

編碼 Harness 七大支柱

兩個層級的關係

第一層：後設 — 編碼 Harness 設計流程

L1 三種代理人 (單向順序，禁止反向參照)

Planner (規劃者)

Generator (生成者)

Evaluator (評估者)

L1 Phase 0: 模式比對 — 參考 harness-100 (新增於 v1.1)

目標範例 (編碼領域 27 個)

Phase 0 流程

將 Phase 0 的結果反映至後續階段

模式保真度 (定性評估，僅限 Phase 0)

觸發邊界 (should + NOT)

Coding Agent 行為原則 (受 Karpathy 啟發，必須注入)

Scale Modes (營運層默認值)

L1 Phase 1: 探索 — Planner 運作

1-1. 階段 1 — 目的與脈絡 (WHY / WHO)

1-2. 階段 2 — 功能與內容 (WHAT)

1-3. 階段 3 — 技術與結構 (HOW)

1-3.5. 階段 3.5 — 流程變更歷史追蹤 (FLOW HISTORY) [選擇性]

1-4. 階段 4 — 品質與評估標準 (QUALITY / EVALUATE)

1-5. 評估權重協商 (階段 4 完成後)

1-6. 架構模式自動對應

1-7. Planner 產出物

L1 Phase 2: 建置 — Generator 運作

2-1. 核心產出物生成 (依序)

2-1b. AGENTS.md 撰寫規則 (最為重要)

2-1c. docs/ 目錄 (System of Record)

Individual skills in this repo

kkh2114/claude-skills-public

kkh2114/claude-skills-public

相關技能

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me