Cc harness patterns

Skill cablate/ai-toolkit/domain-skills/claude-code/cc-harness-patterns

Battle-tested Claude Code skills for relentless AI delivery

Install

npx -y skills add cablate/ai-toolkit --skill cc-harness-patterns

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

14 stars14 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Harness Engineering 設計模式 — 基於 Claude Code 原始碼逆向分析的 12 條可遷移原則。Use when: 設計 agent 系統架構、實作 tool orchestration、設計 context 管理策略、建構 agent loop。

SKILL.md

3.7 KB, as published. Nobody here has run it

Harness Engineering 設計模式

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

基於 Claude Code v2.1.88（92,500 行 TypeScript）逆向分析。

1. Agent Loop：Async Generator 模式

Claude Code 的 agent loop 用 async generator 實作：

async function* queryModel(...): AsyncGenerator<StreamEvent | AssistantMessage> {
  // yield 每個 stream event，呼叫端按需消費
}

核心循環：queryModel() → 檢查 stop_reason → tool_use 時呼叫 runTools() → 結果回注 messages → 再次 queryModel()

stop_reason 分支：end_turn（結束）、tool_use（執行工具）、max_tokens（context 滿了，觸發 compaction）

2. Tool Orchestration：讀寫分離

function isConcurrencySafe(input): boolean {
  // 工具自己聲明是否可並行
}

partitionToolCalls() 把一批工具呼叫分成可並行組和必須串行組
讀工具自動合批並行（FileRead、Grep、Glob）
寫工具強制串行（FileEdit、FileWrite、Bash）
決策權在工具端（Single Responsibility），不在 orchestrator

3. 工具執行 7 層管道

Schema Validation → Custom validateInput() → Input Sanitization
→ PreToolUse Hooks → Permission Resolution → Execution → PostToolUse Hooks

每層只問一個問題：「能否拒絕？」拒絕即停，不往下走。執行邏輯永遠在最後一層。

4. Cache 穩定性模式

Sticky Latch：影響 cache key 的欄位一旦啟用就不在 session 內關閉。

if (!fastModeHeaderLatched && isFastMode) {
  fastModeHeaderLatched = true  // 永遠 latched
}

確定性 ID：注入 context 的 ID 從穩定輸入衍��，不隨機生成。

靜態/動態邊界：SYSTEM_PROMPT_DYNAMIC_BOUNDARY 把 prompt 分成可全域快取的靜態段和 session 特定的動態段，防 2^N 快取桶爆炸。

Attachment > Inline：動態 agent 列表從 tool description 移到 attachment message，避免 MCP 連接/plugin 載入導致 tool schema cache bust。省 fleet 10.2% cache creation tokens。

5. Context Engineering

原則：什麼進 context、什麼順序、何時壓縮。

訊息處理管道 normalizeMessagesForAPI：10 步處理（過濾空訊息、合併連續同角色、注入 system-reminder、truncate 過長結果...）
Compaction 三模式：BASE（全壓）、PARTIAL_FROM（從某點壓）、PARTIAL_UP_TO（壓到某點）
<analysis> 草稿：讓模型在 scratchpad 思考，結果不進 context
Deferred Tool Loading：36 個工具不全塞 prompt，ToolSearch 按需載入 schema

6. Multi-session Continuity

Forked Agent：子 agent 繼承父 session 的 prompt cache（Memory extraction、AgentSummary、Dream 都用此模式）
progress log：跨 context window 的進度檔（claude-progress.txt）
AutoDream：背景記憶整合，三層閘門（時間≥24h + session≥5 + 檔案鎖），四階段 consolidation prompt

7. Observability

三層追��：Analytics（業務事件）/ OpenTelemetry（效能）/ DiagnosticTracking（per-turn 計數器）
PII 安全型別：PiiSafeString<T> 型別系統，編譯期防止 PII 進入遙測
Frustration Signal：追蹤使用者 swearing、重複 "continue" prompt，路由至 Datadog

參考

詳見 references/design-principles.md。