project-onboarding

リソース

scripts/
  validate-onboarding.sh
references/
  onboarding-patterns.md

プロジェクトのオンボーディング品質スキル

このスキルでは、GoodVibes の高精度ツールを使って、新しいプロジェクトに体系的にオンボーディングする方法を説明します。徹底したオンボーディングプロセスでは、アーキテクチャを把握し、パターンを特定し、環境を検証して、すぐに生産的な貢献を始められるようドキュメントを作成します。

このスキルを使用するタイミング

次の場合にこのスキルを読み込みます：

• 新しいプロジェクトやチームに参加するとき
• 未知のコードベースを理解するとき
• プロジェクトのアーキテクチャを文書化するとき
• 開発環境をセットアップするとき
• オンボーディングガイドを作成するとき
• プロジェクトの健全性と技術的負債を監査するとき

トリガーフレーズ：「このプロジェクトにオンボーディングする」、「このコードベースを理解する」、「開発環境をセットアップする」、「アーキテクチャを把握する」、「プロジェクトのドキュメントを生成する」。

中核となるワークフロー

フェーズ 1：プロジェクト構造の分析

ディレクトリ構成、モノレポの設定、エントリーポイントを把握します。

ステップ 1.1：ディレクトリ構成の確認

discover を使ってプロジェクトのディレクトリ構成を把握し、主要な設定ファイルを特定します。

discover:
  queries:
    - id: config_files
      type: glob
      patterns: 
        - "package.json"
        - "tsconfig*.json"
        - "*.config.{js,ts,mjs,cjs}"
        - ".env*"
        - "docker-compose*.yml"
        - "Dockerfile*"
    - id: src_structure
      type: glob
      patterns:
        - "src/**/*"
        - "app/**/*"
        - "pages/**/*"
        - "lib/**/*"
    - id: monorepo_indicators
      type: glob
      patterns:
        - "pnpm-workspace.yaml"
        - "lerna.json"
        - "nx.json"
        - "turbo.json"
        - "packages/*/package.json"
        - "apps/*/package.json"
  verbosity: files_only

ここからわかること：

• プロジェクトの種類（モノレポか単一パッケージか）
• フレームワーク／ビルドツール（Next.js、Vite、Create React App など）
• 設定の複雑さ
• コンテナ化された開発用の Docker 設定

ステップ 1.2：エントリーポイントの特定

アプリケーションの主要なエントリーポイント、サーバーファイル、パブリック API を見つけます。

discover:
  queries:
    - id: entry_points
      type: glob
      patterns:
        - "src/index.{ts,tsx,js,jsx}"
        - "src/main.{ts,tsx,js,jsx}"
        - "src/app.{ts,tsx,js,jsx}"
        - "app/layout.{ts,tsx,js,jsx}"
        - "pages/_app.{ts,tsx,js,jsx}"
        - "server.{ts,js}"
    - id: api_routes
      type: glob
      patterns:
        - "src/api/**/*"
        - "app/api/**/*"
        - "pages/api/**/*"
        - "routes/**/*"
    - id: public_assets
      type: glob
      patterns:
        - "public/**/*"
        - "static/**/*"
  verbosity: files_only

ここからわかること：

• アプリケーションのアーキテクチャ（SPA、SSR、API 専用、フルスタック）
• ルーティングのパターン
• 静的アセットの構成

ステップ 1.3：主要な設定の確認

precision_read を使って package.json と主要な設定ファイルを調べます。

precision_read:
  files:
    - path: "package.json"
      extract: content
    - path: "tsconfig.json"
      extract: content
  verbosity: standard

ここからわかること：

• 依存関係と開発用依存関係
• ビルド、開発、テスト、リント用のスクリプト
• Node のバージョン要件（engines フィールド）
• パッケージマネージャー（npm、yarn、pnpm）

フェーズ 2：依存関係の監査

依存関係のバージョンの新しさ、セキュリティ脆弱性、バンドルサイズを分析します。

ステップ 2.1：すべての依存関係を一覧表示

package.json ファイルから依存関係を抽出します。

