Claude Code /team-onboarding 完整教學 - 讓新同事一天內搞懂你的 AI 開發工作流

新人到職第一天，你遞了一份 README 過去。三小時後他來問你：「這個 /compact 是什麼？」「為什麼你的 CLAUDE.md 裡面有一段看不懂的 hook 設定？」「sub-agent 跟直接問 Claude 差在哪？」

README 沒有錯，是它沒辦法反映你實際的工作方式。而 /team-onboarding 做的事情就是掃描你過去 30 天的 Claude Code 使用紀錄，把你的真實工作流整理成一份結構化的新人指南。

這個指令在幹嘛

/team-onboarding 是 Claude Code v2.1.101（2026 年 4 月 10 日）加入的 slash command。執行之後，它會分析你最近 30 天的 Claude Code 使用歷史，然後產出一份包含以下內容的 onboarding 文件：

你實際用過的 commands 和 workflows、你的 CLAUDE.md 設定邏輯、常用的 MCP server 和工具、sub-agent 的使用模式、還有你團隊特有的慣例（像是 commit message 格式、code review 流程）。

重點不是「Claude Code 有哪些功能」——官方文件已經寫得很清楚了。重點是「你的團隊怎麼用這些功能」。每個團隊的 Claude Code 用法都不一樣，這份文件捕捉的是你們自己的最佳實踐。

怎麼用

在終端機打開 Claude Code，輸入：

1	/team-onboarding

就這樣，沒有參數。Claude 會開始掃描你的使用紀錄，過程大概 30 秒到 2 分鐘，取決於你過去 30 天的活動量。

掃描完之後會產出一份 Markdown 文件，預設存在專案根目錄的 ONBOARDING.md。你可以直接丟給新人看，也可以放進團隊的文件庫。

產出的內容長什麼樣

一份典型的 onboarding 文件會有這些段落：

團隊工作流概覽——你們用 Claude Code 做什麼。是寫新功能、修 bug、做 code review、還是跑自動化腳本？這邊會列出最常見的使用模式。

常用指令速查——不是列出所有 Claude Code 指令，而是列出你們團隊實際高頻使用的那些。/compact 用在什麼時候、/focus 的使用時機、/review 搭配什麼參數。

CLAUDE.md 設定說明——把你的 CLAUDE.md 裡面的設定逐項解釋，讓新人知道每一段在幹嘛。特別是 hooks、permissions、custom rules 這些不看說明很難猜意思的區塊。

MCP Server 清單——團隊接了哪些 MCP server、各自的用途、常見的使用情境。

Sub-agent 使用慣例——什麼時候該開 sub-agent、怎麼設定 isolation、你們團隊的 sub-agent 命名慣例。

Git 工作流——Claude Code 怎麼跟你們的 Git 流程整合。branch naming、commit message、PR 流程。

實際跑一次的經驗

跑完之後最明顯的感受是：原來我的工作模式比自己以為的還固定。

產出的文件準確地抓到我最常用的五個指令組合、我的 CLAUDE.md 裡三個最關鍵的 hook 設定、還有我跑 sub-agent 時固定會加的 --isolation worktree 參數。這些東西我自己從來沒有系統性地整理過，但每天都在用。

一個意外的收穫是它會標出「你的用法跟預設不同」的地方。像是我把 bypassPermissions 設成特定工具組合而不是全開，文件會解釋這個決定背後的安全考量。新人不只知道「怎麼做」，還知道「為什麼這樣做」。

搭配 Brief Mode 和 Focus Mode

既然提到 4 月的更新，順便講一下另外兩個跟團隊協作相關的改進。

Brief Mode 改善了回應品質——當 Claude 用 brief mode 回應時，如果偵測到回應太簡略（純文字而不是結構化訊息），現在會自動 retry 一次。聽起來是小事，但 brief mode 是很多團隊日常用的模式，回應品質的穩定度直接影響工作效率。

Focus Mode 則是另一個維度的改進。開啟 Focus View（Ctrl+O）之後，畫面只顯示 prompt、工具摘要、和最終回應，中間的思考過程和工具呼叫細節全部收起來。適合你已經知道 Claude 在做什麼、只想看結果的場景。

Focus Mode 還有一個對 onboarding 很有用的特性：因為 Claude 知道你只看得到最終訊息，它會寫更完整的 self-contained 摘要。翻譯成白話就是——Focus Mode 下的回應更適合直接截圖貼到文件裡。

跟 Kiro 和 Copilot 的差異

Kiro CLI 最近也在做團隊體驗的投資——2.0 版的 sub-agent 監控和 task list 就是例子。但 Kiro 走的是 spec-driven 路線，團隊知識是透過 specs 和 EARS 語法的 user stories 來傳遞。換句話說，Kiro 的 onboarding 是「讀規格」，Claude Code 的 onboarding 是「看實際用法」。

GitHub Copilot 在這塊目前還比較弱。Copilot 的 instructions 檔案（.github/copilot-instructions.md）可以定義團隊規範，但沒有自動從使用紀錄產生 onboarding 文件的功能。你要自己手動維護。

三者的設計哲學不同：Kiro 認為好的規格文件就是最好的 onboarding，Copilot 靠手動維護的 instructions，Claude Code 則是從實際行為中萃取知識。各有優缺，但 /team-onboarding 的優勢是零維護成本——你不用額外寫任何東西，它自己去看你怎麼用的。

一些使用建議

定期重新產生。你的工作模式會隨專案階段改變，建議每個月或每次有大的 workflow 調整之後重跑一次。舊的文件不用刪，版本比較反而能看出團隊工作方式的演進。

搭配 CLAUDE.md 一起看。/team-onboarding 產出的是「你怎麼用」，CLAUDE.md 定義的是「Claude 怎麼工作」。新人需要兩份文件才能完整理解你的 AI 開發環境。

不要只給新人看，資深成員也該看。跑了之後你會發現團隊裡每個人的使用模式差異可能比想像的大。有人重度用 sub-agent，有人從來不用。有人每次都 /compact，有人讓 context 無限長。把大家的 onboarding 文件放在一起比較，本身就是一次很好的 workflow 對齊。

不要手動修改產出的文件。如果你覺得產出結果不準確，問題通常出在你的使用模式本身。與其修文件，不如調整 CLAUDE.md 的設定或改變操作習慣，下次重新產生自然會反映。