Harness 理論篇 Part 04｜Context Engineering：Context、Memory 與 RAG 各自放在哪裡？

Agent Loop 每跑一輪，都要重新回答同一個問題：

這一次模型應該看到什麼？

答案通常不是「把系統手上的資料全部塞進去」。

假設 Coding Agent 正在修正付款模組。系統可能同時擁有聊天紀錄、Repository Map、數百個檔案、API 文件、過去事故、測試 Log、使用者偏好、上一輪 Tool Result，以及剛從 RAG 找回來的文件片段。

這些資料都可能有用，但不代表它們應該同時進入一次 Model Call。

放得太少，模型會漏掉限制。放得太多，關鍵訊號會被重複、過期或低價值內容稀釋。Context Window 變大，只代表可用容量增加；它不會自動辨認哪一段具有 Authority、哪一段已經過期，也不會替系統阻止跨 Tenant 污染。

Anthropic 將 Context Engineering 描述為：在每次 Inference 時，從持續變動的資訊集合中，整理出最可能產生目標行為的 Context。這個範圍不只包含 Prompt，也包含工具定義、Message History、外部資料與 Runtime Observation。Anthropic 同時提醒，Context 是有限資源，邊際效益會隨長度增加而下降；目標不是一味縮短，而是找出足以完成任務的最小高訊號集合。¹

對 Harness 而言，Context Engineering 是一套治理流程：

Discover
→ Qualify
→ Select
→ Assemble
→ Observe
→ Persist or discard
→ Invalidate when sources change

它決定模型此刻看到什麼，也要保證沒有被載入的資料仍然待在正確的權威系統中，可以在需要時重新取得。

Context Builder and bounded model context

Figure 4-1｜Context Builder 從多個來源挑選本輪需要的內容，保留來源、版本、Scope 與載入理由，再組成有邊界的 Model Context。

Context 不是聊天紀錄，也不是系統知道的一切

「Context」常被拿來泛指 Agent 知道的所有事情。工程上至少要拆成五類，否則資料會在錯誤的位置承擔錯誤責任。

類型	主要用途	是否為 Canonical Authority	是否應預設放進每輪 Context
Model Context	本次 Inference 的輸入	否	只放本輪需要的內容
Runtime State	保存執行狀態與 State Transition	對 Run Lifecycle 而言是	否，通常只載入摘要或相關欄位
Durable Artifacts	保存可版本化的規格、計畫與證據	依 Artifact 類型而定	按任務載入
Long-term Memory	保存跨 Session 可重用的資訊	通常不是業務或 Run State 的最終 Authority	按 Scope 與任務選擇
Retrieved Evidence	提供目前問題的候選證據	取決於原始來源，不取決於 Retriever	按需載入

Model Context

Model Context 是這一次模型呼叫實際收到的 Tokens，例如：

Stable Instructions
使用者要求
Task Contract 摘要
經過選擇的 Conversation History
Tool Definitions
Retrieved Evidence
前一輪 Observation
Output Schema

Policy Summary 不等於 Policy Enforcement。 Policy 可以把適合模型理解的摘要放進 Context，但真正的 Permission、Budget、Sandbox 與 Approval Enforcement 仍由 Runtime 執行。Prompt 中寫著「不可讀取 Production Database」，不等於 Credential 或 Network Boundary 已經被強制。

Model Context 是暫時的 Inference Input，不是整個系統的 Source of Truth。

Runtime State

Runtime State 保存系統執行事實，例如：

Run、Turn 與 Task Status
Current State Version
Pending Approval
Tool Request／Result Receipt
Budget Usage
Active Background Work
Workspace 與 Tenant Identity
Cancellation State
Side-effect Operation ID

其中一部分可以被 Context Builder 轉成模型可理解的摘要，但 Canonical State 不能只存在聊天文字裡。

Durable Artifacts

Durable Artifacts 是可版本化、可審查、跨 Session 延續的工作產物，例如：

