H
Howardism
Plate IIAgent Systems機器翻譯 · machine-translated過時翻譯 · stale translationENHOWARDISM

Claude Code 最佳實務

PublishedApril 10, 2026FiledConceptDomainAgent SystemsTagsClaude CodeAI ToolsDeveloper WorkflowReading12 minSourceAI-synthesised

Anthropic 提供的有效使用 Claude Code 指南：內容管理、以驗證驅動的開發、探索→規劃→編碼工作流程，以及環境設定

Claude Code 最佳實務插圖

資料來源#

摘要#

Anthropic 官方的 Claude Code 有效使用指南，圍繞單一核心限制組織而成：內容視窗很快就會填滿，而隨著填滿程度提高，效能也會下降。所有最佳實務都源自於管理這項稀缺資源——透過以驗證驅動的開發、結構化內容（CLAUDE.md）、積極的工作階段管理，以及透過平行工作階段進行水平擴展。

細節#

以內容視窗作為首要限制#

內容視窗容納整段對話：訊息、檔案讀取結果與指令輸出。單次除錯工作階段就可能消耗數萬個 token。內容填滿後，Claude 會「忘記」較早的指示，並犯下更多錯誤。歸根究柢，每項最佳實務都是在管理這項資源。關於其底層機制（平方級注意力縮放，以及約 100K-token 的 smart-zone 標記），請參閱內容視窗 Smart Zone。

模型層級的放大因素（由 Claude Opus 4.7 引入，在目前的 Claude Opus 4.8 中仍然存在）：更新後的 tokenizer 會將相同輸入映射為多出 1.0–1.35 倍的 token，而 Opus 4.7「在較高 effort 等級下會思考更多」——尤其是在 agentic 設定的後續回合。Claude Code 的預設 effort 已提升至 xhigh。這些因素會疊加：在 4.6 的 high 下能容納的工作階段，在 4.7 的 xhigh 下可能會明顯變得更緊。請先在真實流量上測量，再相信從 4.6 延續而來的直覺。可用的反制手段包括：降低 effort、設定工作任務預算（API）、明確要求簡潔，或設定簡短風格的輸出上限（另見依規模而定的提示敏感度）。

以驗證驅動的開發#

最具槓桿效益的單一實務：讓 Claude 有方法驗證自己的工作。提供測試、截圖、預期輸出或 linter 指令。沒有驗證時，Claude 會產生看似合理但實際損壞的程式碼，而人類就會成為唯一的回饋迴圈。

關鍵模式：

  • 提供包含輸入與預期輸出的具體測試案例
  • 若是 UI 變更，貼上截圖並要求 Claude 比對其結果
  • 提供錯誤訊息，而不只是說「建置失敗」，以處理根本原因
  • 使用 Claude in Chrome 擴充功能進行自動化 UI 測試

探索 → 規劃 → 編碼工作流程#

將研究與實作分開。針對多檔案變更或不熟悉的程式碼，使用 Plan Mode。當範圍明確、且能用一句話描述差異時，跳過規劃。

更積極的變體是：設計概念拷問（Matt Pocock 的 grill-me skill）將「要求 agent 提出計畫」替換為「讓 agent 訪談你，直到你們在任何計畫存在之前達成共同理解」。另見垂直切片 Tracer Bullets，了解如何將產生的 PRD 切分為 agent 可直接領取的 Kanban 工單；以及給 Agent 使用的深層模組，了解如何維持適合 agent 的程式碼庫形狀。

環境設定#

  • CLAUDE.md：每個工作階段都會載入的持久指示。只納入 Claude 無法從程式碼推斷出的內容——bash 指令、非預設的程式碼風格、工作流程規則、架構決策、陷阱。毫不留情地刪減：如果 Claude 沒有這項指示也能正確完成某事，就刪掉它。把它當成程式碼：出問題時檢視，並透過觀察行為變化來測試。使用 @path 匯入以實現模組化。對創辦人／單人建構者而言，每個工作階段以 CLAUDE.md 作為架構內容開始，並在每個工作階段結束時更新它的嚴格紀律，是抵禦代理式技術債的主要防線——這類債務會複利（不只是累積），因為當內容未被持久化時，每個工作階段都必須重新推導基礎決策。
  • Skills（.claude/skills/）：按需載入的領域知識與可重複使用工作流程，不會在每個工作階段載入。使用 /skill-name 呼叫。
  • Subagents（.claude/agents/）：在隔離內容中執行、且工具範圍受限的專門助理。適合處理需要讀取大量檔案、又不想使主要內容混亂的工作。
  • Hooks：在 Claude 工作流程中特定時點執行的確定性腳本。不同於 CLAUDE.md（僅提供建議），hooks 能保證執行。
  • MCP servers：透過 claude mcp add 連接外部工具（Notion、Figma、資料庫）。
  • Plugins：從 marketplace 打包的 skills + hooks + subagents + MCP。
  • Permissions：auto mode（以分類器核准為基礎，介於預設提示與 --dangerously-skip-permissions 之間）、allowlists，或 OS 層級的 sandboxing。

