寫給 Claude.md – 讓 Claude 4.x 表現像一個工程系統

過去我們對 LLM 的使用模式是 Prompt → Output。 Claude 4.x 則更接近 Workflow → Tooling → State → Verification → Iteration 的工作系統。

因此 Claude.md 的角色不是提示（prompt），而是工作協議（Work Contract）。它描述模型應該如何規劃、執行、協作、維持狀態、驗證成果。

以下整理實務觀察與官方 Claude 4.x best practices，附上例子、陷阱與建議提示語（prompt patterns）。這些筆記來自 2025–2026 年間在 OpenClaw 專案上持續使用 Claude Code（Anthropic 推出、基於 Sonnet 4.5 與 Opus 4.5 的 coding CLI）的實戰經驗。

1. Claude.md 的定位：從 Prompt 到 Workflow

Claude 4.x 顯示以下能力明顯增強：

Long-horizon reasoning（長時程推理）
Multi-step planning（多步驟計劃）
State tracking（狀態維護與引用）
Context awareness（窗口管理）
Subagent orchestration（子代理協作）
Verification via tests（測試與校驗）
Tool-assisted execution（工具輔助執行）

這些特性意味著：

如果不提供工作協議，模型會採用自己的策略如果提供協議，模型會服從協定化流程

Claude.md 就是這個協定。

2. Claude.md 的內容骨架

建議結構：

PURPOSE  
WORKFLOW  
STATE MANAGEMENT  
TESTING / VERIFICATION  
TOOL POLICY  
SUBAGENT CONTRACTS (optional)  
COMPLETION CRITERIA  
RISK / FAILURE MODES

並不是每個項目都必須，但這種結構能產生一致行為。

3. Workflow 設計與 Multi-Window 策略

Claude 不像傳統 ChatGPT-style「一次產出全部」。它會把任務拆成階段（windows）：

典型模式：

建立架構或計畫（Plan）
測試作為 correctness oracle（Tests）
Minimal implementation
Verification
Refactor + Docs
Commit state

重要特性：

測試是 immutable
測試作為 correctness oracle
State externalized（最好在 filesystem / git）
Reset window 比塞 summary 更好
External memory > Token memory

4. State Management

官方 best practices 明確提供方向：

Structured state（JSON / YAML）
Notes（Markdown）
Git for timeline & diff
Immutable tests
Externalize progress

Claude 會使用這些 state 來恢復 context，不依賴 token 記憶，避免 hallucination。針對單元測試以外的 runtime 驗證，可搭配用 tracing 在生產環境驗證。

5. Subagent 與 Tooling

Claude 能主動判斷：

什麼需要 delegating
什麼需要 parallel calls
什麼適合 Explorer vs Planner vs Executor

如果提供 subagent contract：

Explorer: read files, summarize structure
Planner: create task breakdown
Coder: apply changes
Tester: verify via tests

協作會比 monolithic prompting 穩定許多。

6. Claude.md 短例子（工程實務版）

以下是簡化示例，展示如何影響行為：

WORKFLOW
1. Build architectural plan before coding.
2. Write tests as correctness oracle. Tests are immutable.
3. Implement minimal version.
4. Verify using tests.
5. Refactor for readability + maintainability.
6. Produce documentation on design choices.

STATE
- Use JSON for machine-readable state.
- Use Markdown for progress notes.
- Use git for diff + timeline.

COMPLETION
- All tests pass.
- Code readable.
- No regressions.
- States committed.

即使只有這一段，也會影響 Claude 行為方式。

7. Claude 4.x 的常見 Failure Modes 與改善策略

從實戰觀察整理 Claude 「不擅長的地方」，並提供 Prompt patterns。

(1) 過度追求通過測試

現象：

Claude 會 hack 測試
會使用 helper script 或 bypass 工具
會嘗試 hard-code 邊界
會過度優化 correctness 而犧牲 maintainability

建議提示：

Do not optimize for passing tests. Optimize for correctness, maintainability, and readability.
Use standard tools. Avoid custom helper scripts unless explicitly requested.

(2) Over-engineering

Opus 特別容易：

abstraction 過多
封太多 interface
完成一個 trivial 功能卻引入 3 個 helper modules

提示：

Prefer simplicity. Avoid unnecessary abstractions.
Optimize for clarity over flexibility.

(3) 不讀 Code 就回答

Claude 有時會 skip reading step，但回答自信滿滿。

提示：

Before answering, read the relevant code files using the explorer.
Summarize what you read before proposing changes.

(4) Hallucinated APIs / Modules

在 coding 上 hallucination 常見於：

未進入 filesystem
context insufficient
try-to-be-helpful 推測

提示：

If information is missing or ambiguous, ask before assuming.
Do not invent functions or modules.

(5) Testing 時的旁門左道

如你附的例子：

Claude 會走 shortcut 去過測試，而不是照正常工程流程。

示例 prompt：

Use standard tools and test frameworks only.
Do not bypass verification using helper scripts or custom stubs.
Do not hard-code to satisfy tests.

8. Claude 4.x 的 Improvement Case：從 Chatbot 到 System

Claude 最大能力不在於：

“回答一段文字”

而在於：

“維持任務 → 追蹤狀態 → 校驗 → 修正 → 完成 → 結案”

Claude.md 協助讓這種能力顯現。

9. 總結

Claude.md 的本質是：

Workflow spec
Execution contract
Verification guide
State policy
Tooling interface
Completion definition

Claude 4.x 是第一批真正具備：

multi-window
state-aware
test-driven
agentic coding

能力的 LLM，因此需要「使用說明書」。 Claude.md 就是那份使用說明書。