Project Context
Specification
Plan
Architecture Decision Record
Progress Ledger
Test Evidence
Diff、Build Log 與 Review Finding

Artifact 可以存在 Repository、Document Store、Object Storage 或其他權威系統。它不必常駐 Context，也不應因為「沒有載入模型」就被複製進 Memory。

Long-term Memory

Memory 保存跨 Session 仍值得重用的資訊，例如已確認偏好、已批准決策或穩定的工作背景。

它不應成為 Canonical Task Progress、Database Record 或 Repository Fact 的替代品。任務目前完成到哪裡，應由 Progress Ledger 或 Run State 持有；Memory 最多保存經過治理的摘要與 Pointer。

Memory 需要：

Scope
Schema
Provenance
Verification Status
Retention
Consent
Supersession
Revocation 與 Deletion

「模型曾經說過」不是可以永久寫入的充分理由。

Retrieved Evidence

Retrieved Evidence 是為目前問題按需取得的資料，來源可能是 Vector Index、SQL、文件搜尋、Web、Code Search 或其他工具。

Retriever 找到的是候選內容，不會因為 Similarity Score 很高就自動變成事實。Authority 來自原始資料源與 Governance，不來自向量距離。

Harness 還要判斷：

是否屬於正確 Tenant 與 Scope
Source 是否允許目前 Actor 使用
Version 與 Freshness 是否符合任務
是否包含未受信任的指令性文字
是否足以支持後續 Claim
是否需要其他來源交叉驗證

把這五類資料混成一個 Prompt，後面很難回答三個問題：這段資料從哪裡來、現在還有效嗎、模型為什麼在這一輪看到它？

Context Builder：誰決定模型這一輪看到什麼？

Context Builder 是 Runtime 組裝器。它從多個來源取得候選 Section，套用 Selection Policy，再輸出模型 API 可以接受的 Bounded Context。

典型輸入包括：

Agent Config 與 Stable Instructions
使用者要求與 Task Contract
Canonical Run State
Tenant、Identity 與 Permission Decision
Project／Work-track Artifacts
Retrieved Evidence
Tool Catalog
Tool Results
Verifier Feedback
Remaining Token、Time 與 Cost Budget
Output Schema

這個元件不只是把字串接起來。它至少要處理七個條件：

條件	Context Builder 要回答的問題
Relevance	這段內容對目前步驟有用嗎？
Source Authority	來源是 Policy、使用者、Artifact、外部系統，還是未驗證模型輸出？
Freshness	Source 或 Dependency 改變後，這份衍生內容是否仍有效？
Isolation	內容是否屬於正確 Tenant、Workspace、Task 與 Actor？
Instruction Boundary	這是可執行指令，還是只能當資料閱讀的 Untrusted Content？
Boundedness	Token、工具輸出與重複內容是否受控？
Traceability	能否重建每段內容的來源、版本、Digest 與載入理由？

Context Builder 不應自行把低可信內容「升格」成 Authority。它應保留來源標籤，依既定 Precedence 組裝，並在矛盾無法安全解決時拒絕組裝或要求澄清。

下面是一個架構級 Context Manifest。它不是任何 Provider 的固定 API，只用來表達責任：

{
 "run_id": "run_204",
 "scope": {
 "tenant_id": "tenant_acme",
 "workspace_ref": "checkout-fix@a81c4f2"
 },
 "sections": [
 {
 "id": "task-contract",
 "role": "instruction",
 "authority": "approved_spec",
 "source_ref": "spec-221",
 "source_version": "spec-v7",
 "tokens": 842
 },
 {
 "id": "retrieved-evidence",
 "role": "untrusted_data",
 "authority": "project_docs",
 "source_ref": "docs-query-481",
 "source_version": "docs-index-93",
 "tokens": 2140
 },
 {
 "id": "latest-test-result",
 "role": "runtime_evidence",
 "authority": "test_runner",
 "source_ref": "artifact-test-881",
 "source_version": "sha256:...",
 "tokens": 1260
 }
 ],
 "budget": {
 "context_tokens": 18000,
 "reserved_output_tokens": 4000
 }
}