工作階段管理#

  • 不相關任務之間使用 /clear——防止內容污染
  • /compact <instructions>——保留指定內容的目標式摘要
  • /rewind 或 Esc+Esc——將對話、程式碼或兩者還原至任一檢查點
  • 使用 Subagents 進行調查——在獨立內容中探索，再回報摘要
  • /btw——永遠不會進入對話歷史的側邊問題
  • 在同一問題上修正失敗兩次後，使用 /clear，並將學到的內容納入重寫後的提示

擴展模式#

  • 非互動模式：claude -p "prompt"，用於 CI、腳本、pre-commit hooks。支援 JSON 與串流輸出。
  • 平行工作階段：desktop app（隔離 worktrees）、web（隔離 VM），或 agent teams（共用協調任務的工作階段）。
  • Writer/Reviewer 模式：一個工作階段進行實作，另一個以全新內容進行審查（不會對自己的程式碼產生偏見）。
  • Fan-out：針對大型遷移，在檔案間迴圈執行 claude -p。使用 --allowedTools 限制權限範圍。
  • 針對無人值守執行的 Auto mode：分類器會阻擋高風險操作、允許例行工作。在非互動模式下重複遭到阻擋時會中止。
  • 迴圈與 routines：/loop（在 CLI 中以 cron 排程的重複工作）與 routines（伺服器端變體）。讓 Kanban 待辦清單在 AFK 狀態下持續清空；這是將規劃成本分攤至多次執行的主要機制。另見 Agent Loop Pattern。

平行生態系統與跨工具概念對照#

Claude Code 是多個逐漸匯聚的 coding-agent 生態系統之一。它與 Hermes Agent（Nous Research）及 Codex（OpenAI）的能力存在對應關係：

能力Claude CodeHermesCodex
專案內容檔案CLAUDE.mdAGENTS.md（專案）+ SOUL.md（個性，分開）AGENTS.md
工作階段壓縮/compact <instructions>/compress（透過 Codex App Server thread compaction）
工作階段中途切換模型/model/model工作階段層級設定
平行 subagents.claude/agents/ 中的 Subagentsdelegate_task由 Symphony orchestrator 產生
非互動／程式化claude -p、Claude Agent SDK腳本中的 hermes CLICodex App Server（JSON-RPC stdio）
多使用者團隊部署每個工作階段的 claude -pHermes Gateway（Telegram/Discord/Slack/WhatsApp），搭配 allowlist 或 DM 配對Symphony（由 issue tracker 驅動的 daemon）
權限閘門auto mode 分類器每種模式的核准（once／session／always／deny）；在 container backend 下跳過依 Symphony spec 定義的實作
記憶體模型對話 + CLAUDE.md有界的 MEMORY.md（約 2,200 字元）+ USER.md（約 1,375 字元）由檔案系統驅動

三者共有的結構性洞見是：agent 行為透過由 repo 版本控制的 markdown 檔案設定（CLAUDE.md／AGENTS.md／SOUL.md／WORKFLOW.md）。這種模式在各家供應商間已足夠一致，看起來像是一項正在形成的標準。（規劃中的專門Agent Context Files概念頁面將使其正式化。）

最大的架構分歧是：Claude Code 採用工作階段優先模式，並可選擇非互動模式；Hermes Gateway 與 Symphony 在團隊規模部署時則採用daemon 優先模式。工作階段與 daemon 的分野，是 2026 年部署架構的主導選擇。

常見失敗模式#

模式修正方式
廚房水槽式工作階段（混合不相關任務）任務之間使用 /clear
重複修正（失敗修正超過 2 次）/clear，將學到的經驗寫入重寫後的提示
過度詳細的 CLAUDE.md刪減；若需確定性則改用 hooks
先信任後驗證的落差始終提供驗證標準
無限探索縮小範圍，或使用 subagents

