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

60 分鐘後你會完成什麼

想像一個場景。星期二早上九點。你有一個熟悉的 codebase、一個順手的 terminal、開會前還有一小時空檔。到十點，你會讓一個 AI agent 裝在你的機器上、訓練好你專案的慣例、在三個真實任務上證明它的能耐。

這是你走出這一小時會帶走的東西：

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

每個段落都有時間估計。追蹤你的進度。某段落落後了，就在下一段追回來。

前置條件：

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

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

第 0-5 分鐘：安裝 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.ai 帳號登入 — 就是你 Pro 訂閱的那個帳號。如果瀏覽器不合作，按 c 把登入 URL 複製到剪貼簿，手動貼過去。

驗證完成後，你會在 terminal 看到 Claude Code 的 prompt。憑證存在 ~/.claude/，除非你主動登出，否則不需要再次登入。

你應該看到的畫面： 乾淨的 prompt，版本號加上游標。如果看到驗證錯誤，到 claude.ai/settings 確認 Pro 訂閱是否啟用。

時間確認： 5 分鐘內完成。瀏覽器驗證的問題是一次性成本，別讓它影響你的節奏。

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

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

cd ~/projects/your-actual-project
claude

輸入這段：

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、設定檔、進入點 — 組裝出你 codebase 的心智模型。幾秒鐘的事。

好的產出長這樣： 結構化的摘要，指名你的框架、畫出目錄配置、追蹤模組之間的資料流向、辨識出設計模式（MVC、repository pattern、feature-based folders）。會提到你專案裡的具體檔案路徑。

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

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

時間確認： 5 分鐘過去。你有了一個可運作的安裝和第一個有用的產出 — 一份架構概覽，可以分享給隊友或直接放進文件。

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

剛才的架構解釋還不錯。現在你要讓它大幅升級。

為什麼 CLAUDE.md 重要

想像你在帶新人入職。你遞給他一份文件：這是我們的技術棧、這是我們的慣例、這是我們為什麼這樣做。CLAUDE.md 就是那份文件 — 只是讀者是 AI agent，不是人類。

每次 Claude Code 在你的專案中啟動 session，它都會從專案根目錄讀取 CLAUDE.md。這個檔案告訴它那些光看程式碼推斷不出的資訊：你團隊的命名慣例、偏好的 pattern、存在於部落知識而非 linter 規則裡的限制、架構決策背後的「為什麼」。

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 要精簡。
• 用指標取代複製。 寫 See src/lib/errors.ts for the error handling pattern，不要貼程式碼片段。片段會過時，檔案參照不會。
• 不要重複 linter 規則。 ESLint 已經在執行的規則，不要在 CLAUDE.md 重述。Claude Code 可以透過 hook 跑你的 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 讀取。 它找到相關檔案 — signup route、既有的 validation pattern、schema 定義。每次檔案存取都記錄在你的 terminal 裡。你看得到它在看什麼。

第二步：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 執行。 批准後，檔案被寫入。它通常會跑後續動作 — 建立檔案、加 import，有時候跑你的測試來驗證變更。

第五步：驗證。 這個習慣把有生產力的開發者和魯莽的開發者分開：

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 任務改了 8 個檔案，那就出了問題。
• 你讀得懂嗎？ 如果程式碼很聰明但讀不懂，直接告訴 Claude Code：「簡化這段。我應該能在 10 秒內讀完每個函式。」

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

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

單一檔案的修改很好，但那不是 Claude Code 和 autocomplete 拉開差距的地方。真正的優勢在多檔案推理 — 追蹤依賴關係、更新 import、在整個 codebase 中維持一致性。就像外科醫生看的是整個病人，不只是切口。

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

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.

差異在哪裡

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

2. 跨檔案規劃。 計畫是多步驟的：建立 error class 繼承體系、更新每個 route handler、修改 error middleware、更新測試。逐檔案說明，每個變更都有理由。

3. 有序執行。 先建立基礎 class，再更新使用端。順序很重要 — 在 error class 建立之前就更新 route handler，build 會在步驟之間壞掉。

4. Import 管理。 每個引用新 error class 的檔案都會更新 import。繁瑣但 Claude Code 機械性地處理完畢。

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

批准之前審查完整的變更集。這是比較大的修改 — 花 2-3 分鐘讀完 diff。確認 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 在你的 codebase 上運作了。現在把它變成日常習慣的一部分。

設定權限

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，處理特定子任務，不汙染你的主對話。把它們想成 worker thread。主 session 保持乾淨，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 保持整潔。

設定 Terminal 做多任務工作

最自然的日常配置：一個面板跑 Claude Code、一個面板跑測試、一個面板開編輯器。並排執行，代表你可以一邊看 Claude Code 工作、一邊即時驗證它的產出。

好的多面板配置讓你把檔案直接拖進 Claude Code terminal、留一個專用面板給驗證指令、同時監看 git status 和 AI agent 的動態。這種並排工作流才是生產力乘數真正出現的地方。

安裝實用的 Skill

Claude Code 支援 skill — 你或社群建立的可重複使用指令集。Skill 可以定義 workflow、強制執行 pattern，或加入專業知識。社群的 skill 生態系涵蓋常見任務如 PR review、測試產生和文件撰寫。

接下來做什麼

六十分鐘。你現在有一個可運作的 Claude Code 設定，搭配專案 context、真實任務的經驗、和設定好的 workflow。接下來的方向：

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

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

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

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