precision_grep:
  queries:
    - id: dependencies
      pattern: '"dependencies":\s*\{[\s\S]*?\}'
      glob: "**/package.json"
      multiline: true
    - id: dev_dependencies
      pattern: '"devDependencies":\s*\{[\s\S]*?\}'
      glob: "**/package.json"
      multiline: true
    - id: peer_dependencies
      pattern: '"peerDependencies":\s*\{[\s\S]*?\}'
      glob: "**/package.json"
      multiline: true
  output:
    format: matches
  verbosity: standard

ステップ 2.2：古くなった依存関係の確認

npm／yarn／pnpm のコマンドを実行して、更新を確認します。

precision_exec:
  commands:
    - cmd: "npm outdated --json"
    - cmd: "npm audit --json"
  verbosity: standard

ここからわかること：

• 更新可能なパッケージ
• セキュリティ脆弱性
• 重大度（重大、高、中、低）

ステップ 2.3：バンドルサイズとツリーの分析

サイズの大きな依存関係と、最適化できる可能性のある箇所を特定します。

precision_exec:
  commands:
    - cmd: "npx bundle-phobia-cli --json react react-dom next"
  verbosity: minimal

ここからわかること：

• ダウンロードサイズとインストールサイズ
• 本番環境での gzip 圧縮後のサイズ
• 注意すべき容量の大きい依存関係

フェーズ 3：アーキテクチャの把握

モジュールの境界、データフロー、API の範囲を把握します。

ステップ 3.1：モジュール構造の抽出

アウトライン抽出を指定して precision_read を使い、コードベースの構造を把握します。

# Note: path "src" works as a directory - precision_read will recursively extract outline
precision_read:
  files:
    - path: "src"
      extract: outline
  output:
    max_per_item: 100
  verbosity: standard

ここからわかること：

• ディレクトリ構成のパターン
• モジュールの境界
• モジュールごとのコード量

ステップ 3.2：主要なシンボルの特定

シンボル抽出を指定して precision_read を使い、エクスポートされている関数、クラス、型を見つけます。

# First discover the files
discover:
  queries:
    - id: lib_files
      type: glob
      patterns: ["src/lib/**/*.{ts,tsx}"]
    - id: api_files
      type: glob
      patterns: ["src/api/**/*.{ts,tsx}"]
  verbosity: files_only

# Then read symbols from discovered files
precision_read:
  files:
    # Use file paths from discover results
    - path: "src/lib/index.ts"  # Example - use actual discovered paths
      extract: symbols
    - path: "src/api/index.ts"  # Example - use actual discovered paths
      extract: symbols
  symbol_filter: ["function", "class", "interface", "type"]
  verbosity: minimal

ここからわかること：

• パブリック API の範囲
• 中核となる抽象化とユーティリティ
• 型定義

ステップ 3.3：データフローの把握

インポートとエクスポートを追跡し、モジュール間の依存関係を理解します。

discover:
  queries:
    - id: imports
      type: grep
      pattern: '^import .* from ["''].*["''];?$'
      glob: "src/**/*.{ts,tsx,js,jsx}"
    - id: exports
      type: grep
      pattern: '^export (default|const|function|class|interface|type|enum)'
      glob: "src/**/*.{ts,tsx,js,jsx}"
  verbosity: count_only

ここからわかること：

• モジュール間の結合度
• インポートのパターン（バレルファイル、直接インポート）
• 循環依存の可能性

フェーズ 4：規約の検出

コードスタイル、命名パターン、ファイル構成のルールを特定します。

ステップ 4.1：命名規約の検出

ファイルやシンボルの命名パターンを検索します。

discover:
  queries:
    - id: component_naming
      type: grep
      pattern: 'export (default )?(function|const) [A-Z][a-zA-Z]*'
      glob: "src/components/**/*.{ts,tsx}"
    - id: hook_naming
      type: grep
      pattern: 'export (default )?(function|const) use[A-Z][a-zA-Z]*'
      glob: "src/**/*.{ts,tsx}"
    - id: util_naming
      type: grep
      pattern: 'export (default )?(function|const) [a-z][a-zA-Z]*'
      glob: "src/lib/**/*.{ts,tsx}"
  verbosity: count_only

