Harness 思維架構全圖 — Prompt → Context → Harness Engineering 演進路線圖

最後更新 2026-06-01

↗ NotebookLM

① 點 PDF 匯出，或 Copy Link 複製網址　② 開 NotebookLM →「新增來源 → 網站」貼上，加入你的筆記本（需 https 網址）

// 目錄

一眼看懂三層架構
Prompt Engineering — 指令層
Context Engineering — 視窗層
Harness Engineering — 系統層
功能完整對比
決策樹：遇到問題選哪層？
立刻開始
資料來源

// 01

一眼看懂三層架構

三層架構是嵌套關係，不是替代關係：Prompt ⊆ Context ⊆ Harness。每一層解決下一層無法獨立解決的問題，工程嚴格性隨層次升高持續遷移（Relocating Rigor）。

📝

Prompt Engineering

設計 LLM 輸入指令的技藝。核心問題：「我該怎麼問？」——透過角色、格式、範例、限制引導模型輸出。

🗂️

Context Engineering

精準管理模型每次推理所見資訊。核心問題：「模型需要知道什麼？」——RAG、記憶、工具結果的動態組裝。

⚙️

Harness Engineering

包圍 Agent 的確定性約束環境。核心問題：「系統如何防止 Agent 出軌？」——CI gate、linter、PEV Loop 機械執行。

// 02

Prompt Engineering — 指令層

📝

Prompt Engineering — 設計輸入指令的技藝

LAYER 1 · 指令層

能做什麼

透過角色設定、格式約束、少樣本範例、思維鏈推理，引導模型在單次對話中產生目標輸出

使用介面

System Prompt、User Message、Few-shot Examples、XML/JSON 格式標記

適合誰

所有層級的起點。初學者用於一問一答任務；工程師用於定義 Agent 角色與輸出規格

核心技術

Zero-shot、Few-shot、Chain-of-Thought（CoT）、Role Prompting、Tree-of-Thought（ToT）、Structured Output

侷限

概率性合規——模型不保證每次遵守格式；長對話後早期指令被稀釋；無法跨 session 持久

典型應用場景

問答、摘要、翻譯等單次回答型任務
定義 AI Agent 的角色身份與專業視角
強制結構化輸出（JSON / XML / Markdown 表格）
要求模型逐步推理解決複雜數學或邏輯問題
文案草稿、程式碼片段生成的品質優化

💡

CLEAR 框架：Context（背景）、Limit（限制）、Examples（範例）、Action（明確動詞）、Review（自我查核標準）。每個任務都應包含這五個元素，是最快提升 Prompt 品質的入門框架。

工程化 Prompt 模板

定義角色與任務身份（Role Prompting）

明確指定模型的專業視角、經驗背景、目標受眾。避免使用過於寬泛的角色，確保與任務領域相符。

加入少樣本示範（Few-shot Examples）

提供 2–5 個輸入→輸出範例，固定格式與風格。範例品質直接決定輸出一致性，差的範例比沒有範例更糟。

啟用思維鏈推理（Chain-of-Thought）

要求模型「先一步步推理再給答案」，顯著提升複雜邏輯與數學任務的正確率。

強制結構化輸出（Structured Output）

指定 XML tags 或 JSON schema，搭配 Pydantic 等工具做 schema 驗證，降低格式不穩定風險。

加入查核標準（Review Criteria）

明確說明「不確定時請標示」、「不得加入原文沒有的資訊」、「必須引用來源」，降低幻覺率。

程式碼範例：工程化問法對比

# ❌ 普通問法
幫我寫產品介紹。

# ✅ 工程化問法
你是 B2B SaaS 產品行銷顧問。
請為「AI 客服知識庫搜尋工具」寫產品介紹。
受眾：中小型電商營運主管。
目標：說明此工具如何降低客服回覆時間。
限制：不得使用未查證數字；不得誇稱保證提升營收。
輸出格式：
  1. 50 字摘要
  2. 3 個核心賣點
  3. 1 段正式網站文案
