Claude Code 高階工作流：記憶、Skills、子代理、MCP、Hooks 同 CI/CD

Claude Code 每次工作階段都是全新上下文視窗，跨工作階段知識靠兩種機制：CLAUDE.md（你寫的指令）與 auto memory（Claude 自記的筆記）。專案級指令放 ./CLAUDE.md 或 ./.claude/CLAUDE.md，隨版本控制與團隊共享；個人偏好放 ~/.claude/CLAUDE.md（跨所有專案）；不想入庫的個人專案偏好放 ./CLAUDE.local.md 並加入 .gitignore。工作階段啟動時從工作目錄向上逐級載入並合併進 context。建議每份控制在 200 行內，用「Use 2-space indentation」「Run npm test before committing」呢類可驗證嘅具體表述。用 /init 自動產生初始 CLAUDE.md，/context 確認已載入（Memory files 列表），/memory 開啟編輯。注意：CLAUDE.md 係上下文而唔係強制設定，硬性攔截需用 PreToolUse hook。

大專案用 .claude/rules/ 目錄按主題拆分指令（如 testing.md、api-design.md、security.md），所有 .md 遞迴發現，可用子目錄分 frontend/backend。帶 paths frontmatter 的規則只在 Claude 讀取相符檔案時才載入，慳 context：

