Claude Code 第一個小時：從安裝到第一個有用的產出

60 分鐘後你會完成什麼

這篇教學結束時，你會有：

1. 安裝並驗證完成的 Claude Code。
2. 一份 CLAUDE.md 檔案，讓 Claude Code 理解你專案的架構和慣例。
3. 在你的真實程式碼庫上完成 3 個任務 — 不是範例專案，是你真正在寫的程式碼。

這不是功能巡禮。你會打開終端、安裝工具、做真正的工作。每個段落都有時間估計，讓你可以追蹤自己的進度。

前置條件：

• macOS、Windows 或 Linux
• Claude Pro 訂閱（$20 美元/月）或 Anthropic API key
• 一個真實的專案，至少有幾個原始碼檔案（任何語言）
• 你習慣使用的終端

不需要任何 AI 編程工具的使用經驗。

第 0-5 分鐘：安裝 Claude Code

Claude Code 用原生安裝器安裝。不依賴 Node.js，不需要 npm。一行指令。

macOS 和 Linux：

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

Windows（PowerShell）：

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

Homebrew（macOS 替代方案）：

brew install --cask claude-code

安裝完成後，執行：

claude

首次啟動時，Claude Code 會開啟瀏覽器進行驗證。用你的 Claude.ai 帳號登入（就是 Pro 訂閱的那個帳號）。如果瀏覽器沒有自動開啟，按 c 把登入 URL 複製到剪貼簿，手動貼到瀏覽器。

驗證完成後，你會在終端看到 Claude Code 的提示符。憑證儲存在 ~/.claude/——除非你主動登出，否則不需要再次登入。

你應該看到的畫面： 乾淨的提示符，顯示 Claude Code 版本號和等待輸入的游標。如果看到驗證錯誤，到 claude.ai/settings 確認 Pro 訂閱是否啟用。

時間確認： 5 分鐘內完成。如果瀏覽器驗證花了比較久的時間，不用擔心——這是一次性的設定。

第 5-10 分鐘：你的第一個 Prompt

切換到一個真實的專案目錄。不要用新建的空專案——挑一個你一直在寫的東西。至少有 5-10 個檔案的專案，才能讓 Claude Code 展現價值。

cd ~/projects/your-actual-project
claude

輸入你的第一個 prompt：

Explain the architecture of this project. What are the main modules,
how do they connect, and what patterns does the codebase follow?

Claude Code 會讀取你的專案檔案——掃描目錄結構、開啟關鍵檔案（package.json、設定檔、進入點），建立程式碼庫的整體理解。這需要幾秒鐘。

好的產出長什麼樣子： 結構化的摘要，能辨識框架、目錄配置、模組之間的資料流向，以及它偵測到的模式（MVC、repository pattern、feature-based folders）。應該提到你專案裡的具體檔案路徑。

差的產出長什麼樣子： 套用在任何專案都成立的泛泛之論。如果 Claude Code 只說「這似乎是一個 web application」卻沒有辨識出你的框架、路由器或狀態管理——程式碼庫太小，或者 Claude Code 讀的檔案不夠多。試更具體的 prompt：「讀取主進入點，追蹤從 API endpoint 到資料庫的完整請求流程。」

第一個 prompt 是唯讀的。Claude Code 讀檔但不修改任何東西。零風險。

時間確認： 5 分鐘過去，你已經有一個可運作的 Claude Code 安裝和第一個有用的產出——一份架構概覽，可以分享給隊友或用來寫文件。

第 10-20 分鐘：建立 CLAUDE.md 檔案

剛才得到的架構解釋還不錯。現在你要透過給 Claude Code 持久的專案 context，讓它的產出大幅提升。

為什麼 CLAUDE.md 重要

每次 Claude Code 在你的專案中啟動 session，它都會從專案根目錄讀取 CLAUDE.md。這個檔案告訴 Claude Code 那些它無法從程式碼推斷出來的資訊：你團隊的慣例、偏好的模式、沒有寫進 linter 的限制條件，以及架構決策背後的「為什麼」。

把它想成新人入職文件——但對象是 AI agent，不是新同事。

ETH Zurich 的研究發現，過度詳細的 context 檔案反而會降低 agent 效能。最佳範圍是 200-500 字的高訊號密度資訊。每一行都應該通過這個測試：「拿掉這一行，Claude Code 會不會犯錯？」如果不會，就刪掉。

實用範本

在專案根目錄建立 CLAUDE.md 檔案：

## Project Overview
[一段話：這個專案做什麼、服務誰、解決什麼問題]

## Architecture
- Framework: [例如 Next.js 15 App Router]
- Database: [例如 PostgreSQL via Prisma]
- Auth: [例如 NextAuth.js v5]
- Styling: [例如 Tailwind CSS]
- Testing: [例如 Vitest for unit, Playwright for e2e]

## Code Conventions
- [例如 TypeScript strict mode everywhere]
- [例如 Prefer server components; 'use client' only when necessary]
- [例如 Error handling uses Result types, not try/catch]
- [例如 No default exports except for pages/layouts]