不確定時：標示「需查證」而非猜測。

結構化輸出範例（XML schema）

<!-- 要求模型嚴格依此 XML 格式輸出，不含其他文字 -->
<analysis>
  <sentiment>正面|負面|中性</sentiment>
  <confidence>0.0–1.0</confidence>
  <keywords>
    <keyword>…</keyword>
  </keywords>
  <summary>一句話總結</summary>
</analysis>

// 03

Context Engineering — 視窗層

🗂️

Context Engineering — 管理模型所見資訊的系統工程

LAYER 2 · 視窗層

能做什麼

動態組裝 context window——RAG 檢索、記憶壓縮、工具定義載入、對話歷史管理，確保模型每次推理看到正確且高密度的資訊

使用介面

向量資料庫、RAG pipeline、記憶系統（向量 / KV store）、工具定義、session 狀態機

適合誰

需要多輪對話、長鏈任務、外部知識庫查詢、或跨 session 狀態持久化的開發者與工程師

四個層次

Working Context（本次可見）、Session（對話事件）、Memory（跨 session 長期知識）、Artifacts（大型檔案與版本化資料）

侷限

Context Rot（長對話後品質下降）、位置偏差（中段資訊易被忽略）、多 Agent 衝突、概率性合規仍無法根除

典型應用場景

企業知識庫查詢——從文件庫 RAG 檢索最新政策或技術規範
長篇研究任務——保留早期對話決策點，防止 Agent 忘記前提
多工具 Agent——僅載入當前步驟需要的工具定義，節省 tokens
跨 session 個人化——向量存儲用戶偏好、過去決策、專案規則
大型 Codebase 分析——按需載入相關檔案而非全量注入

⚠️

Context Rot 警告：當 token 使用率超過 75%，或工具輸出佔比超過 60%，模型注意力品質顯著下降——指令遵循率降低、重複相同回答、忽略工具結果。這時應觸發 /compact（Anthropic Claude）或重新開啟乾淨 session 並注入狀態摘要。

Context Engineering 六大評估指標

Relevance（相關性）：模型看到的是否是任務所需資訊？→ 衡量 retrieval precision
Sufficiency（充分性）：是否遺漏必要資訊？→ 分析失敗案例歸因
Economy（經濟性）：token 成本與延遲是否可接受？→ cache hit rate
Provenance（來源性）：資訊可否追溯？→ citation coverage
Isolation（隔離性）：不相關或不可信內容是否被隔離？→ permission tests
Freshness（新鮮度）：資訊是否過時？→ timestamp policy、source recency

清點任務所需資訊層次

區分：Working Context（本次必需）/ Session（對話歷史）/ Memory（跨 session 知識）/ Artifacts（大型檔案），只注入當前層次需要的內容。

設計 RAG 檢索管線

向量化查詢 → 相似度過濾（threshold ≥ 0.75）→ 片段排序 → 注入 context。RAG 只是 Context Engineering 的一部分，還需處理來源、時效、權限。

設定 Token 預算分配

建議比例：System 20% / History 30% / RAG 30% / Task 20%。工具定義本身消耗 tokens，只載入當前步驟需要的工具。

位置感知設計

LLM 對 context 首尾注意力最高（Stanford「Lost in the Middle」研究）。關鍵約束與指令放首段或末段；用 XML tags 標記重要區域。

建立滾動摘要壓縮

每 N 輪對話，用 LLM 壓縮成摘要替換原始歷史，保留決策點、錯誤記錄、用戶偏好。防止 context 爆炸。

程式碼範例：基礎 RAG 管線

def rag_query(user_question: str) -> str:
    # 1. 向量化查詢
    query_embedding = embed(user_question)

    # 2. 從向量 DB 檢索（threshold 過濾低相關片段）
    relevant_docs = vector_db.search(
        query_embedding, top_k=5, similarity_threshold=0.75
    )

    # 3. 組裝 context（來源追蹤、時效標記）
    context = "\n\n".join([
        f"[{doc.source} · {doc.date}]\n{doc.content}"
        for doc in relevant_docs
    ])

    # 4. 注入 context + 查核要求
    prompt = f"""根據以下資料回答問題。引用來源；不確定處請標示。

{context}

問題：{user_question}"""
    return llm.complete(prompt)

