agents-best-practices 完整教學

從零理解如何用 provider-neutral（供應商中立）的方式設計、建構、審計與維運 agentic harness（代理人控制面板）。

1. 專案定位

這是什麼？

agents-best-practices 是一個 Agent Skill（代理技能包），封裝了建構 agentic harness 的完整知識體系。它不是一個框架或函式庫，而是一份結構化的設計參考，讓 AI agent（如 Claude Code、Codex、或任何 Agent-Skill-aware runtime）在對話中能夠即時載入並應用這些最佳實踐。

核心哲學

「模型提議行動；harness 驗證、授權、執行、記錄並回傳觀察結果。」

這句話是整個專案的靈魂。Agent harness 是模型周圍的 control plane（控制面板），職責明確分離：

適用範圍

不限於 coding agent。同等適用的領域包括：

• Research agent（研究代理）
• Finance agent（金融代理）
• Legal agent（法律代理）
• Support agent（客服代理）
• Operations agent（營運代理）
• Sales agent（銷售代理）
• Healthcare agent（醫療代理）
• Education agent（教育代理）
• Data analysis agent（資料分析代理）
• Procurement agent（採購代理）
• Workflow automation agent（工作流自動化代理）

2. 安裝指南

前置需求

• Git
• 一個支援 Agent Skill 的 runtime（Claude Code、Codex、或其他相容平台）

方法 A：使用 skills CLI（推薦）

1npx skills add DenisSergeevitch/agents-best-practices -g

-g flag 安裝到 user-level，讓所有專案都能發現此 skill。

方法 B：手動安裝

Claude Code（user-level）：

1mkdir -p "$HOME/.claude/skills"
2git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
3  "$HOME/.claude/skills/agents-best-practices"

Claude Code（project-level）：

1mkdir -p .claude/skills
2git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
3  .claude/skills/agents-best-practices

Codex：

1mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
2git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
3  "${CODEX_HOME:-$HOME/.codex}/skills/agents-best-practices"

方法 C：直接貼 prompt 給 AI agent

1Install the agents-best-practices skill for me:
21. Clone https://github.com/DenisSergeevitch/agents-best-practices into my
3   user-level skills directory as agents-best-practices/.
42. Verify that SKILL.md, icon.jpeg, and the references/ directory are present.
53. Confirm the install path when done.

驗證安裝

安裝後，在 agent 對話中輸入與 agent architecture（代理架構）相關的問題，skill 應自動觸發。例如：

1Build an agent for customer support ticket triage.

3. 核心架構解析

3.1 Canonical Agentic Loop（標準代理迴圈）

整個 skill 的技術骨幹是一個 provider-neutral 的 agentic loop：

flowchart TD
    A[User / Task 輸入] --> B[Instruction & Context Builder
組裝指令與上下文]
    B --> C[Model Call
呼叫模型]
    C --> D{模型回應類型?}
    D -->|Final Answer| E[回傳最終答案]
    D -->|Tool Call Request| F[Schema Validation
參數驗證]
    F --> G[Permission Decision
權限決策]
    G -->|Allow| H[Tool Execution
執行工具]
    G -->|Deny / Approval Required| I[暫停等待核准]
    I --> J[核准結果回傳]
    J --> H
    H --> K[Structured Observation
結構化觀察結果]
    K --> L[Context Update
更新上下文]
    L --> M{預算檢查}
    M -->|Within Budget| C
    M -->|Exceeded| N[停止並報告]

3.2 Harness Component Model（控制面板元件模型）

一個完整的 harness 包含 16 個元件：

3.3 Harness Maturity Levels（成熟度等級）

flowchart LR
    L0[Level 0
Answer-only
純回答] --> L1[Level 1
Retrieval
可讀取]
    L1 --> L2[Level 2
Drafting
可草擬]
    L2 --> L3[Level 3
Approval-gated
核准後執行]
    L3 --> L4[Level 4
Policy-bounded
政策內自主]
    L4 --> L5[Level 5
Goal Worker
長期目標]