ここからわかること：

• コンポーネントには PascalCase を使用
• ユーティリティには camelCase を使用
• フックには use 接頭辞を使用
• ファイルの命名パターン

ステップ 4.2：ファイル構成パターンの検出

ディレクトリ構造を分析し、構成に関する規約を特定します。

discover:
  queries:
    - id: index_files
      type: glob
      patterns: ["**/index.{ts,tsx,js,jsx}"]
    - id: type_files
      type: glob
      patterns: ["**/*.types.{ts,tsx}", "**/types.{ts,tsx}", "**/types/**/*"]
    - id: test_colocation
      type: glob
      patterns: 
        - "**/*.test.{ts,tsx}"
        - "**/__tests__/**/*"
  verbosity: count_only

ここからわかること：

• バレルエクスポート（index.ts パターン）
• 型定義の構成
• テストファイルの配置（同じ場所に置くか、専用フォルダーに置くか）

ステップ 4.3：リンティングとフォーマットの設定を確認する

ESLint、Prettier、その他のコード品質設定を確認します。

discover:
  queries:
    - id: lint_config
      type: glob
      patterns:
        - ".eslintrc*"
        - "eslint.config.{js,mjs,cjs}"
        - ".prettierrc*"
        - "prettier.config.{js,mjs,cjs}"
    - id: editor_config
      type: glob
      patterns:
        - ".editorconfig"
        - ".vscode/settings.json"
  verbosity: files_only

設定ファイルを読み取ります：

precision_read:
  files:
    - path: ".eslintrc.json"
      extract: content
    - path: ".prettierrc"
      extract: content
  verbosity: standard

ここから分かること：

• コードスタイルのルール（インデント、引用符、セミコロン）
• 有効または無効になっているリンティングルール
• フォーマットの設定

フェーズ 5：環境のセットアップ

必要な依存関係、設定ファイル、データベースを用意して、開発環境をセットアップします。

ステップ 5.1：Node のバージョン要件を確認する

.nvmrc、package.json engines、または .node-version を読み取ります。

precision_grep:
  queries:
    - id: node_version_nvmrc
      pattern: '.*'
      glob: ".nvmrc"
    - id: node_version_package
      pattern: '"engines":\s*\{[\s\S]*?"node":\s*"[^"]+"'
      glob: "package.json"
      multiline: true
  output:
    format: matches
  verbosity: standard

ここから分かること：

• 必要な Node.js のバージョン
• パッケージマネージャーのバージョン要件

ステップ 5.2：依存関係をインストールする

パッケージマネージャーのインストールコマンドを実行します。

precision_exec:
  commands:
    - cmd: "npm install"
      timeout_ms: 300000
  verbosity: minimal

pnpm または yarn の場合：

precision_exec:
  commands:
    - cmd: "pnpm install"
      timeout_ms: 300000
  verbosity: minimal

ステップ 5.3：環境変数を設定する

.env.example またはコードから、必要な環境変数を特定します。

precision_read:
  files:
    - path: ".env.example"
      extract: content
  verbosity: standard

コード内で環境変数の使用箇所を検索します：

precision_grep:
  queries:
    - id: env_usage
      pattern: 'process\.env\.[A-Z_]+'
      glob: "src/**/*.{ts,tsx,js,jsx}"
  output:
    format: matches
    max_per_item: 20
  verbosity: minimal

ここから分かること：

• 必要な環境変数
• 必要な API キー、データベース URL、シークレット
• サードパーティサービスとの連携

ステップ 5.4：データベースをセットアップする

データベースのスキーマファイル、マイグレーション、シードスクリプトを確認します。

discover:
  queries:
    - id: prisma_schema
      type: glob
      patterns: ["prisma/schema.prisma"]
    - id: migrations
      type: glob
      patterns:
        - "prisma/migrations/**/*"
        - "migrations/**/*"
        - "db/migrations/**/*"
    - id: seed_scripts
      type: glob
      patterns:
        - "prisma/seed.{ts,js}"
        - "db/seed.{ts,js}"
        - "scripts/seed.{ts,js}"
  verbosity: files_only

データベースをセットアップします：

