详解 Claude Code 的 /team-onboarding 命令：我跑完才明白它在替团队干什么

哈喽，我是飞飞。

上周三晚上我升级了 Claude Code 到 v2.1.101，看到 changelog 里多了一行：「Added /team-onboarding command」。

我习惯性在主仓库里跑了一次。

输出贴到屏幕上那一瞬间我有点尴尬。

里面挂着我自己写的好几条绝对路径，挂着我个人 dev 环境的 MCP 配置，挂着一堆我习惯性给自己开的 allow 权限。

如果我把这份直接发给团队新人，他们会以为这就是团队标准。

那一刻我才反应过来，这个命令真正在干的事，是替我审视自己留在这个仓库里的隐性习惯。

/team-onboarding 到底在生成什么

先把命令本身讲清楚。

/team-onboarding 是 Claude Code v2.1.101 在 2026 年 4 月 10 日（Week 15 release）加进来的内置斜杠命令，调用方式就一行：

/team-onboarding

不带参数，在任何活跃的 Claude Code 会话里直接输入即可。

它会做一件事，扫你过去 30 天在这个项目里的会话历史、用过的斜杠命令、配置过和实际调用过的 MCP 服务器，把这些行为揉成一份结构化的 Markdown 草稿。

说白了就是，它把”老同事最近一个月在这个项目里都用了哪些工具，写过哪些 prompt 模板，跑过哪些自定义 workflow”显式地写成文档，让新人能直接拿来用。

为什么是 30 天而不是 7 天或 90 天？

7 天太短，刚好覆盖一个 sprint，抓到的多是临时实验和一次性脚本。

90 天太长，会把项目早期的试错噪音也拖进来。

30 天卡在一个”稳定使用期”的窗口上，既能反映真实习惯，也能过滤掉早期摸索。

这个数字本身是设计选择，不是随便定的。

我跑完那一份 ONBOARDING.md 长什么样

回到我自己那次。

跑完之后 Claude Code 在会话里直接吐出一份完整的 Markdown，大概 600 行，分了 6 个章节。

开头是项目快速 setup，里面挂了我装 hexo CLI 用的 npm 命令、本地起服务的端口、一条我个人习惯的 hexo clean → hexo g → hexo s 三连命令链。

往下是我在这个项目里高频用过的斜杠命令，/content-director、/content-publisher、/content-researcher，加上每条命令的典型触发语和我自己最近一次的实际调用。

再往下挂了我配置过的 MCP 服务器，包括 banana-image 这套生成封面图的私有 MCP、brave-search 拉行业资料用的 MCP。

然后是我反复使用的 prompt 模板，包括我跟 polisher skill 沟通时几乎每次都会带的”扫一遍 grep 硬规则”那条引导句。

倒数第二段叫”常见陷阱”，列了我自己之前踩过的几次：一次是把封面图上传顺序搞反了，一次是 hexo new 之后忘了改 frontmatter 的 date。

最后一段是”团队约定”，这段比较空，因为我这个仓库其实是单人维护，没什么团队约定可以抽取。

整份文档读下来的感觉很直接，它确实能让一个新人在 20 分钟内知道我在这个仓库里”日常都在干什么”。

但它也很赤裸地把我个人的本地习惯暴露了出来。

ShareOnboardingGuide 这个工具单独说一下

光生成一份 Markdown 不算稀奇。

/team-onboarding 真正配套的是一个叫 ShareOnboardingGuide 的内置工具，它负责把这份 ONBOARDING.md 上传到 Anthropic 的 guide 服务，换一个短码（short_code）出来。

短码长这样：6 到 8 位字母数字混合，团队成员拿到短码后可以直接在自己的 Claude Code 里打开对应链接，guide 内容会作为新会话的首条上下文加载进去。

这个工具有 4 个模式。

check 是默认模式，本地有 ONBOARDING.md 文件就上传到组织里最近一份 guide，没有就返回已有链接。

update 是用短码指定某一份 guide 覆盖更新，适合 ONBOARDING.md 改版后同步。

create 是强制新建一条 guide，每次拿到新短码。

delete 是按短码删一条 guide。

我自己实际用 check，每次 ONBOARDING.md 改了跑一次就把同一条链接内容更新掉，团队成员收藏的旧链接还能继续用，体验比群里反复贴新链接舒服多了。

权限上，目前看起来 Pro / Max / Team / Enterprise 几种付费 plan 都能用，免费 plan 是否开放还没看到明确说法。

ONBOARDING.md 跟 CLAUDE.md 各自管的事情不一样

这是最容易被搞混的一点。

CLAUDE.md 是项目根目录下那份每次会话启动都会自动加载的指令文件，里面写的是项目架构、命名规则、构建命令、Git 工作流这种长期不变的硬性规范。

ONBOARDING.md 不一样，它是 /team-onboarding 跑出来的产物，反映的是过去 30 天最近的使用习惯，是一份动态快照。

我用一张表对照一下：

文件	内容性质	加载时机	更新频率	权威性
CLAUDE.md	规范、规则	每次会话自动加载	手动维护，半年改一次	团队标准，Claude 必须遵循
ONBOARDING.md	实践、发现	新人手动加载或通过短码链接	自动重生成，可频繁刷新	入职辅助，不是规范
settings.json	配置	启动时加载	跟着权限变更走	权限和 hook 边界
skills	程序性知识	按需触发	跟着任务模式沉淀	重复任务专用