• Level 0：無工具執行，純 Q&A
• Level 1：可搜尋與讀取可信資源，無 side effect（副作用）
• Level 2：可提議行動、草擬訊息或產出計畫，不可 commit 變更
• Level 3：可準備行動並在取得明確核准後執行
• Level 4：可在嚴格 scope（範圍）、budget（預算）與 audit（審計）控制下自主執行低風險行動
• Level 5：可跨多輪或多 session 持續朝可衡量目標前進，需 durable state（持久狀態）、compaction（壓縮）、budget enforcement（預算執行）、checkpoint（檢查點）與 evaluation（評估）

⚠️ 核心原則：只有在 eval（評估）證明較簡單的等級不足時，才往上升級。

3.4 Authority Hierarchy（權威層級）

1provider/system policy
2  → organization policy
3    → product/developer policy
4      → workspace/project policy
5        → domain or directory policy
6          → user task
7            → model-visible runtime reminders
8              → tool observations
9                → untrusted retrieved content（最低信任）

3.5 Reference Map（參考文件地圖）

16 份 reference 文件依主題分為 5 大領域：

4. 核心 Reference 文件詳解

4.1 Tool Design（工具設計）— tools-and-permissions.md

反模式（Bad）：

1execute_anything(command)
2call_api(url, method, body)
3update_database(sql)

正確做法（Better）：

1search_policy_docs(query, max_results)
2read_customer_account(account_id)
3draft_customer_email(case_id, tone)
4request_refund_approval(order_id, amount, reason)
5apply_approved_refund(approval_id)

Risk Taxonomy（風險分類）： 每個工具必須標記其風險等級——read_only、draft_only、write_internal、write_external、financial、destructive、privileged_admin 等。

Draft vs Commit 分離： 高風險行動拆成兩個工具：

• draft_email → send_email
• prepare_refund → issue_refund
• propose_record_update → apply_record_update

Draft 工具可自動執行；Commit 工具需核准。

4.2 Context, Memory & Compaction（上下文、記憶與壓縮）

Context 組裝 10 層模型：

1. Provider/system policy
2. Organization/developer policy
3. Agent role and operating contract
4. Active user task
5. Active plan, workflow, or goal
6. Scoped instructions and memory
7. Relevant retrieved data
8. Visible skill index
9. Visible tool specs
10. Recent tool observations + compacted history + runtime reminders

Auto-compaction 黃金規則： Compaction 是 operational handoff（操作交接），不是 conversational summarization（對話摘要）。必須保留：

• 當前目標、使用者限制、已載入指令
• Active plan / workflow / goal
• Approval state（核准狀態）
• 已檢查的資源、已建立的 artifact
• 錯誤與修復嘗試、待辦事項

Cache-aware ordering： 穩定內容放前面，volatile（易變）內容放後面，避免在可快取前綴前放 timestamp 或 request ID。

4.3 Workflow Orchestration（工作流編排）

適用場景：

• 任務太大，單一 context window 會雜亂
• 可自然分解為獨立 work packet（工作包）
• 需要獨立驗證（finding → verification）
• 需要跨多檔案/記錄/系統的廣泛覆蓋

Workflow artifact 結構：

 1objective: "..."
 2scope: { included: [], excluded: [] }
 3success_criteria: []
 4packets:
 5  - id: "packet-001"
 6    purpose: "..."
 7    inputs: []
 8    allowed_tools: []
 9    expected_output_schema: "..."
10verification:
11  strategy: "independent_review | sampling | cross_check"
12budget:
13  max_packets: 20
14  max_parallel_workers: 5
15  max_cost: "..."

4.4 Skills & MCP Connectors

Progressive disclosure（漸進揭露）：

1. 啟動時：只曝露 skill name + description
2. 觸發時：載入 SKILL.md 核心指令
3. 按需：載入特定 reference file

