精選 claude-code tutorial guide automation ai-coding

Claude Code 完整指南 2026：從零到精通

2026 年最完整的 Claude Code 指南。學習安裝、必備指令、進階自動化與 Director Mode 工作流程，包含 20 多個實戰範例。

• 更新於 • 15 min read • 作者：Claude World

2026 年 10 月 21 日更新： 本頁原本誤放了一篇一般性的 Claude 入門文章，現已改為與英文、日文版一致的 Claude Code 完整指南，並依 Claude Code 2.1.305 校正安裝（原生安裝程式）、登入、session 與 MCP 指令、改用真實的 settings.json hooks 格式、以權限 deny 規則取代沒有作用的 .claudeignore，模型更新為 Opus 5.5、Sonnet 5.5、Haiku 5.5 與 Fable 5.1。

Claude Code 是 Anthropic 推出、在終端機中運作的 AI 程式設計助手。和傳統的 IDE 外掛不同，Claude Code 是一個代理式（agentic）助手：它能讀懂整個程式碼庫、執行跨多個檔案的複雜操作，並自動化重複性的開發工作。

這份完整指南會帶你從零到精通，涵蓋 2026 年掌握 Claude Code 所需的一切。

為什麼 2026 年要用 Claude Code？

Claude Code 不只是另一個 AI 程式設計工具——它是寫軟體方式的典範轉移：

傳統 AI 助手：
- 聊天機器人介面
- 單一檔案的建議
- 你要自己複製貼上程式碼
- 有限的上下文

Claude Code 2026：
- 原生於終端機
- 跨多個檔案重構
- Claude 直接寫入檔案
- 理解整個程式碼庫

核心能力

功能對你的意義
代理式架構Claude 能自主規劃並執行複雜任務
完整程式碼庫上下文理解整個專案中檔案之間的關係
多檔案操作一次重構、建立、修改多個檔案
終端機整合直接執行指令、測試與 git 操作
Hooks 系統以 PreToolUse/PostToolUse hooks 自動化工作流程
MCP 支援透過 Model Context Protocol 連接外部工具與 API

Part 1：安裝與設定

事前準備

安裝 Claude Code 之前，請確認你具備：

  • macOS 13+、Windows 10 1809+、Ubuntu 20.04+、Debian 10+ 或 Alpine Linux 3.19+，記憶體 4 GB 以上
  • Claude Pro、Max、Team 或 Enterprise 方案，或 Claude Console 帳號（免費的 Claude.ai 方案不含 Claude Code）
# 確認 Git 設定（原生 Windows 建議安裝 Git for Windows）
git --version

# 只有用 npm 安裝時才需要 Node.js 22+
node --version

安裝方式

方法 1：原生安裝程式（建議）

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# 確認安裝
claude --version

原生安裝會在背景自動更新。

方法 2：Homebrew、WinGet 或 npm

# Homebrew
brew install --cask claude-code

# WinGet（Windows）
winget install Anthropic.ClaudeCode

# npm（需要 Node.js 22+；不要使用 sudo）
npm install -g @anthropic-ai/claude-code

Homebrew 與 WinGet 安裝不會自動更新，請定期升級。

初始設定

# 啟動 Claude Code（第一次執行）
claude

# 依照瀏覽器提示，用 Claude 訂閱或 Claude Console 帳號登入
#（也可以執行：claude auth login）

# 若要以 API 計費，也可以改設定 Claude Console 的金鑰
#（https://platform.claude.com），並在 Claude Code 詢問時核准使用
export ANTHROPIC_API_KEY='your-api-key-here'

確認安裝

# 不啟動 session，直接檢查安裝與設定
claude doctor

# 執行一次性的提示後結束
claude -p "Say hello"

Part 2：必備指令

基本工作流程

Claude Code 在終端機中使用對話式介面：

$ claude

🤖 Hi! I'm Claude, your AI coding assistant.
   I can help you write, refactor, and understand code.

💬 How can I help you today?

You: Create a React login form component

Claude: I'll create a Login component for you.
   Let me first check your project structure...
   [Reading src/]
   [Reading package.json]

   I'll create src/components/Login.jsx with:
   - Email/password fields
   - Form validation
   - Submit handler
   - Error display

   [Writing src/components/Login.jsx]
   ✅ Created Login component!

   Would you like me to:
   1. Add form validation
   2. Create API integration
   3. Write tests
   4. Something else

You:

核心指令

指令說明範例
claude啟動互動 sessionclaude
claude "prompt"以初始提示啟動 sessionclaude "fix this bug"
claude -p "prompt"一次性指令（列印模式），完成後結束claude -p "explain this function"
claude --model sonnet指定模型claude --model sonnet "review code"
claude --help顯示所有選項claude --help
按兩次 Ctrl+C，或 /exit結束 session-