這些 Token 數只是示意，不是通用 Budget。

這段可以說明什麼？

Context Section 應帶有 Scope、Role、Authority、Source Reference、Version 與 Token Accounting。
不同 Section 可以由不同 Owner 與權威來源提供。
Retrieved Content 可以被標示為 untrusted_data，避免被當成 System Instruction。
輸出空間需要預留，不能先把整個 Window 填滿。
Trace 可以記錄哪些 Section 被載入、哪些被省略，以及當時使用的 Source Version。

這段不能證明什麼？

沒有定義實際 Prompt 格式或 Provider API。
沒有證明示意 Budget 適合任何真實 Workload。
沒有完整處理 Prompt Injection、Secrets、Data Masking 與 Tenant Authorisation。
沒有證明 Retrieved Evidence 正確或足以支持答案。
沒有證明 Selection Policy 已經經過 Evaluation。

Manifest 讓 Context 變得可觀測，不會替 Selection Policy 自動變聰明。

Runtime Prompt Assembly：穩定內容和動態內容要有邊界

System Prompt 不應是一段持續膨脹的字串。比較可維護的做法，是讓不同 Section 擁有自己的 Owner、Version、Priority、Token Budget 與載入條件。

Stable sections

較適合放在 Stable Prefix：

Identity 與 Operating Principles
Invariant Policies 的模型可讀摘要
Output Conventions
Stable Tool Guidance

Dynamic sections

每輪或每個 Run 可能改變：

Workspace、Branch、Tenant 與 Actor
Current Tool Catalog
Task、Plan 與 Run State
Memory Index Generation
Connected External Capabilities
Current Budget
Retrieved Evidence

Dynamic State 不應污染可重用的 Stable Prefix Cache。Tool Catalog、Permission、Memory、Workspace 或 Policy 改變後，相關組裝結果必須重新計算。

每次 Model Call 至少應記錄：

Loaded Section IDs
Omitted Section IDs and Reasons
Section Digests and Versions
Total Tokens
Cache-hit Scope
Stable／Dynamic Boundary

Section 是否載入應由真實 State 與 Policy 決定，不宜只靠 Query 關鍵詞猜測。

Progressive Disclosure：先給地圖，再按任務載入細節

Coding Agent 很少需要在第一輪讀完整 Repository。比較穩定的做法是分三層載入。

Progressive disclosure for agent context

Figure 4-2｜Always-on Map 負責導航，Task-scoped Context 支援當前工作，On-demand Evidence 透過受控工具按需取得。

Always-on Map

Always-on Map 應短、穩定、可導航，通常包含：

專案目的與主要模組
Build、Test、Lint 與 Run 的入口
關鍵安全與資料限制
深層文件索引
目前任務與狀態的入口

它的工作是告訴 Agent 去哪裡找，不是代替整個知識庫。

Task-scoped Context

只有目前任務需要時才載入：

相關模組與真實檔案路徑
API、Schema 與 Dependency Boundary
既有 Implementation Pattern
Feature／Bug 的 Spec、Plan 與 Acceptance Criteria
Allowed Scope 與必要 Verification

任務或 State 改變後，這一層也要重新選擇，不能沿用上一個 Task 的「看起來差不多」。

On-demand Evidence

更大、較少使用或變動較快的資料，留到需要時透過工具取得：

完整歷史決策
過去 Incident
大型 Log 與 Trace
外部文件
完整測試輸出
大型資料表

Just-in-time Retrieval 的重點不是把所有事情延後，而是讓 Agent 持有可靠 Identifier，例如 File Path、Document ID、Query Handle 或 Artifact URI，再按目前步驟載入必要內容。Anthropic 也將 Agentic Search 與一次預先塞滿所有資料的做法區分開來。¹

