/* 基礎知識 -------------------------------------------------- */
- 目地是透過觀察 claude code 背後的`交談過程`與`資料結構` 從而瞭解 context 管理的重要性
- 如何監看 tools + system prompt 改化學人家怎麼寫提示與設計工具
→ 心法：你懂 context，context 就會幫你 (反之...👻
- `v2.1.69` 首次登場
- context 狂省四倍！
# 以往
- 18,000
- 所有 tools 啟動時全送入
# 現在
- 4,547
- 只剩一個 `ToolSearch` 動態查詢可用工具再載入
'Search for or select deferred tools to make them available for use.'
'**MANDATORY PREREQUISITE - THIS IS A HARD REQUIREMENT**'
'You MUST use this tool to load deferred tools BEFORE calling them directly.'
'This is a BLOCKING REQUIREMENT - deferred tools are NOT available until you load them using this tool. Look for <available-deferred-tools> messages in the conversation for the list of tools you can discover. Both query modes (keyword search and direct selection) load the returned tools — once a tool appears in the results, it is immediately available to call.'
'**Why this is non-negotiable:**'
'- Deferred tools are not loaded until discovered via this tool'
'- Calling a deferred tool without first loading it will fail'
'**Query modes:**'
"1. **Keyword search** - Use keywords when you're unsure which tool to use or need to discover multiple tools at once:"
' - "list directory" - find tools for listing directories'
' - "notebook jupyter" - find notebook editing tools'
' - "slack message" - find slack messaging tools'
' - Returns up to 5 matching tools ranked by relevance'
' - All returned tools are immediately available to call — no further selection step needed'
'2. **Direct selection** - Use `select:<tool_name>` when you know the exact tool name:'
' - "select:mcp__slack__read_channel"'
' - "select:NotebookEdit"'
' - "select:Read,Edit,Grep" - load multiple tools at once with comma separation'
' - Returns the named tool(s) if they exist'
'**IMPORTANT:** Both modes load tools equally. Do NOT follow up a keyword search with `select:` calls for tools already returned — they are already loaded.'
'3. **Required keyword** - Prefix with `+` to require a match:'
' - "+linear create issue" - only tools from "linear", ranked by "create"/"issue"'
' - "+slack send" - only "slack" tools, ranked by "send"'
' - Useful when you know the service name but not the exact tool'
'**CORRECT Usage Patterns:**'
'<example>'
'User: I need to work with slack somehow'
'Assistant: Let me search for slack tools.'
'[Calls ToolSearch with query: "slack"]'
'Assistant: Found several options including mcp__slack__read_channel.'
'[Calls mcp__slack__read_channel directly — it was loaded by the keyword search]'
'</example>'
'<example>'
'User: Edit the Jupyter notebook'
'Assistant: Let me load the notebook editing tool.'
'[Calls ToolSearch with query: "select:NotebookEdit"]'
'[Calls NotebookEdit]'
'</example>'
'<example>'
'User: List files in the src directory'
'Assistant: I can see mcp__filesystem__list_directory in the available tools. Let me select it.'
'[Calls ToolSearch with query: "select:mcp__filesystem__list_directory"]'
'[Calls the tool]'
'</example>'
'**INCORRECT Usage Patterns - NEVER DO THESE:**'
'<bad-example>'
'User: Read my slack messages'
'Assistant: [Directly calls mcp__slack__read_channel without loading it first]'
'WRONG - You must load the tool FIRST using this tool'
'</bad-example>'
'<bad-example>'
'Assistant: [Calls ToolSearch with query: "slack", gets back mcp__slack__read_channel]'
'Assistant: [Calls ToolSearch with query: "select:mcp__slack__read_channel"]'
'WRONG - The keyword search already loaded the tool. The select call is redundant.'
'</bad-example>',
- 延遲載入的 tools 列表
{
role: 'user',
content: [
{
type: 'text',
text: '<available-deferred-tools>'
'Agent'
'AskUserQuestion'
'Bash'
'Edit'
'EnterPlanMode'
'EnterWorktree'
'ExitPlanMode'
'Glob'
'Grep'
'NotebookEdit'
'Read'
'SendMessage'
'Skill'
'TaskOutput'
'TaskStop'
'TeamCreate'
'TeamDelete'
'TodoWrite'
'Write'
'</available-deferred-tools>',
cache_control: {
type: 'ephemeral'
}
}
]
}
# 這就是慎選 agent harness 的好處
- 它是你每天長時間打交道也攸關成敗最重要的工具
- 講穿了就是 AI 基礎建設(loop, tools, subagents...etc)
- claude code `v2.1.69` 這次的大改版就是個例子
- 你啥都不用做效能就提升 4x！
- 這就是一開始慎選 agent harness 的優點
- 人家估值幾百個 Billion 的公司會請全球精英工程師拼命改良 harness
- 你天天坐享其成、直接收割就好，豈不賺爛？😍
- 當然 agent harness 博大精深水超深但這次就先下略三萬字囉~
- `/config`
- reduce motion: true
- 減少畫面跳動與捲動後畫面錯亂問題
- prompt suggestion: false
- 無用的廢材功能，通常它建議的下一步也都是錯的
- verbose output: true
- 能清楚看到每個 tool call 的請求與結果
- default permission mode: Bypass Permission
- 降低跑到一半中斷的機率(有用但不是萬能)
- `/model`
- 選擇預設要用的模型(一般 sonnet 就夠，沒事別上 opus)
- `左/右鍵`設定 `effort` 為 `medium` 就好
- 除了省錢外也會跑的比較快(因為想的少，反應速度就加快)
- 用英文！English Only！
- 18 個月來經多次測試已驗証用英文提問得到的效果最好
- 就算你是菜英文只要在提示後方加上 `in english` 兩字效果也會改善
- 另個變通方式是先用中文提問，再請它譯成英文(`answer in En`)
- 絕不要自己寫 prompt
- 因為你絕不會比 LLM 它本人還懂 LLM 的運作原理
- 跟 AI 說你想做的事，請它寫幾份 prompt 做參考
- 只要能清楚解釋你的意圖、背景與考量，通常 AI 都能一次到位
- 當然別忘了也要叫它寫成英文版本
- 2026/Mar 發現 claude 4.6 寫的最好 ← 用 web 版就能免費玩
- 不像 gemini 3 pro 長篇大論像上市公司財報
- 也不像 gpt 5.4 傾向過度精簡或鑽牛角尖
- context 是神聖寶貴的稀有資源，每一滴都要省著用！
- claude 一般上限是 200K，超過要加錢才能變 1M
- 市面上常見的文章通 99% 都是與最佳化 context 有關
- 這就是為何 context engineering 極為重要的原因
- 關鍵字：attention drift, context rot
- 總之要將它當成你`最新的好朋友`密切關心它身心靈一切狀態！
1. shell
- Agent 超會用 shell 指令(glob, grep, awk, sed...百百種工具可用)
- 能用 bash/zsh 做到的事通常效能最好
- 有人甚至說 80% 的 RAG 都能用 glob/grep 取代
2. fs
- 資料外部化最重要的關鍵
- plan, todolist, progress, log 一律存硬碟
- 講穿了就是儲存 single source of truth
3. scripting
- Agent 超會寫程式(不然 vibe coding 怎會成為顯學) 因此何不讓它發揮長才？
- 現在主流做法是盡量叫 AI 自己在外部寫程式與執行，只返還最終結果
- 如此做最大好處是避免污染主線程
- 例如原本要讀三份 md 內的`結論`部份並摘要
- 原本做法是將三份 md 全讀入後再生成摘要
- 這樣做會立即佔用大量 context 也造成 LLM 注意力渙散(attention drift)
- 新做法是叫 AI 寫支 js 去做事
- js 先從三份 md 裏挖出`結論`部份並組合為一個字串
- 再將此字串返還給 LLM 做最終處理
- 如此一來 LLM 要處理的資料變少、context 也沒被污染
- 更棒的是效率也更高而且更省錢(因為使用的 tokens 減少了)
4. subagents
- 擁有獨立 context 可視為免洗工具避免污染 context
- 附帶好處是可平行運算做事更有效率
- 提示：`use subagent to summarize /tmp/foo.md`
→ 綜合應用上開四秘技效果更好
- 例如上例可要求指派一個 subagent 去寫程式與摘要
- 只要將最終結果返還`主線程`就好
- 如此一來`主線程`的 context 完全不會被污染，只拿到最終結果
- 另一招是如果你有幾百份 md 要做類似處理
- 可以派多個 subagent 寫 js 做事
- 但每支 js 處理完的結果先存入硬碟而不直接返還`主線程`
- 例如分別存成一堆 summary.01.md, summary.02.md...
- 等`主線程`有需要時再用 `glob/grep` 去查詢 summary.NN.md 撈出相關的內容來用
→ 關鍵心法
- 除了在 CLAUDE.md 內明確指示 Agent 要善用這四項超能力外
- 你也要隨時在心中謹記不斷提醒 agent 要這樣做事
→ 總之大原則就是：盡一切可能避免`主線程`寶貴的 context 被污染，能不用就不用啦！
/* agentic engineering 三部曲 -------------------------------------------------- */
→ 如果只會許願然後希望奇蹟發生，那叫 vibe coding / 吃角子老虎
→ 如果懂`許願 → 監工 → 驗收`完整套路那就叫 agentic engineering
- `我們不一樣.jpg`梗圖~🫢
- 需求訪談
- 組隊進行題目背景調查
- 寫出 spec draft
- 快速寫 prototype 驗証可行性與潛在問題(quick pilot run)
- 修正 spec final
→ 詳情看下面`Agent 開發三層次`各有不同實作手法
# 觀察過程中呼叫的工具與操作結果，發現不對就立即中止
- 前提是人需坐在電腦前當保姆
# claude code 不中斷大法
- permission mode
- "defaultMode": "bypassPermissions"
- 設定 `bypassPermissions` 等同於啟動時下參數 `--dangerously-skip-permissions`
- "skipDangerousModePermissionPrompt": true
- 盡量減少提問以避免中斷流程
- 禁用 "ExitPlanMode", "AskUserQuestion"
- 這兩個是最常導致中斷的原兇
- 啟用 ralph-loop plugin
https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum
- `--enable-auto-mode`
↑ 即將推出的新參數，據說可減少九成以上的中斷問題
# claude remote
- 最新推出的遠端遙控大法
- 等於綁尿袋可從外面隨時連回家看進度與操作
# 學 amazon 先寫`行銷文件`與`操作手冊`
- 用`行銷文件`確認需求是否已想清楚、產品規畫是否完整且符合市場所需
- 用`使用手冊`確認程式功能是否完整、成品是否真的好用也實用
- 例子一：pattern_matcher
- 寫完 spec 後要求先寫出 usages guide
- 也就是假裝程式已寫好並開始寫操作手冊
- 讓我能觀察最終 matcher 的語法與參數是否好用
- 以及有無覆蓋我所有的查詢需求
→ 通常這個階段就會發現許多問題而回頭去改 spec
- 例子二：usage guide 成為驗收標準的一部份
- 上開 usages guide 可叫 agent 寫成 test cases
- 並且這些 test cases 是另外保存不讓 coding agent 知道(所謂的 hold-out set)
- 等 coding agent 完工後再用這些 test cases 去驗收成品，如果全通過就代表程式真的可靠
# retro 與 review 不一樣
- retro 是寫完扣趁 context 還沒消失前先 self-review
- 也就是以`第一人`視角檢討開發過程中的缺失
- review 是寫完程式且測試皆通過後才進行
- 也就是以`第三人`視角由外部進行客觀審視
- review 部份看 superpowers 的提示就能學到很多寫法
- retro 可用的提示
`now that you have wrote the code, looking back at the process what did you do wrong or right? If we were to start all over again, what would you do differently to make it better?`
- 叫它檢討完後立即修正所有錯誤，這招往往可大幅改善程式品質，也減少之後 review 的工作量
# 不能盡信 test case
- agent 有時會寫出一堆無用的測試，表面上看數量很多，但裏面都不是在測關鍵`成功`與`失敗`劇情
- agent 也常作弊寫無腦的 assert(true) 只為了讓測試通過
- 有時甚至會直接刪除一直失敗的 test case
- 最糟的是 agent 可能修改測試內容以符合程式實際產出的結果
- 例如 add(1, 2) 的測試結果應是 assert.ok(add(1, 2), 3)
- 今天如果因為某些原因導致 add(1,2) 的 result = 4
- agent 理論上去修正 add() 程式的邏輯，它可能直接改掉 test 變成：
assert.ok(add(1, 2), 4)
→ 大原則：`Trust No One`
# 每階段皆自評 quality_score 做為 `eval` 標準
# 完美的驗收其實是多層次組合共同努力的結果
- 從`許願`階段就要開始發功，透過各種手段在最早期就確保 spec 正確且符合需求
- `監工`過程也很重要，如果發現 agent 需不斷中停來提問，通常就暗示規畫上有問題
- 最終`驗收`時則靠 `hold-out set` 與 `trust no one` 兩大秘技把關
/* Agent 開發三層次 -------------------------------------------------- */
- 用 claude code 內建的 plan mode + tasklist 工具
- 範例
`
write a fn and test for js string reverser
must enter plan mode to make a plan, create todolist to track them,
then start working.
`
- 結果
- 建立 plan： `~/.claude/plans/fluttering-hopping-engelbart.md`
- 建立 tasklist：`~/.claude/tasks/0f9370b2-2183-4da0-aa4a-0eefcfd530c0`
- 共四份 json
- tasklist 前身為 todolist
- 優點
- 60% 的輕量工作可用這招無腦解決
- 缺點
- agent 常做到一半忘了自己的 plan 與曾經建過 tasklist
- 下場是可能多次重建 plan 並重複做事
- 最糟的是根本沒更新 tasklist 內每張票的狀態
- 因此如果中間當掉就不知做到哪
- 更別提下次能從中斷的地方接著做下去
- `/resume` 與 `/continue` 也救不回來 (別問我為何知道)
- 基本步驟包含：
- `需求訪談`
- `規格撰寫`
- `切票細節`
- `實作規範`
→ 但最重要的是寫扣時會嚴格要求採`紅-綠-重構`循環
- 此工法主流代表是 `superpowers`
- https://github.com/obra/superpowers
- 上開基本開發步驟皆已內建
- 無腦依序操作它提供的的 `/brainstorm, /write-plan, /exectute-plan` 就好
- 優點
- prompt 寫的極佳，大部份該想到的事它皆已內建
- 只要安裝完 plugin 就會自動啟用多份 command, skills 與 hooks 非常方便
- 取代 claude code 內建的 enterPlanMode 與 tasklist
- 理由同樣是內建的那套不可靠常會做到一半忘記
- 也無法維護一份 external single truth
- 80% 的工作可用這招解決
- 缺點
- 流程控管是靠寫在 prompt 內的 graphviz 流程圖
- https://x.com/thecat88tw/status/2021835156328464895
- https://x.com/thecat88tw/status/2022074329987797047
- 這等於是要求總是隨機變化的 LLM 控管不可變的狀態機
- 這本質上有所衝突也不可靠
- SDD 為基礎的 end-to-end Agentic Workflow
- 開工前先用自然語言定義好所有開發文件
- 常見主流功能(包含但不限於)：
- Specs as first-class artifacts (stored in repo)
- Structured requirements (stories + acceptance criteria)
- Plan generation from specs
- Task decomposition
- Traceability (spec → task → code)
- Automated or guided implementation
- Test generation/validation from specs
- Versioning of specs and plans
- 知名品牌
- github spec-kit
- https://github.com/github/spec-kit/blob/main/spec-driven.md
- openspec
- https://github.com/Fission-AI/OpenSpec
- kiro
- https://aws.amazon.com/documentation-overview/kiro/
- 優點
- 重度 `human-in-the-loop` 由人類主導設計與驗收因此較可掌控品質與結果
- 95% 的工作能靠這招安全實作
- 缺點
- 通常會產生巨量文件讀起來耗時費力最後可能無腦同意
- 過程中耗用大量 tokens 算是極為昂貴的工法
- 既使層層把關，最終仍可能做歪或出錯
→ 極吃主導者(也就是人類)的品味與能力
- 如果本身不懂技術與需求控管，就只能被 AI 牽著鼻子走
- 也無法在早期發現規畫上的問題導致做錯東西
- 更慘的是等出錯後也無法察覺或人工修復
- 避免 `手上有了鎚子，所有東西看起來都像釘子` 心態
- SDD 雖然強大但不見得適用所有場合
- 凡事可先用`層次一`叫 claude code 快速試做一下觀察結果，搞不好就完事了？
- 但通常甜蜜點會落在`層次二/TDD`
- 僅記不要過度規畫、但絕對要人工嚴密監看產出的文件(plan, spec, todolist...)
- 發現不對勁就要早期制止與修正，否則無腦跑下去只會浪費時間與錢錢
/* 同場加映小秘技 -------------------------------------------------- */
- 程式誰來寫都一樣、魔改多少次也沒差
- 只在意最終`產出結果`正確，也就是`驗收有過`就好！
- 絕不要信任內建的 plan 與 todolist，因為 agent 常跑到一半就忘掉
- 仿效 superpowers 改用自己的外部 plan/todolist 最可靠
- 例如用了 superpowers 即可關掉 `enterPlanMode`, `taskCreate`...等五六支工具
- 用不到 python 的話連 `NotebookEdit` 也關掉
- 因為 context 容量有限，當它一變大，agent 就錯亂
- 因此最佳策略是輕量找機會讓 context 重置(也就是清空重來)
- 基本原理：工作切割成小塊以縮短 context 重置的生命週期
- 實際做法：每小段工作完成即存檔，然後 `/clear` 重置 context 再進行下個工作
- 以`code review`為例
- 原本會一口氣叫它`code review 完修正所有錯誤`
- 但這樣等於一次做三件事：
1. 進行 review 找出錯誤
2. 針對所有錯誤規畫如何修復
3. 真正進行修復
- 當工作內容單純時，確實有可能就一口氣做完
- 但當工作內容複雜時，agent 就可能做到一半錯亂而掛一漏萬
- 理想的解法是拆成三件工作：
1. 專心進行 review 並寫出 `review.md`
2. 讀取 review.md 規畫如何修復並寫出 `plan.md`
3. 讀取 plan.md 依其指示進行修復並寫出最終 `report.md`
→ 上開三步可由不同 subagent 接續進行
- 因此每一步皆由乾淨的 context 開始
- 且每步皆能專心做好一件事而不分心
- 如此可大幅改善品質也提升效率(因為少出錯就不需多次重試)
author: Jeremy Lu jlu@twmug.com All Rights Reserved, No Commercial Use allowed.