Claude Code のチームオンボーディング

問題: カスタムの Claude Code ハーネスを3ヶ月かけて構築した。数十のスキル。いくつかのカスタムスラッシュコマンド。2〜3つのサブエージェント。自分での使い方はもう第二の自然だ。それを使おうとする新しいチームメンバーは全員、最初の1時間で迷子になる。

クイックウィン: v2.1.101 で追加された。プロジェクトのルートで一度コマンドを実行するだけで、実際の作業方法に基づいた完全なランプアップドキュメントが書き出される:

claude -p "/team-onboarding"

Claude はローカルの過去30日間の使用履歴を読み、.claude/ フォルダをスキャンし、CLAUDE.md を検査し、プロジェクト構造をたどり、新しいチームメンバーに渡せるマークダウンファイルを出力する。手動の README なし。「暗黙の知識」スプレッドシートなし。四半期ごとのオンボーディング監査なし。

/team-onboarding の実際の内容

2つの全く異なるデータソースからランプアップガイドを生成するビルトインスラッシュコマンドだ。構造データ: .claude/commands/、.claude/skills/、.claude/agents/、CLAUDE.md、設定された MCP サーバー、兄弟リポジトリ。行動データ: 過去30日間に各コマンドを何回実行したか、それらのコマンドがマップする作業タイプ、触れた MCP サーバー。

2つのソースが組み合わさって、シャドウイングしている新入社員のためにシニアエンジニアが初日ガイドを書くような読み口のマークダウンドキュメントになる。

リアルタイムのオンボーディングインターフェースではない。チャットでもない。一度実行し、ファイルを書き出し、終了する。得られるファイルは、ツールがリポジトリ内でどのように使われてきたかのスナップショットだ。

何を読み取るか

6つの入力がガイドを供給する。すべての入力はローカルだ。Claude への呼び出し以外は何もマシンを離れない。

使用履歴がこの機能を興味深くする理由だ。どんなツールもファイルをリストアップできる。シニアデベロッパーが月に7回 /claude-scout を実行し、MCP に一度も触れたことがないということを新入社員に伝えられるツールはほとんどない。その第2のレイヤーが、ファイルリストをランプアップドキュメントに変える。

出力の形

1ヶ月間アクティブに使用されたコンテンツファクトリーリポジトリからの、編集していないサンプルだ:

# Welcome to Build This Now

## How We Use Claude

Based on speedy_devv's usage over the last 30 days:

Work Type Breakdown:
  Write Docs        █████████░░░░░░░░░░░  44%
  Build Feature     ███████░░░░░░░░░░░░░  33%
  Plan Design       ████░░░░░░░░░░░░░░░░  22%

Top Skills & Commands:
  /claude-scout     ████████████████████  7x/month
  /carousel         ██████░░░░░░░░░░░░░░  2x/month
  /compact          ██████░░░░░░░░░░░░░░  2x/month
  /claude-research  ███░░░░░░░░░░░░░░░░░  1x/month
  /resume           ███░░░░░░░░░░░░░░░░░  1x/month

Top MCP Servers:
  _None configured yet_

## Your Setup Checklist

### Codebases
- [ ] btn-content-factory (this repo, content generation pipeline)
- [ ] claude-code-seo-machine, sibling repo (blog paraphrase + SEO)
- [ ] build-kit-template, the framework itself

### MCP Servers to Activate
- [ ] _None in use yet_

### Skills to Know About
- /claude-scout: hourly scout for Anthropic/Claude Code news. Most-used
  command on the team.
- /carousel: builds an Instagram carousel via the carousel-designer +
  carousel-evaluator GAN loop.
- /blog-post: turns a carousel into a /blog/guide/ MDX page + hero image.

## Team Tips
_TODO_

## Get Started
_TODO_

5つのセクションが返ってくる。ヘッダーは CLAUDE.md からチーム名を取得する。「How We Use Claude」は行動レイヤーだ。「Your Setup Checklist」は構造的だ。「Team Tips」と「Get Started」は、最初の実行後に記入するよう求めるインタラクティブなプレースホルダーだ。

棒グラフは飾りではない。シェルセーフな ASCII なので、どこにでも貼り付けられ、チームの作業リズムが一目で分かる。スキミングする新しいチームメンバーは、このチームがビルドより文書化を多く行い、/claude-scout を常用し、MCP を組み込んでいないことを10秒で知ることができる。それはほとんどのオンボーディングデッキよりも優れたコンテキストだ。

実行方法

2つの呼び出し方がある。どちらも同じ出力に着地する。

ヘッドレスで実行し、ファイルにパイプする:

claude -p "/team-onboarding" > ONBOARDING.md

またはインタラクティブセッション内で実行する:

/team-onboarding

インタラクティブ版は最初の下書きの後に3つのフォローアップ質問をする。チームの名前。新入社員への良い最初のタスクがあるかどうか。CLAUDE.md にまだ書かれていないが書き留めておきたいチームのヒント。答えれば _TODO_ セクションが埋まる。スキップすればファイルはプレースホルダーのまま出荷される。

ヘッドレス版は聞かない。そのまま下書きを書き出し、_TODO_ セクションもそのままだ。

1日目と1週目