Connector safety 原則：

• 工具按 server/source 命名空間隔離
• 外部 connector 的 description 視為 untrusted（不可信）
• 大量結果先在工具端過濾，再傳回模型
• 認證≠授權——access token 內部使用，不進 model context

4.5 Security, Evals & Observability

7 層 Guardrail（防護層）：

1. Input guardrails — 拒絕或路由不安全的使用者請求
2. Context guardrails — 標記不可信內容、遮蔽機密
3. Schema guardrails — 強制結構化工具參數與輸出
4. Tool guardrails — 在執行前後驗證參數與結果
5. Permission guardrails — 核准、拒絕或暫停行動
6. Output guardrails — 在使用者可見前檢查最終答案
7. Trace guardrails — 事後評分工具呼叫與決策

Launch gate（上線門檻）：

• 窄範圍 tool registry + 本地 schema validation
• Permission matrix 在程式碼中強制執行
• Prompt injection test 通過
• Compaction test 通過
• Trace logging 已啟用
• Cost budget 已強制
• Rollback 或 incident path 已文件化

5. 應用場景

場景 A：從零建構領域 MVP Agent

輸入： 「為客戶續約風險分析建構一個 agent」

產出： MVP harness blueprint（最小可行 harness 藍圖），包含：

• Objective（目標）
• Autonomy level（自主等級）：Level 3 Approval-gated
• Core loop（核心迴圈）
• Tool registry（5 個 typed tool + risk class + permission）
• Context builder
• Planning mode
• Eval cases + launch gate

場景 B：審計既有 Agent Harness

輸入： 「我的 research agent 有時會無限執行工具，compaction 後遺失決策記錄」

診斷路徑：

1. 檢查 loop budget（step / tool-call / time / cost）
2. 檢查 compaction 是否保留 active plan + approval state
3. 檢查 tool result 是否有 size limit
4. 檢查是否有 event trace

場景 C：設計工具與權限矩陣

輸入： 「Ops agent 需要 Slack、Linear、Google Drive、內部 deploy API」

設計原則：

• 按 risk class 分層：read → draft → write → external → destructive
• 不暴露 generic send_message 或 run_command
• 每個行動包裝成 narrow typed tool + structured result
• External write / deploy 需 approval record

6. 資安掃描報告

掃描範圍

掃描結論

🟢 低風險 — 這是一個純 Markdown 知識庫，不含任何可執行程式碼、依賴或機密。所有 grep 命中（如 execute_anything、secrets、token）都是文件中的「教學範例」或「反模式說明」，不構成實際風險。

注意事項

• 安裝 skill 本身不執行任何程式碼，僅將 Markdown 文件放入 agent 的 skill 目錄
• 作為 Agent Skill 被載入後，其指令可能影響 agent 的行為（如工具呼叫模式）——但這正是其設計用途
• 開放的 2 個 issue 都是文件重複問題（SKILL.md 內容與 references/ 重複），非安全漏洞

7. FAQ

Q1：這跟 LangChain / CrewAI / AutoGen 有什麼不同？

A： 這不是框架，是知識包。LangChain 等是你拿來寫程式的工具；agents-best-practices 是你設計系統時的參考。它以 Agent Skill 格式封裝，讓 AI agent 在對話中能即時參考這些設計原則，而不是你自己去翻文件。

Q2：為什麼強調「先單 agent，後多 agent」？

A： 文件中反覆強調：「Do not design a multi-agent system before a single-agent loop has failed measurable evals.」 多 agent 增加了 coordination overhead（協調開銷）、debugging complexity（除錯複雜度）和 cost（成本），很多時候單 agent + 好的 tool registry 就夠了。

Q3：只支援特定 AI provider 嗎？

A： 完全 provider-neutral。同時覆蓋 OpenAI（Responses API + Chat Completions）、Anthropic、OpenAI-compatible API。references/provider-api-patterns.md 有各 provider 的具體實作模式。