precision_exec:
  commands:
    - cmd: "npx prisma generate"
    - cmd: "npx prisma migrate dev"
    - cmd: "npx prisma db seed"
  verbosity: standard

ここから分かること：

• データベースのスキーマとモデル
• マイグレーション履歴
• 開発用のシードデータ

フェーズ 6：ビルドと開発のワークフロー

ビルドコマンド、開発サーバー、ホットリロード、テストランナーについて把握します。

ステップ 6.1：ビルドスクリプトを特定する

package.json からスクリプトを抽出します。

precision_grep:
  queries:
    - id: scripts
      pattern: '"scripts":\s*\{[\s\S]*?\}'
      glob: "package.json"
      multiline: true
  output:
    format: matches
  verbosity: standard

ここから分かること：

• ローカル開発用の dev または start コマンド
• 本番ビルド用の build コマンド
• テスト実行用の test コマンド
• リンティング用の lint コマンド
• デプロイ、データベースなどのカスタムスクリプト

ステップ 6.2：ビルドプロセスをテストする

セットアップを検証するため、ビルドコマンドを実行します。

precision_exec:
  commands:
    - cmd: "npm run build"
      timeout_ms: 300000
  verbosity: standard

ここから分かること：

• ビルドエラーや警告
• ビルド成果物の出力先
• ビルド時間とパフォーマンス

ステップ 6.3：開発サーバーを起動する

ホットリロードが機能することを検証するため、開発コマンドを実行します。

precision_exec:
  commands:
    - cmd: "npm run dev"
      timeout_ms: 60000
      until:
        pattern: "(ready|compiled|listening|started)"
        kill_after: true  # Stops dev server after pattern matches
  verbosity: standard

ここから分かること：

• 開発サーバーのポート（通常は :3000、:5173、:8080）
• ホットリロードの設定
• 起動時間

ステップ 6.4：テストを実行する

テストのセットアップを検証するため、テストスイートを実行します。

precision_exec:
  commands:
    - cmd: "npm test"
      timeout_ms: 120000
  verbosity: standard

ここから分かること：

• テストフレームワーク（Jest、Vitest、Mocha など）
• テストカバレッジ
• 失敗したテストやセットアップの問題

フェーズ 7：主要なパターン

状態管理、エラー処理、認証、ルーティングにおける繰り返し使用されるパターンを特定します。

ステップ 7.1：状態管理のパターン

状態管理ライブラリとパターンを検索します。

discover:
  queries:
    - id: react_state
      type: grep
      pattern: '(useState|useReducer|useContext)'
      glob: "src/**/*.{ts,tsx}"
    - id: zustand
      type: grep
      pattern: "(create|useStore).*from ['\"]zustand"
      glob: "src/**/*.{ts,tsx}"
    - id: redux
      type: grep
      pattern: "(useSelector|useDispatch|createSlice)"
      glob: "src/**/*.{ts,tsx}"
    - id: jotai
      type: grep
      pattern: "(atom|useAtom).*from ['\"]jotai"
      glob: "src/**/*.{ts,tsx}"
  verbosity: count_only

ここから分かること：

• 主な状態管理の方法
• グローバル状態とローカル状態のパターン
• ストアの構成

ステップ 7.2：エラー処理のパターン

エラーバウンダリー、try-catch のパターン、エラー報告を確認します。

# Use precision_grep instead of discover for multiline patterns
precision_grep:
  queries:
    - id: error_boundaries
      pattern: "(class|extends) .*ErrorBoundary"
      glob: "src/**/*.{ts,tsx}"
    - id: try_catch
      pattern: "try \{[\s\S]*?\} catch"
      glob: "src/**/*.{ts,tsx,js,jsx}"
      multiline: true
    - id: error_reporting
      pattern: "(Sentry|Bugsnag|ErrorBoundary|reportError)"
      glob: "src/**/*.{ts,tsx,js,jsx}"
  output:
    format: count_only
  verbosity: minimal

ここから分かること：

• エラーバウンダリーの使用状況
• エラーログと報告の設定
• 例外処理の規約

ステップ 7.3：認証のパターン

認証ライブラリとパターンを特定します。