Session 管理

# 繼續此目錄最近的一段對話
claude --continue

# 從清單中挑選先前的 session（或直接傳入 ID 或名稱）
claude --resume

# 在 session 中：重新開始，但保留專案記憶
/clear

Part 3：理解專案

Claude Code 擅長理解整個程式碼庫。以下是善用這項能力的方法：

自動程式碼庫分析

Claude Code 不會事先為你的儲存庫建立索引。每個 session 會載入你的 CLAUDE.md（或 AGENTS.md）指示與 git 狀態，之後 Claude 依每個任務的需要搜尋並讀取檔案。先執行一次 /init 能讓它更快上手：

$ claude
> /init

# Claude 會分析程式碼庫，寫出一份初始 CLAUDE.md，
# 內容包括它找到的建置指令、測試說明與慣例。
# 之後的 session 會自動載入；隨時可以用 /memory 調整。

明確的上下文指令

# 請 Claude 解釋某個檔案
You: Explain how auth works in this project

Claude: Let me trace through your authentication system...
   [Reading src/auth/context.tsx]
   [Reading src/auth/provider.tsx]
   [Reading src/middleware.ts]

   Your auth flow:
   1. User logs in via Login component
   2. Credentials sent to /api/auth/login
   3. Server validates and returns JWT
   4. JWT stored in localStorage
   5. AuthProvider manages session state
   6. Protected routes check auth context

   Key files:
   - src/auth/context.tsx (Auth state)
   - src/middleware.ts (Route protection)
   - src/api/auth.ts (API calls)

跨檔案重構

# 實例：在整個程式碼庫中重新命名函式
You: Rename handleSubmit to onSubmitForm throughout the project

Claude: I'll rename handleSubmit to onSubmitForm.
   Searching for all occurrences...

   Found in 8 files:
   - src/components/Form.jsx
   - src/components/Signup.jsx
   - src/utils/form.js
   - tests/form.test.js
   (and 5 more)

   [Updating src/components/Form.jsx]
   [Updating src/components/Signup.jsx]
   ...

   ✅ Renamed in 8 files successfully
   ✅ Updated all imports and references

Part 4：進階自動化

Hooks：自動化的超能力

Claude Code hooks 會在 Claude 生命週期的固定時間點執行你自己的指令，例如工具呼叫之前或之後。你在 settings.json（使用者、專案或本機）中註冊 hooks，每個 hook 都會從 stdin 以 JSON 收到事件內容。

Hook 類型

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' >> ~/claude-edits.log" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npm test --silent" }
        ]
      }
    ]
  }
}

常見事件有 PreToolUse（在工具呼叫前執行，可以阻擋它）、PostToolUse、UserPromptSubmit、Stop、SessionStart 與 Notification。除了 command，hook 也可以是 http、prompt、agent 或 mcp_tool 處理器。在 session 中執行 /hooks 可查看已註冊的 hooks。

實用 Hook 範例

自動安全檢查：

#!/bin/bash
# .claude/hooks/protect-files.sh：防止 Claude 修改敏感檔案
FILE_PATH=$(jq -r '.tool_input.file_path // empty')

for pattern in ".env" "secrets.json" "prod-config"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: cannot modify $FILE_PATH" >&2
    exit 2  # 結束碼 2 會阻擋工具呼叫，並把原因告訴 Claude
  fi
done
exit 0
// .claude/settings.json（請先用 chmod +x 讓腳本可執行）
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }
        ]
      }
    ]
  }
}

如果只是要擋特定路徑，用 Edit(.env*) 這類 permissions.deny 規則就能達到同樣效果，不需要腳本。

存檔時自動格式化：

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

MCP 整合

Model Context Protocol（MCP）讓 Claude Code 能連接外部工具與 API。

安裝 MCP 伺服器

# 範例：Notion（遠端 HTTP 伺服器）
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 範例：GitHub MCP 伺服器（遠端，使用個人存取權杖）
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

# 範例：自訂的本機 MCP 伺服器（stdio）
claude mcp add my-server -- node ./my-mcp-server/index.js

沒有 claude mcp install 這個指令。在 session 中執行 /mcp（或 claude mcp list）確認每個伺服器都已連線。

在對話中使用 MCP

You: Check if there are any new issues in our GitHub repo

Claude: Let me check your GitHub issues...
   [MCP: github.list_issues]

   Found 5 open issues:

   1. #142 - Memory leak in useEffect (3 days ago)
   2. #141 - Add dark mode support (5 days ago)
   3. #140 - Fix mobile navigation (1 week ago)

   Would you like me to:
   - Tackle the memory leak issue?
   - Implement dark mode?
   - Fix mobile navigation?

