kkh2114/claude-skills-public

Harness Designer v4

原則：「給 Agent 一張地圖，而不是一千頁的手冊。」 — OpenAI Harness Engineering 原則：「不要讓生成者評估自己的工作。」 — Anthropic GAN-Inspired Harness

哈內斯設計的五大支柱

這個技能產生的所有工作空間都必須滿足以下五個支柱：

支柱	核心問題	原則
漸進式揭露 (Progressive Disclosure)	Agent 能看到它需要的東西嗎？	目錄 (~100 行) → 指標 → 深層文件
機械強制 (Mechanical Enforcement)	規則是機械強制的嗎？	僅靠文件無法維持一致性
回饋迴路 (Feedback Loop)	失敗時能進行結構性改善嗎？	不是「更努力」，而是「缺少了什麼能力」
連續性 (Session Continuity)	跨 Session 的交接是否乾淨？	progress + feature-status + git
熵管理 (Entropy Management)	隨著時間推移，結構能維持嗎？	定期清理、文件新鮮度驗證

---

兩層之間的關係

┌─────────────────────────────────────────────────────┐
│  第 1 層：元層（這個技能的角色）                        │
│                                                     │
│  Planner ──→ Generator ──→ Evaluator                │
│     ↑         （單向順序，禁止反向引用）               │
│     └──── 不足時給予回饋 ──────────────────────┘     │
│                                                     │
│  目標：設計、產生、驗證工作空間結構本身                  │
└─────────────────────────┬───────────────────────────┘
                          │ 核准後結構完成
                          ▼
┌─────────────────────────────────────────────────────┐
│  第 2 層：操作層（已完成的工作空間角色）                │
│                                                     │
│  ┌ Initializer（僅首次執行）→ 環境設定                  │
│  │                                                  │
│  └ Operating Agent（重複執行）：                      │
│    Agent-A ─┐                                       │
│    Agent-B ─┼── Chairman 綜合 ──→ 最終產出            │
│    Agent-C ─┘  （獨立平行，彼此不交流）                  │
│                                                     │
│  目標：執行實際任務（分析、決策、報告等）                  │
└─────────────────────────────────────────────────────┘

---

第 1 層：元層 — 哈內斯設計流程

L1 三種 Agent（單向順序，禁止反向引用）

依 Planner → Generator → Evaluator 的順序傳遞產出。 每個 Agent 只接收前一個階段的產出，不能預先看到下一個階段的結果。

Planner（規劃 Agent）

分析使用者意圖，設計哈內斯結構。

• 輸入：使用者需求（透過提問收集）
• 輸出：Agent 配置草案 + 資料夾結構草稿 + 評估標準提案
• 限制：在看到 Generator/Evaluator 結果之前進行設計

Generator（建構 Agent）

將 Planner 的設計方案轉換為實際檔案。

• 輸入：Planner 核准的設計方案
• 輸出：實際的 .md/.json 檔案（完整產出清單請見 Phase 2）
• 限制：在不預先看到 Evaluator 標準的情況下建構

Evaluator（評估 Agent）

獨立驗證 Generator 的產出。

• 輸入：Generator 建立的檔案 + Planner 的評估標準
• 輸出：基於五大支柱的分數 + 功能性驗證結果 + 改善回饋
• 限制：不考慮 Generator 的意圖，只看最終結果

---

L1 Phase 0：模式匹配 — 參考 harness-100（新版 v4.1）

「99% 的好設計都已經有人做出來了。找到它，然後修改。」

