[AI] Claude Code 基礎指南

Claude Code 的安裝、設定、Skill、Hook、MCP 操作速查。

0. Claude 的幾種使用方式

這篇以 Claude Code 為主。Claude Desktop 的設定邏輯大致相通，學一套就夠。

1. 安裝與啟動

1-1. 安裝 Claude Code

需要 Node.js 18 以上，裝成全域套件：

npm install -g @anthropic-ai/claude-code

驗證一下：

claude --version

印得出版本號就是裝好了。

1-2. 登入

第一次啟動會要求登入：

claude

照畫面指示在瀏覽器完成 Anthropic 帳號登入，token 會寫進 ~/.claude/，之後啟動就不用再登入。

1-3. 啟動 Claude Code

在專案根目錄啟動：

cd my-project
claude

啟動後進入互動介面，直接用自然語言下指令：

> 幫我看一下 src/utils/date.ts 這支檔案在做什麼

Claude 會自己讀檔、解釋給你聽；要動手改東西之前，會先問過你。

1-4. 下載 Claude Desktop

從 claude.ai/download 抓對應作業系統的版本（Mac / Windows）。登入同一個 Anthropic 帳號後，MCP 和 skill 設定可以跟 Claude Code 共用。

2. CLAUDE.md vs settings.json — 兩個核心設定

兩者管的事情不一樣：

• CLAUDE.md：規範 Claude 做事的方式
• settings.json：界定 Claude 可以做哪些動作

2-1. CLAUDE.md — 專案說明書

用途：寫下專案規範、架構、coding style、commit 規則和必要的背景知識。Claude Code 每次啟動都會自動讀進來，產出的程式碼就會照著這份規範走。

檔案位置：

Windows 的 ~ 會展開成 C:\Users\<username>，例如 C:\Users\Jeremy\.claude\CLAUDE.md。

適合寫什麼：

• 技術棧、目錄結構
• Coding style（命名規則、縮排、要不要加分號）
• Commit message 規範、PR 流程
• 常見踩雷與 workaround
• 哪些檔案禁止修改

範例 CLAUDE.md：

# my-blog 專案規範

## 技術棧
- Astro 5 + Svelte 5 + Tailwind 4

## Coding Style
- 單引號、不加分號、2 空格縮排
- 不用相對父層引用，用 `@/` alias
- 禁止 `var`，只用 `const` / `let`

## Commit 規則
- 格式：`<type>: <描述>`
- type：feat / fix / docs / refactor / chore
- 不要 amend 已 push 的 commit

## 絕對不要動
- `src/models/menu.ts`（路由 SSOT，改動要先討論）
- `.env`（含密鑰）

2-2. settings.json — 權限與工具設定

用途：控制 Claude Code 能做什麼——允許哪些工具、哪些指令不用每次確認、載入哪些 MCP server、掛哪些 hook。

檔案位置：

settings.local.json 通常會加進 .gitignore，拿來放個人的 MCP token 和私有偏好，避免不小心 commit 進 repo。

最常用的是 permissions：

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test)",
      "Bash(git status)",
      "Bash(git diff)",
      "Read(**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)"
    ]
  }
}

• allow：列在這裡的指令，Claude 執行前不會再問你
• deny：列在這裡的指令，永遠禁止

其他常見欄位：

{
  "model": "claude-opus-4-7",
  "env": {
    "ANTHROPIC_API_KEY": "..."
  },
  "mcpServers": { /* MCP 設定，見 §5 */ },
  "hooks": { /* Hook 設定，見 §4 */ }
}

2-3. 兩者的關係

舉個例子，你說「修掉 lint error」，Claude 的處理流程是：

1. 讀 CLAUDE.md → 知道專案用 ESLint、單引號、不加分號
2. 讀 settings.json → 知道 npm run lint 已經在 allow 名單，不用再問
3. 執行 npm run lint、分析結果、修改程式碼

簡單記：CLAUDE.md 是「規範」，settings.json 是「權限」。兩者都分全域和專案兩層，專案層蓋過全域層。

3. Skill 系統

3-1. Skill 是什麼

Skill 是預先封裝好、可以重複使用的能力包，裡面有描述、指令和相依工具。Claude 在對話中判斷需要時會自動觸發，你也可以主動呼叫。

官方預裝的 skill：

3-2. 查看 / 呼叫 skill

在 Claude Code 輸入：

/skills

就能列出目前可用的 skill。要主動呼叫的話：

/pdf 把 report-q1.pdf 和 report-q2.pdf 合併

3-3. Skill 檔案位置

每個 skill 是一個資料夾，至少要有 SKILL.md：

~/.claude/skills/pr-reviewer/
├── SKILL.md          # skill 描述與使用說明
├── checklist.md      # skill 參考資料
└── scripts/
    └── run-review.sh # 可執行 helper

SKILL.md 開頭用 frontmatter 寫 metadata：

---
name: pr-reviewer
description: 根據團隊 code review checklist 產出審查報告
---

# PR Reviewer

## 使用方式
當使用者說「幫我 review 這個 PR」時，讀取 PR diff 並對照 checklist.md 檢查：
1. 命名一致性
2. Error handling
3. 測試覆蓋
...

3-4. 自訂 skill

最快的做法是直接請 Claude 幫你生：

/skill-creator 幫我建一個 skill：
功能是讀取 PR diff、對照我們的 code review checklist 產出審查報告

Claude 會在 .claude/skills/ 底下自動建好資料夾和 SKILL.md。

4. Hook 系統

4-1. Hook 是什麼

Hook 是在特定事件發生時自動執行的 shell 指令。典型用途：