程式碼範例：三層記憶架構

class AgentMemory:
    def __init__(self):
        self.working_memory = []   # 當前 session（in-context）
        self.episodic_memory = []  # 跨 session 對話歷史（vector DB）
        self.semantic_memory = {}  # 知識庫、文件（vector DB）

    def get_relevant_context(self, task: str, max_tokens: int) -> str:
        parts = [self._format_working_memory()]  # 永遠包含
        parts += self.semantic_memory.search(task, top_k=3)
        if self._token_count(parts) < max_tokens * 0.7:
            parts += self.episodic_memory.search(task, top_k=2)
        return self._truncate_to_budget(parts, max_tokens)

// 04

Harness Engineering — 系統層

⚙️

Harness Engineering — 確定性 Agent 控制環境

LAYER 3 · 系統層

能做什麼

以確定性架構包覆機率性 AI 核心——CI gate 機械執行、架構 linter、PEV Loop、自癒機制、觀測層，讓錯誤「結構上無法再發生」

五大組件

Context Files（AGENTS.md / CLAUDE.md）、MCP Tool Gateway、Mechanical Enforcement（linter + CI gate）、Code GC Agent、Observability Layer

核心設計模式

PEV Loop（Plan → Execute → Verify）、Ralph Loop（跨 session 持久化）、Reasoning Sandwich（高推理模型做首尾，快速模型做中段）、Progressive Disclosure（Just-In-Time context 注入）

適合誰

運行 Coding Agent 的工程師、企業級 AI Agent 系統設計者、需要生產品質保障的 AI 應用開發者

合規性質

確定性——CI gate 是程式碼，不是語言說服。模型無法感知也無法繞過 linter。這是與 Prompt/Context 層最關鍵的差異

典型應用場景

AI Coding Agent 修 bug——任務規格化 + 工具白名單 + pytest gate + rollback
企業合約審查——Pydantic schema 驗證 + 自癒重試迴路（Self-Healing Loop）
多 Agent 協作——context firewall 防止覆蓋，shared state 一致性保障
安全敏感場景——prompt injection 防禦、最小權限工具、human-in-the-loop 審批
持續重構——背景 Code GC Agent 自動掃描技術債，開 refactoring PR

🔑

Hashimoto 原則：「每次 Agent 犯一個錯誤，你就要工程化一個解決方案，確保 Agent 永遠不會再犯同樣的錯誤。」——這就是 Harness 思維的核心：不調整 prompt，而是設計讓這個錯誤結構上不可能再發生的系統。

PEV Loop — 最重要的 Harness 架構模式

Plan（高推理模型）

用高能力模型（如 claude-opus）將複雜任務分解為子任務，輸出 plan.md。這一步不執行，只規劃，確保方向正確再動手。

Execute（快速模型）

用快速模型（如 claude-sonnet）批量執行子任務——讀寫檔案、工具調用。僅操作在工具白名單與 scope 內授權的路徑。

Verify（高推理模型再次）

高能力模型對照 plan 驗證執行結果；CI gate 機械執行測試。未通過 → 帶錯誤 feedback 返回 Execute。通過 → 提交結果。

🥪

Reasoning Sandwich：LangChain Terminal Bench 2.0 實驗——僅修改 harness（不改模型權重），任務完成率從 52.8% 提升至 66.5%。成本優化：只在 Plan 和 Verify 階段使用昂貴模型，執行階段用快速模型。

程式碼範例：架構依賴方向 Linter（機械強制執行）

# ❌ 依賴 prompt 說服（概率性）：
# "請遵循 Types→Config→Repo→Service 依賴方向"
# → Agent 在第 47 步仍可能引入違規依賴