Repository-native Context 不代表所有知識都必須複製進 Git。Code、Build 指令與架構規則通常適合和 Repository 共存；商業、敏感、跨專案或即時資料，可以留在其他 Canonical System，再透過受控工具提供。

不要使用「固定百分比 Context Window」當成通用規則。Always-on Map、Task Context 與 Evidence 的比例應根據任務成功率、Constraint Recall、Retrieval Precision、Tool Error、Latency 與 Cost 實測調整。

Context Artifact Lifecycle：把意圖、計畫與證據做成受治理產物

Chat History 適合記錄互動，不適合作為複雜專案唯一的工作規格。

當工作跨越多個 Turn、Session 或執行者，重要內容需要升級成 Durable Artifact。

Context artifact lifecycle

Figure 4-3｜Project Context、Spec、Plan、Progress 與 Verification Evidence 各自具有版本與審核狀態；變更會建立新版本，而不是偷偷覆寫已批准內容。

一個較完整的 Artifact State Graph 可以整理成：

Bootstrap Project Context
→ Create Work Track
→ Draft Spec
→ Review / Approve Spec
→ Draft Executable Plan
→ Review / Approve Plan
→ Implement + Update Progress Ledger
→ Verify Completion
→ Promote Durable Knowledge / Retain Evidence / Archive Disposable Material

若 Assumption、Scope 或 Architecture 中途改變，流程不應只把舊文件原地改掉：

Detect change
→ create new artifact version
→ record reason and impact
→ re-review affected Spec or Plan
→ update verification requirements
→ resume execution from an explicit state

Google Conductor 將 Project Context、Specs 與 Plans 放入持久 Markdown，讓它們和 Code 一起保存與審查。它的價值不在 Markdown 格式，而在於 Intent、Plan 與 Progress 不再只存在短命 Chat Session。Google 的流程也明確要求 Plan Approval 後才進入 Implementation。²

Project context

跨 Work Track 較穩定的資訊：

Product Users and Goals
Architecture and Domain Boundaries
Technology Stack
Team Workflow and Testing Rules
Security and Operational Constraints

Work-track context

只屬於一項 Bug、Feature 或 Migration：

Problem and Why
Scope／Out-of-scope
Specification
Plan and Phases
Risks
Acceptance Criteria
Progress、Blockers 與 Decisions

Runtime evidence

Agent 工作時產生的可驗證事實：

Test Result
Build Log
Diff
Operation Receipt
Trace／Screenshot
Review Finding
Verification Report

完成後，這些內容不能全部放進同一個「Knowledge」資料夾：

可重用且已驗證的決策，升級成 ADR 或 Maintained Guide。
完成證據依 Retention Policy 保存，不能當成臨時垃圾刪除。
被取代的 Spec／Plan 保留 Supersession 關係。
低價值探索草稿可以 Archive 或 Delete。

Brownfield bootstrap 不能只靠一次自動摘要

既有系統的 Context 要從多種證據建立：

Code 與 Dependency Analysis
Existing Documents
Tests
Git History
Runtime Evidence
Human Interview and Confirmation
Architecture Decision Records

自動產生的 Project Description 只能是 Draft。若來源互相衝突，系統應列出 Conflict 與 Unresolved Assumption，不應挑一個最流暢的版本當成真相。

Context drift

Artifact 和實際系統會分叉。每份重要 Artifact 至少需要：

Owner
Version
Status
Last Verified
Canonical Sources
Related Code／Schema／Policy
Stale Trigger
Supersedes／Superseded By
Archive or Retention Policy

Plan 在工作中途改變不是問題。沒有留下原因、影響範圍、重新批准與新 Verification，才是問題。

Compaction、Clearing 與 Memory 解的是三種不同問題

Agent Context 變大時，常見反應是立刻「做摘要」或「開 Memory」。這兩個選項都可能用錯地方。

Compaction, clearing and memory comparison

Figure 4-4｜Compaction 壓縮工作脈絡，Clearing 移除可安全重取的 Payload，Memory 保存跨 Session 值得重用的資訊；Canonical Progress 仍由 Runtime State 或 Progress Ledger 持有。

