my-claude-code-setup 完整教學

centminmod/my-claude-code-setup — Claude Code 起步模板、Memory Bank 系統、Hooks、Skills 與 Subagents 全解析

1. 專案定位與核心價值

這是什麼

my-claude-code-setup 是一個 Claude Code 的起步模板倉庫 (starter template repository)，由 George Liu 維護，在 GitHub 上獲得 2,387 stars 與 227 forks。它不是一個應用程式，而是一組可直接複製到任何專案的設定檔、模板與工具集。

核心定位

面向	說明
目標使用者	Claude Code 使用者（Pro/Max 訂閱）
解決的問題	Claude Code 缺乏 session 間的 context 保留機制，需要手動管理記憶
核心方案	提供 Memory Bank (記憶庫) 系統 + 3 種 CLAUDE.md 模板 + Hooks + Skills + Subagents 全套設定
授權	MIT（可自由使用、修改、商用）

為什麼重要

Claude Code 每次 session 結束後會失去 context (上下文)。這個 repo 透過 dual-memory architecture (雙層記憶架構) 解決此問題：

Primary Memory — git-shared 的 CLAUDE-*.md 檔案（code patterns、architecture decisions、troubleshooting 等）
Shadow Memory — machine-local 的 auto memory 檔案，即使 CLAUDE.md 被重設也能保留知識

2. 安裝指南

前置需求

已安裝 Claude Code 並擁有付費帳號 (Pro $20/月或 Max $100-200/月)
Git 已安裝
macOS 使用者建議安裝 Homebrew

快速安裝 (3 步驟)

步驟 1：複製檔案到你的專案

1# 方法 A：直接 clone 後複製
2git clone https://github.com/centminmod/my-claude-code-setup.git /tmp/claude-setup
3cp -r /tmp/claude-setup/.claude /tmp/claude-setup/CLAUDE*.md /tmp/claude-setup/AGENTS.md your-project/
4
5# 方法 B：只取需要的檔案
6cd your-project
7curl -sL https://raw.githubusercontent.com/centminmod/my-claude-code-setup/master/CLAUDE.md -o CLAUDE.md
8curl -sL https://raw.githubusercontent.com/centminmod/my-claude-code-setup/master/.claude/rules/core-rules.md --create-dirs -o .claude/rules/core-rules.md

步驟 2：安裝快速搜尋工具

1# macOS
2brew install ripgrep fd jq
3
4# Linux (Debian/Ubuntu)
5apt-get install ripgrep fd-find jq
6
7# 驗證安裝
8rg --version && fd --version && jq --version

步驟 3：初始化 Memory Bank

1cd your-project
2claude  # 啟動 Claude Code
3# 在 Claude Code 內執行：
4/init

Claude Code 會分析你的 codebase 並自動填入 memory bank 檔案。

選配 MCP Servers

1# Context7 (文件查詢)
2claude mcp add --transport sse context7 https://mcp.context7.com/sse -s user
3
4# Cloudflare Documentation
5claude mcp add --transport sse cf-docs https://docs.mcp.cloudflare.com/sse -s user
6
7# Chrome DevTools
8claude --mcp-config .claude/mcp/chrome-devtools.json

3. 核心架構解析

系統總覽