## Directory Structure
- src/app/ — routes and pages
- src/components/ — shared UI components
- src/lib/ — business logic and utilities
- src/db/ — database schema and migrations

## Hard Constraints
- [例如 Never modify migration files directly]
- [例如 All API routes must validate input with Zod]
- [例如 No external HTTP calls in server components]

用你專案的實際細節填入。花 5 分鐘，不要過度思考。可以之後慢慢改進。

關鍵原則：

• 控制在 100 行以內。 Claude Code 自己的 system prompt 大約佔用 200 個指令位中的 50 個。你的 CLAUDE.md 要精簡。
• 用指標取代複製。 不要在 CLAUDE.md 貼程式碼片段，改寫 See src/lib/errors.ts for the error handling pattern。程式碼片段會過時；檔案參照不會。
• 不要重複 linter 規則。 如果 ESLint 已經在執行某個規則，不要在 CLAUDE.md 重述。Claude Code 可以透過 hooks 執行你的 linter——讓確定性工具處理確定性規則。

見證差異

現在再跑一次同樣的架構 prompt：

Explain the architecture of this project. What are the main modules,
how do they connect, and what patterns does the codebase follow?

差異是即時的。有了 CLAUDE.md，Claude Code 使用你的術語、引用你的特定慣例，圍繞你描述的架構來組織回答。它不再猜測，而是說你專案的語言。

時間確認： 20 分鐘過去。你已經安裝、驗證並設定好專案 context。接下來的一切都是實際生產力。

第 20-35 分鐘：你的第一個真實任務

讓 Claude Code 做真正的工作。從你的實際待辦事項中挑一個具體、範圍明確的任務。如果手邊沒有，用這個通用範例：

Add input validation to the signup API endpoint.
Validate email format, password minimum 8 characters,
and username between 3-30 alphanumeric characters.
Use Zod for the schema. Return specific error messages
for each validation failure.

互動流程

第一步：Claude Code 讀取。 提交 prompt 後，Claude Code 找到相關檔案——signup route、既有的 validation 模式、schema 定義。它自動讀取這些檔案，你會在終端看到每次檔案存取的記錄。

第二步：Claude Code 規劃。 在寫任何程式碼之前，Claude Code 先展示它打算做什麼：「我會在 src/lib/validations/auth.ts 建立 Zod schema，在 src/app/api/auth/signup/route.ts 的 signup route 中 import，然後加上回傳欄位特定錯誤訊息的錯誤格式化。」

第三步：你審查並批准。 Claude Code 以 diff 的形式展示擬議的變更。這就是權限模型的運作方式：

• 檔案讀取自動進行——不需要批准。
• 檔案寫入需要你的明確批准。Claude Code 在寫入之前展示它要寫什麼。
• Shell 指令（像 npm install zod）也需要批准。

頭幾次任務仔細審查 diff。隨著時間推移，你會培養出什麼時候直接批准、什麼時候要求修改的直覺。

第四步：Claude Code 執行。 批准後，Claude Code 寫入檔案。它通常會執行後續動作——建立檔案、加入 import，有時候跑你的測試來驗證變更正確。

第五步：驗證。 請 Claude Code 驗證自己的工作：

Run the tests related to the signup endpoint.
If there are no tests, write them first.

這是關鍵習慣。永遠不要在沒有驗證的情況下接受程式碼變更。Claude Code 可以跑你的測試、檢查 TypeScript 錯誤、確認實作正確——但只有你主動要求時才會做。

注意什麼

• Claude Code 有沒有遵守你的 CLAUDE.md 慣例？ 如果你指定用 Zod 做 validation，它卻用了其他 library，你的 CLAUDE.md 需要更強的約束條件。
• 變更是否最小化？ 好的變更只動必要的檔案。如果一個簡單的 validation 任務 Claude Code 改了 8 個檔案，那就出了問題。
• 你讀得懂這段程式碼嗎？ 如果產生的程式碼很聰明但讀不懂，告訴 Claude Code：「簡化這段。我應該能在 10 秒內讀完每個函式。」

時間確認： 35 分鐘過去。你完成了一個有 code review 和驗證的真實任務。這就是 Claude Code 的核心工作流——後面所有東西都建立在這個迴圈上。

第 35-50 分鐘：跨多檔案任務

單一檔案的修改很好，但 Claude Code 相對於簡單 autocomplete 的真正優勢在於多檔案推理。它能追蹤依賴關係、更新 import、在整個程式碼庫中維持一致性。來用用看。

挑一個跨多檔案的任務。如果沒有現成的：

Refactor the error handling in this project to use a centralized
error class. Create a base AppError class with status code, error code,
and user-friendly message. Replace all ad-hoc error throws with
specific subclasses (ValidationError, NotFoundError, AuthError).
Update the error handling middleware to use the new classes.

差異在哪裡

這類任務是 Claude Code 與簡單工具拉開差距的地方。觀察整個過程：

