dev-onboarding-builder

開発者オンボーディングビルダー

新しいチームメンバーが初日からスムーズに過ごせる環境を整えます。

中核となるワークフロー

1. 前提条件を確認する：必要なツールとアクセス権を特定します
2. セットアップガイドを作成する：環境設定を段階的に説明します
3. 最初のタスクを設計する：適切な入門向け課題を選びます
4. 所要時間を追加する：各ステップの目安を示します
5. よくある問題を記録する：事前にトラブルシューティングを用意します
6. チームを紹介する：メンバーや構成について説明します
7. コードベースを案内する：主要な領域を解説します

オンボーディングドキュメントの構成

ONBOARDING.md テンプレート

# Welcome to [Team/Project Name]! 🎉

This guide will help you get set up and productive on your first day.

**Estimated completion time:** 2-3 hours

## Before You Start

### Access Checklist

- [ ] GitHub organization access
- [ ] Slack workspace invitation
- [ ] Email account setup
- [ ] VPN credentials (if remote)
- [ ] Cloud console access (AWS/GCP/Azure)
- [ ] CI/CD dashboard access
- [ ] Project management tool (Jira/Linear)

### Tools to Install

- [ ] Node.js 20+ (via [Volta](https://volta.sh/))
- [ ] pnpm 8+
- [ ] Docker Desktop
- [ ] PostgreSQL 15+
- [ ] VS Code or preferred editor
- [ ] Git configured with your work email

## Day 1: Environment Setup

### Step 1: Clone Repository (5 min)

```bash
git clone [email protected]:company/project-name.git
cd project-name
```

目的： コードベースをマシンに取得します

トラブルシューティング：

• SSH キーが機能しませんか？GitHub SSH の設定をご覧ください
• アクセスが拒否されますか？GitHub へのアクセス権をマネージャーに確認してもらってください

ステップ 2：依存関係をインストールする（10 分）

# Install Volta (Node version manager)
curl https://get.volta.sh | bash

# Install dependencies
pnpm install

期待される出力：「Dependencies installed successfully」

トラブルシューティング：

• pnpm not found と表示されますか？ターミナルを再起動するか、volta install pnpm を実行してください
• インストールが止まっていますか？VPN 接続を確認してください

ステップ 3：環境を設定する（10 分）

# Copy environment template
cp .env.example .env

.env を次の値で編集します：

DATABASE_URL=postgresql://postgres:password@localhost:5432/projectname_dev
REDIS_URL=redis://localhost:6379
API_KEY=ask-team-for-dev-key

認証情報の入手先：

• データベース：ローカルでセットアップします（次のステップを参照）
• API キー：Slack の #dev-onboarding で @alice または @bob に問い合わせてください
• 外部サービス：1Password の保管庫「Dev Credentials」を確認してください

トラブルシューティング：

• 認証情報が見つかりませんか？#dev-onboarding に投稿してください
• 環境変数が不足していますか？必要な変数はすべて .env.example で確認してください

ステップ 4：データベースをセットアップする（15 分）

# Start PostgreSQL with Docker
docker run --name project-postgres \
  -e POSTGRES_PASSWORD=password \
  -p 5432:5432 \
  -d postgres:15

# Run migrations
pnpm db:migrate

# Seed with test data
pnpm db:seed

期待される出力：「Migration complete. Database seeded.」

確認： http://localhost:5432 を開き、テーブルがあることを確認します

トラブルシューティング：

• ポート 5432 はすでに使用中ですか？既存のプロセスを終了します：lsof -ti:5432 | xargs kill
• マイグレーションに失敗しますか？削除して再作成します：pnpm db:reset

ステップ 5：開発サーバーを起動する（5 分）

pnpm dev

期待される出力：

✓ Ready on http://localhost:3000

テスト： http://localhost:3000 を開き、ホームページが表示されることを確認します

トラブルシューティング：

• ポート 3000 は使用中ですか？プロセスを終了するか、.env の PORT を変更してください
• ビルドエラーが発生しますか？キャッシュを消去します：rm -rf .next && pnpm dev

ステップ 6：テストを実行する（5 分）

pnpm test

**期待される出力：**すべてのテストが成功 ✓

テストに失敗した場合：

• 初めてですか？これはバグです！#dev-help で報告してください
• 既知の問題ですか？#dev-help のピン留めされたメッセージを確認してください

1 日目：最初のタスク

タスク：入門向けの課題を修正する

新しいチームメンバー向けに、一部の課題に good-first-issue のラベルを付けています。

目標： 小規模な PR を 1 つ完了し、ワークフローを学びます

手順：

1. 入門向けの課題を確認します
2. 興味のある課題を選びます（または #dev-onboarding でおすすめを尋ねます）
3. 課題に「これを担当します！」とコメントします
4. ブランチを作成します：git checkout -b fix/issue-123-description
5. 変更を加えます
6. テストを作成または更新します
7. pnpm lint と pnpm test を実行します
8. 規約に従ってコミットします
9. プッシュして PR を作成します
10. メンターにレビューを依頼します

所要時間の目安： 2～4 時間

成功基準：

• 適切な名前でブランチを作成した
• コードを変更した
• テストを作成または更新した
• すべてのチェックに合格した
• 説明を添えて PR を作成した
• コードのレビューとマージが完了した

メンター： @alice（バックエンド）、@bob（フロントエンド）、@charlie（フルスタック）

2～3 日目：コードベースの案内

プロジェクト構成の概要

src/
├── app/              # Next.js routes (start here!)
│   ├── api/          # API endpoints
│   └── (auth)/       # Authentication pages
├── components/       # React components
│   ├── ui/           # Base UI components
│   └── features/     # Feature-specific components
├── lib/              # Utilities and helpers
│   ├── api/          # API client
│   ├── hooks/        # Custom React hooks
│   └── utils/        # Helper functions
├── services/         # Business logic layer
└── types/            # TypeScript definitions

理解しておくべき主要なファイル

ファイル	役割	変更する場面
src/app/layout.tsx	ルートレイアウトとプロバイダー	グローバルプロバイダーの追加
src/lib/db.ts	データベースクライアント	データベースクエリ
src/lib/auth.ts	認証ロジック	認証関連の機能
src/middleware.ts	リクエストミドルウェア	認証やリダイレクトの追加

ウォークスルー（以下のファイルを順番に読んでください）

1. src/app/page.tsx - ホームページ（エントリーポイント）
2. src/app/api/users/route.ts - シンプルな API エンドポイント
3. src/services/user.service.ts - ビジネスロジックの例
4. src/components/ui/button.tsx - UI コンポーネントのパターン
5. src/lib/hooks/useUser.ts - カスタムフックの例

課題： ユーザー登録を処理するコードを探してください。ヒント：API ルートから始めましょう！

よくあるパターン

API ルートのパターン

// src/app/api/[resource]/route.ts
export async function GET(req: Request) {
  // 1. Validate auth
  // 2. Parse request
  // 3. Call service layer
  // 4. Return response
}

サービスレイヤーのパターン

// src/services/[resource].service.ts
export class UserService {
  async create(data: CreateUserDto) {
    // 1. Validate data
    // 2. Business logic
    // 3. Database operation
    // 4. Return result
  }
}

第 1 週：学習計画

1 日目

• 環境設定を完了する
• 最初の課題を修正する
• チームメンバーと顔合わせする（1 対 1 のミーティングを予定する）

2～3 日目

• コードベースの案内ドキュメントを読む
• 2 つ目の課題を完了する（中程度の複雑さ）
• チームメイトの PR を 2～3 件レビューする

4～5 日目

• 最初の機能に取り組む（メンターとペアで作業）
• チームのスタンドアップ／計画ミーティングに参加する
• 開発ツールをセットアップする（リンター、拡張機能）

チーム構成

エンジニアリングチーム

Alice（@alice） - テックリード

• アーキテクチャに関する決定を承認します
• 複雑な PR のコードレビューを行います
• 質問する内容：システム設計に関する質問

Bob（@bob） - シニアバックエンドエンジニア

• データベースと API のエキスパートです
• 質問する内容：バックエンド、パフォーマンスに関する質問

Charlie（@charlie） - シニアフロントエンドエンジニア

• UI／UX の実装を担当します
• 質問する内容：React、スタイリングに関する質問

あなたのマネージャー（@manager）

• 毎週金曜日午後 2 時に 1 対 1 のミーティングを行います
• キャリア開発について話し合います
• 質問する内容：プロセス、優先事項、キャリアに関する質問

コミュニケーションチャンネル

• #dev-general - 開発全般に関する話し合い
• #dev-help - 質問や行き詰まりの相談
• #dev-onboarding - 新メンバー向けのサポート
• #dev-releases - リリースのお知らせ
• #dev-alerts - 本番環境のアラート

ミーティング予定

• デイリースタンドアップ - 午前 10:00（15 分）
• スプリント計画 - 毎週月曜日午後 2:00（1 時間）
• チーム振り返り - 毎週金曜日午後 4:00（45 分）
• テックトーク - 毎週木曜日午後 3:00（30 分）

開発ワークフロー

日々のワークフロー

1. 午前： Slack を確認し、最新の main を取得する
2. スタンドアップ： 昨日行ったこと、今日行うこと、障害となっていることを共有する
3. コーディング： 割り当てられたチケットに取り組む
4. 昼食： チームは通常 12:30 に昼食を取ります
5. 午後： コーディングを続け、PR をレビューする
6. 終業時： チケットのステータスを更新し、作業内容をプッシュする

PR レビューのガイドライン

PR をレビューする際は、次のことを行います。

• コードの品質とスタイルを確認する
• テストで変更内容が網羅されていることを確認する
• 重要な変更の場合は、コードをローカルで実行する
• 不明な点があれば質問する
• 納得できたら承認する

コードレビューを依頼する

レビューを依頼する際は、次のことを行います。

• まず自分でレビューする
• 明確な説明を追加する
• 関連する課題へのリンクを追加する
• 適切なレビュアーをタグ付けする
• フィードバックに速やかに対応する

よくある注意点

データベース

問題： relation "users" does not exist 解決策： マイグレーションを実行します：pnpm db:migrate

問題： シードデータが表示されない 解決策： データベースをリセットします：pnpm db:reset

開発サーバー

問題： 変更が反映されない 解決策：

1. ハードリロードする（Cmd+Shift+R）
2. .next フォルダーを消去する：rm -rf .next
3. 開発サーバーを再起動する

問題： ポートがすでに使用されている 解決策： プロセスを終了します：lsof -ti:3000 | xargs kill

環境

問題： 環境変数が不足している 解決策： .env.example を確認し、.env に追加します

問題： API キーが機能しない 解決策： 本番環境用ではなく、開発環境用のキーであることを確認します（チームに問い合わせてください）

リソース

ドキュメント

• アーキテクチャの概要
• API リファレンス
• コントリビューションガイド
• スタイルガイド

学習リソース

• Next.js ドキュメント
• Prisma ガイド
• TypeScript ハンドブック

社内リソース

• 会社の Wiki：https://wiki.company.com
• デザインシステム：https://design.company.com
• API プレイグラウンド：https://api-dev.company.com

ヘルプを求める

困ったとき（5-15-30 ルール）

• 5 分： まず自分で解決を試みます
• 15 分： ドキュメント、Stack Overflow、過去の課題を検索します
• 30 分： 状況を添えて #dev-help で質問します

質問のテンプレート

**What I'm trying to do:** [goal]
**What I tried:** [attempts]
**Error message:** [full error]
**Environment:** [OS, Node version, etc.]
**Related code:** [link to file/line]

質問先

• セットアップの問題： #dev-onboarding または #dev-help
• コードに関する質問： #dev-help またはメンター
• プロセスに関する質問： マネージャー
• 緊急・本番環境に関する問題： #dev-alerts

1 週目のチェックリスト

1 週目の終わりまでに、以下を完了していることを目指します。

• 環境のセットアップを完了した
• good-first-issues を 2～3 件修正した
• 初めての機能 PR を作成した
• チームメンバー全員と面談した
• チームミーティングにすべて参加した
• 主要なドキュメントを読んだ
• 開発ワークフローを理解した
• 助けを求める方法を把握した

フィードバック

オンボーディングは常に改善しています。ぜひ以下をお聞かせください。

• うまくいったことは何ですか？
• 分かりにくかったことは何ですか？
• 足りないものは何ですか？

共有先： #dev-onboarding またはマネージャー

---

チームへようこそ！あなたを迎えられてうれしいです！ 🚀

## Onboarding Best Practices

### Time Estimates
- Be realistic with timing
- Include buffer for troubleshooting
- Track actual time vs estimated

### Progressive Complexity
- Day 1: Setup and simple task
- Week 1: Understanding patterns
- Month 1: Independent features

### Clear Success Criteria
- Checklist for each step
- Objective completion markers
- Regular check-ins

### Preemptive Troubleshooting
- Document known issues
- Provide solutions upfront
- Update based on new dev feedback

### Human Connection
- Introduce team members
- Schedule 1:1s
- Provide mentors

## First Task Selection Criteria

Good first task should:
- [ ] Be completable in 2-4 hours
- [ ] Touch multiple areas lightly
- [ ] Have clear acceptance criteria
- [ ] Require PR and review
- [ ] Be genuinely useful (not busy work)
- [ ] Have mentor availability

**Examples:**
- Fix typo in error message (touches: frontend, i18n, testing)
- Add validation to API endpoint (touches: backend, testing, docs)
- Improve loading state (touches: frontend, UX, components)

## Documentation Components

### Essential Sections
1. Prerequisites and access
2. Step-by-step setup with time estimates
3. First task assignment
4. Codebase tour
5. Team structure
6. Communication channels
7. Common issues and solutions
8. Resources and next steps

### Optional but Valuable
- Video walkthrough
- Pair programming schedule
- Reading list
- Architecture diagrams
- Glossary of terms

## Maintenance

### Keep Updated
- Review after each new hire
- Update tool versions
- Refresh access instructions
- Add new common issues

### Collect Feedback
- Exit survey after week 1
- Regular check-ins
- Track time to productivity
- Document pain points

## Output Checklist

Complete onboarding package includes:

- [ ] ONBOARDING.md with step-by-step guide
- [ ] Time estimates for each step
- [ ] First task identified and documented
- [ ] Team structure and communication
- [ ] Troubleshooting for common issues
- [ ] Links to all necessary resources
- [ ] Checklists for progress tracking
- [ ] Feedback mechanism
- [ ] Mentor assignments
- [ ] Expected timeline (day/week/month)