使用手冊

Claude Code / Agentic Engineering Reference

從 vibe coding 走向可編排的agentic engineering。

shanraisshan/claude-code-best-practice 繁體中文技術解析：Claude Code agents、commands、skills、hooks、MCP、settings、orchestration workflow、reports 與 Codex 可借鑑的 agentic engineering patterns。

claude-code-best-practice 是一座 Claude Code 操作知識庫：它不是單一技巧清單，而是把 agents、commands、skills、hooks、MCP、settings、memory、reports、tips 與實作範例組成一套「怎麼把 Claude Code 當工程系統」的參考架構。

shanraisshan/claude-code-best-practice
星標
55.7K
分支
5.6K
授權
—
資料截至
閱讀時間
7 分
更新日期
開啟原始報告
GitHub Stars
55k+
Primitives: A/C/S
3
Reports / Deep Dives
12+
License
MIT
本頁章節

01Repository Signal

這是一門課, 不是一個可以盲裝的 workflow。

README 自己的 How to Use 說得很清楚：先把這個 repo 當課程讀，而不是當成 workflow 或 skill 直接跑。它收集 Claude Code 的核心 primitives、熱門 beta 功能、社群技巧、實作案例與報告，並用範例 repo 形式展示如何把 Claude Code 從聊天工具變成可編排的工程工作台。

repo metadata 顯示它以 HTML 為主要語言，採 MIT 授權，描述是「from vibe coding to agentic engineering」。topics 包含 claude-code、agentic-engineering、claude-code-agents、claude-code-commands、claude-code-skills 與 context-engineering。

它的價值不在於單篇 best practice，而是把官方文件、Boris/Thariq/社群 tip、workflow repo、實作範例與自己可執行的 weather orchestration demo 串起來。對 Codex 使用者來說，這是理解「agent instructions、skills、commands、hooks、MCP 與驗證流程如何拼在一起」的好參考。

02Concept Map

README 的核心是 Claude Code primitives 的地圖。

Agents

.claude/agents/*.md

展示 feature-specific subagents、frontmatter、model、tools、memory、background、worktree isolation、agent teams 等配置。

Commands

.claude/commands/*.md

slash command 是 workflow entry point，適合負責使用者互動、步驟協調、Agent tool 呼叫與 Skill tool 呼叫。

Skills

.claude/skills/*/SKILL.md

repo 同時示範 agent skill 的 preload 模式，以及 direct Skill invocation 模式，這是 weather workflow 的關鍵教學點。

Hooks

.claude/hooks/

包含 Python hook handler、team config、local override 與大量 sound events；目的是讓工具使用、壓縮、停止、權限等事件可感知。

MCP

.mcp.json

目前配置 Playwright、Context7、DeepWiki，對應 browser automation、文檔查詢與 repo knowledge lookup。

Memory & Rules

CLAUDE.md / .claude/rules

repo 明確建議讓 CLAUDE.md 保持短、讓 rule 依 paths lazy-load，避免把所有規則塞進每次 session。

03Command → Agent → Skill

weather demo 是整個 repo 最重要的 executable teaching artifact。

  1. /weather-orchestrator

  2. AskUser Unit

  3. weather-agent

  4. weather-fetcher

  5. weather-svg-creator

orchestration-workflow/orchestration-workflow.md 描述了一個完整 Command → Agent → Skill flow。command 是入口，負責問使用者 Celsius/Fahrenheit、呼叫 agent、再呼叫 skill；weather-agent 內建 preload 的 weather-fetcher skill；weather-svg-creator 則獨立產生 SVG 與 Markdown output。

這個範例把兩種 skill 型態講清楚：一種是 agent 啟動時預載入 context 的 domain knowledge；另一種是 command 直接用 Skill tool invoke 的可執行能力。這比抽象說「用 skills」更有教育價值。

bash
User: /weather-orchestrator
  1. command asks C or F
  2. command invokes Agent(subagent_type="weather-agent")
  3. weather-agent uses preloaded weather-fetcher skill
  4. command invokes Skill("weather-svg-creator")
  5. outputs orchestration-workflow/weather.svg and output.md