# ✅ Harness 機械執行（確定性）：
class ArchitectureLinter:
    ALLOWED_DEPS = {
        "ui": ["service"], "service": ["repo"],
        "repo": ["config"], "config": ["types"], "types": []
    }

    def check(self, module: str, imports: list) -> list:
        violations = []
        for imp in imports:
            if imp not in self.ALLOWED_DEPS.get(module, []):
                violations.append(
                    f"❌ {module} → {imp} 違反架構依賴方向"
                )
        return violations

    def generate_feedback(self, violations: list) -> str:
        # 將 linter 錯誤自動注入 Agent 的下一個 context
        return f"偵測到 {len(violations)} 個架構違規，請立即修正再繼續：\n" \
               + "\n".join(violations)

程式碼範例：CI 品質門（YAML）

# .github/workflows/harness-gates.yml
name: Harness Quality Gates
on: [pull_request]
jobs:
  architecture-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 架構依賴方向檢查
        run: python tools/arch-linter.py --fail-on-violation
      - name: 測試覆蓋率門檻（80%）
        run: pytest --cov=src --cov-fail-under=80
      - name: 安全漏洞掃描
        run: bandit -r src/
# 關鍵：模型無法感知此 gate 的存在，無法繞過

程式碼範例：Pydantic Schema + 自癒機制

from pydantic import BaseModel, Field, field_validator
from typing import List, Literal

class ContractAnalysis(BaseModel):
    contract_parties: List[str] = Field(description="合約簽署方列表")
    total_amount: float = Field(description="合約總金額（TWD）")
    risk_level: Literal["Low", "Medium", "High"]

    @field_validator("total_amount")
    @classmethod
    def validate_amount(cls, v: float) -> float:
        if v < 0: raise ValueError("金額不可為負數")
        return v

class LLMHarness:
    def execute(self, raw_text: str, max_retries=3) -> ContractAnalysis:
        error_ctx = ""
        for attempt in range(max_retries):
            try:
                raw = self._call_llm(raw_text, error_ctx)
                return ContractAnalysis(**json.loads(raw))  # 驗證
            except (json.JSONDecodeError, ValueError) as e:
                error_ctx = str(e)  # 帶錯誤重試（自癒迴路）
        raise RuntimeError(f"超過 {max_retries} 次重試後仍未通過驗證")

最小可行 Harness（MVH）8 大元件

Task Spec Template：任務目標、scope、限制、完成條件
Project Context File（AGENTS.md）：架構地圖、build/test 指令、禁止事項——是地圖而非百科全書
Tool Allowlist：只開放 read_file, grep, edit_file, run_tests 等必要工具
Deny Rules：禁止刪除 secrets、禁止 rm -rf、deploy 需批准
Checkpointing：每次任務前建立 git branch 或 snapshot
Verification Commands：固定測試命令（pytest, pnpm test, mypy）
Trace Log：記錄工具調用、錯誤、修復、驗證結果——沒有 trace 的行動視為不可接受
Human Review Gate：合併、部署、刪除、高風險變更需人類批准

// 05

功能完整對比

三層架構各有專屬問題域，不互相取代。合規性質的差異（概率性 vs. 確定性）是最關鍵的分水嶺。

比較項目	Prompt Engineering	Context Engineering	Harness Engineering
核心問題	我該怎麼問？	模型需要知道什麼？	系統如何防止 Agent 出軌？
設計對象	指令文字與格式	Context Window 內容結構	Agent 外部的約束環境
時間邊界	單次對話	單個 context window	跨 session 與任務生命週期
控制類型	語言引導	資訊架構	系統性約束 + 反饋迴路
合規性質	概率性（模型不保證遵守）	概率性（資訊更準但仍有機率失效）	確定性（CI gate 機械執行）
典型失效	格式錯亂、指令遺忘、幻覺	Context Rot、位置偏差、多 Agent 衝突	架構漂移、越權行動、無法回滾
主要工作產品	System Prompt / Few-shot 範例	RAG 管線 / 記憶架構 / 壓縮策略	AGENTS.md / CI Gate / PEV Loop / Trace Log
工程職能類比	文案 / 創意寫作	系統設計 / 資料工程	平台工程 / DevOps
代表工具	Prompt Playground、Prompt 管理工具	LangChain、RAG 框架、MCP、向量 DB	CI/CD、Linter、Observability 平台
直觀類比	給騎師任務說明書	給騎師地圖與即時情報	設計賽道、欄杆與計時系統