Primitive	解決的主要問題	適合保存	不應承擔的責任
Compaction	整段 Transcript 太長	Goal、Decisions、Open Issues、Evidence References、Next Step	不保證無損，也不取代 Durable State
Tool-result Clearing	可重取 Tool Payload 太大	Call Record、Source ID、Digest、Retrieval Handle	不可移除 Side-effect Receipt、Approval 或不可重現 Evidence
Memory	資訊要跨 Session 重用	Confirmed Preference、Verified Decision、Curated Background	不持有 Canonical Task Progress 或業務資料

Compaction

Compaction 將長 Transcript 壓縮，再用摘要和近期必要資料繼續工作。

Summary Contract 至少要保留：

Current Objective
User Constraints
Accepted Decisions and Reasons
Modified Resources
Tests and Evidence References
Open Failures
Active Operation IDs
Remaining Work
Next Safe Action

Compaction 本質上有損。Summary Prompt、必留欄位與 Recovery Path 都需要 Evaluation。模型現在認為不重要的細節，可能在三輪後變成根因。

Tool-result Clearing

File Read、Search Page、API Response 與大型 Log 往往佔用最多 Tokens。若 Raw Payload 可以安全重取，可以移除內容，只保留：

Tool Call Identity
Source Identifier and Version
Digest／Metadata
Retrieval Handle
必要引用位置

不能清掉：

Side-effect Receipt
Approval Decision
Operation ID
不可重現結果
後續 Verification 必須引用的 Evidence

Memory

Memory 是外部持久化資料層。它不應自動保存所有模型輸出，也不代表每一條記憶都要在每輪載入。

可用的 Memory Pipeline 至少包含三個獨立步驟：

Selection → load relevant memory
Extraction → propose candidate memory
Consolidation → approve, merge, supersede, expire or delete

候選 Memory 不是事實。寫入前至少要確認：

是否真的需要跨 Session？
是否已存在於更權威的 Source？
是已驗證事實、使用者確認偏好，還是模型推測？
Scope 是 User、Project、Tenant 還是 Session？
是否含敏感資料？使用者是否預期或同意保存？
誰可以修正、撤銷、匯出或刪除？
何時應 Supersede 或 Expire？

示意 Record 可以寫成：

memory_id: mem-123
scope: project
subject_id: checkout-service
type: verified_decision_summary
content: "PostgreSQL remains the source of truth for payment state."
source_ref: adr-017
source_version: 4
verification_status: approved
approved_by: architecture-owner
created_at: 2026-07-08
expires_at: null
policy_version: memory-policy-4

這筆資料較可信，不是因為它使用 YAML，而是因為它指向 Canonical Source，保留 Version 與 Verification Status，也能被 Supersede 或 Delete。

任務進度則應寫入 Progress Ledger：

Canonical progress ledger
→ Context Builder selects relevant summary
→ Model sees current progress

不要反過來讓 Memory Summary 變成 Task Status 的最終真相。

Anthropic 的 Cookbook 也把 Memory、Compaction 與 Tool-result Clearing 視為不同策略，並指出它們針對的瓶頸與成本不同。該 Cookbook 另提到 Subagent Isolation 與 Programmatic Tool Calling，可以讓大型資料根本不必進入主 Context。³

先做低損失處理，再做有損摘要

當 Context 接近限制時，一個較安全的 Degradation Ladder 是：

1. Persist oversized raw artifacts
2. Replace old, reproducible tool payloads with references
3. Remove low-value middle transcript without breaking protocol pairs
4. Create a semantic summary under a Summary Contract
5. Perform bounded emergency compaction
6. Stop safely when further compression cannot preserve required state

順序很重要。若先清除大型 Tool Result，之後才發現它是唯一 Evidence，資料已經救不回來。

任何裁剪都不能拆散：