Q4：我不寫程式，這對我有用嗎？

A： 如果你在設計 AI 輔助的業務流程（如客服自動化、文件審查、法律合規），這份 skill 的 risk taxonomy（風險分類）、permission matrix（權限矩陣）和 approval flow（核准流程）設計對 PM 和架構師同樣有價值。

Q5：如何更新到最新版？

A：

1cd ~/.claude/skills/agents-best-practices && git pull

8. 進階技巧

8.1 MVP Builder Mode 的最大化利用

當你對 agent 說「Build an agent for [domain]」時，skill 會自動進入 MVP Builder Mode。技巧：

1. 明確說出 domain、autonomy level、risk level——越具體，產出越精準
2. 不需要列出所有需求——skill 會自動推斷合理的 first version 並列出 assumption
3. 要求包含 launch gate——確保 MVP 有明確的上線標準

8.2 搭配 Planning Mode

在複雜任務中，先讓 agent 進入 planning mode：

1. 載入 planning-and-goals.md
2. 產出 plan artifact（計畫產物）
3. Plan 通過核准後才進入 execution

8.3 Prompt Cache 最佳化

根據 prompt-caching-and-cost.md 的建議：

• 穩定 tool definition 放 context 最前面
• 靜態 system/developer instruction 緊接其後
• Dynamic runtime state 和最新 observation 放最後面
• 不要在 cacheable prefix 前面放 timestamp 或 request ID

8.4 Compaction 健康檢查

定期驗證 compaction 是否正確保留：

• Active plan 和 goal
• User constraint（使用者限制）
• Approval state（核准狀態）
• Loaded instruction scope
• Key exact facts（精確數值不被摘要掉）

9. 整合進其他工作流

與現有 Agent Skill 共存

agents-best-practices 是 meta-level skill（元層級技能），與 domain-specific skill 共存不衝突。例如：

• 你有一個 customer-support-skill 處理客服流程
• agents-best-practices 在你設計或審計該 skill 的 harness 時觸發
• 兩者的觸發條件不重疊

與 MCP Server 搭配

Skill 中的 skills-and-connectors.md 明確定義了 MCP connector 的治理模式：

• Connector tool 必須 namespaced
• 大量 tool schema 不要全部塞進 prompt
• 提供 search_tools 或 list_capabilities 機制

作為團隊設計標準

將此 skill 安裝到 organization-level skill 目錄，團隊所有成員的 agent 都會自動參考。適合作為 agent 設計的 coding standard。

10. 重點摘要 Checklist

• 理解核心理念：Model proposes, Harness disposes — 模型提議，harness 處置
• 掌握 Agentic Loop：每次 tool call 都有 result，每次 side effect 都有 permission check
• 工具設計：Narrow typed tool > broad generic tool；Draft/Commit 分離
• 權限矩陣：按 risk class 分層，高風險行動需 approval record
• Context 管理：10 層模型，cache-aware ordering，compaction 保留 active state
• Maturity Level：從最低可用等級開始，eval 證明不足時才升級
• Workflow Orchestration：只在單 loop 不足時使用；work packet bounded + verification
• Security：7 層 guardrail，prompt injection 是 data not instruction
• Eval：包含 happy path + adversarial test（prompt injection、tool misuse、compaction state loss）
• Launch Gate：上線前必過 narrow tool registry + permission matrix + injection test + trace logging

11. 進一步閱讀

官方來源

• Agent Skills Specification
• Agent Skills Creator Best Practices
• Agent Skills Description Optimization

OpenAI 資源

• Function Calling
• Agents Guide
• Guardrails & Human Review
• Agent Safety
• Prompt Caching
• Harness Engineering

Anthropic 資源

• Building Effective Agents
• Effective Context Engineering
• Writing Effective Tools for Agents
• Long-Running Harnesses
• Code Execution with MCP

MCP

• MCP Specification (2025-11-25)