「Agent 為什麼會這樣做？」——這個問題有兩個部分：它看到了什麼，以及它憑什麼去做。

Stage 2（Day 06-12）把 brain-cli 打造成一個毫秒級跑完全庫分析的核心工具，scan、capture、health 三個指令串起來也證明了在千篇筆記規模下依然夠快。但截至目前，這個工具只有人類在敲鍵盤呼叫。Stage 3（Day 13-19）要做的事，是讓 Claude Code Agent 也開始頻繁呼叫它——讀取知識庫狀態、判斷該執行哪個動作、甚至直接把結果寫回筆記。

在動手寫 CLAUDE.md 提示詞（Day14）、打造 /refine-inbox 這類 Agent 工作流指令（Day15 起）之前，有一個更基本的問題得先講清楚：Claude Code 到底是「怎麼讀懂一個專案」的？又是「怎麼決定要執行什麼動作」的？如果不先建立這兩個問題的共同答案，接下來六天的每一篇文章都會各自零散地解釋一次同樣的機制，讀者也很難判斷「Agent 為什麼會這樣做」——是因為它讀到了某個檔案，還是因為某個權限設定允許它這麼做。

今天不寫程式碼，也不碰 obsidian-agent-brain。這是一篇純概念文章，目標是建立 Stage 3 剩下六天要共用的詞彙表與心智模型。

Claude Code 怎麼「看到」一個專案

打開一個新對話，Claude Code 幾乎立刻就能講出這個專案的慣例、用什麼語言寫測試、有哪些既有的模組——這不是猜的，也不是模型本身「認識」這個專案，而是有一套具體的上下文建立機制在背後運作。

目錄結構的讀取：Claude Code 會依需要瀏覽專案的檔案與目錄結構——列出檔案清單、讀取特定檔案內容、搜尋關鍵字或符號。這件事本身沒有魔法，就是「讀檔案」這個動作，只是由 Agent 自己決定該讀哪些檔案，而不是把整個專案一次塞進上下文。

CLAUDE.md 的載入時機與作用範圍：這是最關鍵的一塊。CLAUDE.md 是一份會在對話啟動時被讀入專案上下文的說明文件，內容通常是這個專案的慣例、常用指令、架構取捨等等——寫在裡面的東西不需要每次對話重新提一次，Claude Code 一開始就知道。它的作用範圍分兩層：專案層級的 CLAUDE.md（放在專案目錄裡，只影響這個專案）與使用者層級的設定（跨專案生效，反映的是使用者個人的偏好，而不是某個專案的特性）。兩者疊加，但專案層級的內容通常更具體、更貼近「這個 repo 該怎麼做事」。

換句話說：「Claude Code 一開始就知道這個專案的程式碼慣例」這句話背後的答案很具體——因為 CLAUDE.md 在對話啟動時就被讀進上下文了，而不是模型對這個專案有什麼先天認識。

跨對話的記憶機制：換一個新對話後，Claude Code 有時還記得先前談過的某個決定或偏好——這也不是模型本身具備長期記憶。運作方式是：對話中值得保留的資訊，會在對話過程或結束後被持久化成某種形式的記錄；等到後續對話開始時，再依相關性把這些記錄回填進上下文。模型每次仍然是從「這次對話看到的上下文」出發做推論，差別只在於這次的上下文裡多了一些從過去對話回填回來的資訊。這個機制讓 Agent 的行為看起來有連續性，但底層仍然是「讀取」，不是「記得」。

Claude Code 怎麼「決定並執行」動作

看懂了專案之後，下一個問題是：Agent 怎麼決定要做什麼、又是怎麼真的做到的。

工具呼叫（tool use）迴圈：這是執行機制的核心，運作方式是一個簡單的迴圈——模型根據目前的上下文判斷「我需要呼叫某個工具才能繼續」，發出一次工具呼叫請求（例如讀檔案、寫檔案、執行 shell 指令），取得執行結果後，把結果併入上下文，再判斷下一步該做什麼：可能是呼叫下一個工具，也可能是直接回覆使用者。整個互動,就是這個迴圈反覆跑，直到 Agent 判斷任務完成。

