Claude Code 實戰筆記：一份公開的 AI 開發最佳實踐指南

我把這段時間使用 Claude Code 的所有筆記整理成了一個公開的 GitHub 儲存庫：claude-code-insights。它不是原創研究，而是一份把 Anthropic 官方文件、社群文章與熱門 GitHub 專案的觀點整理在一起的學習資源——讓自己（也讓任何想踩進這個 AI 開發工具的人）有一個可以直接查閱的地方。

這篇筆記說明這份倉庫的結構、為什麼我決定把它公開，以及如果你剛開始用 Claude Code，該從哪裡切入。

什麼是 Claude Code

Claude Code 是 Anthropic 推出的命令列 AI 開發助理。它不只是一個 ChatGPT 式的對話視窗——它可以讀寫檔案、跑指令、執行長時間任務、整合到你的 IDE 或 CI 管線裡。跟其他 AI coding 工具相比，它的差異在於：

• 開放的檔案系統存取：直接讀寫你專案裡的任何檔案，不需要複製貼上
• 工具使用（tool use）能力：可以執行 Bash、呼叫 MCP server、啟動 subagent
• 可被自訂的行為：透過 CLAUDE.md、Skills、Hooks 三層系統，讓它的行為契合你的工作流
• 在 terminal 裡就能用：不綁定任何 IDE，也能整合進 VS Code、Cursor、JetBrains

這些特性讓 Claude Code 不只是「幫你寫 code 的工具」，更像是一個可被你訓練成熟悉你專案的隊友。

三個核心主題

整個倉庫圍繞 Claude Code 最關鍵的三塊：CLAUDE.md、Skills 與 Subagents。三者各自有自己的設計模式與反模式，我把它們分開拆解，並記錄了每一塊的觸發機制與安全考量。

CLAUDE.md：agent 的長期記憶與行為憲章

CLAUDE.md 是 Claude Code 每次對話開始時自動讀取的檔案，等於是 agent 的「工作手冊」。它適合放：

• 專案的架構總覽（有哪些資料夾、各自職責）
• 程式碼風格慣例（縮排、命名、不寫註解的理由）
• 嚴禁的操作（不要 push 到 main、不要碰 secrets）
• 專案特定的術語對照表

一個常見的反模式是把 CLAUDE.md 寫成「待辦清單」或「開發日誌」——這兩者都應該放到 issues 或其他地方。CLAUDE.md 應該只記錄跨對話都成立的規則。

Skills：把重複工作模板化

Skills 是把你會重複做的工作流程打包成可被召喚的能力。例如「每次寫完 feature 就跑 security review」、「每次開新 branch 就先更新 changelog」。

Skills 的好處是：

• 不需要每次都把完整指令輸入一次
• 可以被多個專案重用
• 可以被團隊共享，讓所有人都用同一套流程

Skills 的觸發可以是明確指令（/security-review），也可以是自動（看到特定情境就提示使用）。

Subagents：讓主對話保持乾淨

Subagents 是 Claude Code 的隔離工作區機制。你可以把「搜尋整個 codebase」、「跑一組測試並歸納錯誤」這類會吃掉大量 context 的任務丟給 subagent 處理，主對話只會收到結論摘要。

這對長時間工作、複雜專案特別重要——一個 context 塞滿垃圾資訊的 agent，判斷力會明顯下降。善用 subagent 是讓 Claude Code 長期可用的關鍵。

為什麼我決定公開這份筆記

工具的能力比官方文件更新得快。當你開始大量使用 Claude Code，會發現很多「該不該這樣做」的問題其實散落在：

• GitHub issues 的討論串
• Anthropic Discord 的 #claude-code 頻道
• 別人公開的 dotfiles 與工作流
• Reddit、Twitter、Hacker News 的零散分享

沒有一個地方統一整理。我做這件事，是因為我自己需要它——每次切新電腦或新專案，重新找這些資源都太痛。

公開它的另一個理由：AI 工具的使用經驗本身就是一種應該被分享的知識。我從很多人的 gist、dotfiles、openly-shared prompts 裡學到東西，現在把我的版本也丟回去。

倉庫裡的實作範例

除了三份核心指南之外，倉庫也收錄了幾組可以直接複製到 .claude/ 使用的實戰範例：

• security-reviewer subagent：Semgrep + Codex 雙重驗證的安全稽核，嚴格劃分 review（唯讀）與 fix（需明確 opt-in）邊界
• npm 供應鏈三層防禦：.npmrc 腳本封鎖 + PreToolUse Hook 檢查（registry、OSV.dev、版本解析）+ Semgrep 掃描，附 42 個回歸測試
• rules 入門套件：6 份風險分級的 .claude/rules/ 規則檔，核心是 pragmatism 層——以風險分級決定規則執行強度
• 個人開發工作流：/grill-me（設計質詢）→ /write-prd（寫 PRD）→ /prd-to-plan（拆階段）→ /tdd（實作）
• Skill 開發工作流：/write-a-skill（撰寫 Skill）→ /skill-eval-toolkit（盲測 A/B、benchmark、description 觸發優化）
• frontend-design skill：拒絕 AI 罐頭美學的前端介面設計，含 Glassmorphism Wallet 實作展示

如果你也在摸索怎麼把 Claude Code 整合進自己的開發流程，這份筆記應該能省下你不少時間。

給想入門的人：從哪裡開始

如果你是第一次用 Claude Code，我的建議順序是：

1. 先用它做一件真的要交差的任務。不要空跑範例，選一個你本來就要做的功能，直接叫它寫
2. 寫第一份 CLAUDE.md。就算只有 10 行也好，把你最常重複的指令寫進去
3. 觀察它卡在哪裡。每次它誤解你的意圖，就把「正確的做法」回寫進 CLAUDE.md
4. 重複兩到三週後，開始用 Skills。把重複流程抽出來
5. 遇到長任務再啟用 Subagents。不要一開始就用，會過度工程

這個順序的核心是讓工具配合你的節奏，而不是你去學工具的節奏。

結語

AI 開發工具的進化速度比任何開發者能追上的都快。我們能做的不是追上它，而是沉澱自己的使用經驗、找到跟工具共同演化的節奏。

這份筆記會持續更新。如果你也在用 Claude Code 或類似的 AI 開發工具，歡迎 star、fork、或提 issue 討論。

/ GITHUB / REPO

查看 GitHub 儲存庫 claude-code-insights

https://github.com/dianyike/claude-code-insights

→