在進入 Discovery 之前，先從 harness-100 (https://github.com/revfactory/harness-100, Apache-2.0) 中尋找最相似的經過驗證的範例 (exemplar) 作為參考基準。對於非開發者，則引導其轉向使用 harness-starter-workspace 技能。

目標範例（工作空間領域，共 73 個）

• Content #01–15, Business #43–55, Education #56–65, Legal #66–72, Lifestyle #73–80, Docs #81–88, Operations #89–95, Specialized #96–100

Phase 0 流程

1. 從使用者 1~2 句的請求中提取領域關鍵字
2. 從上述 73 個範例中，提出前 3 個候選 + 讓使用者確認
3. 將所選範例的編號記錄在 _workspace/00_input.md 的 reference_exemplar 欄位中
4. 匹配相似度 < 0.5 → 回退到自由設計模式（依原有 Phase 1 進行）

將 Phase 0 結果反映到後續階段

• Planner：預設使用範例的 4~5 位 specialist + Reviewer 配置
• Generator：使用範例的骨架 Scaffolder，強制使用 _workspace/NN_*.md 的編號慣例
• Evaluator：使用範例的 8 項 Quality Standards (Agent Team Mode / Domain Expertise / Structured Outputs / Dependency DAG / Error Handling / Scale Modes / Test Scenarios / Trigger Boundaries) 作為評分標準

Pattern Fidelity（定性評估，僅限 Phase 0）

不計入五大支柱自動評分。僅在 Phase 0 進行 exemplar 匹配時進行定性評估。

在 Phase 0 中，檢查所選 harness-100 exemplar 的 8 項 Quality Standards (Agent Team Mode / Domain Expertise / Structured Outputs / Dependency DAG / Error Handling / Scale Modes / Test Scenarios / Trigger Boundaries)， 此檢查獨立於 Evaluator 評分。

• 檢查時機：Phase 0 (選擇 exemplar 時) 1 次、Evaluator PASS 後報告時 1 次
• 不計分：不計入五大支柱的 22 項評分
• pillar-weight：只能調整五大支柱的權重。Pattern Fidelity 不是權重的調整對象

Review 強制化

操作層必須包含 Reviewer Agent（交叉驗證角色）。在現有的 Chairman 綜合模型中增加 Reviewer 交叉驗證步驟。

Trigger Boundaries（should + NOT）

Planner/Generator 在產生的 orchestrator skill.md 中必須包含 should-NOT trigger 區段。

領域框架注入

根據類別自動注入經過驗證的框架：

• Content: AIDA, Pattern Interrupt, CURVE formula
• Business: BMC, TAM/SAM/SOM, Porter's 5 Forces, RICE, Van Westendorp PSM
• Education: Bloom's Taxonomy, ADDIE, CEFR, SM-2, Toulmin Model
• Legal: IRAC, MQM, GDPR/PIPA, IPC/CPC
• Lifestyle: BMR/TDEE, ACSM Guidelines, Compound Interest
• Docs: Diataxis, PREP, STAR, MADR, SemVer
• Operations: SIPOC/RACI, 4C Framework, SMART, NPS/CSAT, BARS
• Specialized: GHG Protocol, Cap Rate/IRR, IMRaD, Georgia-Pacific, Double Materiality

---

L1 Phase 1：探索 — Planner 運作

探索由 4 個階段的提問組成。 按順序進行每個階段，根據使用者的回答分支後續提問。 收到一個階段的回覆後，再進入下一個階段。 不要一次問完。

1-1. 階段 1 — 目的與背景 (WHY / WHO)

不是結構，而是理解這個工作空間存在的原因。

W1. 這個工作空間要解決的問題是什麼？
    （目前哪個決策/分析/判斷進行得不順利？）

W2. 誰來使用它？
    （僅限 Agent / Agent + 人 / 人消費結果）
    → 後續：使用者在該領域的專業程度如何？

W3. 這個工作空間的成功標準是什麼？
    （出現什麼結果時，可以說「做得好」？）

W4. 有類似的現有流程嗎？
    （是取代現有的 / 還是從頭建立）
    → 後續 [取代]：現有流程最大的問題是什麼？
    → 後續 [新建]：有想要參考的系統嗎？

後續提問分支：

• W2 回答「人消費結果」→「接收結果的人的職位/角色是什麼？偏好什麼格式？」
• W3 回答模糊 →「具體來說，出現什麼產出才算是成功？」

1-2. 階段 2 — 產出與結構 (WHAT)

要製作什麼、需要哪些觀點。

S1. 最終產出是什麼？
    （報告 / 決策記錄 / 分析報告 / 企劃書）

S2. 重複性的核心工作模式是什麼？
    （輸入 → 分析 → 決策 → 記錄 → 知識累積）

S3. 需要多少種觀點/角色？各自有什麼特質？
    （例如：樂觀/悲觀/數據/經驗/法規 — 相互衝突/互補）
    → 後續：觀點之間有優先順序嗎？是平等的嗎？

S4. 需要 Chairman（綜合角色）嗎？
    （負責主要 Session / 獨立 Agent / 不需要）
    → 後續 [需要]：Agent 模型配置是？
      → 參考 references/agent-archetypes.md 後提出建議

S5. 輸入形式是什麼？
    （直接輸入文字 / 上傳檔案 / URL / 複合形式）

S6. 需要保留的輸出是什麼？
    （Session 檔案 / 決策記錄 / 知識累積 / deep-research）

後續提問分支：

• S3 回答超過 5 個觀點 →「這些觀點可以分組嗎？順序 vs 平行？」
• S4 回答「獨立 Agent」→「Chairman 的判斷框架是什麼？Go/Pivot/No-Go？」

1-2.5. 階段 2.5 — 知識管理 (KNOWLEDGE) [條件式]

對於多重議題研究工作空間，為了系統性參考現有研究而提供的 wiki 選項。 如果是單一議題或非研究工作空間，則跳過。

K1. 「是否需要同時進行多個議題（研究主題），並在後續研究中參考現有研究？」
    → 「否」→ 不含 wiki。前往階段 3。
    → 「是」→ 前往 K2。

K2. 確認是否安裝 /graphify 技能（自動偵測）
    - 檢查 ~/.claude/skills/graphify/ 或 .claude/skills/graphify/ 是否存在
    - 已安裝 → 前往 K3。
    - 未安裝 → 提供說明：
      ┌─────────────────────────────────────────────────┐
      │ wiki 是透過 /graphify 技能建立的。               │
      │ 如果沒有這個技能，就無法建立 wiki。              │
      │                                                 │
      │ /graphify 是什麼？                               │
      │ - 分析文件/報告，建立知識圖譜                    │
      │ - 自動發現概念間關聯並視覺化                      │
      │ - 自動產生基於社群（community）的 wiki 文件        │
      └─────────────────────────────────────────────────┘
      「您要安裝 graphify 嗎？」
      - 全域安裝 (~/.claude/skills/) [所有專案使用]
      - 專案安裝 (.claude/skills/) [僅此專案使用]
      - 不安裝 → ⚠️ 「wiki功能將被停用。
          45-wiki/ 資料夾會建立，但會是空的。
          之後安裝 /graphify 後，可透過 /wiki-update 建立。」
        → 僅包含 wiki 結構，但功能停用。前往階段 3。

K3. 「要將 wiki 存放庫放在哪裡？」
    - 專案內部 (45-wiki/) [預設]
    - 指定外部路徑

K4. 「開始新的研究時，是否自動探索 wiki？」
    - 自動探索 + 使用者核准後參考 [預設]
    - 僅允許手動呼叫 (/wiki-ref)

Planner 輸出新增（與 wiki 相關）：

• wiki_enabled: true/false
• wiki_location: "45-wiki/" 或使用者指定的路徑
• wiki_auto_ref: true/false
• graphify_installed: true/false
• graphify_scope: "global" | "project" | "none"

⚠️ 保護 wiki 參考的獨立性：

• 絕對禁止將 wiki 內容注入 Phase A（獨立研究）Agent
• 僅允許 Phase B（Creative Thinker）/ Phase C（Chairman）在使用者核准後參考
• 參考時只傳遞框架/方法論/數據點，而非結論
• 產出必須記錄 wiki_ref、ref_approved_by、ref_approval_date

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

建議用於預期工作流程會隨時間改善的專案。 一次性分析、一次性專案可以跳過。

F1. 「未來工作流程改善或變更時，是否要記錄歷程？」

    用途：
    - 專案改善歷程回顧（為什麼這樣改變）
    - 需要回滾到舊版本時，確保有依據
    - 設計下一個類似專案時的參考

    ※ 不是每個新 Session 都要讀取。
      只有在修改、回滾、移植流程時才參考。

    → 「否」→ 不含 05-flow-history/。前往階段 3。
    → 「是」→ 前往 F2。

F2. 「是否自動將初始建置 (v1) 記錄為 change 0001 記錄？」
    - 預設值：是（Planner Discovery 的回覆會直接保留為設計依據）
    - 否 → 只產生 CHANGELOG，第一次變更時手動記錄

流程歷程管理原則（建立後的運作標準）： 此歷程只記錄工作流程系統（規則、程序、工具、提示、指令、腳本、CLAUDE.md）的變更。 系統產生的成果（研究結果、報告、分析、議題註冊）不是記錄對象。 區分標準：「如果沒有這個變更，下一次執行的結果會不同嗎？」 → 會不同 = 系統變更 = 記錄 / 不會不同 = 成果 = 不需要記錄 詳情：00-system/protocols/flow-change-protocol.md

Planner 輸出新增（與 flow-history 相關）：

• flow_history_enabled: true/false
• flow_history_initial_record: true/false（F2 回答）

1-3. 階段 3 — 環境與工具 (HOW)

要在什麼環境下、如何運作。

H1. 使用哪種 AI 工具？
    (Claude Code / Desktop Claude / 其他)
    → 根據工具不同，哈內斯設定方式也不同

H2. 需要跨 Session 的連續性嗎？
    （一次性分析 / 長期專案 / 多 Session）
    → 如果是「長期」，則包含 Session 交接產出

H3. Agent 模型配置是什麼？
    → 透過網路搜尋確認最新的 Claude 型號後提出建議
    → 不要硬編碼型號名稱。始終由使用者決定。

H4. Agent 的自律性等級是？
    （每次都要人確認 / Agent 自主判斷並報告 / 完全自主）

後續提問分支：

• H2 回答「長期」→「預計有多少 Session？知識累積重要嗎？」
• H4 回答「完全自主」→「升級（Escalation）的標準是什麼？什麼情況下必須問人？」

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

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

E1. 這個工作空間最重要的品質屬性是？（選前 3 個）
    □ 分析深度（非表面性的洞察）
    □ 獨立性（Agent 之間不互相影響的獨立分析）
    □ 標明出處（基於證據的結論）
    □ 一致性（跨 Session 維持品質）
    □ 快速反應（較短的處理時間）
    □ 可擴展性（易於新增 Agent/角色）
    □ 文件化（過程與結果的可追溯性）
    □ 使用者親和性（非專業人士也能理解結果）

E2. 未來有擴展計畫嗎？
    （無 / 新增觀點 / 應用到其他領域 / 加強自動化）

E3. 在這個工作空間中，絕對不能妥協的是什麼？
    （例如：「Agent 之間不能相互影響」、「不能有無來源的結論」）

E4. 相反地，初始階段可以沒有的東西是什麼？

後續提問分支：

• E1 回答「獨立性」→「到什麼程度？連結果都不能共享？還是只有分析過程獨立？」
• E3 的回答 → 作為 Evaluator 權重計算的核心輸入

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

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

[權重提議流程]

步驟 1. 從階段 1~4 回答中提取關鍵字
  - 「獨立性必須」→ Mechanical Enforcement ↑
  - 「長期專案」→ Session Continuity ↑, Entropy Management ↑
  - 「快速反應」→ Progressive Disclosure ↑
  - 「標明出處」→ Mechanical Enforcement ↑

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

  預設權重（反映專案特性前）：
  | 支柱 | 預設 | 調整依據 | 提議 |
  |------|------|----------|------|
  | Progressive Disclosure | 20% | (調整依據) | ?% |
  | Mechanical Enforcement | 25% | (調整依據) | ?% |
  | Feedback Loop | 20% | (調整依據) | ?% |
  | Session Continuity | 15% | (調整依據) | ?% |
  | Entropy Management | 20% | (調整依據) | ?% |

  「考慮到這個專案的 [依據]，
   我們將 [支柱] 的權重從 [預設]% 調整為 [提議]%。
   如果您有任何意見或需要修改，請告訴我們。」

步驟 3. 反映使用者回饋
  - 同意 → 確定
  - 「提高獨立性」→ 上調 Mechanical Enforcement，下調其他支柱後重新提議

步驟 4. 最終核准
  → 在 evaluator-protocol-workspace.md 中使用協商後的權重，而非預設權重

1-6. 模式自動映射

根據階段 2 的回答，自動推薦資料夾模式：

使用者回答關鍵字	推薦模式	參考
分析、投資、決策、判斷	模式 A（分析/決策型）	folder-patterns.md
施工、工序、估價單、建築	模式 B（建築/專案管理型）	folder-patterns.md
研究、內容、報告	模式 C（研究/內容型）	folder-patterns.md
長期程式設計、自動化建置	模式 D（長期 Agent 型）	folder-patterns.md

1-7. Planner 產出

① 專案背景摘要 — 目的、使用者、成功標準、核心限制（基於階段 1~2） ② Agent 配置草案 — 角色、特質、模型分配 ③ 資料夾結構草案 — 模式映射 + 客製化 ④ Session 連續性設計 — 決定交接方式（一次性 / 使用 progress.json） ⑤ 擴展策略 — 為未來擴展所做的設計決策（基於階段 4 E2） ⑥ 評估標準 + 協商後的權重 — 五大支柱檢查清單 + 權重表

[Planner 完成 — 請求使用者核准]
請檢閱 ①~⑥ 後，告訴我們需要修改的地方。
經核准後，Generator 將開始建置。

---

L1 Phase 2：建置 — Generator 運作

Planner 產出核准後，按照以下順序建立檔案。 Generator 同時建立資料夾結構 + 檔案內容。

2-1. 工作流程圖（Mermaid）

一個同時表達兩個層級的圖表。包含 Evaluator→Planner 重新設計迴圈：

flowchart TD
    USER[使用者] -->|需求| P
    subgraph L1[第 1 層：元層]
        P[Planner] --> G[Generator]
        G --> E[Evaluator]
        E -->|不足 70~89%| G
        E -->|重新設計 70%以下| P
        E -->|核准 90%+| DONE[結構完成]
    end
    DONE --> INIT
    subgraph L2[第 2 層：操作層]
        INIT[Initializer\n僅首次執行] --> OP
        subgraph OP[Operating Agent 重複執行]
            INPUT[輸入] --> SPLIT[ ]
            SPLIT --> A1[Agent-A]
            SPLIT --> A2[Agent-B]
            SPLIT --> A3[Agent-C]
            A1 --> CH[Chairman 綜合]
            A2 --> CH
            A3 --> CH
            CH --> OUT[輸出 + 狀態儲存]
        end
    end

2-2. 核心產出建立（依序）

順序	產出	參考檔案	備註
2-2a	WORKSPACE_TREE.md	folder-patterns.md	確定資料夾結構
2-2b	CLAUDE.md (~100 行)	claude-md-template.md	作為目錄，必須包含參考路由表
2-2c	AGENTS.md	（本技能內的指南）	Agent 操作規則 + model_config
2-2d	Agent 角色檔案	agent-archetypes.md	00-system/prompts/*.md
2-2e	五種協議	（本技能內的指南）	00-system/protocols/
2-2f	Session 交接產出	session-handoff.md	progress.json + feature-status.json
2-2g	強制規則	enforcement-patterns.md	可驗證結構的規則
2-2h	斜線指令	（基於 Planner 設計）	.claude/commands/*.md
2-2i	README.md	（使用者指南）	快速開始 + 指令 + 疑難排解
2-2j	流程變更歷程 Wiki（選擇性）	flow-history-template.md	僅在階段 2.6 中 F1=是時建立

2-2b. CLAUDE.md 撰寫規則（最重要）

→ 參考 references/claude-md-template.md。務必在 100 行以內。

CLAUDE.md 是 Agent 的進入點 (entry point)。 過長的指令會變成「非指引 (non-guidance)」：

• 上下文會排擠實際任務和程式碼
• Agent 會陷入局部模式匹配，而非有意識地探索
• 單一巨型文件會很快過時

必須包含的內容：

• 工作空間身份 (3 行)
• Agent 配置表
• 參考路由表 ← Progressive Disclosure 的核心
• 獨立性原則的指標
• 指令列表

參考路由表格式：

## 參考路由
| 情境 | 要讀取的檔案 |
|------|----------|
| 確認 Agent 角色 | → 00-system/prompts/[role].md |
| 討論進行規則 | → 00-system/protocols/council-protocol.md |
| 獨立性原則詳情 | → 00-system/protocols/independence-protocol.md |
| 檢查 Session 狀態 | → progress.json |
| 功能完成狀態 | → feature-status.json |

2-2c. AGENTS.md 撰寫規則

必須包含：

• 第 2 層 Agent 列表表（角色 / 模型 / 啟用條件）
• model_config 區段（使用者選擇的模型 + 重新檢視觸發條件）
• Chairman 綜合方式 + 決定框架 (Go/Pivot/No-Go)
• 獨立性原則摘要
• 上下文管理規則

...