graph TB
    subgraph "Claude Code Session"
        CC[Claude Code CLI]
    end

    subgraph "Context Layers (上下文層)"
        CL1["CLAUDE.md
(Always loaded)"]
        CL2[".claude/rules/core-rules.md
(Always loaded)"]
        CL3["memory/MEMORY.md
(Auto memory, always loaded)"]
        CL4["CLAUDE-*.md
(On demand)"]
        CL5[".claude/skills/
(On demand)"]
    end

    subgraph "Memory Bank (記憶庫)"
        MB1["CLAUDE-activeContext.md
Session state + goals"]
        MB2["CLAUDE-patterns.md
Code patterns"]
        MB3["CLAUDE-decisions.md
Architecture ADRs"]
        MB4["CLAUDE-troubleshooting.md
Known fixes"]
        MB5["CLAUDE-config-variables.md
Config reference"]
    end

    subgraph "Shadow Memory (影子記憶)"
        SM1["memory/MEMORY.md
Index"]
        SM2["memory/patterns.md"]
        SM3["memory/architecture.md"]
        SM4["memory/build.md"]
    end

    CC --> CL1 & CL2 & CL3
    CL1 --> CL4
    CL4 --> MB1 & MB2 & MB3 & MB4 & MB5
    MB1 & MB2 & MB3 --> SM1 & SM2 & SM3 & SM4

    style CC fill:#4A90D9,color:#fff
    style CL1 fill:#E8D44D,color:#000
    style CL2 fill:#E8D44D,color:#000
    style CL3 fill:#7BC67E,color:#000

目錄結構與角色


graph LR
    subgraph "Root Files"
        A["CLAUDE.md — 專案入口"]
        B["CLAUDE-template-1/2/3.md — 模板選擇"]
        C["AGENTS.md — 快速工具規則"]
        D["GEMINI.md — Gemini CLI 規則"]
    end

    subgraph ".claude/"
        E["settings.json — Hooks + Model"]
        F["settings.local.json — Permissions + Env"]
        G["rules/ — 行為規則"]
        H["agents/ — 6 個 Subagents"]
        I["commands/ — Slash commands"]
        J["skills/ — 7 個 Skills"]
        K["hooks/ — 通知系統"]
        L["mcp/ — MCP 設定"]
    end

    A --> E
    A --> G
    A --> H & I & J & K & L

Context Layers (上下文層) 優先順序

層級	位置	載入時機	Git 共享	韌性
1	CLAUDE.md	永遠載入	Yes	No (可從 auto memory 復原)
2	.claude/rules/core-rules.md	永遠載入	Yes	Yes
3	memory/MEMORY.md	永遠載入 (前 200 行)	No	Yes
4	memory/*.md	需要時載入	No	Yes
5	CLAUDE-*.md	需要時載入	Git (但建議排除 commit)	No (mirror 到 auto memory)
6	.claude/skills/	需要時載入	Yes	Yes
7	CLAUDE.local.md	永遠載入	No (gitignored)	視檔案而定

4. 核心功能詳解

4.1 CLAUDE.md 模板系統

提供 3 種模板，遵循 Anthropic 官方最佳實踐：

模板	行數	設計理念	適用情境
Template 1	~101	精簡自足 + memory resilience (記憶韌性)	快速啟動、小型專案
Template 2	~153	Memory bank headline + dual memory (雙層記憶)	現有 memory bank 使用者
Template 3	~105	Progressive disclosure (漸進揭露) native	團隊使用、最大 context 效率

關鍵設計原則：

HTML comments () 在 runtime 被 strip，不消耗 token
CLAUDE.md 保持在 200 行以內
行為規則 (behavioral rules) 獨立在 .claude/rules/core-rules.md
遷移指南 CLAUDE-migrate-to-new-template.md 可作為 prompt 讓 Claude Code 自動遷移

4.2 Memory Bank (記憶庫) 系統

Memory Bank 由 5 個 CLAUDE-*.md 檔案組成，按需讀取 (on demand)：

檔案	讀取時機	內容
`CLAUDE-activeContext.md`	Session 開始時	當前狀態與目標
`CLAUDE-patterns.md`	實作前	程式碼模式 (code patterns)
`CLAUDE-decisions.md`	設計決策前	Architecture Decision Records (ADRs)
`CLAUDE-troubleshooting.md`	除錯時	已知問題與修復方式
`CLAUDE-config-variables.md`	動到設定時	設定變數參考

Sync Workflow (同步流程)：

1完成重要工作 → 更新 CLAUDE-*.md → 同步到 auto memory
2                                      ↓
3                              memory/patterns.md
4                              memory/architecture.md
5                              memory/build.md

若 CLAUDE.md 被意外重設，可透過 /memory 從 auto memory 復原。

4.3 Core Rules (核心規則)

.claude/rules/core-rules.md 定義 5 大行為準則：

Investigation & Accuracy (調查與準確性) — 讀取實際檔案後才能做判斷，不猜測
Scope Discipline (範圍紀律) — 只做被要求的事，不自行擴展
Verification & Safety (驗證與安全) — 完成前重新檢查需求、執行測試
Efficiency (效率) — 並行獨立的 tool calls
Memory Resilience (記憶韌性) — 更新 memory bank 時同步到 auto memory

4.4 Session Metrics Skill (Token 用量分析)

這是 repo 中最活躍的 skill (截至 v1.63.1)，提供：

Per-turn breakdown (逐回合分析) — Input/Output/CacheRd/CacheWr/Cost
HTML 報告 — Dark-theme dashboard + detail page, 含圖表
Project scope (專案層級) — 所有 session 加總
Instance scope (全域層級) — 跨專案成本追蹤
Model comparison (模型比較) — Opus 4.6 vs 4.7 等 A/B 測試
Task breakdown (任務分解) — 語義分組 + worth-it/mixed/waste 評價
Export 格式 — JSON / CSV / MD / HTML
Cache break detection (快取中斷偵測) — 找出 cache 爆掉的 turn
Subagent attribution (子代理歸屬) — 把 subagent 成本歸到觸發者

使用方式：

 1# 當前 session 成本
 2/session-metrics
 3
 4# 專案所有 session 成本
 5/session-metrics project
 6
 7# 匯出 HTML
 8/session-metrics export to html
 9
10# 全域 dashboard
11/session-metrics all-projects
12
13# Model comparison
14/session-metrics compare-run

4.5 Subagents (子代理)

Agent	功能	Model
code-searcher	程式碼搜尋 + 分析，含 Chain of Draft (CoD) 精簡模式	sonnet
memory-bank-synchronizer	Memory Bank 文件與 codebase 同步	(預設)
codex-cli	與 OpenAI Codex GPT-5.5 諮詢	(預設)
zai-cli	與 Z.AI GLM 4.7 諮詢	(預設)
get-current-datetime	取得當前日期時間	(預設)
ux-design-expert	UX 設計專家	(預設)

code-searcher 的 Chain of Draft (CoD) 模式：

CoD 是一種 token 節省技術，從論文衍生而來。每個推理步驟限制在 5 個字以內，使用符號標記法 (symbolic notation)：

1Auth→glob:*auth*→grep:login→found:auth.ts:45→implements:JWT+bcrypt

相比標準模式可減少 80-92% 的 token 消耗。

4.6 Slash Commands (斜線指令)

分為 6 大類：

類別	指令	用途
anthropic	`/apply-thinking-to`, `/update-memory-bank`	深度思考、更新記憶
architecture	`/explain-architecture-pattern`	架構模式解說
ccusage	`/ccusage-daily`	每日用量
documentation	`/create-readme-section`, `/create-release-note`	文件生成
promptengineering	`/batch-operations-prompt`, `/convert-to-test-driven-prompt`	Prompt 工程
security	`/check-best-practices`, `/secure-prompts`, `/security-audit`	安全審查

安全指令附帶 6 個測試範例 (test-examples)，涵蓋 prompt injection 攻擊模式：basic role override、authority claims、CSS hiding、encoding attacks、invisible chars、advanced injection。

4.7 Unified Notifier Hook (統一通知系統)

unified_notifier.py 是一個 Python hook，支援所有 Claude Code hook events：

SessionStart — session 開始通知
UserPromptSubmit — prompt 提交通知
Notification — 需要輸入時通知
PreToolUse_Bash — 執行命令前通知（TTS 只唸程式名）
PreToolUse_FileOp — 檔案操作前通知
PostToolUse_Bash/FileOp — 操作完成通知
SubagentStop — Subagent 完成通知
Stop / SessionEnd — Session 結束通知
PreCompact — Memory compaction (記憶壓縮) 通知
PermissionRequest — 權限請求通知

每個 event 同時觸發 桌面通知 (terminal-notifier) 和 TTS 語音播報。路徑自動轉為相對路徑以提高可讀性。

4.8 AI Image Creator

多模型 AI 圖片生成 skill，支援：

模型關鍵字	模型
`gemini` (預設)	Google Gemini 3.1 Flash
`flux2`	FLUX.2 Max
`riverflow`	Sourceful Riverflow v2 Pro
`seedream`	ByteDance SeedDream 4.5
`gpt5`	OpenAI GPT-5 Image
`gpt5.4`	OpenAI GPT-5.4 Image 2

透過 Cloudflare AI Gateway BYOK 或 OpenRouter 路由，支援透明背景 (-t)、reference image editing (-r)、image analysis (--analyze)。

4.9 Dual-AI Consultation (雙 AI 諮詢)

兩個 skill 實現「交叉驗證」模式：

consult-codex — 同時查詢 OpenAI Codex GPT-5.5 + Claude code-searcher
consult-zai — 同時查詢 Z.AI GLM 4.7 + Claude code-searcher

兩者都會產生比較表 (Comparison Table)、Agreement Level (共識程度)、Synthesized Summary (綜合摘要)。

5. 應用場景

場景 A：新專案起步

11. Fork / 複製 repo 到你的專案
22. 選擇 CLAUDE.md 模板 (建議 Template 3)
33. 執行 /init 初始化 memory bank
44. 開始開發，結束後執行 /update-memory-bank

場景 B：既有專案加入 Memory Bank

11. 複製 CLAUDE-migrate-to-new-template.md 的內容作為 prompt
22. Claude Code 會自動遷移你的 CLAUDE.md
33. 複製 .claude/ 目錄到專案中
44. 執行 /init 重新初始化

場景 C：追蹤 Claude Code 使用成本

11. 安裝 session-metrics skill
22. 每次 session 結束前執行 /session-metrics export to html
33. 定期執行 /session-metrics all-projects 看跨專案成本
44. 用 /session-metrics compare-run 比較不同 model 的性價比

場景 D：多 AI 交叉驗證

11. 設定 Codex CLI 或 Z.AI CLI
22. 遇到複雜問題時使用 /consult-codex 或 /consult-zai
33. 比較兩個 AI 的回答，取共識作為高信心結論

場景 E：平行開發 (Git Worktree)

1# 啟動 Claude Code worktree
2clx feature-auth
3
4# 啟動 Codex CLI worktree
5cx bugfix-123
6
7# 兩個 session 完全隔離，互不干擾

6. 資安掃描報告

掃描結果：🟢 安全

掃描範圍： 全部 125 個檔案，掃描 eval、exec、subprocess、shell=True、secret、token、password、api_key 等關鍵字。

發現：

類別	項目	風險等級	說明
subprocess	`unified_notifier.py`	🟢 無風險	有 `check=True` + `timeout=5` 保護
硬編碼路徑	`unified_notifier.py` 第 22 行	🟡 注意	TTS 腳本路徑 (`/Users/george/...`) 是作者本機路徑，使用時需修改
API Key	`mcp-servers.md`	🟢 佔位符	`GEMINI_API_KEY`、`OPENROUTER_API_KEY`、`ntn_API_KEY` 都是佔位符
URL	多處 `.md` 檔案	🟢 正常	文件內的 URL reference，非可執行程式碼
安全測試	`commands/security/test-examples/`	🟢 有意為之	Prompt injection 測試範例，供安全審計使用

結論： 此 repo 不含真實機密，不含危險的程式執行模式。唯一需注意的是 unified_notifier.py 內的 TTS 路徑需根據個人環境修改。

7. FAQ

Q1：CLAUDE.md 應該 commit 到 git 嗎？

CLAUDE.md 本身建議 commit（它是模板設定）。但 CLAUDE-*.md 的 memory bank 檔案建議加入 .gitignore，因為它們包含 session-specific 資訊。repo 建議用 private git repo 做 memory bank backup。

Q2：Template 1/2/3 該選哪個？

獨立開發小專案 → Template 1（最精簡）
已在使用 memory bank → Template 2（平滑遷移）
團隊專案或追求最高 context 效率 → Template 3（需搭配 core-rules.md）

Q3：session-metrics 需要 API key 嗎？

不需要。它讀取 Claude Code 產生的本地 JSONL log 檔案（~/.claude/projects/），完全離線計算。

Q4：hooks/unified_notifier.py 在 Linux 上能用嗎？

桌面通知部分使用 terminal-notifier（macOS only）。Linux 使用者需替換為 notify-send 或其他通知工具。TTS 部分需確認 uv 和 TTS 腳本的可用性。

Q5：能同時使用 Claude Code 和其他 AI CLI 嗎？

可以。repo 提供 Gemini CLI 的 GEMINI.md、Codex CLI 和 Z.AI CLI 的 subagent 設定，以及 Git Worktree 函式讓你在隔離環境中同時執行多個 AI CLI。

8. 進階技巧

8.1 自訂 Hook Events

在 .claude/settings.json 中加入更多 hook 設定：

 1{
 2  "hooks": {
 3    "PreToolUse": [
 4      {
 5        "matcher": "Bash",
 6        "hooks": [{
 7          "type": "command",
 8          "command": "python .claude/hooks/unified_notifier.py PreToolUse_Bash"
 9        }]
10      }
11    ]
12  }
13}

8.2 Session Metrics 進階用法

1# 只看快取健康度（cache hit rate）
2/session-metrics export project to html
3
4# Model comparison 自訂 prompt
5/session-metrics compare-run --compare-add-prompt "Explain the architecture of a microservices system"
6
7# 隱私模式匯出（隱藏 prompt 內容）
8/session-metrics export to html --export-share-safe

8.3 Chain of Draft (CoD) 觸發

在使用 code-searcher subagent 時加入關鍵字：

1use CoD to find all authentication endpoints
2chain of draft: where is the payment logic?
3concise reasoning: analyze error handling patterns

8.4 Statusline 自訂

在 ~/.claude/settings.json 加入 statusline 設定，顯示 model name、context usage bar、cost、git branch 等資訊。

9. 整合進其他工作流

整合到 CI/CD

1# GitHub Actions 範例
2- name: Claude Code Review
3  run: |
4    claude --model sonnet --permission-mode plan \
5      -p "Review the PR changes and suggest improvements"

整合到 Dev Container

repo 作者提供了 VS Code dev container 設定，可在 Debian 12 容器中同時執行 Claude Code、Codex CLI、Gemini CLI、OpenCode 等。

搭配 Z.AI 使用

透過 Z.AI 可取得更高的 token quota 並使用 GLM-4.7 模型。在 Claude Code 中設定後，可透過 consult-zai skill 做雙 AI 諮詢。

10. 重點摘要 Checklist

選擇適合的 CLAUDE.md 模板 (Template 1/2/3)
複製 .claude/ 目錄到專案
安裝 ripgrep、fd、jq 快速搜尋工具
執行 /init 初始化 memory bank
了解 dual-memory architecture 的運作方式
設定需要的 MCP servers
修改 unified_notifier.py 的 TTS 路徑（或移除 TTS）
用 /session-metrics 追蹤 token 成本
有需要時使用 /consult-codex 或 /consult-zai 做交叉驗證
每次重要工作後執行 /update-memory-bank 保存 context
了解 security slash commands 的 prompt injection 測試範例

11. 進一步閱讀

資源	連結
GitHub Repo	https://github.com/centminmod/my-claude-code-setup
Claude Code 官方文件	https://docs.anthropic.com/en/docs/claude-code/overview
Claude Code 記憶系統	https://code.claude.com/docs/en/memory
Claude Code Hooks	https://code.claude.com/docs/en/hooks
Claude Code Skills	https://code.claude.com/docs/en/skills
作者 Substack	https://ai.georgeliu.com
Chain of Draft 論文概念	code-searcher agent 內建實作
Dev Container 設定	https://claude-devcontainers.centminmod.com/
README-v2 (漸進指南)	https://github.com/centminmod/my-claude-code-setup/blob/master/README-v2.md
README-v3 (任務導向指南)	https://github.com/centminmod/my-claude-code-setup/blob/master/README-v3.md
README-v4 (技術參考手冊)	https://github.com/centminmod/my-claude-code-setup/blob/master/README-v4.md

my-claude-code-setup 完整教學

Contents

my-claude-code-setup 完整教學

1. 專案定位與核心價值

這是什麼

核心定位

為什麼重要

2. 安裝指南

前置需求

快速安裝 (3 步驟)

選配 MCP Servers

3. 核心架構解析

系統總覽

目錄結構與角色

Context Layers (上下文層) 優先順序

4. 核心功能詳解

4.1 CLAUDE.md 模板系統

4.2 Memory Bank (記憶庫) 系統

4.3 Core Rules (核心規則)

4.4 Session Metrics Skill (Token 用量分析)

4.5 Subagents (子代理)

4.6 Slash Commands (斜線指令)

4.7 Unified Notifier Hook (統一通知系統)

4.8 AI Image Creator

4.9 Dual-AI Consultation (雙 AI 諮詢)

5. 應用場景

場景 A：新專案起步

場景 B：既有專案加入 Memory Bank

場景 C：追蹤 Claude Code 使用成本

場景 D：多 AI 交叉驗證

場景 E：平行開發 (Git Worktree)

6. 資安掃描報告

掃描結果：🟢 安全

7. FAQ

8. 進階技巧

8.1 自訂 Hook Events

8.2 Session Metrics 進階用法

8.3 Chain of Draft (CoD) 觸發

8.4 Statusline 自訂

9. 整合進其他工作流

整合到 CI/CD

整合到 Dev Container

搭配 Z.AI 使用

10. 重點摘要 Checklist

11. 進一步閱讀

Related Posts

Comments