相關連結#

  • Agent Harness Engineering — Claude Code 的 CLAUDE.md、skills 與 hooks，是 OpenAI 和 Anthropic 研究團隊所描述之 harness engineering 模式的實際實作
  • LLM-as-Compiler Knowledge Base — CLAUDE.md 檔案在此知識庫的 LLM-as-compiler 架構中扮演 schema 層
  • LLM-Driven Vulnerability Research — Claude Code 是 Anthropic 弱點研究 scaffold 的執行環境；所有 Mythos Preview findings 都使用了 Claude Code 的 agentic 能力
  • Client-Side Agent Optimization — 直接挑戰「使用最強模型」這項預設：Claude Opus 4.6 搭配較便宜 planner 的組合，在 HotpotQA 上比全 Opus 高出超過 40 個百分點。AgentOpt 的 httpx interception 與 claude -p 非互動模式相容
  • 依規模而定的提示敏感度 — 補充內容視窗管理：簡潔限制既能提升容易過度思考問題的準確度，也能保留內容預算。當大型模型的冗長輸出可能掩蓋推理錯誤時，以驗證驅動的開發尤其重要
  • Claude Code Auto Mode — 完整說明環境設定與擴展模式中提到的「auto mode」權限選項
  • Claude Opus 4.7 — 引入了重塑 CLAUDE.md 與工作階段管理寫法的字面指令遵循能力及 tokenizer 膨脹
  • Claude Opus 4.8 — 現在大多數 Claude Code 工作所鎖定的模型（自 2026-05-28 起普遍可用）；它是 4.7 的直接升級版，因此上方的內容預算指南可以原封不動沿用。環境設定一節有一項注意事項：4.8 對提示注入的穩健性低於 4.7，因此狹窄的工具權限更有價值
  • Hermes Agent — 來自 Nous Research 的平行生態系統；許多 Claude Code 模式可直接對應（/compress ↔ /compact、delegate_task ↔ subagents、AGENTS.md ↔ CLAUDE.md）；差異（Gateway daemon、有界記憶體檔案、SOUL.md 分拆）凸顯各自的設計選擇
  • Codex App Server Protocol — claude -p + Claude Agent SDK 在 OpenAI 端的對應方案；兩者都能讓外部 orchestrator 驅動工作階段，但 App Server 更明確地採用穩定的 JSON-RPC stdio 協定
  • Symphony — daemon 優先的部署原型；Claude-Code 對應方案會以 Symphony 將 Codex 連接至 Linear 的相同方式，把 claude -p 加上 subagents 接入 issue tracker
  • Ticket-Driven Agent Orchestration — 非互動模式穩定後自然形成的協調模式；將單一工作階段最佳實務橋接至團隊規模部署
  • 內容視窗 Smart Zone — 驅動本文所有內容管理實務的底層限制
  • 設計概念拷問 — 探索→規劃→編碼更積極、以對齊優先的變體
  • 垂直切片 Tracer Bullets — 由 loop primitive 清空 Kanban 待辦清單所需的任務分解模式
  • 給 Agent 使用的深層模組 — 讓 Claude Code 的審查與驗證模式可靠的程式碼庫形狀；push 與 pull 的指示傳遞
  • Agent Loop Pattern — /loop 與 routines，作為取代逐步提示的新世代 primitive
  • 模型進步下的 Harness 縮減 — 為何最佳實務提示與 CLAUDE.md 區段會隨每次模型發布而縮短；Cat Wu 在每次發布時進行刪減的紀律
  • Claude Code — entity 層級頁面
  • AI Native Product Cadence — 這些最佳實務產物，是以該內部節奏運作的團隊對外公開的成果
  • Engineer PM Convergence — 本指南含蓄鎖定的「具備產品品味的工程師」人格
  • 代理式技術債 — CLAUDE.md 主要防範的失敗模式；在創辦人手冊中有明確命名
  • AI-Native Startup Lifecycle — 將 CLAUDE.md 從「最佳實務」提升為「MVP 生存紀律」的創辦人階段框架
  • MCP and Computer Use — 「以自訂工具擴充 Claude Code」擴展模式背後的 connector substrate；MCP 與 computer use 是讓外部系統成為 agent 行動介面的方式
  • Evals as Product Spec — 「以驗證驅動的開發」的嚴格形式：十個優秀 evals 以功能層級編碼完成的樣貌，補充本文規定的工作流程層級驗證

衍生內容#

待解決的問題#

  • CLAUDE.md 在指示開始遺失前的最佳長度是多少？是否存在可測量的門檻？
  • Writer/Reviewer 模式與 agent 對 agent 審查相比如何（如 OpenAI 的 Codex 工作流程）？
  • 何時 subagent 的額外成本會超過內容隔離帶來的效益？

資料來源#

§ end
About this piece

Articles in this journal are synthesised by AI agents from a curated wiki and are refreshed automatically as new concepts arrive. Topics, framing, and editorial direction are curated by Howardism.

Cited by 45
Related articles
  • Agent Harness Engineering

    Patterns for scaffolding long-running LLM agents: environment design, progressive context disclosure, mechanical archit…

  • Harness Shrinkage as Models Improve

    Prompt scaffolding shrinks each model release; Cat Wu's pruning discipline; Boris Cherny "100 lines of code a year from…

  • Client-Side Agent Optimization

    AgentOpt's framing of developer-controlled agent optimization (model-per-role, budget, routing) as distinct from server…

  • Claude Code

    Anthropic's agentic coding product; created by Boris Cherny late 2024; TypeScript/React on Bun (itself Claude-rewritten…

  • Open Questions Backlog

    _456 actionable open questions across 205 pages · 107 predictions · 9 notes · 147 in progress · 69 watching (entities),…