🔧 阿川の電商水電行

Shopify 顧問、維護與客製化

💡

小任務 / 單次支援方案

單次處理 Shopify 修正／微調

⭐️

維護方案

每月 Shopify 技術支援 + 小修改 + 諮詢

🚀

專案建置

Shopify 功能導入、培訓 + 分階段交付

👉 瞭解詳情 / 免費諮詢

小編精選 - 技術文章翻譯 · 03月04日

克勞德程式碼最佳實踐－獲得穩定結果的7條黃金法則

Claude Code的官方最佳實踐中列出了許多穩定成果的模式。然而，信息量龐大，不知該從何著手的人恐怕也不少。

在本記事中，我們參考了官方文件的內容，將特別需要注意的要點整理成七條鐵則，並將其分類為四個類別，包括基本操作到自動化。

鐵則1: 具體要求

Claude Code的輸出品質取決於指示的具體性。模糊的指示會引發多次來回溝通，浪費時間與令牌。

Bad / Good 比較

Bad（模糊）	Good（具體）
「這段程式碼修正一下」	「將`src/auth.ts`中的`login`函數修改為，當未輸入密碼時返回null，並增加空字符串檢查，拋出`ValidationError`」
「寫個測試」	「為`src/utils/format.ts`中的`formatDate`函數寫3個正常情況和2個邊界情況的Vitest測試」
「改善性能」	「`/api/users`端點的響應時間為2秒。請解決SQL查詢的N+1問題，使它降至500毫秒以下」

指示檢查5項清單

在發出指示之前，請確認以下項目。

什麼: 目標檔案・函數・組件
哪裡: 確定需要變更的部分
為什麼: 變更的目的・背景
到什麼程度: 期望的完成條件
約束: 使用的函式庫、編碼規範、相容性

並不需要每次都填寫所有項目，但「什麼」和「到什麼程度」這兩項是必須始終包含進去的。

具體的指示可以顯著減少回合數，從而降低成本。

有關上下文工程的詳細資訊，請參考「編碼代理時代的上下文工程實踐指南」。

鐵則2: 一定要驗證

Claude Code能夠高精度地生成程式碼，但並不是100%正確的。徹底執行「生成後一定要驗證」，可以及早發現問題。

三個驗證要點

1. 確認差異
當Claude Code進行變更後，首先確認差異，檢查是否有意外的更動。可以在終端執行git diff或使用編輯器的差異顯示功能。

2. 執行測試
變更後必須執行測試。你可以要求Claude Code執行測試，確認現有測試沒有毀損。

執行測試並報告結果

3. 使用/cost確認消耗量
使用/cost命令查看當前會話的令牌消耗量。如果消耗量超過預期，則可能需重新檢視指示方式。

30秒驗證檢查清單

任務完成時，請確認以下三點。

[ ] diff中是否有意外的變更
[ ] 測試是否通過（或手動驗證是否正常運作）
[ ] 消耗成本是否在預期範圍內

在沒有測試的情況下隨意判斷「運行正常就沒問題」是非常危險的。Claude Code生成的程式碼仍可能缺少對邊界情況的考量。

徹底進行驗證會減少返工，從而提高開發速度。

驗證和除錯的實用技術在「測試驅動的上下文工程實踐指南」中有詳細解釋。

鐵則3: 在CLAUDE.md中語言化規則

你是否一直重複相同的指示？「用TypeScript寫」「測試使用Vitest」「提交信息為日文」等規則可以寫在CLAUDE.md中，這樣就會自動應用。

什麼是CLAUDE.md

CLAUDE.md是放置於專案根目錄的設定檔。Claude Code在會話開始時會自動讀取並反映在所有互動中。

開始模板

最初可以簡單開始，以下四個部分即可。

# 專案概要
- Node.js + TypeScript的Web應用
- 框架: Next.js 15（App Router）
- 套件管理器: pnpm

# 編碼規範
- 變數名・函數名使用camelCase
- 組件使用PascalCase
- 每個檔案只包含一個組件

# 測試
- 測試框架: Vitest
- 測試檔案位於__tests__/目錄

# Git
- 提交信息為日文
- 每次提交一個功能

CLAUDE.md除了專案根目錄外，還有多個範疇可以設定，但首先只需一個根文件即可。更詳細的範疇使用方式請參見「Claude Code擴展功能活用指南」。

使用過程中持續完善

CLAUDE.md不需要一開始就做好的。Boris Cherny（《Programming TypeScript》的作者）提倡CLAUDE.md的自我改善循環。

在使用Claude Code時，發現「又一次給了相同的指示」
將該指示追寫至CLAUDE.md
從下一次開始自動應用

這樣反覆進行，CLAUDE.md自然會得到充實。兩周之內，它將成為專案特有的知識庫。

