project-onboarding

プロジェクトオンボーディングスペシャリスト - プロジェクトをすばやく理解するために、コードベースの探索とナレッジの記録を支援します。 - プロジェクト構造と構成パターンの把握 - ビルドシステムとパッケージマネージャーの特定 - テストコマンドとカバレッジ設定の確認 - 主要なディレクトリとエントリーポイントのマッピング - 今後のセッションで使う永続的なメモリの作成 - プロジェクト概要ドキュメントの生成 - 開発ワークフローと規約の特定

使用するタイミング

次の場合にこのスキルを呼び出します。

• 未知のコードベースで作業を開始するとき
• コンテキストを失った後（新しいセッション）
• check_onboarding_performed がメモリなしを示しているとき
• ユーザーが「このプロジェクトについて学びたい」または「このコードベースを理解したい」と依頼したとき

オンボーディングのワークフロー

ステップ 1：既存の知識を確認する

まず、オンボーディングがすでに実施されているか確認します。

List files in: .claude/context/memory/
Look for: project-structure.md, build-commands.md, test-commands.md

メモリが存在する場合は、それらを読み込み、ステップ 6（検証）に進みます。

ステップ 2：プロジェクトの調査

まず、プロジェクトを分類します。

Greenfield と Brownfield の判定

指標	該当するか？	分類
履歴のある .git ディレクトリ	はい	Brownfield
パッケージマニフェスト（package.json、requirements.txt など）	はい	Brownfield
コードを含むソースディレクトリ（src/、app/、lib/）	はい	Brownfield
Git の変更状態がクリーンでない（未コミットの変更がある）	はい	Brownfield（ユーザーに警告）
空、または README.md のみ	上記のいずれにも該当しない	Greenfield

Brownfield プロジェクトの場合：

1. 除外ファイルを尊重する：スキャンする前に .gitignore と .claudeignore を確認します
2. 効率的にファイルを選別する：
   • git ls-files を使って追跡対象のファイルを一覧表示します（.gitignore を尊重します）
   • 大きなファイル（>1MB）は、先頭と末尾のみを読み込みます（最初と最後の 20 行）
   • バイナリファイル、node_modules、ビルド生成物はスキップします
3. 技術スタックを推定する：質問する前にマニフェストを分析します
4. コンテキストに応じた質問をする：見つかったパターンに基づいて質問します

# Efficient file listing (respects .gitignore)
git ls-files --exclude-standard -co | head -100

# For non-git projects with manual ignores
find . -type f \
  -not -path '*/node_modules/*' \
  -not -path '*/.git/*' \
  -not -path '*/dist/*' \
  -not -path '*/build/*' \
  | head -100

Greenfield プロジェクトの場合：

• 新しいコンテキスト用の成果物を作成します
• セットアップには interactive-requirements-gathering スキルを使用します

プロジェクトのルートを分析し、次の項目を特定します。

1. パッケージマネージャーと言語：

   • package.json - Node.js／JavaScript／TypeScript
   • pyproject.toml、requirements.txt - Python
   • Cargo.toml - Rust
   • go.mod - Go
   • pom.xml、build.gradle - Java
   • composer.json - PHP

2. プロジェクトの種類：

   • フロントエンド、バックエンド、フルスタック、ライブラリ、CLI、モバイル、モノレポ

3. フレームワークの検出：

   • 依存関係を解析して、フレームワーク（React、Next.js、FastAPI など）を検出します

ステップ 3：ビルドシステムの分析

プロジェクトのビルド方法と実行方法を特定します。

1. package.json のスクリプトを確認する（Node.js）：

   {
     "scripts": {
       "dev": "...",
       "build": "...",
       "start": "...",
       "test": "..."
     }
   }
   

2. Makefile を確認する（Python、Go、Rust）：

   build:
   test:
   lint:
   

3. pyproject.toml を確認する（Python）：

   [tool.poetry.scripts]
   [tool.poe.tasks]
   

4. 見つかったコマンドを記録する：

   • 開発：npm run dev、uv run dev
   • ビルド：npm run build、cargo build
   • テスト：npm test、pytest
   • Lint：npm run lint、ruff check

ステップ 4：ディレクトリ構造のマッピング

主要なディレクトリをマッピングします。

ディレクトリ	用途
src/	ソースコード
lib/	ライブラリコード
test/、tests/、__tests__/	テストファイル
docs/	ドキュメント
scripts/	ユーティリティスクリプト
config/	設定ファイル

次の項目を特定します。

• エントリーポイント（index.ts、main.py、app.py）
• コンポーネントディレクトリ
• API ルート
• データベースモデル

ステップ 5：オンボーディングメモリを作成する

発見した情報を永続メモリに保存します。

メモリ：project-structure.md

# Project Structure

## Overview

- Project Type: [fullstack/backend/frontend/library]
- Primary Language: [TypeScript/Python/Go/Rust]
- Framework: [Next.js/FastAPI/Express/etc.]

## Key Directories

- Source: `src/`
- Tests: `test/`
- Config: `.claude/`

## Entry Points

- Main: `src/index.ts`
- API: `src/api/`

## Important Files

- Configuration: `package.json`, `tsconfig.json`
- Environment: `.env.example`

メモリ：build-commands.md

# Build Commands

## Development

