Claude Code 教學：安裝、CLAUDE.md、skills 到先寫 spec 的工作流

Claude Code 是 Anthropic 的 AI 程式開發工具，在終端機裡讀你的專案、改檔案、跑指令。上手的順序是：裝好並登入，把專案規則寫進 CLAUDE.md，把重複的做法寫成 skill，做功能時先寫 spec 再寫 plan；subagents、hooks 和 MCP 分別用來分出旁支工作、強制執行規則、連接外部工具。功能說明以 Anthropic 官方文件為準。

Claude 和 GPT 的方案我都有訂，Claude Code 是我用的工具之一。去年底開始，我逐漸把 AI 接進開發流程，讓它協助 review PR，甚至處理 merge。

安裝與第一次啟動

官方建議用原生安裝程式。macOS、Linux、WSL 執行：

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex

也可以用 Homebrew（brew install --cask claude-code）或 WinGet（winget install Anthropic.ClaudeCode）。原生安裝會在背景自動更新，Homebrew 和 WinGet 要自己升級。裝完開一個新的終端機視窗，跑 claude --version，印出版本號就是裝好了。

接著進到專案資料夾啟動：

cd /path/to/your/project
claude

第一次啟動會要求登入。可以用 Claude 訂閱方案（Pro、Max、Ultra、Team、Enterprise）、Claude Console 帳號，或透過 Amazon Bedrock 這類雲端供應商。

幾個一開始就用得到的指令：

• /init：分析專案，產生第一版 CLAUDE.md。已經有 CLAUDE.md 的話，它會提修改建議，不會覆蓋。
• Shift+Tab：切換權限模式，決定哪些動作 Claude 可以不問你直接做。
• /clear：清掉目前的對話，換到不相關的任務前用。
• claude -c 接續這個資料夾最近一次的對話，claude -r 從清單挑一個舊對話。

第一個任務可以很小。官方 quickstart 建議先讓它讀專案，問「這個專案在做什麼」，再試一個小修改。

CLAUDE.md：寫下 AI 從程式碼讀不出來的事

每次開新對話，Claude Code 的 context 都是空的。CLAUDE.md 是它每次啟動都會讀進來的說明檔，常用的位置有三個：

位置	用途
~/.claude/CLAUDE.md	個人偏好，所有專案都會讀
./CLAUDE.md 或 ./.claude/CLAUDE.md	專案規則，放進版本控制跟團隊共用
./CLAUDE.local.md	只給自己的專案設定，加進 .gitignore

官方文件提到幾個寫法重點：

• 每個檔案控制在 200 行以內。檔案越長，佔掉的 context 越多，遵守度也會下降。
• 寫到可以檢查的程度。「commit 前跑 npm test」比「記得測試」有用。
• 只寫程式碼裡看不出來的事：怎麼跑測試、哪裡容易誤導、團隊做過哪些決定、已經糾正過兩次的事。架構和檔案結構不用寫，Claude 會自己讀 repo。
• 可以用 @path/to/file 匯入其他檔案，最多四層。匯入方便整理，但匯入的內容一樣會佔 context。

我的網站專案 CLAUDE.md 節錄如下（有刪減）：

# personal-website — agent notes

- Design spec: read `DESIGN.md` before changing anything visible.
- Work directly on `main` unless Kelvin asks for a branch.
  Pushing to `main` deploys (Cloudflare Workers Builds).
- Tests: `npx vitest run`. Mobile checks per `DESIGN.md` §0.5 and §7.
- SEO Monitor: Loaded with: @seo/CLAUDE-SEO.md

畫面設計的規則放在 DESIGN.md，CLAUDE.md 只用一行要求改畫面前先讀它。SEO 的工作指南由另一個系統維護，這裡用 @ 匯入，不另外複製一份。我在 Day 5 寫過這件事：規則寫在文件裡，AI 改功能時有依據，不用每次重講；我也能直接改文件，把之後要遵守的決定留下來。

全域那一層，我的 ~/.claude/CLAUDE.md 只有一行，用 @ 匯入一份 AGENTS.md。真正的規則都在那份檔案，Codex 讀的也是同一份，所以兩個工具看到同一套規則，改一次就好。官方文件也說明，repo 裡沒有 CLAUDE.md 時，Claude Code 會直接讀 AGENTS.md；兩種檔案都有時預設只讀 CLAUDE.md，要共用就在 CLAUDE.md 裡用 @AGENTS.md 匯入。

Skills：把重複的做法寫成技能