04Repo Instructions

CLAUDE.md 把這個 repo 定位成 reference implementation。

該 repo 的 CLAUDE.md 明確說明：這不是 application codebase，而是 Claude Code configuration 的 best-practices reference。它記錄 weather system、skill frontmatter、presentation delegation、hooks system、subagent orchestration、configuration hierarchy、best-practice search policy、workflow tips、debug tips 與 git commit rules。

對大型知識庫很關鍵的一條：當使用者問 Claude Code best practice 時，先搜尋本 repo 的 best-practice/、reports/、tips/、implementation/、README.md，再 fallback 到外部資料。這是一個「repo 自身成為 agent knowledge base」的好 pattern。

主題repo 指令Codex 借鑑
Config hierarchymanaged → CLI args → local project → shared project → global把覆寫順序寫進 AGENTS.md，避免 agent 猜設定來源。
Workflow scale複雜任務先 plan mode，小任務拆到 50% context 內可完成。把 context budget 與 verification checkpoints 寫成標準流程。
Debugging/doctor、background tasks、browser MCP、screenshots。對應 Codex 可用 lint/build、browser plugin、curl route checks。
Git commits每個檔案分開 commit。不一定照抄，但可借鑑「可 review、可 revert」的 commit discipline。

05Reports & Implementations

深度報告讓 repo 從清單變成研究索引。

Agent SDK vs CLI

系統 prompt 與 runtime 對照

reports/claude-agent-sdk-vs-cli-system-prompts.md 這類報告適合回答「何時用 CLI、何時用 SDK」。

Browser MCP

Claude in Chrome vs DevTools MCP

瀏覽器自動化被放進 reports，而不是散在 README。這讓工具比較可以被版本化。

Global vs Project

設定與 tasks 系統

適合團隊釐清哪些該放全域，哪些該在 repo shared settings 或 local settings。

Skills in Monorepos

大型 repo 的 skill 組織

對這個 Tenten Skills repo 也直接相關：generated docs、skills、templates 需要清楚邊界。

Implementations

不是只講觀念

implementation/ 包含 agent teams、commands、goal、scheduled tasks、skills、subagents 等可讀範例。

Development Workflows

跨 repo workflow 比較

README 對 Superpowers、Spec Kit、gstack、GSD、BMAD 等 workflow 進行對照，像是一份 agentic workflow 市場地圖。

06Codex Translation

這份 repo 對 Codex 最有用的是結構, 不是 Claude 專有指令。

repo 甚至包含 .codex/config.toml 與 .codex/hooks/，代表作者已經把 Claude Code hooks 思路往 Codex CLI 移植。對 Codex 而言，不能照搬 .claude/commands，但可以借用三層結構：root instructions 定義政策、skills 提供 progressive disclosure、hooks/verification 提供操作回饋。

如果要把它變成 Codex 最佳實務頁，建議聚焦在四件事：AGENTS.md instruction hygiene、可重複的 verification commands、repo-local skill discovery、以及不要讓 agent 把 workflow 變成不可 review 的巨型改動。

bash
1. Map CLAUDE.md guidance into AGENTS.md.
2. Replace Claude slash commands with documented Codex task recipes.
3. Treat skills as small, load-on-demand knowledge modules.
4. Use hooks only where they improve operator feedback.
5. Always finish with source-index regeneration plus type/lint/build checks.

07Operational Risks

大型 best-practice repo 最大風險是把參考材料誤當模板。

08Usage Playbook

如何真的讀這個 repo。

先跑 weather flow

它是 command、agent、skill 三者如何分工的最小完整範例。

再讀 CLAUDE.md

理解 repo 自己如何指導 Claude Code 操作這個 knowledge base。

按問題查 reports

不要從頭讀所有報告。遇到 settings、memory、MCP、tool use 再打開對應篇。

用 implementation 做 copy source

要做 agent teams、goal、scheduled task 時，從實作檔案學 frontmatter 與資料流。

最後才移植到 Codex

先抽象出流程與驗證點，再轉成 Codex 的 AGENTS.md、skills、hooks 或 local scripts。

參考資料