discover:
  queries:
    - id: auth_providers
      type: grep
      pattern: "(NextAuth|Clerk|Auth0|Supabase|Lucia|useAuth)"
      glob: "src/**/*.{ts,tsx}"
    - id: protected_routes
      type: grep
      pattern: "(withAuth|requireAuth|ProtectedRoute|middleware)"
      glob: "src/**/*.{ts,tsx}"
    - id: session_usage
      type: grep
      pattern: "(getSession|useSession|getServerSession)"
      glob: "src/**/*.{ts,tsx}"
  verbosity: count_only

ここから分かること：

• 認証プロバイダー（Clerk、NextAuth、カスタム）
• 保護されたルートのパターン
• セッション管理の方法

ステップ 7.4：ルーティングのパターン

ルーティングのアーキテクチャを把握します。

discover:
  queries:
    - id: app_router
      type: glob
      patterns: ["app/**/page.{ts,tsx}", "app/**/layout.{ts,tsx}"]
    - id: pages_router
      type: glob
      patterns: ["pages/**/*.{ts,tsx}"]
    - id: react_router
      type: grep
      pattern: "(BrowserRouter|Routes|Route|useNavigate)"
      glob: "src/**/*.{ts,tsx}"
  verbosity: count_only

ここから分かること：

• ルーティングフレームワーク（Next.js App Router、Pages Router、React Router）
• ルートの構成
• 動的ルートのパターン

フェーズ 8：ドキュメントの生成

CLAUDE.md、アーキテクチャドキュメント、オンボーディングガイドを生成します。

ステップ 8.1：プロジェクトの指示を記載した CLAUDE.md を作成する

プロジェクトのコンテキストを網羅した CLAUDE.md を作成します。

precision_write:
  files:
    - path: ".claude/CLAUDE.md"
      mode: fail_if_exists
      content: |
        # Project Name

        ## Overview
        [Brief description of the project, its purpose, and key features]

        ## Architecture
        - **Framework**: [Next.js 14 App Router / Remix / etc.]
        - **Language**: [TypeScript]
        - **Database**: [PostgreSQL with Prisma]
        - **Authentication**: [Clerk / NextAuth]
        - **State Management**: [Zustand / Redux / etc.]

        ## Directory Structure
        ```
        src/
          app/          # Next.js App Router pages and layouts
          components/   # React components
          lib/          # Utility functions and shared logic
          api/          # API route handlers
          types/        # TypeScript type definitions
        ```

        ## Development Workflow
        1. Install dependencies: `pnpm install`
        2. Setup environment: Copy `.env.example` to `.env.local`
        3. Setup database: `npx prisma migrate dev`
        4. Start dev server: `pnpm dev`
        5. Run tests: `pnpm test`

        ## Key Patterns
        - Components use PascalCase naming
        - Utilities use camelCase naming
        - Hooks start with `use` prefix
        - Server components by default, use 'use client' directive for client components

        ## Testing
        - Unit tests: Vitest
        - E2E tests: Playwright
        - Run with: `pnpm test`

        ## Deployment
        - Platform: [Vercel / Netlify / etc.]
        - CI/CD: [GitHub Actions]
        - Deploy command: `pnpm build`
  verbosity: minimal

ステップ 8.2：アーキテクチャ図を生成する

アーキテクチャを示す Mermaid 図を作成します。

precision_write:
  files:
    - path: "docs/ARCHITECTURE.md"
      mode: fail_if_exists
      content: |
        # Architecture

        ## System Overview
        ```mermaid
        graph TD
          A[Client Browser] --> B[Next.js App Router]
          B --> C[React Server Components]
          B --> D[API Routes]
          D --> E[Database - Prisma]
          D --> F[External APIs]
          C --> E
        ```

        ## Module Boundaries
        - `app/`: Page routes and layouts (Next.js App Router)
        - `components/`: Reusable UI components
        - `lib/`: Business logic and utilities
        - `api/`: Backend API handlers

        ## Data Flow
        1. User requests page -> Next.js App Router
        2. Server Component fetches data -> Prisma -> Database
        3. Server renders component with data
        4. Client receives HTML with hydration instructions
        5. Client-side interactions -> API routes -> Database

        ## External Dependencies
        - Authentication: Clerk
        - Email: Resend
        - Storage: Vercel Blob
  verbosity: minimal