Tool Request 與 Correlated Result
Approval Request 與 Decision
Background Accepted 與 Work ID
Side-effect Operation 與 Receipt
Task Claim 與 Ownership Record

完整 Transcript 可以保存到 Durable Storage，但「已保存」不代表模型仍然可以使用。系統還需要 Artifact Tool、Retrieval 或明確 Reference，才能讓後續 Session 重新取得細節。

Semantic Compaction 失敗或仍然超限時，重試次數要有限。繼續壓縮可能只會消耗成本並放大資訊遺失。

RAG 在 Harness 中的位置

RAG 是 Harness 治理下的 Knowledge Acquisition Subsystem，不是整個 Harness，也不必和 Harness Runtime 部署在同一個 Process。

Harness and RAG responsibility boundary

Figure 4-5｜RAG 規劃與執行檢索，回傳帶有 Provenance 的 Candidate Evidence；Harness 仍負責 Scope、Policy、Context Assembly、Fallback、Completion 與 Trace。

RAG 通常負責：

Query Planning
Query Rewrite／Decomposition
Corpus／Index Routing
Metadata Filter Construction
Retrieval
Reranking
Deduplication
Candidate Evidence Packaging

Harness 還要負責：

這一輪是否需要 Retrieval
Actor 可以查哪些 Corpus、Tenant 與欄位
使用哪個 Retrieval Profile、Model 與 Budget
Query Planning 可用哪些 Scope 與 Filter
Empty／Low-confidence Retrieval 如何處理
是否允許改查 SQL、Web、Code Search 或詢問使用者
Candidate Evidence 如何被 Qualify 後放進 Context
Claim 與 Citation 是否得到對應 Evidence 支持
何時 Retry、Degrade、Ask User 或 Stop
Trace、Cost 與 Evaluation Evidence 如何保存

因此：

Good Retrieval ≠ Grounded Answer ≠ Good Production Harness

一個 Retriever 可以找到高相似度文件，系統仍可能因 Permission 錯誤、過期內容、錯誤 Citation Mapping 或不合理 Stop Policy 產生不可信結果。

Candidate Evidence 需要帶回什麼？

RAG 不應只回傳純文字片段。至少應保留：

Source ID and URI
Source Version or Timestamp
Tenant／Scope
Chunk Location
Retrieval Query and Profile
Rank／Score as Retrieval Signal
Content Digest
Data Classification
Freshness or Validity Metadata

Score 是排序訊號，不是 Truth Score。Context Builder 可以根據 Policy 與 Budget 選擇內容，但 Claim Verification 要在答案或行動產生後另外進行。

Query Planning 只回答「怎麼查」

Query Planning 可能包含：

Rewrite Ambiguous Query
Split into Sub-queries
Route to Different Indexes
Add Metadata Filters
Run Multi-step Retrieval
Merge and Deduplicate Results
判斷是否已取得足夠 Retrieval Evidence

最後一項只代表檢索計畫可以停止，不代表整個 Task 已經完成。

Orchestration 的範圍更大。它還要決定是否改用 SQL、是否詢問使用者、是否進入 Verifier，以及整個 Run 何時結束。

Context Builder 與 Synthetics 不要混在一起

面向	Context Builder	Synthetics
發生時間	每輪 Runtime	Retrieval、Training 或 Evaluation 前後
目的	組裝模型此刻需要的 Context	生成輔助 Query、Document、QA 或 Training Data
常見輸出	Messages、Input Items、Section Manifest	HyDE Document、Synthetic Query、QA Pair、Hard Negative
主要風險	污染、過長、過期、跨 Scope	偏誤、幻覺、Evaluation Leakage

HyDE 或 Synthetic Query 可以改善特定檢索問題，但它們不是 Memory，也不會取代 Context Builder。

Derived Context Cache：摘要也會活在過期世界裡

Context Builder 常建立昂貴的 Derived Context：

Repository Map
Schema Summary
Recent Commits Digest
Documentation Index
Tool Catalog Summary
Memory Index