glob 支援 **/*.ts、src/**/*、*.md、src/components/*.tsx 及 {ts,tsx} 花括號展開。CLAUDE.md 用 @path 匯入其它檔案：@README、@package.json、@docs/git-instructions.md，相對匯入深度最多 4 層，匯入內容同樣在啟動時進 context（反引號包住 @README 則不匯入）。相容其它代理的 AGENTS.md：在 CLAUDE.md 首行寫 @AGENTS.md，或 ln -s AGENTS.md CLAUDE.md。忽略 monorepo 裡他人 CLAUDE.md 用 claudeMdExcludes。

auto memory 預設開啟，Claude 在工作過程中自動記錄建置指令、除錯經驗、程式碼風格偏好等，儲存到 ~/.claude/projects/<project>/memory/ 目錄，其中 MEMORY.md 係索引，每工作階段載入前 200 行或前 25KB，細節放獨立主題檔案（如 debugging.md）。同一 git 倉庫的所有 worktree 共用一個記憶目錄，且只存本機。開啟時你會看到「Saved 2 memories / Recalled 2 memories」提示。關閉方式三選一：/memory 面板切換、settings.json 寫 {"autoMemoryEnabled": false}、或環境變數 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。儲存位置可用 autoMemoryDirectory 自訂。subagent 也可用 frontmatter 的 memory 欄位維護自己的記憶目錄。

Skill 係含必需 SKILL.md 的目錄（YAML frontmatter + 指令正文），目錄名即指令，可直接 /skill-name 呼叫。自訂 slash command 已併入 skills：.claude/commands/deploy.md 與 .claude/skills/deploy/SKILL.md 都會產生 /deploy 且行為一致，舊指令檔仍可用。位置：個人 ~/.claude/skills/<name>/SKILL.md（跨專案）、專案 .claude/skills/（入庫共享）。最小示例：

frontmatter 欄位：name、description、disable-model-invocation（僅手動觸發，適合 /deploy）、user-invocable、allowed-tools、model、context。與 CLAUDE.md 不同，skill 正文只在被呼叫時才載入，適合放長流程文檔。

參數佔位符：$ARGUMENTS（全部參數）、$ARGUMENTS[N] / $N（按位置，0 起）、frontmatter arguments: [issue, branch] 映射 $issue。動態上下文注入 !command：在發送給 Claude 前執行並把輸出替換進 skill 正文（如 !gh pr diff、!gh pr view --comments），多行指令用

Subagent 係獨立 context 視窗、獨立 system prompt 與獨立權限嘅專職助手，只把摘要回傳主對話，從而保護主 context。內置三類：Explore——唯讀、擅長搜尋/分析程式庫（Write/Edit 被拒，model 繼承主工作階段且封頂 Opus）；Plan——plan mode 下做唯讀程式庫調研；general-purpose——擁有全部 subagent 工具嘅複雜多步助手（探索+修改）。Claude 依據任務描述和 subagent 的 description 自動委派。停用/限制：permissions.deny: ["Agent(Explore)"] 阻止單個類型，deny Agent 工具本身則禁止一切委派，CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 移除內置 Explore/Plan。

Subagent = 帶 YAML frontmatter 的 Markdown 檔案，放 .claude/agents/（專案共享、入庫）或 ~/.claude/agents/（個人跨專案）。完整示例：

僅 name 和 description 必填；tools 省略則繼承全部可用工具，disallowedTools: Write, Edit 做黑名單；model 可寫 sonnet/opus/haiku 或 inherit。呼叫方式三檔：自然語言點名、@"code-reviewer (agent)" @ 提及（保證執行）、claude --agent code-reviewer 整工作階段以該 subagent 執行。位置優先級：managed settings > --agents CLI > .claude/agents/ > ~/.claude/agents/ > plugin。

frontmatter 更多能力：memory: user 給 subagent 持久記憶目錄（user→~/.claude/agent-memory/<name>/、project→.claude/agent-memory/、local→本地不入庫）；mcpServers: - github 或內聯定義 - playwright: {type: stdio, command: npx, args: ["-y", "@playwright/mcp@latest"]} 讓子代理獨享 MCP 工具；frontmatter 內可寫 hooks: 作用域到該 agent；tools: Agent(worker, researcher) 白名單限制可派生的子代理（預設可嵌套 3 層）。控成本：model: haiku 把任務路由到更平價模型。CLI 臨時定義：claude --agents '{ "code-reviewer": { "description": "...", "prompt": "...", "tools": ["Read","Bash"], "model": "sonnet" } }'。v2.1.198 起 subagent 預設背景執行，Ctrl+B 前後台切換，/tasks 查看；permissionMode: acceptEdits 可讓子代理自動接受檔案編輯。

MCP（Model Context Protocol）讓 Claude Code 直連外部工具/資料庫/API。新增伺服器：遠端 HTTP（推薦，支援 OAuth）claude mcp add --transport http notion https://mcp.notion.com/mcp；本地 stdio claude mcp add --transport stdio airtable -- npx -y airtable-mcp-server（注意 -- 之後才是伺服器指令，之前是 --transport/--env/--scope 等自身參數）；SSE --transport sse 已棄用。管理指令：claude mcp list、claude mcp get <name>、claude mcp remove <name>，工作階段內 /mcp 面板查看連線狀態與工具數。三種 scope：--scope local（預設，寫 ~/.claude.json 只限當前專案私有）、--scope project（寫 .mcp.json 入庫與團隊共享）、--scope user（跨所有專案）。同一伺服器重名時按 local > project > user > plugin > claude.ai 連接器取最高優先級。

專案共享伺服器寫入 .mcp.json，格式：

.mcp.json 支援 ${VAR} 與 ${VAR:-default} 環境變數展開（可用於 command/args/env/url/headers，如 "Authorization": "Bearer ${API_KEY}"），安全起見 .mcp.json 首次使用需批准。認證：HTTP 伺服器 OAuth 在工作階段內 /mcp 登入，或指令行 claude mcp login <name>（無瀏覽器加 --no-browser）；靜態 token 用 --header "Authorization: Bearer your-token" 傳入。安全注意：遠端 MCP 伺服器可能引入 prompt injection 風險，只連接信任的伺服器；MCP 工具走標準權限系統，可用 permissions.deny 限制，伺服器作者可用 _meta["anthropic/requiresUserInteraction"]: true 強制每個工具呼叫都需人工批准。企業可用 managed-mcp.json 集中管控（allowedMcpServers/deniedMcpServers）。

Hooks 係用戶定義嘅 shell 指令，Claude Code 在生命週期固定節點確定性執行（不依賴 LLM 決策），用於強制執行規則與自動化。核心事件：SessionStart（工作階段開始）、UserPromptSubmit（提交提示詞）、PreToolUse（工具呼叫前，可阻止）、PostToolUse（成功後）、PermissionRequest（權限決策）、Notification（等待輸入通知）、Stop（回應結束）、PreCompact/PostCompact（壓縮前後）、SubagentStart/SubagentStop、SessionEnd。在 settings 裡配 hooks 區塊：

位置決定作用域：~/.claude/settings.json（全域）、.claude/settings.json（入庫共享）、.claude/settings.local.json（個人不入庫）。/hooks 選單瀏覽；disableAllHooks: true 全域關閉。

自動格式化：PostToolUse + matcher Edit|Write，指令 jq -r '.tool_input.file_path' | xargs npx prettier --write。保護敏感檔案：PreToolUse 腳本讀 stdin JSON，命中 .env/package-lock.json/.git/ 時向 stderr 寫原因並 exit 2 阻止（exit 0 = 放行走正常權限流）。壓縮後重注入上下文：SessionStart matcher compact，echo 'Reminder: use Bun, not npm. Run bun test before committing.'。自動批准計劃模式：PermissionRequest matcher ExitPlanMode，stdout 輸出 JSON {"hookSpecificOutput": {"hookEventName": "PermissionRequest", "decision": {"behavior": "allow"}}}。判定類決策用 type: "prompt"（Haiku 單輪返回 {"ok": true/false}）或 type: "agent"（subagent 核查程式碼後決定）。matcher 區分大小寫，工具名用 | 分隔（Bash|Edit）。

非交互模式畀 -p（或 --print）傳提示詞即可跑腳本/CI：claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"。自動批准用 --allowedTools "Bash(git diff *)"（尾隨 * 前綴匹配）；或用權限模式 --permission-mode acceptEdits（免確認改檔案）、dontAsk（鎖定 CI，未授權即拒絕）。結構化輸出 --output-format json（含 result/session_id/每模型成本 total_cost_usd）或 stream-json（--verbose --include-partial-messages 流式事件）；--json-schema '{"type":"object",...}' 獲得 schema 化輸出。管道 stdin：cat build-error.txt | claude -p 'concisely explain this build error' > output.txt。CI 推薦加 --bare 跳過 hooks/skills/plugins/MCP/CLAUDE.md 自動發現，保證各機器結果一致。續工作階段：claude -p "..." --continue 或 --resume "$session_id"。

用官方 anthropics/claude-code-action@v1 喺 workflow 度跑 Claude Code（基於 Agent SDK）。先在倉庫 Settings→Secrets 新增 ANTHROPIC_API_KEY，workflow 中引用 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}（絕不可硬編碼密鑰）。基本示例：

claude_args 透傳任意 CLI 參數（--max-turns/--model/--mcp-config/--allowedTools）。在 PR/issue 評論裡 @claude implement this feature 可觸發交互；skill 經 plugin_marketplaces/plugins 安裝後可在 prompt 裡以 /code-review:code-review ... 呼叫。成本控制：設定合理 --max-turns 防失控迭代、加 workflow 級 timeout、用 GitHub 並發限制，並優先讓 CLAUDE.md 引導行為減少無效呼叫。倉庫根的 CLAUDE.md 即 CI 中 Claude 遵循的編碼規範來源。