常見工作流程
使用 Claude Code 探索程式碼庫、修復錯誤、重構、測試和其他日常任務的逐步指南。
本頁涵蓋日常開發的實用工作流程：探索陌生程式碼、除錯、重構、編寫測試、建立 PR 和管理會話。每個部分都包含您可以根據自己的專案調整的範例提示。如需更高層級的模式和提示，請參閱最佳實踐。
了解新的程式碼庫
快速取得程式碼庫概覽
假設您剛加入一個新專案，需要快速了解其結構。
導航到專案根目錄
cd /path/to/project
啟動 Claude Code
claude
要求高層級概覽
give me an overview of this codebase
深入探討特定元件
explain the main architecture patterns used here
what are the key data models?
how is authentication handled?
尋找相關程式碼
假設您需要找到與特定功能相關的程式碼。
要求 Claude 尋找相關檔案
find the files that handle user authentication
取得元件如何互動的背景資訊
how do these authentication files work together?
了解執行流程
trace the login process from front-end to database
有效地修復錯誤
假設您遇到了錯誤訊息，需要找到並修復其來源。
與 Claude 分享錯誤
I'm seeing an error when I run npm test
要求修復建議
suggest a few ways to fix the @ts-ignore in user.ts
應用修復
update user.ts to add the null check you suggested
重構程式碼
假設您需要更新舊程式碼以使用現代模式和實踐。
識別用於重構的舊版程式碼
find deprecated API usage in our codebase
取得重構建議
suggest how to refactor utils.js to use modern JavaScript features
安全地應用變更
refactor utils.js to use ES2024 features while maintaining the same behavior
驗證重構
run tests for the refactored code
使用專門的 subagents
假設您想使用專門的 AI subagents 來更有效地處理特定任務。
檢視可用的 subagents
/agents
這會顯示所有可用的 subagents 並讓您建立新的。
自動使用 subagents
Claude Code 會自動將適當的任務委派給專門的 subagents：
review my recent code changes for security issues
run all tests and fix any failures
明確要求特定的 subagents
use the code-reviewer subagent to check the auth module
have the debugger subagent investigate why users can't log in
為您的工作流程建立自訂 subagents
/agents
然後選擇「建立新 subagent」並按照提示定義：
- 描述 subagent 目的的唯一識別碼（例如
code-reviewer、api-designer）。 - Claude 何時應使用此代理
- 它可以存取哪些工具
- 描述代理角色和行為的系統提示
使用 Plan Mode 進行安全的程式碼分析
Plan Mode 指示 Claude 通過使用唯讀操作分析程式碼庫來建立計畫，非常適合探索程式碼庫、規劃複雜變更或安全地檢查程式碼。在 Plan Mode 中，Claude 使用 AskUserQuestion 在提出計畫之前收集需求並澄清您的目標。
何時使用 Plan Mode
- 多步驟實現：當您的功能需要編輯許多檔案時
- 程式碼探索：當您想在進行任何變更之前徹底研究程式碼庫時
- 互動式開發：當您想與 Claude 迭代方向時
如何使用 Plan Mode
在會話期間開啟 Plan Mode
您可以在會話期間使用 Shift+Tab 循環切換權限模式。
如果您處於 Normal Mode，Shift+Tab 首先切換到 Auto-Accept Mode，在終端底部顯示 ⏵⏵ accept edits on。隨後的 Shift+Tab 將切換到 Plan Mode，顯示 ⏸ plan mode on。
在 Plan Mode 中啟動新會話
要在 Plan Mode 中啟動新會話，請使用 --permission-mode plan 標誌：
claude --permission-mode plan
在 Plan Mode 中執行「無頭」查詢
您也可以使用 -p 直接在 Plan Mode 中執行查詢（即在「無頭模式」中）：
claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"
範例：規劃複雜的重構
claude --permission-mode plan
I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.
Claude 分析當前實現並建立全面的計畫。使用後續問題進行細化：
What about backward compatibility?
How should we handle database migration?
當您接受計畫時，Claude 會自動從計畫內容命名會話。名稱會出現在提示欄和會話選擇器中。如果您已經使用 --name 或 /rename 設定了名稱，接受計畫不會覆蓋它。
將 Plan Mode 設定為預設值
// .claude/settings.json
{
"permissions": {
"defaultMode": "plan"
}
}
有關更多配置選項，請參閱設定文件。
使用測試
假設您需要為未涵蓋的程式碼新增測試。
識別未測試的程式碼
find functions in NotificationsService.swift that are not covered by tests
產生測試框架
add tests for the notification service
新增有意義的測試案例
add test cases for edge conditions in the notification service
執行並驗證測試
run the new tests and fix any failures
Claude 可以產生遵循您專案現有模式和慣例的測試。要求測試時，請明確說明您想驗證的行為。Claude 會檢查您現有的測試檔案，以符合已在使用的風格、框架和斷言模式。
為了獲得全面的涵蓋範圍，要求 Claude 識別您可能遺漏的邊界情況。Claude 可以分析您的程式碼路徑，並建議測試錯誤條件、邊界值和容易忽視的意外輸入。
建立提取請求
您可以直接要求 Claude 建立提取請求（「為我的變更建立 pr」），或逐步引導 Claude 完成：
總結您的變更
summarize the changes I've made to the authentication module
產生提取請求
create a pr
檢查並細化
enhance the PR description with more context about the security improvements
當您使用 gh pr create 建立 PR 時，會話會自動連結到該 PR。您稍後可以使用 claude --from-pr <number> 繼續。
處理文件
假設您需要為程式碼新增或更新文件。
識別未記錄的程式碼
find functions without proper JSDoc comments in the auth module
產生文件
add JSDoc comments to the undocumented functions in auth.js
檢查並增強
improve the generated documentation with more context and examples
驗證文件
check if the documentation follows our project standards
在筆記和非程式碼資料夾中工作
Claude Code 可在任何目錄中工作。在筆記保管庫、文件資料夾或任何 markdown 檔案集合中執行它，以搜尋、編輯和重新組織內容，就像您處理程式碼一樣。
.claude/ 目錄和 CLAUDE.md 與其他工具的配置目錄並存，不會產生衝突。Claude 在每次工具呼叫時都會重新讀取檔案，所以它會在下次讀取該檔案時看到您在另一個應用程式中所做的編輯。
使用影像
假設您需要在程式碼庫中使用影像，並希望 Claude 幫助分析影像內容。
將影像新增到對話中
您可以使用以下任何方法：
- 將影像拖放到 Claude Code 視窗中
- 複製影像並使用 ctrl+v 將其貼到 CLI 中（不要使用 cmd+v）
- 向 Claude 提供影像路徑。例如，「分析此影像：/path/to/your/image.png」
要求 Claude 分析影像
What does this image show?
Describe the UI elements in this screenshot
Are there any problematic elements in this diagram?
使用影像作為背景資訊
Here's a screenshot of the error. What's causing it?
This is our current database schema. How should we modify it for the new feature?
從視覺內容取得程式碼建議
Generate CSS to match this design mockup
What HTML structure would recreate this component?
參考檔案和目錄
使用 @ 快速包含檔案或目錄，無需等待 Claude 讀取它們。
參考單個檔案
Explain the logic in @src/utils/auth.js
這會在對話中包含檔案的完整內容。
參考目錄
What's the structure of @src/components?
這提供了帶有檔案資訊的目錄清單。
參考 MCP 資源
Show me the data from @github:repos/owner/repo/issues
這使用 @server:resource 格式從連接的 MCP 伺服器取得資料。有關詳細資訊，請參閱 MCP 資源。
使用擴展思考（Thinking Mode）
擴展思考預設啟用，為 Claude 提供空間在回應前逐步推理複雜問題。此推理在詳細模式中可見，您可以使用 Ctrl+O 切換。在擴展思考期間，進度提示會出現在指示器下方，例如「still thinking」和「almost done thinking」，以指示 Claude 正在積極工作。
此外，支援努力級別的模型使用自適應推理：不是固定的思考令牌預算，而是模型根據您的努力級別設定和手邊的任務動態決定是否以及如何思考。自適應推理讓 Claude 對日常提示回應更快，並為受益於深度思考的步驟保留更深層的思考。
擴展思考對於複雜的架構決策、具有挑戰性的錯誤、多步驟實現規劃和評估不同方法之間的權衡特別有價值。
配置 Thinking Mode
思考預設啟用，但您可以調整或禁用它。
| 範圍 | 如何配置 | 詳細資訊 |
|---|---|---|
| 努力級別 | 執行 /effort、在 /model 中調整，或設定 CLAUDE_CODE_EFFORT_LEVEL |
控制支援的模型上的思考深度 |
ultrathink 關鍵字 |
在提示中的任何地方包含「ultrathink」 | 在該輪添加上下文指令，告訴模型進行更多推理。不會改變努力級別本身；請參閱調整努力級別以了解相關資訊 |
| 切換快捷鍵 | 按 Option+T（macOS）或 Alt+T（Windows/Linux） |
切換當前會話的思考開/關（所有模型）。可能需要終端配置來啟用 Option 鍵快捷鍵 |
| 全域預設值 | 使用 /config 切換 Thinking Mode |
在所有專案中設定預設值（所有模型）。 儲存為 ~/.claude/settings.json 中的 alwaysThinkingEnabled |
| 限制令牌預算 | 設定 MAX_THINKING_TOKENS 環境變數 |
將思考預算限制為特定數量的令牌。在支援自適應推理的模型上，只有設定為 0 時才適用，除非禁用自適應推理。範例：export MAX_THINKING_TOKENS=10000 |
要檢視 Claude 的思考過程，按 Ctrl+O 切換詳細模式，並查看顯示為灰色斜體文字的內部推理。
擴展思考如何運作
擴展思考控制 Claude 在回應前執行多少內部推理。更多思考提供更多空間來探索解決方案、分析邊界情況和自我糾正錯誤。
在支援努力級別的模型上，思考使用自適應推理：模型根據您選擇的努力級別動態分配思考令牌。這是調整速度和推理深度之間權衡的推薦方式。如果您想讓 Claude 比您的努力級別會產生的更多或更少地思考，您也可以直接在提示中或在 CLAUDE.md 中說明。
使用較舊的模型，思考使用固定令牌預算，從您的輸出分配中提取。預算因模型而異；有關詳細資訊，請參閱 MAX_THINKING_TOKENS。您可以使用該環境變數限制預算，或通過 /config 或 Option+T/Alt+T 切換完全禁用思考。
在支援自適應推理的模型上，MAX_THINKING_TOKENS 只在設定為 0 以禁用思考時適用，或當 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 將模型恢復為固定預算時適用。CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING 僅適用於 Opus 4.6 和 Sonnet 4.6。Opus 4.7 始終使用自適應推理，不支援固定思考預算。請參閱環境變數。
繼續之前的對話
啟動 Claude Code 時，您可以繼續之前的會話：
claude --continue繼續當前目錄中最近的對話claude --resume開啟對話選擇器或按名稱繼續claude --from-pr 123繼續連結到特定提取請求的會話
從活躍會話內，使用 /resume 切換到不同的對話。
當選定的會話足夠舊且足夠大，以至於重新閱讀它會消耗您使用限額的大部分時，--resume、--continue 和 /resume 會提供從摘要繼續而不是載入完整記錄的選項。此提示在 Amazon Bedrock、Google Cloud Vertex AI 或 Microsoft Foundry 上不可用。
會話按專案目錄儲存。預設情況下，/resume 選擇器顯示來自當前 worktree 的互動式會話，帶有快捷鍵以擴展清單到其他 worktrees 或專案、搜尋、預覽和重新命名。有關完整的快捷鍵參考，請參閱下面的使用會話選擇器。
當您從同一儲存庫的另一個 worktree 選擇會話時，Claude Code 會直接繼續它，無需您先切換目錄。從不相關的專案選擇會話會將 cd 和繼續命令複製到您的剪貼簿。
按名稱繼續會在當前儲存庫及其 worktrees 中解析。claude --resume <name> 和 /resume <name> 都會尋找精確匹配並直接繼續它，即使會話位於不同的 worktree 中。
當名稱不明確時，claude --resume <name> 會開啟選擇器，並將名稱預先填充為搜尋詞。/resume <name> 從會話內報告錯誤，所以執行 /resume 不帶引數以開啟選擇器並選擇。
由 claude -p 或 SDK 調用建立的會話不會出現在選擇器中，但您仍然可以通過將其會話 ID 直接傳遞給 claude --resume <session-id> 來繼續。
命名您的會話
給會話起描述性名稱以便稍後找到它們。這是在處理多個任務或功能時的最佳實踐。
命名會話
在啟動時使用 -n 命名會話：
claude -n auth-refactor
或在會話期間使用 /rename，這也會在提示欄上顯示名稱：
/rename auth-refactor
您也可以從選擇器重新命名任何會話：執行 /resume，導航到會話，然後按 Ctrl+R。
稍後按名稱繼續
從命令列：
claude --resume auth-refactor
或從活躍會話內：
/resume auth-refactor
使用會話選擇器
/resume 命令（或 claude --resume 不帶引數）開啟具有以下功能的互動式會話選擇器：
選擇器中的快捷鍵：
| 快捷鍵 | 動作 |
|---|---|
↑ / ↓ |
在會話之間導航 |
→ / ← |
展開或摺疊分組的會話 |
Enter |
選擇並繼續突出顯示的會話 |
Space |
預覽會話內容。Ctrl+V 在不將其捕獲為貼上的終端上也有效 |
Ctrl+R |
重新命名突出顯示的會話 |
/ 或除 Space 外的任何可列印字元 |
進入搜尋模式並篩選會話 |
Ctrl+A |
顯示此機器上所有專案的會話。再次按下以恢復當前儲存庫 |
Ctrl+W |
顯示當前儲存庫所有 worktrees 的會話。再次按下以恢復當前 worktree。僅在多 worktree 儲存庫中顯示 |
Ctrl+B |
篩選為來自您當前 git 分支的會話。再次按下以顯示所有分支的會話 |
Esc |
退出選擇器或搜尋模式 |
會話組織：
選擇器顯示帶有有用中繼資料的會話：
- 會話名稱（如果設定），否則對話摘要或第一個使用者提示
- 自上次活動以來經過的時間
- 訊息計數
- Git 分支（如果適用）
- 專案路徑，在使用
Ctrl+A擴展到所有專案後顯示
分叉的會話（使用 /branch、/rewind 或 --fork-session 建立）在其根會話下分組，使找到相關對話更容易。
使用 Git worktrees 執行平行 Claude Code 會話
同時處理多個任務時，您需要每個 Claude 會話都有自己的程式碼庫副本，以便變更不會衝突。Git worktrees 通過建立單獨的工作目錄來解決此問題，每個目錄都有自己的檔案和分支，同時共享相同的儲存庫歷史記錄和遠端連接。這意味著您可以讓 Claude 在一個 worktree 中處理功能，同時在另一個 worktree 中修復錯誤，而不會相互干擾。
使用 --worktree（-w）標誌建立隔離的 worktree 並在其中啟動 Claude。您傳遞的值成為 worktree 目錄名稱和分支名稱：
# 在名為「feature-auth」的 worktree 中啟動 Claude
# 建立 .claude/worktrees/feature-auth/ 和新分支
claude --worktree feature-auth
# 在單獨的 worktree 中啟動另一個會話
claude --worktree bugfix-123
如果您省略名稱，Claude 會自動產生一個隨機名稱：
# 自動產生名稱如「bright-running-fox」
claude --worktree
Worktrees 建立在 <repo>/.claude/worktrees/<name> 並從預設遠端分支分支。worktree 分支命名為 worktree-<name>。
預設遠端分支不可通過 Claude Code 標誌或設定配置。origin/HEAD 是儲存在您本地 .git 目錄中的參考，Git 在您複製時設定一次。如果儲存庫的預設分支稍後在 GitHub 或 GitLab 上變更，您的本地 origin/HEAD 會繼續指向舊的，worktrees 將從那裡分支。要重新同步您的本地參考與遠端目前認為的預設值：
git remote set-head origin -a
這是一個標準 Git 命令，只更新您的本地 .git 目錄。遠端伺服器上沒有任何變更。如果您想 worktrees 基於特定分支而不是遠端的預設值，請使用 git remote set-head origin your-branch-name 明確設定它。
為了完全控制 worktrees 的建立方式，包括為每次調用選擇不同的基礎，配置 WorktreeCreate hook。該 hook 完全取代 Claude Code 的預設 git worktree 邏輯，所以您可以從任何您需要的 ref 中取得和分支。
您也可以在會話期間要求 Claude「在 worktree 中工作」或「啟動 worktree」，它會自動建立一個。
Subagent worktrees
Subagents 也可以使用 worktree 隔離來並行工作而不會衝突。要求 Claude「為您的代理使用 worktrees」或在自訂 subagent 中配置它，方法是在代理的 frontmatter 中新增 isolation: worktree。每個 subagent 都獲得自己的 worktree，在 subagent 完成而沒有變更時自動清理。
Worktree 清理
當您退出 worktree 會話時，Claude 根據您是否進行了變更來處理清理：
- 無變更：worktree 及其分支會自動移除
- 存在變更或提交：Claude 提示您保留或移除 worktree。保留會保留目錄和分支，以便您稍後返回。移除會刪除 worktree 目錄及其分支，丟棄所有未提交的變更和提交
Subagent worktrees 由於崩潰或中斷的平行執行而孤立的，一旦它們超過您的 cleanupPeriodDays 設定，就會在啟動時自動移除，前提是它們沒有未提交的變更、沒有未追蹤的檔案且沒有未推送的提交。使用 --worktree 建立的 Worktrees 永遠不會被此掃描移除。
要在 Claude 會話外清理 worktrees，請使用手動 worktree 管理。
複製 gitignored 檔案到 worktrees
Git worktrees 是新鮮的簽出，所以它們不包含來自主儲存庫的未追蹤檔案，如 .env 或 .env.local。要在 Claude 建立 worktree 時自動複製這些檔案，請在專案根目錄新增 .worktreeinclude 檔案。
該檔案使用 .gitignore 語法列出要複製的檔案。只有符合模式且也被 gitignored 的檔案才會被複製，所以追蹤的檔案永遠不會被複製。
.env
.env.local
config/secrets.json
這適用於使用 --worktree 建立的 worktrees、subagent worktrees 和桌面應用中的平行會話。
手動管理 worktrees
為了更好地控制 worktree 位置和分支配置，直接使用 Git 建立 worktrees。當您需要簽出特定現有分支或將 worktree 放在儲存庫外時，這很有用。
# 使用新分支建立 worktree
git worktree add ../project-feature-a -b feature-a
# 使用現有分支建立 worktree
git worktree add ../project-bugfix bugfix-123
# 在 worktree 中啟動 Claude
cd ../project-feature-a && claude
# 完成時清理
git worktree list
git worktree remove ../project-feature-a
在官方 Git worktree 文件中了解更多。
非 git 版本控制
Worktree 隔離預設使用 git。對於其他版本控制系統（如 SVN、Perforce 或 Mercurial），配置 WorktreeCreate 和 WorktreeRemove hooks 以提供自訂 worktree 建立和清理邏輯。配置後，當您使用 --worktree 時，這些 hooks 會取代預設 git 行為，所以.worktreeinclude 不會被處理。改為在您的 hook 指令碼中複製任何本地配置檔案。
對於具有共享任務和訊息的平行會話的自動協調，請參閱代理團隊。
在 Claude 需要您注意時獲得通知
當您啟動長時間執行的任務並切換到另一個視窗時，您可以設定桌面通知，以便在 Claude 完成或需要您的輸入時知道。這使用 Notification hook 事件，每當 Claude 等待權限、閒置並準備好新提示或完成身份驗證時觸發。
將 hook 新增到您的設定
開啟 ~/.claude/settings.json 並新增一個 Notification hook，該 hook 呼叫您平台的原生通知命令：
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
}
]
}
]
}
}
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
}
]
}
]
}
}
如果您的設定檔已有 hooks 鍵，請將 Notification 項目合併到其中，而不是覆蓋。您也可以通過在 CLI 中描述您想要的內容來要求 Claude 為您編寫 hook。
可選地縮小匹配器範圍
預設情況下，hook 在所有通知類型上觸發。要僅針對特定事件觸發，請將 matcher 欄位設定為以下值之一：
| 匹配器 | 觸發時機 |
|---|---|
permission_prompt |
Claude 需要您批准工具使用 |
idle_prompt |
Claude 完成並等待您的下一個提示 |
auth_success |
身份驗證完成 |
elicitation_dialog |
MCP 伺服器開啟引發表單 |
elicitation_complete |
MCP 引發表單已提交或關閉 |
elicitation_response |
MCP 引發回應已傳送回伺服器 |
驗證 hook
輸入 /hooks 並選擇 Notification 以確認 hook 出現。選擇它會顯示將執行的命令。要端到端測試它，要求 Claude 執行需要權限的命令並切換離開終端，或要求 Claude 直接觸發通知。
如需完整的事件架構和通知類型，請參閱通知參考。
將 Claude 用作 unix 風格的實用程式
將 Claude 新增到您的驗證過程
假設您想將 Claude Code 用作 linter 或程式碼審查者。
將 Claude 新增到您的建置指令碼：
// package.json
{
...
"scripts": {
...
"lint:claude": "claude -p 'you are a linter. please look at the changes vs. main and report any issues related to typos. report the filename and line number on one line, and a description of the issue on the second line. do not return any other text.'"
}
}
管道進入、管道輸出
假設您想將資料管道輸入 Claude，並以結構化格式取回資料。
通過 Claude 管道資料：
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt
控制輸出格式
假設您需要 Claude 的輸出採用特定格式，特別是在將 Claude Code 整合到指令碼或其他工具時。
使用文字格式（預設）
cat data.txt | claude -p 'summarize this data' --output-format text > summary.txt
這只輸出 Claude 的純文字回應（預設行為）。
使用 JSON 格式
cat code.py | claude -p 'analyze this code for bugs' --output-format json > analysis.json
這輸出包含中繼資料（包括成本和持續時間）的訊息的 JSON 陣列。
使用串流 JSON 格式
cat log.txt | claude -p 'parse this log file for errors' --output-format stream-json
這在 Claude 處理請求時實時輸出一系列 JSON 物件。每個訊息都是有效的 JSON 物件，但如果連接，整個輸出不是有效的 JSON。
在排程上執行 Claude
假設您想讓 Claude 自動定期處理任務，例如每天早上檢查開放 PR、每週審計依賴項或在夜間檢查 CI 失敗。
根據您想讓任務執行的位置選擇排程選項：
| 選項 | 執行位置 | 最適合 |
|---|---|---|
| Routines | Anthropic 管理的基礎設施 | 應該在您的電腦關閉時執行的任務。也可以由 API 呼叫或 GitHub 事件觸發，除了排程。在 claude.ai/code/routines 配置。 |
| 桌面排程任務 | 您的機器，通過桌面應用 | 需要直接存取本地檔案、工具或未提交變更的任務。 |
| GitHub Actions | 您的 CI 管道 | 與儲存庫事件（如開啟的 PR）相關的任務，或應與工作流程配置一起存在的 cron 排程。 |
/loop |
當前 CLI 會話 | 會話開啟時的快速輪詢。任務在您開始新對話時停止；--resume 和 --continue 恢復未過期的任務。 |
詢問 Claude 其功能
Claude 內建存取其文件，可以回答有關其自身功能和限制的問題。
範例問題
can Claude Code create pull requests?
how does Claude Code handle permissions?
what skills are available?
how do I use MCP with Claude Code?
how do I configure Claude Code for Amazon Bedrock?
what are the limitations of Claude Code?