Cache Hit 可以降低 Latency 與 Cost，但底層資料改變後，舊摘要會讓 Agent 持續基於過期世界推理。

每個 Cached Block 應記錄：

Tenant and Workspace Scope
Source Ref
Dependency Versions or Generations
Policy Version
Tool Catalog Version
Memory Index Generation
Generated At
Content Digest

例如：

repository-map-v21
├── tenant: tenant_acme
├── workspace_ref: a81c4f2
├── file_tree_generation: 94
├── policy_version: policy-8
├── tool_catalog_version: tools-31
└── generated_at: 2026-07-08T10:30:00Z

常見 Mutation Point 包括：

File Write／Rename／Delete
Git Checkout、Merge、Rebase
Schema Migration
Tool Registration 或 Plugin Enablement
Permission／Policy Change
Memory Update
Dependency or Environment Change

Mutation Point 應產生 Invalidation Event。若 Dependency 無法可靠追蹤，使用短 TTL 或不快取。

只測「第二次 Cache Hit」不夠。正確性測試應是：

Build cache
→ mutate a declared dependency
→ verify invalidation event
→ rebuild context
→ confirm the old source version is absent

Provider Stable-prefix Cache、Application Section Assembly Cache 與 Derived-data Cache 是三個不同層次。它們不能共享一個模糊的 cached=true，也不能使用相同 Invalidation 規則。

Fresh Session Test：新 Session 能不能重建工作狀態？

Context Artifact 的品質，可以用一個不太客氣但很有效的方法測試：啟動全新 Session，不提供口頭補充，讓 Agent 從標準入口重建工作狀態。

測試條件應盡量接近真實執行：

使用和 Production 相同的 Instruction Precedence
使用標準 Tool 與 Permission Profile
從乾淨 Checkout 或已知 Checkpoint 開始
不提供測試者的私下提示
要求 Agent 引用用來做判斷的 Artifact

新的 Session 至少應能回答：

這個系統是什麼？
主要模組與 Authority Boundary 在哪裡？
如何安裝、啟動、停止與驗證？
現在正在做什麼？哪些已完成、阻塞或取消？
下一個安全動作是什麼？
哪些操作需要批准或禁止？
它引用了哪些 Artifact 得出上述判斷？

測試時記錄：

Discovery Time
無效 Tool Calls
錯誤假設
人工介入次數
找到但過期的文件
找不到的 Canonical Artifact

失敗可以分類為：

Missing：必要資訊不存在。
Hidden：資訊存在，但標準入口找不到。
Stale：Artifact 與系統已分叉。
Ambiguous：同一件事有多個互相衝突的 Authority Claim。
Inexecutable：指令存在，實際不能執行。
Unauthorized：恢復流程要求不應暴露的權限。

OpenAI 在 Harness Engineering 文章中把 Repository Knowledge 做成 System of Record，並將 Agent Legibility 當成工程目標。這不表示所有資料都必須塞進 Repository，而是 Agent 所需的權威資訊要能被定位、理解、驗證與追溯。⁴

Fresh Session Test 若持續失敗，不應只把更多內容塞進 AGENTS.md。真正的修復可能是補文件索引、建立可執行命令、修正 Progress Ledger、標出 Ownership，或刪除已失效的重複說明。

Context 需要 Gardening，也需要 Admission Gate

當 Agent 大量生成 Spec、Summary、Memory 與 Documentation，Context 系統會遇到另一種瓶頸：低訊號內容增長得比驗證能力快。

每份準備進核心知識庫的內容都應回答：

它增加了什麼決策價值？
和既有內容是否重複或衝突？
Source Authority 與 Temporal Scope 是什麼？
誰維護？哪些 Mutation 會讓它失效？
放入 Core、Reference、Watchlist，還是 Reject／Expired？

Agent 可以協助抓取、摘要、去重、檢查 Broken Link 與提出分類建議。是否進入 Canonical Knowledge，仍是治理決策。