CLAUDE.md 是”团队应该怎么做”的规范，ONBOARDING.md 是”老同事最近实际怎么做”的快照。

这两份文件不该混在一起，也不该一份替代另一份。

CLAUDE.md 一旦写好就要被严格遵守，ONBOARDING.md 反过来，跑一次看一次，能看到什么就是什么。

分享前必查的三件事

回到我那次的初跑。

输出文档里挂的那些本地路径、MCP 配置、宽松权限，是 /team-onboarding 这个命令本身没办法替你过滤的。

分享给团队之前，你必须自己 review 三个区域。

先说本地机器假设这一块。

绝对路径（/Users/vancexin/Documents/...）、临时目录（/tmp/cache-xxx）、私人 shell 别名，这些只对你自己有意义，新人拿到会一脸懵。

我那次扫了一遍，把 4 处绝对路径全部替换成项目相对路径或环境变量。

MCP 假设那一项更隐蔽。

我自己装的 banana-image MCP 是私有的，团队新人没有，文档里挂着这个 MCP 的调用会让对方以为这是项目标配。

正确做法是在 ONBOARDING.md 里给每个 MCP 加一行说明，标注”团队必装”还是”我个人在用”。

权限和安全这块最容易被忽略。

我个人开发环境里给 Claude Code 的 allow 列表特别宽松，连 rm 都直接放行。

这份默认设置一旦被新人当成团队标准抄过去，刚入职那周可能就会出事。

所以 ONBOARDING.md 里凡是碰到 settings，必须按”最严格的团队默认”重写一遍，把个人宽松设置剔除。

这三件事 SmartScope 那篇评测文章总结得很到位，他们叫”local-machine assumptions / MCP assumptions / permissions and safety”，跟我的实际遭遇完全对得上。

把它当探测器用，会比当生成器用走得远

跑过几次之后我形成了一个新理解。

实话讲，/team-onboarding 真正值钱的地方在于它逼你看清你团队的隐性知识到底卡在哪几个人脑子里。

每次跑出来的那份 ONBOARDING.md，本质上是一面镜子，照的是过去 30 天在这个仓库里最活跃的那个人的工作流。

如果你跑出来看了之后觉得”嗯这就是我团队的标准做法”，那说明你的团队工作流已经够清晰了。

但如果你看了之后惊呆，发现”原来我每天都在用这么多本地路径”、”原来这个 MCP 只是我一个人装了”、”原来我给自己开了这么多宽 allow”，那才是这个命令命中目标的时刻。

惊呆的那一刻，就是你应该把这些隐性习惯升级成显性规范的时刻。

SmartScope 把这套用法叫”tribal-knowledge detector”（部落知识探测器），我觉得这个词比”onboarding guide generator”准确得多。

操作上的最佳循环大概是这样。

让最活跃的成员先在成熟仓库里跑一次 /team-onboarding，然后人工 review 一遍，把本地路径、私有 MCP、宽权限这些个人化的东西全部剔除。

剔除下来发现的稳定规范，挪进 CLAUDE.md 或 .claude/settings.json，让它们正式成为团队规则。

清洗过的 ONBOARDING.md 通过 ShareOnboardingGuide 上传，发短码链接给新人。

新人入职几周后，再跑一次 /team-onboarding，看新的输出里还有没有从老同事那继承下来的本地噪音，没有就说明知识沉淀已经落地。

这套流程跑两轮，团队隐性知识基本就被显式化了。

我自己跑下来踩过的两个小坑

再说两个我跑这个命令时撞到的具体障碍。

一个是老版本看不到这个命令。

我同事的 Claude Code 还是 v2.0.x 的版本，我跟他说”你跑一下 /team-onboarding”，他在自己机器上敲完发现命令根本不存在。

解决办法是先 claude --version 看版本，低于 2.1.101 就先升级。

另一个是新项目跑出来的内容会很稀薄。

我在一个刚建两周的新仓库里跑了一次，输出只有不到 100 行，因为 30 天会话历史里没多少东西可抓。

这个命令的产出质量跟项目使用历史强相关，越成熟、越活跃的仓库跑出来越饱满。

如果是新项目想做入职引导，老老实实手写 CLAUDE.md 更合适，/team-onboarding 留到项目跑了三个月再用。

章节结构会不会迭代和短码会不会挂 dashboard

下个月我自己想观察的是这两个具体动向。

一个是 /team-onboarding 输出的章节结构会不会再加一层。

目前 6 个章节里”团队约定”那一段对单人维护的仓库基本是空的，等 Claude Code 能把多人协作的 PR 评论、Code Review 习惯也抓进去，这段就会真的有内容。

另一个是 ShareOnboardingGuide 的短码会不会向团队管理工具方向延伸。

现在短码只是一个 URL，等它能挂到企业级 dashboard 上做版本追踪和访问统计，团队就能看到”新人入职 7 天内有几个人打开了这份指南”，入职效果第一次有了可观测的指标。

你呢，升级到 v2.1.101 了吗？

如果你在自己最常用的那个仓库里跑了一次 /team-onboarding，输出里有没有让你尴尬到想立刻删的几行？

评论区告诉我，下次我可以聊一篇”我清理 ONBOARDING.md 的具体改动日记”。