Part 5：Director Mode

Director Mode 是發揮 Claude Code 全部潛力的關鍵。與其逐行微管理程式碼，不如像技術主管一樣指揮 Claude。

思維轉換

微管理模式（低效率）：
- "Write a function that..."
- "Change this variable to..."
- "Add a parameter for..."
- "Refactor this loop to..."

Director Mode（高效率）：
- "Implement user authentication with JWT"
- "Optimize this database query for performance"
- "Add error handling to this API endpoint"
- "Refactor this component for better testability"

Director Mode 最佳實踐

1. 給出明確目標

# ❌ 模糊
You: Make the code better

# ✅ 明確的目標
You: Refactor this component to improve maintainability:
- Extract logic into custom hooks
- Add TypeScript types
- Write unit tests
- Follow React best practices

2. 提供背景

# ❌ 沒有背景
You: Fix the bug

# ✅ 有背景
You: Users report that the login form doesn't submit on mobile.
   I suspect it's a form validation issue.
   The form is in src/components/Login.jsx
   Can you investigate and fix it?

3. 讓 Claude 規劃

# ❌ 微管理
You: First check the file, then look at line 42,
   then change the condition, then add a console log...

# ✅ 讓 Claude 規劃
You: Users are experiencing slow load times on the dashboard.
   Investigate performance issues and propose optimizations.

Part 6：常見工作流程

工作流程 1：開發新功能

$ claude

You: I need to add user comments to blog posts

Claude: I'll help you add a commenting system. Let me plan this:
   1. Create Comment component
   2. Add comment API endpoints
   3. Update blog post display
   4. Add comment form
   5. Store comments in database

   Does this plan work for you?

You: Yes, but use the existing database schema

Claude: Let me check your schema first...
   [Reading prisma/schema.prisma]

   I see you already have a Comment model.
   I'll use that instead.

   [Implementing commenting system...]
   ✅ Created components/CommentSection.tsx
   ✅ Created api/comments/route.ts
   ✅ Updated pages/blog/[id].tsx
   ✅ Added comment form

   Ready for testing!

工作流程 2：除錯

You: The search feature isn't working

Claude: Let me investigate...
   [Reading components/SearchBar.tsx]
   [Reading api/search/route.ts]
   [Reading utils/search.js]

   Found the issue! In utils/search.js line 42:
   The filter function is case-sensitive, but your data
   has mixed case. This causes search failures.

   [Fixing utils/search.js]
   ✅ Fixed: Added toLowerCase() to filter

   Would you like me to write a test to prevent regression?

工作流程 3：程式碼審查

You: Review this PR for best practices