一個可維護的 Gardening Loop 可以是：

Scan
→ classify stale / orphan / conflict
→ open a bounded repair
→ verify against code or authority
→ update indexes
→ supersede, archive or delete safely

如果每次失敗都新增一份文件，卻從不修正或淘汰舊文件，Knowledge Base 會逐漸變成一套多個答案都看似合理的系統。

用「修正付款狀態不一致」走一次

延續前幾篇的付款案例，假設 Coding Agent 要修正：付款供應商已成功扣款，但內部 Order 仍停在 pending。

一個受治理的 Context 流程可能是：

Always-on Map 提供 Checkout、Payment、Order 三個模組的入口與測試指令。
Task Contract 限定：修正狀態同步，不更換供應商，不直接操作 Production Data。
Context Builder 讀取目前 Workspace、Run State、相關 API Contract 與最新 Test Evidence。
RAG／Code Search 找到 Webhook Handler、Order State Transition 與過去 Incident，並保留 Source Version。
Policy 在 Retrieval 前套用 Tenant、Corpus 與 Field Scope。
Context Builder 將 Retrieved Text 標為 Data，不讓其中的文字覆蓋 System Instruction。
Agent 讀取必要檔案與 Log，不把整個 Repository 塞進 Model Context。
大型 Raw Log 先存成 Artifact，只把 Relevant Lines、Time Range、Digest 與 Artifact ID 放回模型。
Agent 提出 Patch，測試產生新的 Runtime Evidence。
下一輪 Context 優先載入 Patch Diff、失敗測試、原始 Acceptance Criteria 與 Remaining Work。
若 Webhook Schema 改變，舊 Schema Summary 與相關 Context Cache 立即失效。
完成後，Temporary Search Payload 被清理；Evidence 依 Retention 保存；已確認的設計決策升級成 ADR，而不是寫成無來源 Memory。

表面上「Context 很完整」不代表它有效。若第 11 步沒有 Invalidation，Agent 下一輪仍可能使用舊欄位推理，只是錯得更有條理。

用十個問題審查一套 Context 系統

Context Builder 的 Owner 是誰？它依據什麼 State 與 Policy 選擇內容？
Model Context、Runtime State、Durable Artifact、Memory 與 Retrieved Evidence 是否分開？
每個 Section 是否有 Role、Authority、Scope、Source Version、Digest 與載入理由？
Retrieved 或 Tool Content 是否被當成 Data，而不是偷偷升格成 Instruction？
Always-on Map 是否只負責導航？Task-scoped Context 是否會隨任務重新選擇？
大型 Raw Data 是否先落成 Artifact 或外部處理，而不是直接灌進 Prompt？
Compaction、Clearing 與 Memory 是否對應實際 Bottleneck，且遵循低損失優先順序？
Canonical Progress 是否留在 Run State／Progress Ledger，而非 Memory Summary？
RAG 的 Permission、Freshness、Fallback、Provenance 與 Citation Verification 是否由 Harness 治理？
Derived Context Cache 與 Fresh Session Test 能否揭露 Stale、Hidden、Ambiguous 或 Inexecutable Context？

Context Engineering 做得好時，模型不需要知道所有事情。它需要在正確時間看到足夠、可信、可操作的資訊，並能沿著穩定 Identifier 找到下一層證據。

理論轉實作：Part 04 檢查表

Part 05 會把 Context Builder 可以暴露給模型的 Capability Surface 拆開：Tool、Skill、Hook、Plugin 與 MCP 分別處理什麼，以及為什麼工具愈多，不一定讓 Agent 更有能力。

References

Anthropic, Effective context engineering for AI agents, 29 September 2025. ↩ ↩²
Google Developers Blog, Conductor: Introducing context-driven development for Gemini CLI, 17 December 2025. ↩
Anthropic, Context engineering: memory, compaction, and tool clearing, 20 March 2026. ↩
OpenAI, Harness engineering: leveraging Codex in an agent-first world, 11 February 2026. ↩