一個 skill 就是一個資料夾，裡面放一份 SKILL.md。開頭的 YAML frontmatter 告訴 Claude 什麼時候該用，後面寫它要照著做的步驟：

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks.

!`git diff HEAD` 這一行會先由 Claude Code 執行，把輸出換進 skill 內容，Claude 讀到的就是目前的 diff。

放在 ~/.claude/skills/<名稱>/SKILL.md 是個人技能，所有專案都看得到；放在專案的 .claude/skills/<名稱>/SKILL.md，commit 之後團隊也拿得到。平常 Claude 只看每個 skill 的 description，判斷相關才載入全文；也可以打 /skill-名稱 直接叫用。舊的 .claude/commands/ 自訂指令已經併進 skills，原本的檔案照樣能用。

別人做好的 skill 多半包成 plugin 發布。Anthropic 的官方 marketplace 在第一次開互動 session 時就會自動加好，其他來源要先加 marketplace：

/plugin marketplace add owner/repo
/plugin install 名稱@marketplace

plugin 可以帶 hooks 和 MCP server，安裝前先看它會裝哪些東西。

我的 skill 從哪裡來，Day 6 寫過。我會先看開源專案，中國、美國的都看，也找其他語系的版本。中國開源社群常在海外專案的基礎上補上更多中文說明和細節，順著原版、衍生版看下去，常能找到不同的東西。另外我也會留意 X 上別人分享的 skill。我的流程裡用到 Superpowers 的 brainstorming 和 writing-plans，寫文章時則用 humanizer-zh-tw 修稿。

共用的部分，我同時用 Claude Code 和 Codex，兩邊讀 skill 的目錄不同（Claude Code 是 ~/.claude/skills，Codex 那邊我用 ~/.agents/skills）。我開了一個 git repo 專門放 AI 設定：

• skills/：自己維護的 skill
• vendor/：第三方 skill 的快照，不直接改，要更新就整包換成新版
• skills.manifest：正本放在其他專案 repo 的 skill，一行一個

再寫一支 setup.sh，用 symlink 把這些 skill 同時連到兩邊。兩邊指向同一份檔案，不複製；只裝在其中一邊的 skill，它也會鏡像到另一邊。setup.sh --check 只檢查不動手，列出還沒連結、只在一邊、或兩份內容分岔的 skill。第三方 skill 用快照，是為了讓同事照著裝，拿到的版本跟我一模一樣。

先寫 spec，再寫 plan，review 完才動手

我用 AI 做功能的順序是：先寫 spec，再寫 plan，review 過後才執行。Day 9 有完整的例子。

AI 常常一開口就給三個選項，我們很自然就開始比較，挑一個做。但它列出的選項，未必包含最適合自己的做法，因為自己的使用習慣、真正覺得麻煩的地方，可能根本還沒告訴它。所以我會這樣做：

1. Brainstorming：用 Superpowers 的 brainstorming，讓它先了解專案和我的目的，透過提問把需求問清楚。
2. 寫 spec：說清楚目的、使用流程、範圍和完成條件。之後的實作要受它約束；做到一半發現規劃不對，就回頭改 spec，把改動和理由寫下來。
3. 寫 plan：用 Superpowers 的 writing-plans 展開成能逐項執行的步驟。每一步要完成什麼、前面要準備什麼、做完怎麼檢查，需要我開權限或給設定的地方也先列出來。
4. Review：把 plan 拿回去對照 spec，確認這些步驟做完，真的能解決一開始的問題。
5. 執行：交給 agent 跑，最後我看實際成果驗收。

Claude Code 本身有兩個功能可以搭配：

• Plan mode：按 Shift+Tab 切到狀態列顯示 ⏸ plan mode on，或用 claude --permission-mode plan 啟動。這個模式下 Claude 只讀檔、提計畫，你核准之前不會改任何檔案。
• /goal：設定一個完成條件，每一輪結束後由另一個模型判斷條件是否成立，還沒成立就繼續做。條件要寫成對話裡能證明的事，例如「npm test 結束碼為 0」，再寫上哪些東西不能動。

Day 5 我舉過一個文章草稿的完成條件：

把確認過的大綱整理成繁體中文文章，保存到指定的 Studio 草稿，重新讀取並確認正文一致。維持待審狀態，不發布；如果無法保存，交代卡住的原因並保留稿件。

成果放哪裡、怎麼確認存對了、哪些操作不在範圍內，都寫清楚，AI 才有依據判斷自己做完了沒有。

Subagents：把旁支工作移出主對話