🌿 遇到問題，選哪一層優先修正？

模型輸出格式不穩定、遺漏關鍵欄位

→

Prompt Engineering

回答缺少文件中的重要資訊

→

Context Engineering（RAG 優化）

回答引用過時或已失效的資料

→

Context Engineering（Freshness 管理）

長對話後，早期指令被 Agent 遺忘

→

Context Engineering（壓縮 / Checkpoint）

Agent 讀取或修改了不在 scope 內的檔案

→

Harness Engineering（工具白名單 + Deny Rules）

Agent 不確定任務是否完成，自行宣稱完成

→

Harness Engineering（Verification 條件 + Verify 步驟）

安全漏洞、Prompt Injection、越權行動風險

→

Harness Engineering（最小權限 + 隔離 + Audit Log）

Agent 失敗後重複犯同樣的錯誤

→

Harness + Context（失敗歸因 + Memory + 自癒迴路）

小改動造成既有功能退化（regression）

→

Harness Engineering（Evaluation Harness + 回歸測試）

Token 成本與延遲過高

→

Context Engineering（Economy 優化 + Progressive Disclosure）

// 07

立刻開始

根據你的角色選擇起點。三條路徑不互斥——工程師仍需精通 Prompt，進階者的基礎是前兩層。

PATH A — 初學者 / 一般使用者

套用 CLEAR 框架（Context / Limit / Examples / Action / Review）寫每個任務 prompt
要求模型以 XML 或 JSON 格式輸出，固定結構便於後續處理
加入「不確定時標示，不可加入原文沒有的資訊」等查核指令
把第一次輸出當草稿，帶著具體改進點迭代 2–3 次再定稿
學習資源：Anthropic Prompt Engineering Guide

PATH B — 工程師 / AI 開發者

建立 AGENTS.md / CLAUDE.md——寫成地圖（index 指向子文件），不是百科全書（全部塞入）
實作基礎 RAG 管線，設定 token 預算（System 20% / History 30% / RAG 30% / Task 20%）
定義工具白名單（allowed_tools）與 deny rules（禁止路徑、禁止命令）
設計 PEV Loop：高推理模型做 Plan + Verify，快速模型做 Execute
建立 CI 品質門（architecture linter + test gate），部署結構化 trace 日誌
每次 Agent 犯錯 → 工程化一個確定性解決方案，不調 prompt

PATH C — 企業 / 進階研究者

設計 H3 等級 Harness（任務規格、權限系統、失敗歸因、驗證報告、人類介入紀錄）
部署 Reasoning Sandwich：計劃與驗證用高能力模型，執行用快速模型，控制成本
建立最小可行 Harness（MVH）八元件：Task Spec / AGENTS.md / Tool Allowlist / Deny Rules / Checkpoint / Verification Commands / Trace Log / Human Review Gate
部署背景 Code GC Agent，持續掃描 codebase divergence，自動開 refactoring PR
建立 Evaluation Harness，定期對基準任務集做 regression，量化 Harness 改動的實際效果
關鍵腳本（release / migration / cron）務必三模型交叉 audit：Claude + Gemini + GPT

// 08

資料來源 / Sources

本指南整合三份 AI 生成源文件，已交叉比對衝突，優先採用學術文獻與官方文件。

三份源文件（本次整合基礎）

