メインコンテンツへスキップ
BayashiLab LogoBayashiLab(バヤシラボ)
ブログ一覧

Claude Code /team-onboarding 実践ガイド — Skills・Subagents・Hooksが肥大化したリポジトリで暗黙知の継承システムを構築する

Claude Codeteam-onboardingSkillsSubagentsHooks

CLAUDE.md は3000行、Skills は40個、Subagent は8体、Hooks は12種類。新メンバーや別エージェントに引き継ぐたびに「このリポジトリの作法」を口頭で説明していませんか？v2.1.101（2026年4月11日）で追加された /team-onboarding は、単なるドキュメント生成ツールではなく、リポジトリ固有の暗黙知を「継承可能な形」に再パッケージするためのコマンドです。本記事では、自律開発デーモン slave のリポジトリ（Skills 50+、Subagent 4種、Hook 多数）での実例を踏まえ、生成品質を最大化する設計と CI 連携・自己ブートストラップ手法までを解説します。

/team-onboarding が内部で何をスキャンしているのか

過去30日のセッション履歴を要約する仕組み

/team-onboarding は、リポジトリのコードを直接読むのではなく、~/.claude/projects/<project-hash>/ 配下の *.jsonl セッション履歴と ~/.claude/history.jsonl を起点にスキャンします。具体的には以下を集計しています。

  • 過去30日間に呼び出された Skill とその頻度
  • Subagent 起動回数とタスクパターン
  • MCP サーバーへの呼び出し履歴
  • 頻出スラッシュコマンドの実行統計

つまり「実際にどう使われているか」をベースにした事後的なドキュメント生成です。

履歴がないリポジトリで実行できない理由

ここで多くの人がハマるのが、履歴ゼロのリポジトリでは生成自体が失敗するという仕様です。Valibot 検証時のレポートでも、まっさらな clone 直後に実行すると「No usage history found in the last 30 days」と返って終わります。

bash
$ claude -p '/team-onboarding'
Error: insufficient session history.
Please use this repository with Claude Code for at least a few sessions
before running /team-onboarding.

settings.json の cleanupPeriodDays を短く設定しているチームも要注意で、30日より短いと履歴がスキャン前に削除されている可能性があります。

生成される ONBOARDING.md の3セクション構造

生成物は必ず以下の3セクション構造になります。

How We Use Claude（タスク分類と頻出ツール）

実セッションから抽出された頻出 Skill / Subagent / MCP がパーセンテージで並びます。slave リポジトリで実行した場合の例。

markdown
## How We Use Claude

Top Skills:
- gemini-code-review (23%)
- tasklist-executor (18%)
- spec-interviewer (12%)
- doc-generator (9%)
- review (7%)

Active Subagents: Explore, general-purpose, Plan
MCP Servers: gsc, analytics-mcp, claude_ai_Canva

Setup Checklist（再現可能な環境構築）

MCP サーバー登録 → Skill 検証 → CLAUDE.md レビューの順で並びます。新メンバーがそのままチェックボックスとして使える形式です。

Team Tips（暗黙のルール）

ここが一番の注意点で、Team Tips は canonical source ではない という前提で読む必要があります。durable な規約は CLAUDE.md・settings.json・Skills のいずれかに昇格させないと、次の再生成でガラッと変わる可能性があります。これは地味に重要なので、生成直後に必ずレビューフローに乗せておくのがおすすめです。

Skills・Subagents・Hooks の description 設計が生成品質を決める

/team-onboarding は、各 Skill / Subagent / Hook の description フィールドを直接要約材料として利用 します。description が貧弱だと、ONBOARDING.md には「目的不明の Skill 群」がただ羅列されるだけになります。

description テンプレート3パターン

Skill の場合（before/after）:

yaml
---
name: gemini-code-review
description: Gemini AI でコードレビュー
---

これを /team-onboarding に通すと「Gemini を使う何か」程度しか出ません。

yaml
---
name: gemini-code-review
description: |
  Gemini AIを使用してコードレビューを実施。
  実装後の品質チェック、バグ検出、セキュリティ監査が必要な時に使用。
  「Geminiでレビュー」「/gemini-code-review」で起動。
  Claudeレビューと併用することで観点の偏りを軽減できる。
---

こう書き直すと、ONBOARDING.md の Team Tips に「実装後は gemini-code-review で二重チェックする運用」と書き起こされます。

Subagent の場合、frontmatter description には以下の3点を必ず入れます。

  1. 何をするか
  2. いつ呼ぶか（トリガー条件）
  3. 呼ばない条件（誤起動防止）

Hook の場合、events と matchers の意図は YAML コメントではなく description フィールドに埋めます。コメントはスキャン対象外です。

CI で定期再生成して陳腐化を防ぐ運用パターン

ONBOARDING.md は git 管理し、週次で再生成して PR 化するのが現実的な落とし所です。slave の scheduler.ts に組み込む例を示します。

