Claude Code 代理開發三原則：地圖、強制、累積

我最近寫了一篇關於如何在我的個人專案應用程式中，為 Claude Code 設定一個「代理框架」（包含 CLAUDE.md、Hooks 和 Skills）的文章。那篇文章記錄了我實際建構的過程。

這次，我想退一步整理其背後的核心概念，也就是「代理框架工程」的三個原則，並以對照表的形式呈現：哪些 Claude Code 功能負責實現哪個原則。

這些原則本身源自 OpenAI 的一篇文章，我是透過一份日文摘要頁面（連結在文末的「參考資料」中）了解到的。請注意，我只閱讀了參考頁面的第一部分（原則表、提示詞結構以及 CLAUDE.md 指南的開頭），因此我在此的詮釋部分結合了我自己的實踐經驗。

將三個原則對應到 Claude Code 功能：

原則：① 提供地圖，而非手冊

一句話：教導大局觀和查找方向，僅此而已。

Claude Code 功能：CLAUDE.md（搭配 docs/ 資料夾）

原則：② 強制不變性，而非規定實作

一句話：僅機械性地防範那些一旦違反就會造成事故的規則。

Claude Code 功能：Hooks

原則：③ 將缺失的能力編碼化

一句話：將每個失敗的程序轉化為資產。

Claude Code 功能：Skills

將其歸納為這三行後，很明顯每個原則都扮演著截然不同的角色。接下來我們將逐一探討。

人們常會想把整本手冊都交出去。然而，冗長的手冊會消耗上下文，而最重要的內容往往會被跳過。

「地圖」原則指出：將 CLAUDE.md 保持在 200 行以內的指引，把詳細內容推到 docs/ 資料夾中，並讓代理程式在需要時自行追蹤連結。

建議的結構分為五個部分，其中專案概覽應放在最前面：

CLAUDE.md (骨架)

1. 專案概覽 <- 永遠放在最前面

2. 技術棧與常用指令

3. 不變性（違反將被 Hooks 阻擋）

4. 建議慣例（可恢復的錯誤）

5. 查找位置（詳細內容位於 docs/）

在我的專案中，遵循這項政策讓 CLAUDE.md 縮減到 48 行。預設的做法變成了「移至 docs/」，而不是「再加一行」。

自然語言指令本質上都是「請」求，它們被遵循的機率性較高。然而，像讀取 .env 檔案或直接編輯原生目錄這類事故，即使只發生一次也是不可接受的。

因此，這項原則指出：僅使用 PreToolUse Hook（exit 2）機械性地阻擋那些一旦違反就會造成事故的行為，而將其他所有內容作為「建議」保留在 CLAUDE.md 中。

另一個同樣重要的方向是：不要使用 Hooks 和規則來限制實作方式。過度限制手段會阻礙模型自身的解決方案工具箱。守護條件，委託實作。

具體的 Hook 設定以及我如何測試它，都記錄在我之前的文章中，這裡就不再贅述。

第三個原則是最不引人注目，卻也最有效。每當某個步驟失敗時，就將正確的程序寫成一個 Skill。從此以後，你只需呼叫它，就不會再在同一個步驟上跌倒。

---

名稱：new-screen

描述：新增畫面的步驟

---

1. 在 app/ 下建立 expo-router 路由檔案

2. 將畫面元件放在 components/screens/ 下

3. 新增後執行型別檢查和測試

每一個 Skill 都是一個小備忘錄，但專案運行時間越長，「扶手就會精準地出現在你跌倒的地方」，因此效果會不斷累積。

一旦你心中有了這張對照表，新專案的啟動方式就會改變。我現在的第一個提示詞是生成代理框架結構，而不是應用程式本身：

為這個儲存庫設定一個 Claude Code 代理框架。

1. CLAUDE.md（200 行以內，5 個部分，專案概覽優先）

2. .claude/hooks/ 下的 PreToolUse Hooks，用於保護不變性（例如保護 .env 檔案）

3. .claude/skills/ 下的 /commit 和 /review 的 Skill 骨架

將詳細文件拆分到 docs/ 中。

當進入應用程式實作階段時，我會預先說明設計和驗證條件，例如：「單色配色方案」、「不使用表情符號作為裝飾」、「實作後務必執行 lint → 型別檢查 → 測試的驗證循環」。

將這些作為初始條件提供，遠比之後來回溝通「這看起來像是 AI 生成的，請修正」要快得多。另一方面，資產和版面調整我則視為無法一次到位的事項，這些會透過迭代指令進行精修。

地圖 (CLAUDE.md)：200 行以內的指引。將詳細內容移至 docs/，並讓代理程式追蹤連結。

強制 (Hooks)：僅機械性地阻擋那些一旦違反就會造成事故的不變性。不要限制實作方式。

累積 (Skills)：每當某個步驟失敗時，就將程序記錄下來。效果會不斷累積。

透過這三個層次（地圖、強制、累積）的思考，你將獲得一個透過結構而非提示詞撰寫技巧來避免重複犯錯的開發環境。在精修提示詞之前，先檢查代理框架。這是我目前思考問題的順序。

參考資料：

關於 Claude Code 和代理框架工程的日文摘要頁面 (Notion)