ai-harness-by-gpt.md（GPT 生成，查證 2026-06-01）：學術引用最完整，包含 arXiv 論文索引，覆蓋安全治理章節，為本指南學術定義的主要依據。
ai-harness-by-claude.md（Claude 生成，2026-06-01）：設計模式（PEV Loop、Ralph Loop、Reasoning Sandwich、Hashline Format）與程式碼範例最豐富，OpenAI 1M LOC 案例研究詳細。
ai-harness-by-gemini.md（Gemini 生成，2026-06-01）：Pydantic 自癒機制範例清晰，架構四模組定義簡潔，適合快速入門。

官方文件 / Primary Sources

Anthropic Prompt Engineering Overview：docs.anthropic.com/…/prompt-engineering/overview
OpenAI Harness Engineering Report (2026-02-11)：openai.com/index/harness-engineering/
Model Context Protocol Docs：modelcontextprotocol.io
Martin Fowler / ThoughtWorks Harness Engineering (2026-02-17)：martinfowler.com/…/harness-engineering-memo.html
Augment Code Harness Engineering Guide：augmentcode.com/guides/harness-engineering-ai-coding-agents

學術論文

Zhong & Zhu, "AI Harness Engineering" arXiv:2605.13357：arxiv.org/abs/2605.13357
Lin et al., "Agentic Harness Engineering" arXiv:2604.25850：arxiv.org/abs/2604.25850
Mei et al., "Context Engineering Survey" arXiv:2507.13334：arxiv.org/abs/2507.13334
Ning et al., "Code as Agent Harness" arXiv:2605.18747：arxiv.org/abs/2605.18747
Qu et al., "Overeager Coding Agents" arXiv:2605.18583：arxiv.org/abs/2605.18583

術語來源差異說明 / Caveats

「Harness」術語的起源有兩個脈絡，三份源文件各有側重：（1）實踐社群——Claude 源文件主要援引 Mitchell Hashimoto Blog（2026-02-05）、OpenAI Report（2026-02-11）與 ThoughtWorks 分析（2026-02-17）為「三大獨立收斂事件」；（2）學術定義——GPT 源文件引用 arXiv 2605.13357（Zhong & Zhu）作為「AI Harness Engineering」的正式學術定義。兩個脈絡並不矛盾：Hashimoto 等人是實踐命名者，arXiv 論文是學術系統化，本指南兩者並用。

「88% 企業 AI Agent 專案未能投入生產」數據引自 Claude 源文件（Codiste Research 2026），原文件未提供 DOI 或完整引用，標記為未驗證數據，供參考但不作為論據。

Harness 思維架構全圖三次典範轉移解析

一眼看懂三層架構

Prompt Engineering

Context Engineering

Harness Engineering

Prompt Engineering — 指令層

Prompt Engineering — 設計輸入指令的技藝

典型應用場景

工程化 Prompt 模板

定義角色與任務身份（Role Prompting）

加入少樣本示範（Few-shot Examples）

啟用思維鏈推理（Chain-of-Thought）

強制結構化輸出（Structured Output）

加入查核標準（Review Criteria）

程式碼範例：工程化問法對比

結構化輸出範例（XML schema）

Context Engineering — 視窗層

Context Engineering — 管理模型所見資訊的系統工程

典型應用場景

Context Engineering 六大評估指標

清點任務所需資訊層次

設計 RAG 檢索管線

設定 Token 預算分配

位置感知設計

建立滾動摘要壓縮

程式碼範例：基礎 RAG 管線

程式碼範例：三層記憶架構

Harness Engineering — 系統層

Harness Engineering — 確定性 Agent 控制環境

典型應用場景

PEV Loop — 最重要的 Harness 架構模式

Plan（高推理模型）

Execute（快速模型）

Verify（高推理模型再次）

程式碼範例：架構依賴方向 Linter（機械強制執行）

程式碼範例：CI 品質門（YAML）

程式碼範例：Pydantic Schema + 自癒機制

最小可行 Harness（MVH）8 大元件

功能完整對比

🌿 遇到問題，選哪一層優先修正？

立刻開始

資料來源 / Sources

三份源文件（本次整合基礎）

官方文件 / Primary Sources

學術論文

術語來源差異說明 / Caveats

Harness 思維架構全圖
三次典範轉移解析