鐵則4: 保持短暫的會話

長時間的會話會導致Claude Code的輸出品質逐漸降低，因為上下文窗口有上限。

「一任務一會話」規則

一個任務完成後，開始新的會話。僅此一點，品質就能穩定。

「實現認證功能」→ 新會話 →「添加測試」
「修復漏洞A」→ 新會話 →「修復漏洞B」

/compact命令

如果在會話中上下文膨脹，則可以使用/compact命令。它會壓縮對話歷史，騰出上下文空間。不過，請注意在摘要過程中可能會丟失一些細微的語氣。

上下文劣化的三個跡象

出現以下信號時，應切換到新的會話。

忘記以前傳達的指示（重複問同樣的問題）
程式碼的一致性崩潰（命名規則不一致）
開始編輯與任務無關的檔案

上下文窗口的機制和最佳管理方法可參見「上下文窗口的處理流程與工作機制完全解說」。

鐵則5: 先計畫，再執行

突然要求執行複雜任務容易導致方向偏離。需要先讓其制定計畫，再進行確認，最後才開始執行。

三步驟流程

「5分鐘規則」

作為指標，手作需要5分鐘以上的任務應從計畫開始。

5分鐘以下: 直接指示執行
5分鐘以上: 首先讓其提交計畫

實例進行式

以要求添加認證功能為例。

步驟1: 請求計畫

我想要添加用戶認證功能，使用JWT + 刷新令牌方式，
制定符合以下要求的實現計畫：
- 登入 / 登出 / 令牌刷新API
- 中介軟體的認證檢查
- 使用現有的用戶表
請現在不要編寫程式碼。

步驟2: 檢閱計畫
Claude Code將提交計畫，確認檔案結構、實現順序及使用的函式庫。如有問題，請求修正。

步驟3: 允許執行

計畫內容確認無誤。請按照步驟1開始實現。

這種工作流程可以防止出現重大返工。

進一步發展計畫驅動工作流程的技術，請參見「Claude Code超能力完全指南」。

鐵則6: 注意成本

Claude Code的運作是按需付費。如果無意識地使用，成本將會增加。平時應有一個了解成本的機制。

/cost命令的使用方法

在會話中執行/cost可以查看消耗的令牌數量和預估費用。定期檢查，務必確認是否與預期有顯著偏差。

成本降低的三個要點

1. 具體化指示（實踐鐵則1）
模糊的指示會引發反覆試探，浪費令牌。一次性清楚地傳達是最有效的成本控制方法。

2. 不要讓其讀取不必要的檔案
透過.claudeignore檔案排除Claude Code不應讀取的檔案，目標包括node_modules/、編譯生成物和大型數據檔案。

node_modules/
dist/
*.log
*.csv

3. 保持會話短暫（實踐鐵則4）
長會話會增加上下文重發的次數，導致成本上升。應經常切換會話。

錯誤模式: 無意識的令牌消耗

一次性貼上大檔案內容（只需相關部分即可）
提出像「全部修正」這樣範圍廣泛的要求
在同一會話中繼續無關任務

利用Claude Code進行商務效率提升的具體案例，請參考「利用Claude Code實現業務自動化」。

鐵則7: 下一步 - 自動化的入口

在掌握鐵則1到鐵則6後，接下來就要邁向自動化。Claude Code具備多種機制來自動化重複性工作。

依興趣的下一步

希望更有效地使用CLAUDE.md
可以使用專案根目錄以外的範疇（~/.claude/CLAUDE.md或依目錄區分）來更細緻地管理規則。
→ Claude Code擴展功能活用指南

想要自動化命令執行
使用Hooks可以在特定事件（如檔案保存、提交前等）自動執行腳本。
→ Claude Code Hooks全14事件完全解說

希望與外部工具集成
建立MCP伺服器可以將Claude Code與資料庫或API等外部工具連接。
→ MCP自建伺服器構建指南

希望協調多個Claude Code
使用Agent Teams可以讓多個Claude Code實例並行工作。
→ Agent Teams實踐指南
→ 子代理 vs Agent Teams 比較

總結

回顧本記事介紹的七條鐵則。

類別	鐵則	要點
基本操作	鐵則1: 具體要求	通過5項檢查清單構建指示
基本操作	鐵則2: 一定要驗證	確認diff、測試與成本的三點
環境整備	鐵則3: 在CLAUDE.md中語言化	重複的指示寫入檔案
環境整備	鐵則4: 保持短暫會話	遵循一任務一會話規則
工作流程	鐵則5: 先計畫，再執行	根據5分鐘規則做決策
工作流程	鐵則6: 注意成本	定期確認/cost
自動化	鐵則7: 自動化的入口	向Hooks、MCP、Agent Teams發展