- Start dev server: `npm run dev`
- Watch mode: `npm run watch`

## Build

- Production build: `npm run build`
- Type check: `npm run typecheck`

## Clean

- Clean build: `npm run clean`

メモリ：test-commands.md

# Test Commands

## Unit Tests

- Run all: `npm test`
- Watch mode: `npm test -- --watch`
- Coverage: `npm test -- --coverage`

## E2E Tests

- Run: `npm run test:e2e`

## Linting

- Lint: `npm run lint`
- Fix: `npm run lint:fix`

ステップ 6：検証

発見した情報を検証します。

1. テストコマンド（安全な場合）：

   • npm --version または同等のコマンドを実行して、パッケージマネージャーを確認します
   • npm run --silent を実行して、利用可能なスクリプトを一覧表示します
   • ユーザーの許可なくビルドやテストを実行しないでください

2. パスの確認：

   • 主要なディレクトリが存在することを確認します
   • エントリーポイントが正しいことを確認します

ステップ 7：概要を報告する

簡潔な概要を出力します。

## Onboarding Complete

**Project**: [name]
**Type**: [fullstack/backend/etc.]
**Framework**: [Next.js/FastAPI/etc.]

**Quick Commands**:
- Dev: `npm run dev`
- Test: `npm test`
- Build: `npm run build`

**Key Locations**:
- Source: `src/`
- Tests: `test/`
- API: `src/api/`

**Memories Created**:
- .claude/context/memory/project-structure.md
- .claude/context/memory/build-commands.md
- .claude/context/memory/test-commands.md

**ユーザーのリクエスト**：「このコードベースについて理解したいです」

エージェントの操作：

1. .claude/context/memory/ に既存のメモリがあるか確認する
2. メモリがない場合、プロジェクトの調査を実行する
3. package.json とディレクトリ構造を分析する
4. メモリファイルを作成する
5. 概要を報告する

出力：

## Onboarding Complete

**Project**: agent-studio
**Type**: Multi-agent orchestration framework
**Framework**: Claude Code + Custom agents

**Quick Commands**:
- Validate: `node .claude/tools/cli/validate-agents.mjs`
- Test hooks: `node .claude/hooks/routing/router-enforcer.cjs` (uses `.claude/lib/routing/routing-table.cjs`)

**Key Locations**:
- Agents: `.claude/agents/`
- Skills: `.claude/skills/`
- Memory: `.claude/context/memory/`

**Memories Created**: 3 files

</usage_example>

**関連スキル**： - `project-analyzer` - 詳細な自動分析（オンボーディングを補完します） - `repo-rag` - パターンのセマンティック検索 - `session-handoff` - 新しいセッションに向けてコンテキストを準備する

絶対に守るべきルール

1. 必ず調査を実行する前に既存のオンボーディングメモリを確認してください。オンボーディングを重複して行うと、将来のエージェントを誤らせる矛盾した知識エントリが作成されます。
2. 標準的な規約を確認せずに想定してはなりません。このプロジェクト環境で実際に動作するものをコマンドで確認してください。
3. 発見したコマンドとパスは、必ず永続メモリファイルに記録してください。セッションのコンテキストはリセットされますが、名前付きメモリファイルは永久に残ります。
4. 発見したコマンドを文書化する前に、安全なテスト手順で必ず検証してください。オンボーディングメモリに誤ったコマンドが記載されていると、それを読むすべてのエージェントを誤らせます。
5. プロジェクトが進化した際にメモリを見直さず、オンボーディングを完了してはなりません。古くなったオンボーディング資料は、オンボーディングがない状態よりも危険です。

アンチパターン

アンチパターン	失敗する理由	正しいアプローチ
確認せずに標準的な規約を想定する	プロジェクトごとにビルド／テスト／リントのコマンドは異なります。誤った想定は、気づかれないまま失敗を引き起こします	package.json、Makefile、または pyproject.toml を読み、--version を実行して確認します
発見したコマンドの検証を省略する	文書化されていても誤ったコマンドは、今後のすべてのエージェントセッションを誤らせます	各コマンドを安全な no-op または --help フラグ付きで実行し、動作することを確認します
オンボーディング情報をセッションのコンテキストだけに保存する	新しい会話のたびにコンテキストがリセットされ、発見した情報が永久に失われます	すべての調査結果を .claude/context/memory/named/ 内の名前付きメモリファイルに記録します
オンボーディングを一度限りの作業として扱う	プロジェクトは進化します。古いコマンドは気づかれないまま失敗し、エージェントの時間を浪費します	プロジェクト構造に大きな変更があったら、オンボーディングメモリを更新します
重要なコマンドの優先順位を付けずに情報を詰め込みすぎる	重要度の低い情報が記載された長いファイルでは、肝心のビルド／テストコマンドが埋もれます	メモリはクイックスタートコマンドを先頭に置き、その下に詳細を記載する構成にします

メモリの規約（必須）

開始前： .claude/context/memory/learnings.md を読みます

完了後：

• 新しいパターンを発見した場合 → .claude/context/memory/learnings.md
• 問題が発生した場合 → .claude/context/memory/issues.md
• 決定を行った場合 → .claude/context/memory/decisions.md

中断を想定してください。メモリに記録されていなければ、何も起きていないのと同じです。