Subagent 有自己的 context window、system prompt 和工具權限。適合的情況是：一件旁支工作會帶進一大堆搜尋結果、log 或檔案內容，而你之後不會再看它們。subagent 在自己的 context 裡做完，只回傳摘要。

Claude Code 內建幾個：Explore（唯讀，專門搜尋和分析程式碼）、Plan（plan mode 時蒐集資料用）、general-purpose（要探索也要動手的多步驟任務）。自訂的放在專案的 .claude/agents/ 或個人的 ~/.claude/agents/，格式是 Markdown 加 frontmatter：

---
name: reviewer
description: Reviews changed files against the spec they were built from.
tools: Read, Grep, Glob
---
You're reviewing code you didn't write. Compare the changed files against the spec,
and report only the gaps that affect correctness. Skip style.

tools 只給讀取類工具，它就只能看、不能改。這個限制由 Claude Code 執行，prompt 怎麼寫都改變不了。官方文件也提醒，subagent 主要花的是 token；同一個任務交給它，答案不會因此變好。它的用處在平行處理、隔開大量輸出，以及找一個沒看過推理過程的 reviewer。

我的 skill 清單裡有一個 subagent-driven-development：執行 plan 時，每個獨立任務交給一個新的 subagent，任務之間再做 code review。

Hooks 與 MCP

CLAUDE.md 和 skill 都是給模型讀的 context。模型通常會照做，但沒有保證。一定要發生、或絕對不能發生的事，要交給 hooks：在 Claude Code 生命週期的特定時間點執行的 shell 指令，由程式負責，不靠模型判斷。

官方的例子是每次編輯檔案後自動跑 Prettier，寫在專案的 .claude/settings.json：

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

PreToolUse 在工具執行前觸發，腳本以結束碼 2 退出就能擋下這個動作。設好之後用 /hooks 確認有沒有載入。

我在全域設定裡掛了一個 PreToolUse hook，AI 透過 Supabase MCP 執行 SQL 之前先檢查一遍，刪表、清空資料這類破壞性的語句會跳出確認，讓我看過完整的 SQL 再決定。

MCP（Model Context Protocol）是讓 Claude Code 連接外部工具和資料來源的開放標準。加一個遠端 server：

claude mcp add --transport http <name> <url>

預設的 scope 是 local，只有你在這個專案能用；加上 --scope project 會寫進專案根目錄的 .mcp.json，跟著 repo 分享給團隊。我的網站 repo 就用 .mcp.json 登記了一個讀 SEO 資料的 MCP 工具，檔案裡沒有任何金鑰，憑證放在本機的私有設定檔。另外要記得官方的提醒：連接前先確認你信任這個 server，會抓取外部內容的 server 有 prompt injection 的風險。

常見的坑

• 把 CLAUDE.md 寫成說明書。架構和檔案結構 Claude 會自己讀，檔案越長，遵守度越低。留下測試指令、容易誤導的地方和已經做過的決定就好。
• 以為 CLAUDE.md 能強制執行。它只是給模型讀的 context，模型可能不照做。不能有例外的規則，改用 hook 或權限規則。
• 「說寫好了」不等於「存好了」。工具回報完成後，程式要跑對應的測試，畫面要看實際呈現，文章要確認存進正確的位置。也可以直接要證據：跑了哪個指令、輸出是什麼。
• 只拿到一句結論。我習慣這樣問：「這個結論依據哪些資料或實驗結果？哪些部分還是假設？請說明關鍵的推導步驟，並給我可以實際檢查的方法。」AI 多寫了一段解釋，不代表那段解釋已經被驗證。
• 同一件事糾正到第三次。官方建議是糾正兩次還不對，就 /clear，把學到的東西寫進一個新 prompt 重來，不要讓對話裡一直堆著失敗的嘗試。
• 直接從 AI 給的選項裡挑。先想想自己要解決的問題有沒有說完整，習慣和限制有沒有交代，再判斷它的建議適不適合。
• 兩個工具各裝一份同名 skill。改了一邊、忘了另一邊，內容就分岔了。用 symlink 指向同一份正本，裝完或移除 skill 後跑一次檢查。
• 隨手裝來路不明的 plugin 或 MCP server。它們能執行 hooks、能讀外部內容，先看清楚再裝。

Day 8 我寫過，AI 能幫忙的範圍越大，我越需要保留判斷：手上這份成果，憑什麼可以採用。這些設定做的事，是把判斷的依據寫下來：規則寫進 CLAUDE.md，做法寫成 skill，目的和完成條件寫進 spec。回頭檢查時，才有東西可以對照。