1. 廣泛的檔案掃描。 Claude Code 不只讀錯誤處理的程式碼，還讀整條 middleware 鏈、丟出錯誤的 route handler、以及對錯誤行為做 assert 的測試。它需要在提出變更之前理解完整的錯誤表面積。

2. 跨檔案規劃。 Claude Code 提出多步驟計畫：建立 error class 繼承體系、更新每個 route handler、修改 error middleware、更新測試。計畫會逐檔案說明變更內容。

3. 有序執行。 Claude Code 先建立基礎 class，再更新使用者端。順序很重要——如果它在建立 error class 之前就更新 route handler，程式碼在步驟之間會壞掉。

4. Import 管理。 每個引用新 error class 的檔案都會更新 import。這是繁瑣但 Claude Code 自動處理的工作。

5. 測試更新。 如果你的測試對特定錯誤訊息或 status code 做 assert，Claude Code 會更新它們以匹配新的 error class 結構。

批准之前審查完整的變更集。這是比較大的修改——花 2-3 分鐘讀完 diff。確認 error class 繼承體系合理、沒有遺漏錯誤情境、middleware 正確捕捉新的 error type。

Show me a summary of all files changed and what changed in each one.

批准並執行後，驗證：

Run the full test suite. Show me any failures.

時間確認： 50 分鐘過去。你完成了一個涉及多個檔案的非平凡重構任務——這類工作手動做通常需要 30-60 分鐘。

第 50-60 分鐘：建立你的工作流

你已經證明 Claude Code 在你的程式碼庫上能運作。現在設定它來日常使用。

設定權限

Claude Code 的權限系統放在專案根目錄的 .claude/settings.json。它控制哪些操作自動執行，哪些需要批准。

一個實用的起始設定：

{
  "permissions": {
    "allow": [
      "Bash(npm test *)",
      "Bash(npm run lint *)",
      "Bash(npx tsc --noEmit)"
    ]
  }
}

這允許測試和 lint 指令不需批准就執行，而檔案寫入和其他 shell 指令仍然需要確認。保守開始——隨著你建立信任感，再逐步擴大 allowlist。

學會關鍵指令

在 Claude Code session 內，這些指令是必備的：

• /help — 顯示所有可用指令
• /compact — 壓縮對話 context，session 過長時使用
• /clear — 重置 session，context 變得混亂時很有用
• /effort — 控制推理深度（複雜任務用高 effort，簡單任務用低 effort）

了解 Subagent

對大型任務，Claude Code 可以產生 subagent——獨立的子 session，處理特定子任務，不會汙染你的主對話 context。你不需要手動設定這些；Claude Code 在任務適合平行或隔離處理時自動使用 subagent。

你也可以明確地使用 subagent：

Use a subagent to research all the places in this codebase
where we handle authentication tokens. Report back with
file paths and a summary.

Subagent 有自己的 context window，完成工作後回報給主 session。你的主 session 保持乾淨。

設定終端做多任務工作

讓 Claude Code 和你的日常開發工作流並行運作——一個面板跑測試、一個面板跑 Claude Code、一個面板開編輯器——這是最自然的日常配置。你需要一個能無摩擦處理多面板的終端環境。

好的多面板配置讓你在一個終端看 Claude Code 工作、同時在另一個終端跑測試或查 git status。把檔案直接拖進 Claude Code 終端。留一個專用面板給驗證指令。這種並排工作流才是生產力乘數真正出現的地方。

安裝實用的 Skills

Claude Code 支援 skills——你或社群建立的可重複使用指令集。Skills 可以定義工作流程、強制執行模式，或加入專業知識。社群已經有越來越多針對常見任務的 skills，例如 PR review、測試產生和文件撰寫。

接下來做什麼

你花了 60 分鐘，現在有了一個可運作的 Claude Code 設定，搭配專案 context、真實任務的經驗，以及設定好的工作流。接下來的方向：

深入了解工具全貌。 2026 AI CLI 工具完全指南涵蓋每一個主要的 AI CLI 工具——Claude Code、Gemini CLI、Copilot CLI、Codex CLI 和另外六個——附完整定價、能力比較和多 agent 工作流模式。

優化你的成本。 Claude Code Pro 方案每月 $20 美元是入門價，但你可以把它用得更有效率。雙工具策略教你如何把 Claude Code 和 Gemini CLI 的免費方案搭配使用——用 Gemini CLI 做探索和簡單任務，把 Claude Code 的額度留給真正需要的複雜工作。很多開發者用這個方式降低了 60-70% 的實際成本。

持續完善你的 CLAUDE.md。 今天建立的範本是起點。日常使用一週後，你會知道哪些指令 Claude Code 穩定遵守、哪些它會忽略。根據 Claude Code 實際犯的錯誤來改進你的 CLAUDE.md，不要根據你想像中它可能犯的錯誤。

用 hooks 強制執行規則。 CLAUDE.md 的指令大約有 70% 的遵守率。對於必須 100% 執行的規則——像是每次 commit 前跑 linter，或封鎖對某些目錄的寫入——用 hooks。Hooks 是在 Claude Code 工作流特定時間點觸發的 shell script，確定性地強制執行規則。