Claude Cookbooks 是 Anthropic 官方維護的 Jupyter Notebook 範例集，涵蓋 Claude API 的各種進階用法——從 RAG、Tool Use 到 Agent Patterns。但真正值得深讀原始碼的不是那些 notebook 範例本身，而是這個倉庫如何用 Claude Code 的 slash commands、skills、agents 和 CI workflows 建立起一套「AI 驅動的品質治理系統」。讀完你會學到：如何用 CLAUDE.md 定義專案契約、如何用 registry + schema 管理內容目錄、如何讓 AI 在 CI pipeline 中當 reviewer，以及 Anthropic 內部的 notebook 教學設計方法論。
Claude Cookbooks GitHub Repository — 專案原始碼，包含本文解讀的所有設計實作
專案概覽
Claude Cookbooks 是一個包含 60+ Jupyter Notebook 的教學資源庫，主要以 Python 撰寫，依功能分為 capabilities、tool_use、patterns/agents、multimodal、skills、extended_thinking 等目錄。表面上看是一個文件集，但底層有完整的工程化基礎設施：JSON Schema 驗證的 registry、Claude Code 驅動的自動化審查、自訂 skill 系統、以及教學設計方法論（TLO/ELO 學習目標體系）。技術棧包括 Python 3.11+、uv 套件管理、Ruff linter、pre-commit hooks、GitHub Actions CI，以及 claude-code-action 整合。
架構總覽
claude-cookbooks/
├── .claude/ # Claude Code 整合層
│ ├── commands/ # Slash commands（CI 與本地共用）
│ │ ├── notebook-review.md # notebook 品質審查
│ │ ├── model-check.md # 模型版本驗證
│ │ ├── link-review.md # 連結品質檢查
│ │ ├── review-pr.md # PR 審查流程
│ │ └── add-registry.md # 新增 registry 條目
│ ├── agents/
│ │ └── code-reviewer.md # 代碼審查 agent 定義
│ └── skills/
│ └── cookbook-audit/ # Notebook 審計 skill
│ ├── SKILL.md # skill 入口定義
│ ├── style_guide.md # 教學設計指南
│ └── validate_notebook.py# 自動化驗證腳本
├── .github/
│ ├── workflows/ # CI pipeline
│ │ ├── claude-pr-review.yml # Claude 驅動的 PR 審查
│ │ ├── claude-model-check.yml # 模型版本自動檢查
│ │ ├── notebook-quality.yml # Notebook 品質閘門
│ │ └── ...
│ ├── registry_schema.json # Registry JSON Schema
│ └── authors_schema.json # Authors JSON Schema
├── patterns/agents/ # Agent 設計模式範例
│ ├── prompts/ # 分離的 prompt 檔案
│ └── util.py # 共用工具函式
├── claude_agent_sdk/ # Claude Agent SDK 範例
│ ├── research_agent/ # 研究代理
│ ├── chief_of_staff_agent/ # 多代理系統範例
│ └── observability_agent/ # 可觀測性代理
├── capabilities/ # 核心能力範例
├── tool_use/ # 工具使用範例
├── skills/ # Skills 功能範例
├── registry.yaml # 內容目錄（schema 驗證）
├── authors.yaml # 貢獻者資料
├── CLAUDE.md # 專案契約文件
└── CONTRIBUTING.md # 貢獻指南
Code language: PHP (php)核心設計解析
設計一：CLAUDE.md 作為專案契約——為 AI 協作者而寫的 README
Claude Cookbooks 的 CLAUDE.md 不只是給人類看的說明文件，它是為 Claude Code 這個 AI 協作者量身打造的「專案契約」。整份文件的設計意圖是：讓 AI 在進入倉庫時，立即理解開發規範、程式碼風格、可用命令，以及絕對不能做的事。
CLAUDE.md — 定義 Claude Code 在此倉庫中應遵守的專案契約
## Key Rules
1. **API Keys:** Never commit `.env` files. Always use `os.environ.get("ANTHROPIC_API_KEY")`
2. **Dependencies:** Use `uv add <package>` or `uv add --dev <package>`. Never edit pyproject.toml directly.
3. **Models:** Use current Claude models. Check docs.anthropic.com for latest versions.
- Sonnet: `claude-sonnet-4-5-20250929`
- Haiku: `claude-haiku-4-5-20251001`
- Opus: `claude-opus-4-5-20251101`
4. **Notebooks:**
- Keep outputs in notebooks (intentional for demonstration)
- One concept per notebook
- Test that notebooks run top-to-bottom without errors
Code language: CSS (css)設計亮點在於「明確列出模型版本」——這不是給人記的，而是讓 Claude Code 在生成或審查程式碼時，能直接比對是否使用了正確的模型名稱。Key Rules 的每一條都是可機器執行的約束，而非模糊的建議。同時注意 CLAUDE.md 也列出了所有 slash commands（/notebook-review、/model-check、/link-review），讓 Claude Code 知道自己有哪些能力可以調用。
設計二：Slash Commands 的 CI/本地雙用設計
這個倉庫最精巧的設計之一是：.claude/commands/ 中定義的 slash commands 同時服務兩個場景——開發者在本地使用 Claude Code 時可直接調用，GitHub Actions CI 也透過 claude-code-action 調用同一套命令。
.claude/commands/notebook-review.md — Notebook 品質審查命令定義
---
allowed-tools: Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(echo:*),Read,Glob,Grep,WebFetch
description: Comprehensive review of Jupyter notebooks and Python scripts
---
**IMPORTANT**: Only review the files explicitly listed in the prompt above. Do not search for or review additional files.
Review the specified Jupyter notebooks and Python scripts using the Notebook review skill.
Code language: PHP (php)注意 frontmatter 中的 allowed-tools 定義——這是一個安全邊界設計。每個 command 只被授予完成任務所需的最小工具集。例如 notebook-review 可以讀檔和搜尋，但不能寫入檔案；它可以用 gh pr comment 發表評論，但不能合併 PR。
.github/workflows/claude-pr-review.yml — CI 中調用 Claude Code 進行 PR 審查的 workflow
- name: Run Claude PR Review
uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
github_token: ${{ secrets.GITHUB_TOKEN }}
prompt: |
/review-pr-ci ${{ steps.pr-number.outputs.number }}
claude_args: |
--allowedTools "SlashCommand,Task,Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr review:*),Bash(git diff:*),Bash(git log:*),Read,Glob,Grep"
Code language: PHP (php)CI workflow 透過 prompt: /review-pr-ci 直接觸發 slash command，claude_args 再加上一層 allowed tools 限制。這意味著同一個審查邏輯，開發者在本地和 CI 中得到完全一致的體驗。
設計三：分層式 Code Reviewer Agent——從 Skill 到 Agent 的職責分離
倉庫定義了一個完整的代碼審查 agent，它的設計體現了清晰的職責分層：
.claude/agents/code-reviewer.md — 代碼審查 agent 的完整定義
---
name: code-reviewer
description: Performs thorough code reviews for the Notebooks in the Cookbook repo...
tools: Read, Grep, Glob, Bash, Bash(git status:*)
---
You are a senior software engineer specializing in code reviews for Anthropic's Cookbooks repo.
## SPECIFIC CHECKLIST
### Notebook Structure & Content
- **Introduction Quality**:
- Hooks with the problem being solved (not the machinery being built)
- Lists 2-4 Terminal Learning Objectives (TLOs) as bullet points
### Python & Code Style
- **Type Safety**: Explicit return types on functions, comprehensive type annotations
- **Modern Python**: Use `str | None` instead of `Optional[str]`
### CI/CD & GitHub Actions
- **Workflow Efficiency**:
- Only run on changed files where possible
- Restrict expensive workflows to internal contributors:
`if: github.event.pull_request.head.repo.full_name == github.repository`
這個 agent 定義了 300+ 行的審查清單，涵蓋 notebook 結構、Python 風格、安全性、CI 效率等面向。特別值得注意的是「Notebook Pedagogy」維度——它要求 introduction 必須「hooks with the problem being solved, not the machinery being built」，這是 Anthropic 內部的教學設計理念直接嵌入到了自動化審查流程中。
同時注意 agent 如何引用 skill：code-reviewer 會調用 cookbook-audit skill 中的 style_guide.md 和 validate_notebook.py，形成 agent -> skill -> script 的三層架構。
設計四：Registry + JSON Schema——內容目錄的結構化管理
倉庫用 registry.yaml + JSON Schema 建立了一套內容索引系統，每個 notebook 都是一筆有結構的記錄。
registry.yaml — 所有 cookbook 的結構化目錄
- title: Automatic context compaction
description: Manage context limits in long-running agentic workflows by automatically
compressing conversation history.
path: tool_use/automatic-context-compaction.ipynb
authors:
- PedramNavid
date: '2025-11-24'
categories:
- Tools
- Agent Patterns
Code language: JavaScript (javascript).github/registry_schema.json — 定義 registry 條目的 JSON Schema
{
"properties": {
"categories": {
"type": "array",
"items": {
"type": "string",
"enum": [
"Agent Patterns", "Claude Agent SDK", "Evals",
"Fine-Tuning", "Multimodal", "Integrations",
"Observability", "RAG & Retrieval", "Responses",
"Skills", "Thinking", "Tools"
]
},
"minItems": 1
}
},
"required": ["title", "path", "categories", "authors", "date"]
}
Code language: JSON / JSON with Comments (json)Schema 透過 enum 限定了分類詞彙表——只有 12 個預定義類別。這防止了分類混亂（例如有人寫「tool-use」、有人寫「ToolUse」）。加上 add-registry slash command，新增 notebook 時 Claude Code 會自動讀取 notebook 內容、生成符合 schema 的條目、檢查 authors.yaml 中的作者資訊。
設計五：教學設計方法論——TLO/ELO 學習目標體系
這個倉庫最獨特的設計不是程式碼，而是一套完整的教學設計方法論，被編碼到了 style_guide.md 和審查流程中。
.claude/skills/cookbook-audit/style_guide.md — 定義 notebook 教學設計標準
# 1. Introduction
Purpose: Frame the notebook around the problem being solved and the value
delivered, not the machinery being built.
Good:
Your engineering team's GitHub Actions workflows fail for dozens of reasons:
flaky tests, dependency conflicts, infrastructure issues, or real bugs.
Manually triaging which failures need immediate attention versus which
can wait wastes hours of senior engineer time every week.
Bad:
In this notebook we will build a research agent. Research agents are useful
because they can search the internet and analyze information. We will use
the Claude Code SDK to create an agent with the WebSearch tool.
Code language: PHP (php)Style guide 明確區分了「問題導向」vs.「機制導向」的寫法，並用 TLO（Terminal Learning Objectives）和 ELO（Enabling Learning Objectives）來結構化每個 notebook 的學習契約。這不是學術概念的堆砌——它被嵌入到 validate_notebook.py 腳本和 code-reviewer agent 的審查清單中，成為可自動化檢查的品質閘門。
Content Philosophy 部分也明確定義了 Cookbook「不是什麼」：
### What Cookbooks Are NOT
Cookbooks are not pure tutorials: We assume users have basic technical skills
Cookbooks are not comprehensive explanations: We don't teach transformer architecture
Cookbooks are not reference docs: We don't exhaustively document every parameter
Cookbooks are not simple tips and tricks: We don't teach "hacks"
Cookbooks are not production-ready code: They showcase use cases, not production patterns
Code language: PHP (php)設計六：Notebook 自動化驗證——從 Secret Detection 到結構檢查
validate_notebook.py 是一個精心設計的自動化品質閘門，執行多層檢查。
.claude/skills/cookbook-audit/validate_notebook.py — Notebook 自動化驗證腳本
class NotebookValidator:
def run_all_checks(self):
"""Run all validation checks."""
self.check_hardcoded_secrets()
self.check_introduction()
self.check_pip_install_output()
self.check_code_explanations()
self.check_verbose_output()
self.check_variable_names()
self.check_model_constant()
self.check_deprecated_patterns()
self.check_conclusion()
Code language: CSS (css)驗證邏輯涵蓋 9 個維度。值得注意的設計細節包括：
- Secret detection 的降級策略：優先使用
detect-secrets工具（支援自訂 baseline 和 plugin），但若工具不可用則自動降級到基於 regex 的簡單檢測。 - Model 版本驗證：不只檢查模型名稱是否有效，還維護了一個 deprecated models 映射表，能告訴你「用 claude-opus-4-1 是過時的，請更新到 claude-opus-4-5」。
- 結構化問題分級：將問題分為
issues（critical，必須修復）和warnings（should review），反映在 exit code 中——只有 critical issues 會導致 CI 失敗。 - Markdown 轉換：驗證前先將 notebook 轉為 markdown（排除 output），方便人工和 AI 審查，避免處理原始
.ipynbJSON 的複雜性。
設計七：Agent Patterns 的抽象層——util.py 的極簡設計
Agent 設計模式範例中的 util.py 只有兩個函式，但體現了重要的抽象原則。
patterns/agents/util.py — Agent 模式的共用工具層
def llm_call(prompt: str, system_prompt: str = "", model="claude-sonnet-4-5") -> str:
"""Calls the model with the given prompt and returns the response."""
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
messages = [{"role": "user", "content": prompt}]
response = client.messages.create(
model=model, max_tokens=4096, system=system_prompt,
messages=messages, temperature=0.1,
)
return response.content[0].text
def extract_xml(text: str, tag: str) -> str:
"""Extracts the content of the specified XML tag from the given text."""
match = re.search(f"<{tag}>(.*?)</{tag}>", text, re.DOTALL)
return match.group(1) if match else ""
Code language: JavaScript (javascript)llm_call 將 API 呼叫抽象為「prompt in, text out」的純函式，讓 notebook 中的 agent 模式範例（Prompt Chaining、Routing、Parallelization）能聚焦在模式本身而非 API 細節。extract_xml 則是一個輕量的結構化輸出解析器——用 XML tag 來結構化 LLM 回應，比 JSON 更寬容、更不容易因格式問題而失敗。
設計八：Prompt 分離原則——Agent 定義與 Prompt 檔案的解耦
Agent patterns 範例將 prompt 檔案獨立到 prompts/ 目錄，而非嵌入 notebook code cells 中。
patterns/agents/prompts/research_lead_agent.md — 研究主導 agent 的 system prompt
<research_process>
Follow this process to break down the user's question:
1. **Assessment and breakdown**: Analyze and break down the user's prompt
2. **Query type determination**: Explicitly state your reasoning on what type:
* **Depth-first query**: When the problem requires multiple perspectives
* **Breadth-first query**: When the problem can be broken into distinct sub-questions
* **Straightforward query**: When the problem is focused, well-defined
3. **Detailed research plan development**: Based on the query type, develop a plan
4. **Methodical plan execution**: Execute the plan fully, using parallel subagents
</research_process>
<subagent_count_guidelines>
1. Simple/Straightforward queries: create 1 subagent
2. Standard complexity: 2-3 subagents
3. Medium complexity: 3-5 subagents
4. High complexity: 5-10 subagents (maximum 20)
**IMPORTANT**: Never create more than 20 subagents unless strictly necessary.
</subagent_count_guidelines>
Code language: HTML, XML (xml)這個 prompt 設計體現了幾個高級技巧：
- 查詢分類策略（Depth-first / Breadth-first / Straightforward）：先判斷問題類型，再決定研究策略和 subagent 數量。
- 資源預算機制：明確限制 subagent 數量上限（20），並按問題複雜度分級。
- XML tag 結構化：用
<research_process>、<delegation_instructions>等 XML tag 組織 prompt 的不同段落，讓 prompt 自身成為可維護的結構化文件。 - 反模式防護：「NEVER create a subagent to generate the final report」——防止 agent 把核心任務委託出去。
設計九：Memory Tool Handler——路徑安全與 Command Pattern
tool_use/memory_tool.py 實作了一個完整的記憶體工具處理器，展示了 Claude Tool Use 的 client-side 實作最佳實踐。
tool_use/memory_tool.py — 記憶體工具的 client-side 實作
class MemoryToolHandler:
def _validate_path(self, path: str) -> Path:
"""Validate and resolve memory paths to prevent directory traversal attacks."""
if not path.startswith("/memories"):
raise ValueError(f"Path must start with /memories, got: {path}.")
relative_path = path[len("/memories"):].lstrip("/")
full_path = (self.memory_root / relative_path).resolve()
try:
full_path.relative_to(self.memory_root.resolve())
except ValueError as e:
raise ValueError(
f"Path '{path}' would escape /memories directory."
) from e
return full_path
def execute(self, **params: Any) -> dict[str, str]:
"""Execute a memory tool command."""
command = params.get("command")
try:
if command == "view": return self._view(params)
elif command == "create": return self._create(params)
elif command == "str_replace": return self._str_replace(params)
elif command == "insert": return self._insert(params)
elif command == "delete": return self._delete(params)
elif command == "rename": return self._rename(params)
except ValueError as e:
return {"error": str(e)}
這裡有兩個核心設計理念：
- 路徑安全：
_validate_path先檢查前綴、然後 resolve 絕對路徑、最後用relative_to確認路徑沒有逃逸出 sandbox。這是防止 directory traversal 攻擊的標準做法，在 AI tool use 場景中尤其重要——因為路徑是由 LLM 生成的，不可信。 - Command Pattern：
execute()方法將不同操作（view、create、str_replace 等）統一到一個入口點，每個操作返回dict[str, str]（含 success 或 error key），為 Claude 提供一致的回應格式。
設計十：CI 中的 AI 守門員——分層安全模型
GitHub Actions workflows 設計了一個精巧的分層安全模型，決定「誰能觸發什麼」。
.github/workflows/notebook-quality.yml — Notebook 品質檢查 CI workflow
# Only run for internal contributors (not forks) unless manually triggered
if: github.event_name == 'workflow_dispatch' ||
github.event.pull_request.head.repo.full_name == github.repository
# API tests only for maintainers (costs money)
- name: Execute notebooks (API Testing)
if: |
github.event_name == 'push' ||
github.event.pull_request.author_association == 'MEMBER' ||
github.event.pull_request.author_association == 'OWNER'
# Mock testing for external contributors
- name: Execute notebooks (Mock Testing)
if: |
github.event_name == 'pull_request' &&
github.event.pull_request.author_association != 'MEMBER' &&
github.event.pull_request.author_association != 'OWNER'
Code language: PHP (php)三層策略：
- 內部成員：完整 API 測試（花費 API credits）
- 外部貢獻者：結構驗證 + Mock 測試（零成本）
- 手動觸發：
workflow_dispatch作為逃生艙口
當 notebook 驗證發現問題時，workflow 不只是讓 CI 失敗——它會呼叫 claude-code-action 讀取驗證輸出，生成一條友善的 PR comment，解釋問題所在和修復方式。AI 不只是評判者，也是老師。
Prompt 設計解讀
倉庫包含兩套精心設計的 prompt 體系，分別服務不同目的。
研究 Agent 的 Prompt 架構
patterns/agents/prompts/research_lead_agent.md — 研究主導 agent 的完整 system prompt
Research lead agent 的 prompt 長達 400+ 行，結構為：<research_process> -> <subagent_count_guidelines> -> <delegation_instructions> -> <answer_formatting> -> <important_guidelines>。值得學習的設計技巧：
- 分類決策樹：先識別查詢類型（depth-first/breadth-first/straightforward），再匹配對應的研究策略。每個類型都提供了具體的 example，降低 LLM 的判斷不確定性。
- 資源控管：明確設定 subagent 數量上限，並解釋為什麼——「More subagents = more overhead. Only add subagents when they provide distinct value.」
- OODA 循環：subagent prompt 中要求執行 Observe-Orient-Decide-Act 循環，這是軍事決策理論在 AI agent 中的應用。
Citations Agent 的精確度設計
patterns/agents/prompts/citations_agent.md — 引用標註 agent 的 prompt
**Rules:**
- Do NOT modify the <synthesized_text> in any way - keep all content 100% identical
- Pay careful attention to whitespace: DO NOT add or remove any whitespace
- ONLY add citations where the source documents directly support claims
**Citation guidelines:**
- Avoid citing unnecessarily: Not every statement needs a citation
- Cite meaningful semantic units: Citations should span complete thoughts
- Minimize sentence fragmentation: Avoid multiple citations within a single sentence
- No redundant citations close to each other
Code language: PHP (php)Citation agent 的設計核心是「精確度優先」——它不產生新內容，只在既有文本上添加引用標記。規則的嚴格程度（「keep all content 100% identical」、「DO NOT add or remove any whitespace」）反映了 Anthropic 對 LLM 輸出可控性的追求。
設計理念萃取
- AI 作為 CI 參與者，而非旁觀者 — 傳統 CI 只跑 lint 和 test，這個倉庫讓 Claude 直接參與 PR 審查、模型版本驗證、連結品質檢查。slash commands 的 CI/本地雙用設計，確保開發者和 CI 用同一套邏輯。這個模式可以直接應用到任何需要 AI-in-the-loop 品質控制的專案。
- Allowed-tools 作為安全邊界 — 每個 command 和 agent 都定義了精確的工具白名單（如
Bash(gh pr comment:*)而非Bash(*)）。這不只是安全考量，更是職責邊界的明確化——reviewer 不該有 merge 的權限。在設計 AI agent 系統時，最小權限原則應該從工具層開始。 - 教學設計方法論的工程化 — TLO/ELO 學習目標體系、「問題導向而非機制導向」的寫作原則、style guide 中的 Good/Bad 對比範例——這些教學設計理念被編碼到了 skill 定義、驗證腳本和審查清單中。如果你也在維護技術文件庫，將寫作標準從「指南」轉化為「可自動化驗證的規則」是值得借鏡的方向。
- Registry 作為 Single Source of Truth — 用 JSON Schema 驗證的
registry.yaml取代鬆散的 README 列表，配合add-registryslash command 自動化條目生成。這個模式適用於任何需要管理大量內容/模組的專案——以 schema 約束結構，以自動化工具降低人為錯誤。 - Prompt 分離與結構化 — 將 prompt 從程式碼中分離到獨立的
.md檔案，用 XML tag 組織 prompt 內部結構。這讓 prompt 可以被版本控制、被 diff、被獨立審查——跟程式碼一樣對待。
延伸思考
這個倉庫展示的核心思想是：用管理程式碼的方式管理內容。當你維護的不只是程式碼，還有技術文件、教學材料、API 範例時，可以借鑑以下做法：
- 為 AI 協作者寫 README：如果你的團隊使用 Claude Code 或類似工具，在 CLAUDE.md 中定義明確的規則、模型版本、禁止事項。不要假設 AI 會從程式碼中「推斷」出規範。
- 統一 CI 與本地的品質檢查邏輯：將審查邏輯定義為 slash commands 或 scripts，讓開發者在本地可以跑同一套檢查，而非只在 CI 中才發現問題。
- 漸進式安全模型：針對不同貢獻者層級（maintainer vs. external contributor）設定不同的 CI 行為——既保護 API credits，又不阻擋社群參與。
- 將 Prompt 當程式碼管理：放在版本控制中、用結構化格式（XML tags）組織、分離到獨立檔案。Prompt 的品質直接影響 agent 的行為，值得跟產品程式碼一樣對待。
Vibe Coding：把觀念變成程式碼
以下是你可以直接給 AI 的 prompt 指令，將本文介紹的設計觀念應用到你的專案中：
為 AI 協作者撰寫專案契約（CLAUDE.md）
場景：你的團隊開始使用 Claude Code 或其他 AI 編碼工具，但 AI 每次都要重新理解專案慣例，產出的程式碼風格不一致。
給 AI 的指令：
請分析我的專案結構和現有的設定檔（package.json / pyproject.toml / tsconfig.json 等），為我生成一份 CLAUDE.md 專案契約文件。內容需包含：
1. Key Rules 段落：列出 5-8 條可機器執行的開發規範（不是模糊建議），包括套件管理指令、程式碼風格、禁止事項
2. 明確列出專案使用的 model 版本或重要依賴版本號
3. 常用指令段落：列出 build、test、lint、deploy 的完整命令
4. 專案架構概覽：用樹狀圖說明目錄結構和每個目錄的職責
5. 不能做的事清單：列出絕對禁止的操作（例如不要直接編輯某些自動生成的檔案、不要 commit .env）
參考 Claude Cookbooks 的 CLAUDE.md 設計模式：每條規則都要具體到 AI 可以直接據此判斷對錯，而非「盡量保持一致」這種模糊描述。
效果：AI 會掃描你的專案結構，產出一份結構化的 CLAUDE.md，未來所有 AI 協作者（包括 CI 中的 AI）進入專案時都能立即遵守一致的規範。
用 Slash Command 統一 CI 與本地的品質檢查
場景：你想讓 Claude Code 在本地和 GitHub Actions CI 中執行相同的程式碼審查邏輯，避免「本地通過、CI 才發現問題」的情況。
給 AI 的指令：
我想為專案建立一套 Claude Code 的 slash command 體系，實現 CI 與本地共用同一套審查邏輯。請幫我：
1. 在.claude/commands/目錄建立一個review.mdslash command，用 frontmatter 定義 allowed-tools（採用最小權限原則，只授予讀取和搜尋相關工具，參考 Claude Cookbooks 的 allowed-tools 安全邊界設計）
2. 在命令內容中定義審查清單，涵蓋：[替換為你的專案關注項目，例如：型別安全、錯誤處理、測試覆蓋率、命名慣例]
3. 建立對應的.github/workflows/claude-review.yml，使用anthropics/claude-code-action@v1調用同一個 slash command
4. CI workflow 中需區分內部成員（完整審查）和外部貢獻者（僅結構檢查），採用 Claude Cookbooks 的分層安全模型設計
每個 command 的 allowed-tools 要精確到操作層級（如Bash(gh pr comment:*)而非Bash(*)）。
效果：AI 會生成一組 slash command 定義檔和對應的 CI workflow，開發者在本地輸入 /review 和 CI 自動觸發時執行完全相同的審查邏輯，並且每個角色只有最小必要權限。
用 JSON Schema 建立內容目錄管理系統
場景：你的專案管理大量內容（API 範例、教學文件、設定範本等），目前用 README 手動列表管理，經常出現格式不一致或遺漏。
給 AI 的指令：
我的專案中有 [替換為你的內容類型，例如：API 範例 notebook / 設定範本 / 教學文件] 需要統一管理。請參考 Claude Cookbooks 的 Registry + JSON Schema 設計模式，幫我建立：
1. 一個registry.yaml檔案，為每個內容項目定義結構化條目（title、description、path、categories、authors、date）
2. 一個registry_schema.json，用 JSON Schema 約束 registry 的結構，特別是用enum限定分類詞彙表，防止分類名稱混亂
3. 一個 CI 驗證步驟，在 PR 時自動檢查 registry.yaml 是否符合 schema
4. （可選）一個.claude/commands/add-registry.mdslash command，讓 Claude Code 自動讀取新增內容並生成符合 schema 的 registry 條目
分類詞彙表先定義以下類別：[替換為你的分類]。schema 要設定 required fields 確保每筆記錄完整。
效果：AI 會建立完整的 registry 管理系統，所有內容索引都有 schema 驗證，新增內容時可以自動化生成條目，避免人為錯誤。
實作 Tool Use 的路徑安全驗證
場景：你正在開發讓 AI agent 操作檔案系統的工具（Tool Use），需要防止 LLM 生成的路徑逃逸出預期目錄。
給 AI 的指令：
我正在實作一個讓 Claude 操作的自訂工具，需要處理檔案路徑。請參考 Claude Cookbooks 中 Memory Tool Handler 的路徑安全設計和 Command Pattern，幫我實作：
1. 一個_validate_path()方法：先檢查路徑前綴是否在允許範圍內，然後用Path.resolve()解析絕對路徑，最後用relative_to()確認路徑沒有逃逸出 sandbox 目錄。這三步驗證缺一不可，是防止 directory traversal 攻擊的標準做法。
2. 一個execute()入口方法：採用 Command Pattern，將不同操作（view、create、update、delete）統一到一個入口點
3. 每個操作都返回一致的dict[str, str]格式（包含 success 或 error key），方便 Claude 解析工具回應
4. 所有 ValueError 統一在 execute() 層捕獲並轉為 error 回應，不讓例外洩漏到 Claude
我的 sandbox 根目錄是：[替換為你的目錄路徑]
需要支援的操作有：[替換為你需要的操作]
效果：AI 會生成一個安全的工具處理器，包含三層路徑驗證、統一的 command dispatch、一致的回應格式，適合作為任何 AI tool use 實作的安全基底。
將 Prompt 分離為可版控的獨立檔案
場景：你的 AI agent 專案中，system prompt 都寫死在程式碼裡，難以追蹤變更、進行 A/B 測試、或讓非工程師參與 prompt 調整。
給 AI 的指令：
請幫我重構專案中的 prompt 管理方式，採用 Claude Cookbooks 的 Prompt 分離原則：
1. 將所有嵌入在程式碼中的 system prompt 抽取到prompts/目錄下的獨立.md檔案
2. 每個 prompt 檔案內部用 XML tag 組織不同段落（例如<role>、<instructions>、<constraints>、<output_format>），讓 prompt 自身成為結構化文件
3. 在程式碼中建立一個load_prompt(name: str) -> str工具函式，負責讀取和快取 prompt 檔案
4. 如果 prompt 中有需要動態替換的部分，用{{variable_name}}佔位符標記，load_prompt 支援 keyword arguments 替換
目前我的 prompt 分散在這些檔案中：[替換為你的檔案路徑]
每個 prompt 的用途是：[簡述每個 prompt 的功能]
效果：AI 會將散落在程式碼各處的 prompt 統一抽取到獨立檔案，用 XML tag 結構化組織，並建立載入工具函式。之後 prompt 可以被版本控制、被 diff、被獨立審查，跟程式碼一樣對待。
延伸閱讀
- Claude Cookbooks GitHub Repository — 本文解讀的專案原始碼，包含所有 slash commands、agents、skills 定義和 CI workflows，值得直接閱讀
.claude/目錄下的完整實作 - Building Effective Agents — Anthropic Research — Anthropic 官方的 agent 設計模式指南，定義了 Prompt Chaining、Routing、Parallelization 等組合式模式，是 Cookbooks 中 agent patterns 範例的理論基礎
- Claude Code: Best Practices for Agentic Coding — Anthropic Engineering — Anthropic 工程團隊撰寫的 Claude Code 最佳實踐，涵蓋 CLAUDE.md 撰寫原則、slash commands 設計、subagent 使用策略，與本文解讀的專案契約設計直接相關
- Using CLAUDE.md Files: Customizing Claude Code for Your Codebase — 官方 Blog 深入說明 CLAUDE.md 的階層式載入機制和進階用法，幫助理解本文「為 AI 協作者寫 README」的設計意圖
- Claude Code GitHub Actions 官方文件 — claude-code-action 的完整設定指南，包含 allowed-tools 安全模型、觸發條件設定、企業環境整合等，是實作本文 CI/本地雙用設計的必備參考
- Use XML Tags to Structure Your Prompts — Claude Docs — Anthropic 官方的 XML tag prompt 結構化指南，解釋為什麼 XML tag 能提升 Claude 的指令理解精確度，是本文 Prompt 分離原則的技術基礎