• Claude 改完程式，自動跑 lint
• 呼叫工具前，自動備份
• 請求權限時，推一則 Slack 通知

4-2. 事件類型

4-3. Hook 設定位置

Hook 寫在 settings.json 的 hooks 欄位：

• 全域：~/.claude/settings.json
• 專案：<project-root>/.claude/settings.json

4-4. 範例：改完檔案自動 lint

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

• matcher: "Edit|Write"：只在 Claude 呼叫 Edit 或 Write 時觸發
• command：要執行的 shell 指令
• $CLAUDE_FILE_PATH：Claude 自動帶入被編輯的檔案路徑

4-5. 範例：commit 前先跑 test

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'git commit'; then npm test; fi"
          }
        ]
      }
    ]
  }
}

5. MCP（Model Context Protocol）

5-1. MCP 是什麼

MCP 是 Anthropic 推行的開放協定，讓 Claude 能跟外部工具與服務溝通。

Claude 本身不內建 Notion、GitHub 這些服務的連線——但只要那個服務有 MCP server，加進設定之後就能直接操作。

常見的 MCP server：

5-2. MCP 設定位置

寫在 settings.json 的 mcpServers 欄位：

• 全域：~/.claude/settings.json
• 專案：<project-root>/.claude/settings.json
• 本機私有（不進 git）：<project-root>/.claude/settings.local.json

含 token 的設定建議放 settings.local.json，並加入 .gitignore。

5-3. 範例：接 Notion

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_API_KEY": "secret_xxxxxxxxxx"
      }
    }
  }
}

設定完重啟 claude，就可以這樣用：

> 幫我搜 Notion 裡所有標籤是 "frontend" 的頁面，整理成清單

5-4. 範例：接本機 filesystem（細粒度權限）

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/jeremy/projects/my-blog"
      ]
    }
  }
}

這個 MCP server 只能存取指定的資料夾，比 Claude Code 預設的全盤存取更安全。

5-5. 尋找 MCP server

• 官方 registry：modelcontextprotocol.io/registry
• 在 Claude 裡輸入 search_mcp_registry 搜關鍵字
• 大多數可以直接用 npx 跑起來，不用自己建置

6. 常用指令速查

在 Claude Code 互動介面裡，/ 開頭的是內建指令：

7. Model 選擇與 Prompt 技巧

7-1. 三個模型怎麼選

7-2. Prompt：具體 vs 模糊

模糊（產出不可預期）：

幫我寫一個驗證函式

具體（產出貼近預期）：

幫我寫一個 TypeScript 函式 validateEmail：
- 參數：string
- 回傳：{ valid: boolean; error?: string }
- 規則：
  1. 不能為空
  2. 必須含 @ 和 .
  3. @ 前至少一個字元
  4. 不允許連續的 ..
- 位置：src/utils/validate.ts
- 風格：專案用單引號、無分號

差別在於把輸入 / 輸出格式、規則、位置、風格這四個面向的限制都講清楚了。

7-3. 提問時附上完整 context

Debug 時不要只丟一句「build 壞了」，把完整 error 和相關程式碼一起貼上：

我跑 npm run build 遇到這個錯誤：

<貼完整 stack trace>

相關檔案：

<貼 src/xxx.ts>
<貼 astro.config.mjs>

我預期的行為是 ...

8. 其他事項

8-1. Permission mode

Claude Code 啟動時可以切換權限模式：

claude --permission-mode plan        # 只規劃、不動手
claude --permission-mode acceptEdits # 自動允許改檔案
claude --permission-mode bypassPermissions # 全自動（危險）

預設是每個有副作用的操作都要你確認一次。還不熟之前，建議維持預設。

8-2. 不應 commit 的檔案

放個人 token 和偏好設定的路徑，要加進 .gitignore：

.claude/settings.local.json
.claude/.env

團隊共用的設定則放 .claude/settings.json 並 commit，這樣所有成員 clone 下來就有一致的 hook / MCP 基礎設定。

8-3. 停止與回退

• Esc 可以中斷目前的輸出
• 跟它說「請停止」、「還原剛才的修改」，Claude 會嘗試復原
• 用 git status / git diff 確認實際改了什麼
• 重要操作前先 git commit，出問題還能 git reset 救回來

9. 總結

• 安裝：npm install -g @anthropic-ai/claude-code → claude
• 規範 Claude 行為：CLAUDE.md
• 控制 Claude 權限：.claude/settings.json
• 預裝能力：/skills 查看，檔案放在 ~/.claude/skills/ 或 .claude/skills/
• 事件自動化：settings.json 的 hooks
• 外部服務連線：settings.json 的 mcpServers
• 模型切換 / 對話壓縮 / 費用查詢：/model、/compact、/cost

完整生態：

使用者 ─> Claude Code / Desktop
           │
           ├── 讀 CLAUDE.md     → 知悉專案規範
           ├── 讀 settings.json → 知悉可用工具、hook、MCP
           │
           ├── 內建工具：Read / Edit / Write / Bash / Glob / Grep
           ├── Skill：可重複使用的任務模板（docx、pdf、自訂…）
           ├── Hook：事件驅動的 shell 指令
           └── MCP：外部世界（Notion / GitHub / Slack / Chrome…）

要擴充 Claude 的能力時，照這個順序判斷：

1. 想改它做事的方式 → CLAUDE.md
2. 想開放或禁止工具 → settings.json 的 permissions
3. 想在特定時機自動跑腳本 → hooks
4. 想連外部服務 → mcpServers
5. 想封裝重複的任務流程 → skill