typescript
// src/pipelines/onboarding-refresh.ts
import { runClaude } from "../claude-runner.js";
import { execSync } from "node:child_process";

export async function refreshOnboarding(repoPath: string) {
  await runClaude({
    cwd: repoPath,
    prompt: "/team-onboarding",
  });

  execSync("git checkout -b chore/refresh-onboarding", { cwd: repoPath });
  execSync("git add ONBOARDING.md", { cwd: repoPath });
  execSync('git commit -m "chore: refresh ONBOARDING.md"', { cwd: repoPath });
  execSync("git push -u origin HEAD", { cwd: repoPath });
  execSync("gh pr create --fill", { cwd: repoPath });
}
typescript
// src/scheduler.ts に追加
cron.schedule("0 9 * * 1", () => {
  enqueue({ type: "custom", payload: { pipeline: "onboarding-refresh" }, priority: 5 });
});

差分が出たら自動で PR 化されるので、レビュー時に「新しい Skill が定着した」「使われなくなった Subagent がある」をそのまま暗黙知の変化として可視化できます。履歴30日制約に合わせて、再生成サイクルは7〜14日が現実的です。

/powerup・Routines・Agent Teams との連携設計

April 2026 のリリース群は組み合わせて使うと効果が跳ね上がります。

  • /powerup: /team-onboarding 生成直後に実行すると、ONBOARDING.md に列挙された頻出 Skill が即時アクティブ化されます
  • Routines: 「毎回 ONBOARDING.md を最初に読む」ステップを定義し、全 Subagent に継承させる
yaml
# .claude/routines/bootstrap.yaml
name: bootstrap
description: 全ての Subagent 起動前に必ず実行する初期化手順
steps:
  - read: ONBOARDING.md
  - read: CLAUDE.md
  - confirm: "リポジトリ固有の作法を理解しました"
  • Agent Teams: 複数エージェント間で onboarding を統一する場合、ONBOARDING.md を team-level の共有コンテキストとして登録することで、メンバー間の認識ズレを防げます

AIエージェント自身を「新人」として扱う自己ブートストラップ手法

ここが本記事の核です。/team-onboarding は人間の新人だけでなく、AI エージェント自身に読ませることで真価を発揮します。

slave の claude-runner.ts で、Claude CLI 呼び出し前に ONBOARDING.md を prepend する実装例。

typescript
// src/claude-runner.ts
import { readFile } from "node:fs/promises";
import { spawn } from "node:child_process";

export async function runClaudeWithOnboarding(
  prompt: string,
  cwd: string,
) {
  let onboarding = "";
  try {
    onboarding = await readFile(`${cwd}/ONBOARDING.md`, "utf-8");
  } catch {
    // ONBOARDING.md がなければスキップ
  }

  const fullPrompt = onboarding
    ? `# Repository Onboarding\n\n${onboarding}\n\n---\n\n${prompt}`
    : prompt;

  const child = spawn("claude", ["-p", "--dangerously-skip-permissions"], {
    cwd,
    env: getCleanEnv(),
  });
  child.stdin.write(fullPrompt);
  child.stdin.end();
  // ... 以下は既存の実装
}

これにより autonomous-dev パイプラインで生成される新規プロジェクトでも、最初の Claude 呼び出しからリポジトリ固有作法を把握した状態でスタートできます。「人間の新人」と「AIの新人」を同じドキュメントで扱うことで、二重メンテの罠を避けられるのが大きな利点です。個人的にはこの自己ブートストラップが一番好きで、ONBOARDING.md を書き直すモチベーションが上がります。

ハマりやすいポイントとトラブルシュート

最後に運用で遭遇しがちな落とし穴を3つ。

1. 履歴ゼロエラー: cleanupPeriodDays を30未満にしているチームは事前確認必須。settings.json を見直すか、再生成前に十分なセッションを積みましょう。

2. 巨大リポジトリでのスキャンタイムアウト: Skills が50を超えるリポジトリでは上位N件のみ列挙され漏れが発生します。重要な Skill には description で「重要度: high」のような明示タグを入れると拾われやすくなります。

3. machine-local な内容が混入する問題: MCP の auth token や個人のローカルパスがそのまま doc に出るケースがあります。共有前に必ずレビュー、できれば pre-commit hook で OAUTH_TOKEN 等の文字列をブロックしておくと安全です。

/team-onboarding は「新人向けドキュメント生成ツール」ではなく「リポジトリ固有の暗黙知を継承可能な形に再パッケージするコマンド」として捉え直すと真価が見えてきます。Skills・Subagents・Hooks の description 品質が生成 doc の品質に直結する以上、onboarding doc の改善は結局のところリポジトリ全体のメタデータ整備に繋がります。CI で週次再生成し、人間と AI エージェントの両方を「新人」として同じドキュメントで迎え入れる仕組みを作れば、組織でもソロでも引き継ぎコストは劇的に下がります。

もっと読む他の技術記事も読む