ステップ 8.3：オンボーディングのチェックリストを作成する

新しい開発者向けのチェックリストを生成します。

precision_write:
  files:
    - path: "docs/ONBOARDING.md"
      mode: fail_if_exists
      content: |
        # Onboarding Checklist

        ## Prerequisites
        - [ ] Node.js 18+ installed
        - [ ] pnpm installed (`npm install -g pnpm`)
        - [ ] Git configured
        - [ ] PostgreSQL installed locally (or Docker)

        ## Setup Steps
        1. [ ] Clone repository
        2. [ ] Install dependencies: `pnpm install`
        3. [ ] Copy `.env.example` to `.env.local`
        4. [ ] Fill in environment variables (get from team)
        5. [ ] Setup database: `npx prisma migrate dev`
        6. [ ] Seed database: `npx prisma db seed`
        7. [ ] Start dev server: `pnpm dev`
        8. [ ] Open http://localhost:3000
        9. [ ] Run tests: `pnpm test`
        10. [ ] Verify build: `pnpm build`

        ## Key Resources
        - Architecture: [docs/ARCHITECTURE.md](./ARCHITECTURE.md)
        - API Docs: [docs/API.md](./API.md)
        - Code Review: Use `/code-review` skill

        ## First Tasks
        1. Read through CLAUDE.md for project context
        2. Explore the codebase structure
        3. Review recent pull requests
        4. Pick a "good first issue" from GitHub
  verbosity: minimal

フェーズ 9：コントリビューションのワークフロー

Git のブランチ戦略、PR プロセス、CI/CD パイプラインについて把握します。

Step 9.1: Git の設定を確認する

ブランチ保護ルールとワークフローファイルを確認します。

discover:
  queries:
    - id: github_workflows
      type: glob
      patterns: [".github/workflows/**/*.yml", ".github/workflows/**/*.yaml"]
    - id: git_hooks
      type: glob
      patterns: [".husky/**/*", ".git/hooks/**/*"]
    - id: branch_config
      type: glob
      patterns: [".github/CODEOWNERS", ".github/pull_request_template.md"]
  verbosity: files_only

GitHub Actions ワークフローを読み取ります：

precision_read:
  files:
    - path: ".github/workflows/ci.yml"
      extract: content
  verbosity: standard

ここからわかること：

• CI/CD パイプラインの手順
• マージ前に必須となるチェック
• デプロイプロセス

Step 9.2: PR プロセスを理解する

PR テンプレートとコントリビューションガイドラインを読みます。

precision_read:
  files:
    - path: ".github/pull_request_template.md"
      extract: content
    - path: "CONTRIBUTING.md"
      extract: content
  verbosity: standard

ここからわかること：

• PR の説明に必要な内容
• レビュープロセス
• テストに関する期待事項

Step 9.3: コミット規約を確認する

コミットメッセージの規約を検索します。

# Check for commitlint config
precision_grep:
  queries:
    - id: commitlint
      pattern: '.*'
      glob: ".commitlintrc*"
  output:
    format: matches
  verbosity: minimal

# Check commit convention from recent commits
precision_exec:
  commands:
    - cmd: "git log --oneline -20"
  verbosity: standard

ここからわかること：

• コミットメッセージの形式（Conventional Commits、独自形式）
• コミットで使用されるスコープ

Phase 10: 検証と確認

環境がエンドツーエンドで動作することを確認します。

Step 10.1: テストスイート全体を実行する

カバレッジを含めてすべてのテストを実行します。

precision_exec:
  commands:
    - cmd: "npm test -- --coverage"
      timeout_ms: 180000
  verbosity: standard

ここからわかること：

• テストカバレッジ率
• カバーされていないファイルや行
• 遅いテストや不安定なテスト

Step 10.2: リンティングが通ることを確認する

コード品質を確保するため、リンティングを実行します。

precision_exec:
  commands:
    - cmd: "npm run lint"
  verbosity: standard

