Claude Code 完整實戰指南:從安裝到工作流,踩過的坑都寫下來

如果你剛看完 我為什麼放下了 Cursor,這篇是讓你真的能跑起來的完整教學。

我會從零開始 — 假設你有 terminal 基礎(會用 cd / ls),但完全沒用過任何 AI CLI 工具。

1. 安裝 Claude Code

系統需求

項目	需求
OS	macOS 11+ / Linux / Windows(WSL2 推薦)
Node.js	20+
終端機	iTerm2 / Warp / Windows Terminal / 任何現代 terminal
帳號	Claude.ai 帳號(免費版可註冊,但執行需要 Pro/Max/API key)

安裝指令

# npm 全域安裝(任何系統都行)
npm install -g @anthropic-ai/claude-code

# 或用 brew(macOS)
brew install claude-code

確認安裝:

claude --version
# 應該顯示 1.x.x 之類

第一次認證

打開 terminal,跑:

claude

第一次跑會彈出瀏覽器讓你 OAuth 登入 Claude.ai。登入後 terminal 會顯示「Logged in as [email protected]」。

如果你想用 API key(避免 OAuth):

export ANTHROPIC_API_KEY="sk-ant-..."

(放到 .zshrc / .bashrc 永久生效)

2. 第一個 task — 跟它聊聊

進 terminal 打 cd 到任一資料夾,然後:

claude

進入互動模式。第一句試試:

> 這個資料夾有什麼東西?

Claude Code 會列出資料夾結構。再試:

> 幫我看看 README.md 寫什麼

它會自己讀檔再總結。注意它不需要你貼路徑、不需要你 attach 檔案 — terminal 內它預設知道 cwd。

3. 真實小 task:修一個檔案

假設你想改 package.json 加個 script。傳統做法:

1. 開 editor
2. 找 scripts 區塊
3. 加新 entry
4. 存檔

用 Claude Code:

> 幫我在 package.json 加一個 script:
> "check:all" = "npm run check:content && npm run check:seo && npm run build"

它會:

1. 自己讀 package.json
2. 規劃要怎麼改
3. 顯示 diff 讓你看(這步重要,不是默默改)
4. 等你按 Enter 確認才寫入

不要習慣盲按 Enter — 每次 diff 都看一下,養成「審稿」習慣。

4. 中型 task:跨檔修改

這是 Cursor 不擅長、Claude Code 強的地方。例:

> 把整個專案內所有用「我的舊名」字串的地方,改成「我的新名」。
> 但 .git 跟 node_modules 跳過。

Claude Code 會:

1. 用 grep 找出所有 match
2. 列清單給你看(N 個檔)
3. 你可以說「只改前 3 個」或「全部都改」
4. 它逐檔改 + diff
5. 改完跑 git status 給你看清楚

這個 task 在 Cursor 你要手動切 tab 一個一個改。Claude Code 一句話搞定。

5. 整合 git workflow

Claude Code 對 git 支援極好。常見用法:

> 我剛改了什麼?
→ 它跑 git status + git diff,總結改動

> 幫我寫個 commit message
→ 它讀 diff,寫合理的 commit message,讓你確認

> 把這次改動 commit + push 到 main
→ 它跑 git add + commit + push,每步問你確認

重點:它不會默默 push。每個 destructive 動作(git push、刪檔)都會先確認。

6. 跟你的編輯器整合

Claude Code 是 terminal-native,但這不表示你不能跟 GUI editor 整合。我的設定:

方法 A:VS Code + Claude Code in terminal panel

VS Code 內建 terminal,可以同時開:

• 左邊看檔案
• 中間寫程式碼
• 右下 terminal 跑 Claude Code

兩邊同步改動。VS Code 也會自動 reload 被 Claude Code 改的檔。

方法 B:Cursor / Windsurf + Claude Code

如果你還想保留 Cursor 的 GUI AI,可以兩個 AI 並用:

• 簡單修改用 Cursor(快)
• 大重構用 Claude Code(穩)

實務上我不推薦並用 — 容易混亂。選一個用就好。

7. 進階:常用 patterns

跑熟之後,我固定的 5 個 pattern:

Pattern 1:Debug 流程

> 跑 npm run dev 看看
→ 它跑 dev server
> 開 http://localhost:4321,看 console 有沒有 error
→ 它報告 server log
> 有 error,幫我修
→ 它分析 + 修 + 再跑

Pattern 2:Code review

> 我準備 push 這次 commit,幫我先 review
→ 它讀 diff,給出建議(可能會說「這段邏輯有 race condition」)
> 修一下
→ 它改

Pattern 3:Spike + cleanup

> 我想試試把 X 功能加上,先快速寫一版能跑就好
→ 它寫粗糙但能跑的
> 跑起來!
→ 跑
> 看起來 OK,幫我整理一下,加上 type + error handling
→ 它清乾淨

Pattern 4:Documentation

> 把這次新加的 feature 寫成 docs,markdown 格式,放 docs/features/ 下
→ 它讀程式碼,寫 docs,放到對的位置

Pattern 5:Refactor pieces

> ContentSearch.astro 的 JS 太長了,幫我看看哪段可以抽出來
→ 它讀檔,建議拆分
> 動手抽
→ 它拆,我看 diff,OK 就保留

8. 我踩過的坑

坑 1:Permission 拒絕後不知所措

Claude Code 預設「destructive 動作要確認」。如果你按 No 拒絕,有時候它會卡在「不知道下一步」。解法:明確告訴它「跳過這個,做下一步」。

坑 2:超出 context 上限

長 session 下,context 會堆。到某個點 Claude Code 會跑 /compact 自動壓縮(把舊對話總結)。但壓縮會丟一些細節 —重要的決策記在 markdown 檔,不要只靠 conversation history。

坑 3:中文檔名 / 路徑

我這個專案資料夾名含中文(D:/冬蜜VT_資料檔案/...),早期 Claude Code 對 Windows 中文路徑偶爾出錯。用 WSL2 + Linux mount 路徑可避免。

坑 4:API 額度爆掉

我有次跑大 refactor,一次燒了 $4 美元。Claude Code 每個 message 都消耗 token,大檔案讀多次也算。Pro 訂閱固定月費比較好,API key pay-as-you-go 要設預算警報。

坑 5:跟 git 衝突

如果你在 Claude Code 改檔的同時自己也在 GUI editor 改,容易衝突。Claude Code 工作時你不要也碰檔案。

結論:工具,不是替身

Claude Code 一週上手,一個月真的好用。但它跟 Cursor 一樣 — 是工具,不是替身。

工具的價值,在於「能讓你做你想做的事」,不在於「能替你做事」。

Claude Code 強迫你「先想清楚再說」,而這個強迫,長期下來會讓你思考更扎實。值不值得?看你願不願意花前兩天的卡頓,換接下來的扎實。

如果你也準備跳 Claude Code,我寫了一篇 Cursor → Claude Code 的轉換體驗,那邊是更多「感受面」的紀錄。

有問題到首頁 Discord(支持冬蜜彈窗)聊。