Claude: I'll review the changes...
   [Reading PR #142 - Feature/user-dashboard]

   Review Summary:

   🟢 Strengths:
   - Good separation of concerns
   - Proper error handling
   - Clear variable names

   🟡 Suggestions:
   - Consider adding TypeScript strict mode
   - Some functions could be extracted for reusability
   - Missing unit tests for utility functions

   🔴 Issues:
   - Line 87: Potential SQL injection risk
   - Missing authentication check on /api/dashboard
   - Memory leak in useEffect (missing cleanup)

   I can fix these issues. Should I proceed?

Part 7：效能與成本最佳化

降低 token 用量

Claude Code 不會讀取 .claudeignore 檔案。要讓 Claude 的檔案工具遠離產生出來的檔案或敏感檔案，請改用 Read deny 規則：

// .claude/settings.json
{
  "permissions": {
    "deny": [
      "Read(./node_modules/**)",
      "Read(./dist/**)",
      "Read(./build/**)",
      "Read(./coverage/**)",
      "Read(./.env*)"
    ]
  }
}

執行 /context 查看上下文視窗被什麼佔用，太擁擠時用 /compact 或 /clear。

快取上下文

# Claude 會快取你的專案上下文
# 重複使用 session，避免重新讀取檔案

$ claude --continue

# 以快取的上下文繼續

模型選擇

任務建議模型成本／效能
快速提問Haiku 5.5最快、最便宜
產生程式碼Sonnet 5.5快速且成本較低
複雜重構Opus 5.5預設模型，也是 Anthropic 建議的起點（支援 /fast）
最困難的架構與判斷工作Fable 5.1能力最強的等級；不會是預設
大型程式碼庫Sonnet 5.5最划算，具備 1M token 上下文視窗

在 Anthropic API 上的 Claude Code，haiku、sonnet、opus、fable 別名都指向上述模型。Opus 5.5、Sonnet 5.5 與 Haiku 5.5 預設以 medium effort 執行；遇到較難的工作，可用 /effort 調高。

Part 8：疑難排解

常見問題

問題：“API key not found”

# 解法：登入，再確認目前使用的是哪個憑證
claude auth login
claude auth status --text
# 若要以 API 計費，改設定 Claude Console 的金鑰
export ANTHROPIC_API_KEY='your-key'

問題：“Context too large”

# 解法：先看 /context，再 /compact，或把需求講得更具體
You: Only look at src/auth/, not the whole project

問題：“Hook not triggering”

# 解法：確認 hook 已註冊、腳本可執行
/hooks                         # 在 session 中：列出已註冊的 hooks
chmod +x .claude/hooks/*.sh
claude --debug                 # hook 的執行紀錄會寫到 ~/.claude/debug/<session-id>.txt

Part 9：最佳實踐

該做與不該做

✅ 該做：

  • 給出明確的目標與背景
  • 實作前先讓 Claude 規劃
  • commit 前審查變更
  • 用 hooks 自動化
  • 善用 MCP 整合

❌ 不該做：

  • 逐行微管理程式碼
  • 忽略 Claude 的建議
  • 跳過程式碼審查
  • 忘了測試 Claude 的產出
  • 用 Claude 處理一行就能改完的小事（改用你的 IDE）

進階技巧

  1. 開場就講清楚：「我想要 [目標]。背景是：[細節]」
  2. 請 Claude 解釋：問「你為什麼選這個做法？」
  3. 協作式迭代：「不錯，但能不能最佳化 X？」
  4. 向 Claude 學習：遇到不熟悉的模式就發問
  5. 建立工作流程：為常用任務建立 hooks

Part 10：下一步

持續學習

  1. 練習：只用 Claude Code 完成一個小專案
  2. 探索：嘗試不同的 MCP 伺服器
  3. 客製化：建立你自己的 hooks
  4. 分享：為團隊記錄你的工作流程

進階主題

  • 多檔案重構：大規模改善程式碼庫
  • 產生測試：用 Claude Code 自動化測試
  • 文件：從程式碼自動產生文件
  • CI/CD 整合：自動化部署工作流程

常見問題

Claude Code 是免費的嗎？

不是。Claude Code 需要 Claude Pro、Max、Team 或 Enterprise 訂閱，或以 token 計費的 Claude Console 帳號；免費的 Claude.ai 方案不包含 Claude Code。以 API 計費時，成本取決於用量與使用的模型：Haiku 5.5（每百萬輸入／輸出 token $0.10/$0.50，適用 100K 以內的提示）、Sonnet 5.5（$2/$10）、Opus 5.5（$4/$20）或 Fable 5.1（$10/$50）。最新費率請查閱 Anthropic 官方定價頁。

根據 Anthropic 的成本文件，企業部署的平均花費約為每位開發者每個活躍日 $13，或每位開發者每月 $150–250。

Claude Code 能取代我的 IDE 嗎？

不能，Claude Code 是 IDE 的補充。以下情況用 Claude：

  • 複雜的多檔案操作
  • 理解大型程式碼庫
  • 自動化重複性工作

以下情況用 IDE：

  • 快速編輯
  • 語法標示
  • 除錯

用 Claude Code 時我的程式碼安全嗎？

是的。Claude Code：

  • 在你的電腦上本機執行
  • 只把相關的程式碼上下文傳送到 API
  • 遵守 Read(./.env) 這類 permissions.deny 規則來保護敏感檔案
  • 可以透過 Amazon Bedrock、Google Cloud’s Agent Platform 或 Microsoft Foundry 傳送請求

Claude Code 和 Claude.ai 有什麼不同？

  • Claude Code：用於終端機、IDE、桌面 App 與網頁的代理式程式設計工具
  • Claude.ai：提供一般 AI 協助的網頁介面

兩者使用相同的 Claude 模型，但介面與使用情境不同。

結語

2026 年的 Claude Code 不只是 AI 程式設計助手——對懂得有效運用它的開發者來說，它是能力倍增器。

重點整理：

  1. ✅ 從明確的目標與背景開始
  2. ✅ 採用 Director Mode 取得更好的成果
  3. ✅ 用 hooks 自動化你的工作流程
  4. ✅ 整合 MCP 伺服器擴充能力
  5. ✅ 審查並測試 Claude 的產出

下一步：在你的下一個功能開發中開始使用 Claude Code。用得越多，你就越擅長指揮你的 AI 開發團隊。

準備好升級你的開發工作流程了嗎？看看我們的 Claude Code vs Cursor 比較，或了解 Director Mode 方法論。

參考資料：