--- title: "Claude Code Rules·Skills·Agents 實戰指南" locale: zh-hant category: tutorial category_name: "教學課程" translation_status: reviewed license: cc_by author: "injoys" source_url: https://injoys.com/en/articles/claude-code-rules-skills-agents-guide published_at: 2026-08-19T16:14:05+09:00 --- # Claude Code Rules·Skills·Agents 實戰指南 > Claude Code 的 Rules、Skills、Agents 分別負責持續性指示、可重複使用的程序，以及隔離式任務委派。本指南透過實戰範例，說明正確的檔案結構與呼叫方式，以及安全和情境管理原則。 ## Key Points - 在專案根目錄建立 `.claude` 目錄，並區分共用設定與個人設定的適用範圍。 - 將必須始終遵守的準則分別寫入 `.claude/rules` 的 Markdown 檔案，並視需要限制適用路徑。 - 將重複執行的程序寫入 `.claude/skills/<名稱>/SKILL.md`，並設定自動或明確呼叫方式。 - 將需要獨立情境與角色的任務，委派給 `.claude/agents/<名稱>.md` 子代理程式。 - 先以小型驗證任務確認載入、工具權限與結果品質，再套用至團隊儲存庫。 Claude Code 的擴充功能並非都是同一類型的提示詞。**Rules 是持續套用的指引**、**Skills 是可重複使用的工作流程**、**Agents 是在獨立上下文中工作的角色型執行者**。準確區分這三項功能，就能減少重複輸入提示詞，同時有效管理主要對話的上下文。 本文以專案層級的設定為基準進行說明。Claude Code 支援的中繼資料或畫面可能因版本而異，因此若有欄位無法運作，應至已安裝版本的官方文件中再次確認。 ## 第 1 步：決定 `.claude` 目錄與設定範圍 專案中要共用的 Rules、Skills、Agents，通常會放在儲存庫根目錄的 `.claude` 下。 ```text my-project/ ├── .claude/ │ ├── rules/ │ │ ├── code-style.md │ │ └── api.md │ ├── skills/ │ │ └── fix-issue/ │ │ └── SKILL.md │ └── agents/ │ ├── code-reviewer.md │ └── test-runner.md ├── src/ └── package.json ``` 可以使用以下方式建立目錄。 ```bash mkdir -p .claude/rules mkdir -p .claude/skills/fix-issue mkdir -p .claude/agents ``` ### 關於 `.claude` 的兩項誤解 1. Claude Code 的所有指引並非都必須使用 `.claude`。專案指引也可透過根目錄的 `CLAUDE.md` 或 `.claude/CLAUDE.md` 管理，而使用者個人設定則可放在家目錄的 `~/.claude` 下。 2. 檔名是否區分大小寫取決於作業系統。為符合官方格式，Skill 的進入點檔案最好使用大寫的 `SKILL.md`。若儲存為 `skill.md`，可能無法被辨識。 ### 專案設定與個人設定的選擇標準 | 範圍 | 適合的內容 | 範例 | |---|---|---| | 專案共用 | 所有貢獻者都必須同樣遵循的規則與自動化 | 測試命令、目錄結構、API 規範 | | 使用者個人 | 個人偏好或不應公開至儲存庫的設定 | 個人工作方式、本機工具選擇 | | 僅限本機 | 只在特定電腦上有效的路徑或實驗性設定 | 本機資料路徑、臨時偵錯流程 | 只有團隊會共同使用的檔案才提交至 Git。不要將祕密金鑰、權杖、內部伺服器密碼記錄在 Rules 或 Skills 中。 ## 第 2 步：使用 Rules 建立持續性指引 Rules 是將 Claude 工作時應參考的專案指引，拆分成多個 Markdown 檔案進行管理的功能。`.claude/rules` 下沒有 `paths` 條件的規則檔案會載入為專案指引，而指定路徑條件的檔案則會在處理相關檔案時套用。 ### 基本 Rule 範例 可以如下編寫 `.claude/rules/code-style.md`。 ```markdown # 程式碼撰寫原則 - 新的應用程式程式碼使用 TypeScript 撰寫。 - 公開函式須說明輸入值、回傳值與失敗條件。 - 不得透過刪除既有測試來掩蓋失敗。 - 變更後執行相關測試與型別檢查。 - 說明使用韓文撰寫，但程式碼識別字應遵循既有命名規則。 ``` 好的 Rule 應該能夠驗證。比起「把程式碼寫得漂亮」，「變更後執行 `npm test` 與 `npm run typecheck`」更加明確。 ### 僅套用至特定路徑的 Rule 如果前端與後端的規則不同，可以透過 YAML front matter 的 `paths` 縮小適用範圍。 ```markdown --- paths: - "src/api/**/*.ts" - "tests/api/**/*.ts" --- # API 規則 - 所有 API 輸入都必須透過結構描述進行驗證。 - 將驗證失敗與權限不足視為不同的錯誤處理。 - 變更端點時，也要更新對應的 API 測試。 ``` 依路徑套用規則，可以減少不必要的指引占用所有工作上下文的問題。 ### 不應放入 Rules 的內容 - 只執行一次的遷移流程 - 僅特定議題需要的詳細需求 - 彼此衝突的絕對指示 - 冗長重複已由程式碼或 linter 設定強制執行的內容 - 密碼、API 金鑰、客戶資訊等敏感資料 Rules 並不是「保證無條件遵循的魔法裝置」。若指引含糊或彼此衝突，結果可能有所不同，因此必須搭配測試、linter、權限控管等確定性的驗證手段。 ## 第 3 步：使用 Skills 自動化重複流程 Skill 將說明、工作流程、所需工具與輔助資料整合成一個可重複使用的單位。專案 Skill 的基本結構為 `.claude/skills//SKILL.md`，必要時也可在同一目錄加入範本或指令碼。 與 Rules 不同，Skill 會在特定工作需要時使用。Claude 可以根據 Skill 的說明自動選擇，也可以由使用者以 `/` 格式明確呼叫。它並非只能手動執行。 ### 修正議題的 Skill 範例 `.claude/skills/fix-issue/SKILL.md` 的範例如下。 ```markdown --- name: fix-issue description: 重現錯誤並縮小原因範圍，接著進行最小幅度的修正與迴歸測試。 disable-model-invocation: true allowed-tools: Read, Grep, Glob, Edit, Bash(npm test:*) --- # 議題修正流程 目標議題：$ARGUMENTS 1. 調查相關程式碼與既有測試。 2. 修正前整理重現方法與預期行為。 3. 以一個段落說明根本原因。 4. 套用影響範圍最小的修正。 5. 新增迴歸測試，或確認既有測試能否驗證該問題。 6. 執行允許的測試並摘要結果。 7. 回報變更檔案、剩餘風險與手動確認項目。 ``` 可以如下呼叫此 Skill。 ```text /fix-issue 登入後個人資料照片未更新的問題 ``` 當需要限制 Claude 不得自行執行此 Skill，而必須由使用者直接呼叫時，`disable-model-invocation: true` 很有用。支援的 front matter 欄位可能因 Claude Code 版本而異。 ### 設計優先的 Skill 範例 若希望先建立設計文件，而不是立即撰寫程式碼，可以將以下流程放入 Skill。 1. 區分需求與含糊不清的部分。 2. 調查既有結構與可重複使用的模組。 3. 設計資料流、介面與失敗條件。 4. 在 `docs/design/` 下撰寫設計文件。 5. 確認使用者批准或明確指定的批准條件後再實作。 6. 提出測試與回復方法。 ### 良好 Skill 的條件 - 輸入與最終產出明確。 - 明確指定流程順序與中止條件。 - 僅允許必要工具。 - 將冗長的參考資料拆分為獨立檔案。 - 失敗時不應自行繼續，而應進行回報。 - 單一 Skill 不應具有過多目的。 像是建立提交、程式碼審查、發布檢查、API 設計等會重複發生且起點與終點明確的工作，都適合使用 Skill。 ## 第 4 步：使用 Agents 分離角色與上下文 Claude Code 的子代理程式會在獨立上下文中執行特定角色，並將結果傳回主要對話。當不希望大量搜尋結果或測試記錄全都累積在主要上下文中時，這項功能很有用。 專案代理程式通常定義於 `.claude/agents/.md`。可以透過 `/agents` 命令確認或管理代理程式，也可以用自然語言要求將工作委派給特定代理程式。 ### 程式碼審查代理程式範例 可以如下編寫 `.claude/agents/code-reviewer.md`。 ```markdown --- name: code-reviewer description: 以唯讀為主，審查已變更程式碼中的缺陷、安全風險與測試缺漏 tools: Read, Grep, Glob, Bash model: sonnet --- 你是專門負責程式碼審查的代理程式。 依照以下優先順序進行審查。 1. 可能造成實際故障或資料遺失的缺陷 2. 與驗證、權限、輸入驗證有關的安全問題 3. 並行處理、交易與錯誤處理問題 4. 無法驗證需求的測試缺漏 5. 大幅降低可維護性的結構 每項發現都須包含檔案路徑、依據、發生條件與最低限度的修正方向。 不要將沒有依據的風格偏好回報為缺陷。 不要直接修改程式碼，只回傳審查結果。 ``` 可以如下提出要求。 ```text 請讓 code-reviewer 代理程式審查目前分支的變更。 ``` ### Skill 與 Agent 的差異 | 標準 | Rules | Skills | Agents | |---|---|---|---| | 核心目的 | 提供持續性指引 | 重複使用反覆執行的流程 | 委派各角色的工作 | | 套用時機 | 一律套用或依路徑條件套用 | 自動選擇或明確呼叫 | Claude 委派或使用者要求 | | 上下文 | 作為指引包含在主要工作中 | 主要在目前工作流程中執行 | 在獨立上下文中執行後回傳結果 | | 代表範例 | 程式設計標準 | 議題修正流程 | 程式碼審查員 | | 儲存位置 | `.claude/rules/*.md` | `.claude/skills/<名稱>/SKILL.md` | `.claude/agents/*.md` | ### Agents 與 Agent Teams 並不相同 一般子代理程式使用獨立上下文，並不代表代理程式之間能夠自由對話。一般的子代理程式是執行受委派的工作，再將結果傳回主要代理程式的委派架構。多個獨立工作階段彼此收發訊息的 Agent Teams 是另一項功能，必須至官方文件確認其支援狀態與啟用條件。 如果在設計工作流程時，預設代理程式會持續連鎖建立其他代理程式，可能因版本或權限限制而失敗。較安全的做法是先從簡單的架構開始，由主要代理程式將工作分配給各角色的子代理程式，再彙整結果。 ## 第 5 步：驗證載入、權限與品質 不要因為建立了設定檔，就假設它會按照預期運作。應透過小型工作分別驗證各個元件。 ### 建議的驗證順序 1. **確認 Rules：** 分別要求處理會套用規則與不會套用規則的檔案，以確認路徑條件。 2. **確認 Skills：** 明確呼叫 Skill，查看輸入引數、產出與中止條件是否正常運作。 3. **確認 Agents：** 委派唯讀審查等風險較低的工作，並檢查結果格式。 4. **確認權限：** 檢查 Bash、Edit 等可進行變更的工具，是否僅授予真正需要的設定。 5. **自動驗證：** 透過測試、型別檢查、linter、安全檢查，獨立驗證 AI 的結果。 ### 失敗時應確認的項目 - `.claude` 是否位於實際的專案根目錄？ - Skill 檔名是否正確為 `SKILL.md`？ - Skill 是否位於 `.claude/skills/<名稱>/SKILL.md` 結構中？ - Agent 檔案是否為直接位於 `.claude/agents` 下的 Markdown 檔案？ - YAML front matter 的開頭與結尾是否都使用 `---` 關閉？ - `name` 與 `description` 是否具體到足以區分工作？ - 路徑模式是否符合實際專案結構？ - 已安裝的 Claude Code 版本是否支援所使用的中繼資料？ - 工具權限或組織政策是否正在阻擋執行？ ## 必須一併設計上下文預算與安全性的原因 Rules、Skills、Agents 的目的不只是新增功能。它們也是控制何時將哪些資訊放入上下文的**上下文工程手段**。 如果規則過於冗長，與目前工作無關的指引就會占用上下文，發生衝突的可能性也會提高。相反地，若將探索與記錄分析交給子代理程式，主要對話中就可以只保留結論與依據。 在安全性方面，以下原則很重要。 - Rules 與 Skills 也要像儲存庫中的其他程式碼一樣接受審查。 - 執行來自外部的 Agent 或 Skill 檔案前，先閱讀其內容。 - 將 shell 命令、網路存取與檔案修改權限降至最低。 - 不要無條件信任使用者輸入或議題本文中包含的命令。 - 部署、刪除、付款與資料遷移都應加入人工批准步驟。 - 不要將祕密資訊儲存在提示詞檔案中，應使用獨立的祕密管理系統。 ## 應該選擇哪項功能 可以透過以下問題快速決定。 - 所有相關工作都必須遵循嗎？→ **Rule** - 是一項有起點與終點的重複流程嗎？→ **Skill** - 需要獨立角色與獨立上下文嗎？→ **Agent** - 必須在特定事件前後執行確定性的命令嗎？→ **考慮 Hook** 例如，「使用 TypeScript」屬於 Rule，「從重現錯誤到執行迴歸測試」屬於 Skill。「讀取變更內容並只回報安全缺陷」則適合使用 Agent。像是編輯檔案後必須執行格式化工具等與特定事件連動的行為，可能更適合使用 Hooks。 最穩定的設定方式，不是將這三項功能視為競爭關係，而是加以組合。使用 Rule 提供共同標準、透過 Skill 執行標準流程、利用 Agent 分離調查與審查等上下文較大的工作，再以測試和 Hooks 補充確定性的驗證。 ## FAQ ### 在 Claude Code 中，`.claude` 資料夾是必要的嗎？ 它用於以標準結構管理專案用的 Rules、Skills、Agents，但並非所有指示都一定需要它。專案指示也可以放在根目錄的 `CLAUDE.md` 或 `.claude/CLAUDE.md` 中，個人設定則可在 `~/.claude` 下管理。 ### Rules 和 `CLAUDE.md` 有什麼差異？ `CLAUDE.md` 適合以單一文件提供專案的核心指示。`.claude/rules` 有利於依主題拆分檔案及依路徑套用條件，因此隨著專案規模擴大，有助於將規則模組化。 ### Skill 的檔名是 `skill.md` 還是 `SKILL.md`？ 符合官方 Agent Skills 結構的進入點檔名是大寫的 `SKILL.md`。將專案 Skill 放在 `.claude/skills//SKILL.md` 較為穩妥，而在區分大小寫的作業系統中，`skill.md` 會被視為不同的檔案。 ### Claude Code Skill 只有在使用者呼叫時才會執行嗎？ 不一定。Claude 可以根據 Skill 的說明，在適合的工作中自動選用，使用者也可以透過 `/` 呼叫。如果需要防止自動呼叫，可以在支援的版本中檢視 `disable-model-invocation` 設定。 ### 應該使用 Skill 還是 Agent？ 若要在目前的工作流程中執行重複程序，Skill 較為合適。若像大量調查、測試分析、程式碼審查那樣，需要獨立角色與隔離的上下文，則 Agent 較為合適。像通用程式碼撰寫標準這類需要持續套用的內容，則應分離為 Rule。 ### 子代理程式之間可以直接對話或呼叫其他代理程式嗎？ 一般的 Claude Code 子代理程式會在獨立上下文中工作，之後將結果回傳給主代理程式。多個獨立工作階段的直接協作應與另一項 Agent Teams 功能加以區分，並且必須確認目前使用版本的支援狀態與限制。 ### 撰寫 Rules 後，Claude 就會始終完全遵守指示嗎？ 不會。Rules 是持續提供的指示，但並非決定性的強制機制。由於指示衝突或含糊不清，可能會有所遺漏，因此應搭配程式碼檢查工具、型別檢查、測試、Hooks 及程式碼審查使用。 ### 直接使用從外部取得的 Skill 或 Agent 安全嗎？ 建議不要直接執行。應先檢視檔案中包含的指示、Shell 命令、允許使用的工具、網路及檔案存取範圍，並以最低權限進行測試。也必須確認其中是否包含誘導傳送機密資訊或進行危險檔案變更的內容。 ## Sources - [Claude Code 文件：管理 Claude 的記憶](https://code.claude.com/docs/en/memory) - [Claude Code 文件：透過技能擴充 Claude](https://code.claude.com/docs/en/skills) - [Claude Code 文件：建立自訂子代理程式](https://code.claude.com/docs/en/sub-agents) - [Claude Code 文件：Claude Code 設定](https://code.claude.com/docs/en/settings) ## Images ![坐在書桌前查看筆電開發工作流程儀表板的人](https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6OTgyOSwicHVyIjoiYmxvYl9pZCJ9fQ==--8ba3d33d24232863ea1d744998bca1e2dbb088c6/ai-7c680af1.webp) ![連結資料夾、篩選器、自動化步驟、AI 工作區、安全與驗證的流程圖](https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6OTgzNSwicHVyIjoiYmxvYl9pZCJ9fQ==--458d876e5a3cb0d4581f0909c6198e47789eda8b/ai-54d6eb4e.webp)