ここからわかること：

• リンティングのエラーや警告
• コードスタイル違反

Step 10.3: 型安全性を確認する

TypeScript の型チェッカーを実行します。

precision_exec:
  commands:
    - cmd: "npm run typecheck"
  verbosity: standard

ここからわかること：

• 型エラー
• 不足している型定義
• any の使用状況

Step 10.4: 本番用ビルドを確認する

本番用にビルドし、バンドルサイズを確認します。

precision_exec:
  commands:
    - cmd: "npm run build"
      timeout_ms: 300000
    - cmd: "ls -lh .next/static/chunks" # Next.js example
  verbosity: standard

ここからわかること：

• ビルドの警告やエラー
• バンドルサイズ
• 最適化の機会

ベストプラクティス

1. 小さく始め、深く理解する

すべてを一度に理解しようとしないでください。まずは次の項目から始めます。

1. プロジェクト構成（Phase 1）
2. 環境のセットアップ（Phase 5）
3. ビルドのワークフロー（Phase 6）

その後、アーキテクチャ、パターン、コントリビューションのワークフローを詳しく調べます。

2. 精密なツールを効率よく使う

• まず discover を verbosity: count_only とともに使用して、対象範囲を把握します
• verbosity: files_only を使用して、対象のリストを作成します
• 全文を読む前に、extract: outline を指定して precision_read を使用します
• パターンの出現頻度を確認するには、output.format: count_only を指定して precision_grep を使用します

3. 学びながらドキュメントを作成する

オンボーディング中にドキュメントを作成または更新します。

• プロジェクトのコンテキストを記載した CLAUDE.md
• アーキテクチャ図
• セットアップガイド
• よくある落とし穴と解決策

4. 早い段階で検証する

オンボーディングの早い段階でビルド、テスト、リンティングを実行します。これにより、コードベースの理解に時間をかける前に、環境の問題を検出できます。

5. 質問する

次のようなものを見つけた場合：

• ドキュメント化されていないパターン
• 複雑な抽象化
• 不足しているテスト
• 一貫性のない規約

チームへの質問として記録します。

よくある落とし穴

落とし穴 1：依存関係のインストールを省略する

問題： 依存関係をインストールせずにコードを読み始めてしまいます。

解決策： 必ず最初に npm install を実行します。TypeScript や ESLint など、多くのツールは動作に依存関係を必要とします。

落とし穴 2：環境変数を無視する

問題： .env.local ファイルがないと、実行時エラーが発生します。

解決策： .env.example を .env.local にコピーし、必須の値を設定します。シークレットはチームに確認してください。

落とし穴 3：ビルドをテストしない

問題： 確認せずにビルドが動作すると想定してしまいます。

解決策： 設定の問題、依存関係の不足、TypeScript のエラーを早期に検出するため、npm run build を実行します。

落とし穴 4：データベースのセットアップを見落とす

問題： データベーススキーマがないため、実行時にアプリケーションが失敗します。

解決策： 開発サーバーを起動する前に、マイグレーション（npx prisma migrate dev）を実行し、シードデータを投入します。

落とし穴 5：既存のドキュメントを読まない

問題： README.md、CONTRIBUTING.md、またはプロジェクトドキュメントに記載された重要な背景情報を見落とします。

解決策： まず precision_read を使用して、ルートと docs/ フォルダー内のすべての Markdown ファイルを読みます。

検証スクリプト

オンボーディングの完了状況を確認するには、検証スクリプトを使用します。

bash plugins/goodvibes/skills/quality/project-onboarding/scripts/validate-onboarding.sh

次の項目が確認されます：

• 依存関係がインストールされている
• 環境変数が設定されている
• データベースのセットアップが完了している
• テストが成功している
• ビルドが成功している

参考資料

詳細なパターンや例については、以下を参照してください。

• オンボーディングパターンのリファレンス
• アーキテクチャのマッピング例
• 規約の検出パターン

関連スキル

• quality/code-review - コードベースを理解した後に、コード品質をレビューします
• architecture/system-design - 既存のパターンに従って新機能を設計します
• testing/test-strategy - プロジェクトの規約に沿ったテストを作成します