權限模式如何介入這個迴圈：迴圈本身的結構不會變，但「工具呼叫請求發出之後，是不是要先讓使用者確認才能真正執行」這一步,會被權限模式左右。唯讀模式下,大部分會改動狀態的動作根本不會被允許執行；自動接受編輯模式下,像編輯檔案這類動作可以直接執行不用逐次確認；規劃模式則是連執行都先不做,只產出計畫給使用者過目。這也解釋了一個常見的疑問——「為什麼執行 shell 指令前會跳出確認,但讀取檔案不會」：不是工具呼叫迴圈對這兩種工具有不同的處理邏輯,而是權限模式對不同風險等級的動作,設下了不同的確認門檻。讀檔案通常不會造成不可逆的後果,執行任意 shell 指令則可能修改或刪除東西,風險等級不同,確認門檻自然不同。

把這兩塊放在一起看：工具呼叫迴圈決定「Agent 可以做哪些種類的事」,權限模式決定「這件事做之前需不需要先問過你」。兩者是分開的兩個維度,疊加起來才是使用者實際感受到的行為。

Agent、Skill、Workflow：三種擴展能力，解決三種不同形狀的問題

除了核心的工具呼叫機制,Claude Code 還有三種讓能力延伸出去的方式,常常被搞混,因為它們表面上都是「叫它做一件比較複雜的事」。但三者解決的問題形狀不一樣：

• Agent：適合一次性委派出去的開放式子任務——研究一個問題、探索一段陌生程式碼、獨立完成一個不需要精確控制內部步驟的實作。委派出去之後,你在意的是結果,不是它中間怎麼一步步做到的。
• Skill：適合一套已經想清楚、會重複用到的固定流程,包裝成一個可以直接呼叫的指令。它的價值在於把「已經知道該怎麼做」的事情變成可重複呼叫、不用每次重新描述一遍。
• Workflow：適合需要跨多個步驟、有明確依賴或並行結構的編排,而且這個編排本身要是決定性的——同樣的輸入,應該產生同樣的執行結構,不是每次跑出來的步驟順序都不一樣。

判斷該用哪一種,可以依序問三個問題:這是一個開放式、不需要精確控制過程的子任務嗎？如果是,交給 Agent。這是一套我已經想清楚、會重複用到的固定流程嗎？如果是,包裝成 Skill。這需要跨多步驟、有明確依賴或並行結構,而且流程本身需要是決定性的嗎？如果是,用 Workflow。

舉個例子:如果需求是「把雜亂的草稿筆記整理成結構化格式」——這通常是一套已經想清楚的固定流程（判斷筆記類型、補齊 Frontmatter、建立雙向連結),不需要每次臨場決定怎麼做,適合包裝成 Skill；但如果需求變成「先探索整個知識庫,找出所有可能值得重構的筆記結構問題,再逐一評估」,這是開放式、需要探索與判斷的子任務,適合交給 Agent；如果需求是「掃描 → 分類 → 依分類分別呼叫不同的整理邏輯 → 彙總報告」這種有明確依賴順序、且流程本身要每次都跑出一樣的步驟結構,就適合 Workflow。這個判斷依據,Day15（/refine-inbox）與 Day17（/new-adr）在決定該用哪種機制實作時會直接引用。

銜接 Day18：Agent 為什麼能呼叫 brain-cli

把上面兩段放在一起,其實已經能推導出 Day18 要做的事為什麼可行。

工具呼叫迴圈裡,其中一種工具就是「執行 shell 指令」——這件事在今天已經講過了,不是什麼額外的新機制。brain-cli 是一個既有的命令列工具,能被 shell 指令執行,而 Agent 本來就能在工具呼叫迴圈中發出「執行 shell 指令」的請求。把兩者接起來:Agent 透過 subprocess 呼叫 brain-cli 的 scan、capture、health,只是「執行 shell 指令」這個工具在某個權限模式下的一個具體案例——是不是需要使用者先確認,取決於當時的權限模式,不是取決於呼叫的目標是不是 brain-cli。

換句話說,Day18 不需要發明新的橋接機制,它做的事,是今天講的執行機制的一個應用實例。

銜接 Day14

今天講的是「CLAUDE.md 什麼時候被讀取、讀取之後如何影響 Agent 的行為」——這是機制層。明天 Day14 要講的是「CLAUDE.md 裡該寫什麼提示詞、怎麼寫才會讓 Agent 真的照著慣例做事」——這是內容層。兩者分開,是因為機制講清楚之後,提示詞工程才有地基可以站——不然每次討論怎麼寫 CLAUDE.md,都要先確認一次「這份檔案到底何時被讀進去、讀進去之後管不管用」。

👉 明天 Day 14,我們要動手寫真正的 CLAUDE.md,把今天講的機制,轉換成能讓 Agent 真的照著這個專案的慣例做事的提示詞工程。我們明天見！