ほとんどの人が見逃す部分だ。このコマンドは構造データと行動データをブレンドする。構造データは1日目から存在する。行動データは存在しない。

使用履歴がゼロのリポジトリのフレッシュクローンは半分しか埋まらないドキュメントを出す。セットアップチェックリスト、スキルインベントリ、MCP リストは得られる。作業タイプの内訳、頻度バー、どのコマンドが最もよく使われているかを新入社員に伝えるシグナルは得られない。

早すぎると出力は乾いたファイルリストのように読める。1週間の実際の作業後に実行すると、シニアエンジニアが書いてくれたように読める。

正しいやり方は「新しいチームメンバーが1日目に実行する」ではない。正しいやり方は「経験豊富なエンジニアが自分の環境で実行し、出力を編集し、キュレーションされたファイルを新しい採用者に渡す」だ。

ハーネスと一緒に出荷する

フレームワーク、テンプレート、または他の人が使う社内ツールキットを管理している場合、このコマンドは配布機能になる。

メインの開発環境で /team-onboarding を実行する。使用履歴は今や豊富だ。完全な行動レイヤーが得られる。共有したくない個人パスを編集する。docs/how-we-use-claude-code.md としてリポジトリにコミットする。次のリリースと共に出荷する。

ユーザーは今や、ボイラープレートやスターターキットがかつて与えたことのないものを手に入れる。フレームワークを構築した人々が実際にどのように使っているかのスナップショットだ。マーケティング版ではない。機能リストでもない。実際の使用パターンだ。

リリースごとに更新する。追加した新しいコマンドは、それらを実行してきたので自動的に表示される。組み込んだ新しいスキルは、構造スキャンがそれらをキャッチするので表示される。使用をやめた古いコマンドはトップリストから消える。ドキュメントはツールと共に進化し、1文も手で書かずに済む。

同じパターンが会社内でも機能する。スタッフエンジニアの環境で実行する。出力をチームの正規「Claude Code の使い方」ファイルとしてコミットする。四半期に1回レビューする。乖離したら更新する。

設定と制御

知っておく価値のある3つのノブがある。

出力先。 ヘッドレス実行はどこにでもパイプできる。リポジトリファイル、チームウィキ、共有ドキュメントに。出力は ASCII セーフなバーを持つプレーンマークダウンだ。

振り返り期間。 デフォルトは30日だ。数ヶ月そのリポジトリにいるシニアエンジニアにはこれが正しいウィンドウだ。短いプロジェクトには、30日が今まで行ったことすべてをカバーする場合もある。

インタラクティブフォローアップ。 インタラクティブ版は質問をする。ヘッドレス版はスキップする。フロー全体をスクリプト化したい場合はヘッドレスを使い、_TODO_ セクションは手動で埋める。チームのヒントの下書きに Claude に手伝ってもらいたい場合はインタラクティブを使う。

ファイルの下部にも隠れたシグナルがある。onboarding buddy mode と読める HTML コメントだ。これはフォローアップフックだ。チームメンバーが次に同じリポジトリで Claude Code セッションを開くと、Claude はそのファイルのオンボーディングバディとして自分を扱う。新しい採用者にマークダウンドキュメントと Claude Code 自体を渡す。Claude はドキュメントを1セクションずつ案内し、途中で質問に答える。

ベストプラクティス

最も使用履歴が豊富な環境で実行する。 行動レイヤーはコマンドに読み取れる実際のデータがある場合にのみ効果を発揮する。フレッシュクローンで実行しない。実際の作業が行われるノートパソコンで実行する。

出荷前に編集する。 最初の下書きには個人パス、兄弟リポジトリの参照、時にはチームメンバーの GitHub ハンドルが組み込まれている。ファイルをコミットする前にこれらを削除する。出力を最終ドキュメントではなく、最初の下書きとして扱う。

リリースごとに再生成する。 just onboarding または npm スクリプトをセットアップする。1行、1コマンド。新しいバージョンをリリースするときに再実行する。ドキュメントは手を触れなくても最新の状態に保たれる。

CLAUDE.md とペアにする。 CLAUDE.md は AI のルールだ。オンボーディングドキュメントは人間のルールだ。それらは補完し合う。一方は Claude にどう振る舞うかを伝える。もう一方は新しい採用者にチームがどのように機能するかを伝える。

出力を自分で読む。 最初に実行したとき、Claude が自分の作業について気づいたことを5分かけて読む。何かを学ぶはずだ。ほとんどのエンジニアは棒グラフを見るまで自分のトップ3コマンドを知らない。

次のステップ

• チームの Claude に対するルールを確立するために CLAUDE.md をセットアップする
• Claude が自分のために書くプロジェクトごとの知識のためのオートメモリを探索する
• モジュール式プロジェクト指示のための .claude/rules/ ディレクトリについて学ぶ
• オンボーディングドキュメントがインベントリ化しているものを理解するためのカスタムスキルを読む
• ワークフローが複数の並行サブエージェントにまたがる場合はエージェントチームを見る

チームオンボーディングは、構築したものと実際にチームが使えるものの間のループを閉じる。ハーネスは個人のコックピットから共有のワークベンチになる。一度実行し、ファイルを新しい採用者に渡し、出荷に戻ろう。