developer-onboarding-doc

開発者オンボーディングドキュメントのスキル

サービスやチーム向けに、開発者オンボーディングドキュメントを完全な形で作成します。新しいエンジニアが最初の1週間で業務に取り組めるようになるために必要な情報をすべて網羅します。

優れたオンボーディングドキュメントは、Wiki の内容をそのまま詰め込んだものではありません。新しいエンジニアが初日に実際に抱く疑問に、疑問を抱く順番で答えます。

必須入力情報

まだ提示されていない場合は、次の情報を確認してください。

• サービス名とその機能
• 担当チーム
• 技術スタック — 言語、フレームワーク、データベース、メッセージキューなど
• 主な外部依存関係 — 上流サービス、サードパーティ API
• デプロイ先 — Kubernetes、ECS、Lambda、ベアメタルなど
• ローカル開発環境のセットアップ — ローカルでの実行方法（Docker Compose、ローカル DB など）
• テスト方針 — ユニットテスト、統合テスト、E2E テスト、テストコマンド
• デプロイプロセス — コードを本番環境に反映する手順の概要
• オンコール体制 — 担当者、アラートの仕組み
• 連絡先 — 技術リード、プラットフォームチーム、関連サービスの担当者

出力形式

---

開発者オンボーディング：［サービス名］

チーム：［チーム名］ | 技術リード：［名前］ 最終更新日：［日付］ | 更新者：［名前］

このドキュメントに誤りや古い情報があれば、今すぐ修正してください。後からオンボーディングするすべてのエンジニアに影響します。

---

このサービスの機能

［3～5文で記載します。このサービスはどのような問題を解決しますか？誰がこのサービスを呼び出し、このサービスは何を呼び出しますか？このサービスが停止した場合、何が影響を受けますか？］

サービス種別：［API / バックグラウンドワーカー / イベントコンシューマー / データパイプラインなど］ 利用者：［このサービスに依存する内部サービスまたは外部クライアントの一覧］ 依存関係：［このサービスが呼び出す上流サービス、データベース、サードパーティ API の一覧］

アーキテクチャ図：［リンクまたは埋め込み。簡単な ASCII 図でも役立ちます］

[Caller A] ──→ [This Service] ──→ [Database]
                      │
                      └──→ [Downstream Service]

---

コードベースの概要

リポジトリ：［リンク］ メインブランチ：[main / master] 言語：［例：Go 1.22 / Node.js 20 / Python 3.12］ フレームワーク：［例：Express / FastAPI / Gin / Rails］

主なディレクトリ

[repo-root]/
├── [src/ or cmd/]          # Application code
│   ├── [handlers/]         # HTTP handlers / controllers
│   ├── [services/]         # Business logic
│   ├── [repository/]       # Database access layer
│   └── [models/]           # Data models / types
├── [tests/]                # Test files
├── [migrations/]           # Database migrations
├── [scripts/]              # Utility scripts
├── [.github/workflows/]    # CI/CD pipeline definitions
└── [docs/]                 # Additional documentation

最初に読む箇所：［全体像を把握するのに役立つ主要ファイルを2～3個挙げます。例：main.go、routes.js、app.py］

知っておくとよい意外な点

• ［一般的でないパターン 1 — 例：「イベントソーシングを採用しています。状態は直接保存するのではなく、イベントログから導出されます」］
• ［一般的でないパターン 2 — 例：「認証はゲートウェイで処理されます。このサービスは X-User-Id ヘッダーを信頼します」］
• ［一般には分かりにくい設計判断や、レガシーな選択など］

---

ローカル開発環境のセットアップ

セットアップの所要時間：［まっさらなマシンで X 分］

前提条件

• ［ツール 1］ — バージョン［X］ — ［インストールリンク］
• ［ツール 2］ — バージョン［X］ — ［インストールリンク］
• ［リポジトリ / 社内パッケージレジストリ］へのアクセス — ［誰に］申請
• ［必要なシークレットまたは認証情報］ — ［誰に］申請

セットアップ手順

# 1. Clone the repo
git clone [repo URL]
cd [repo-name]

# 2. Copy and configure environment variables
cp .env.example .env
# Edit .env — see "Environment Variables" section below

# 3. Start dependencies (database, cache, etc.)
[docker compose up -d / make deps / etc.]

# 4. Install dependencies
[npm install / go mod download / pip install -r requirements.txt]

# 5. Run database migrations
[migration command]

# 6. Start the service
[start command]

# 7. Verify it's working
curl http://localhost:[PORT]/health
# Expected: {"status":"ok"}

うまくいかない場合：［以下のトラブルシューティングセクション］を確認するか、#[channel] で質問してください。

環境変数

変数	必須	説明	例
DATABASE_URL	はい	プライマリ DB の接続文字列	postgres://localhost:5432/[db]
[VAR_2]	はい	［説明］	［例］
[VAR_3]	いいえ	［説明 — デフォルト値］	［例］

ローカル開発用のシークレット：［入手先を記載します。例：「[command] を実行して Vault から取得します」または「#[channel] で［担当者］に依頼します」］

便利なローカルコマンド

[start command]           # Start the service
[test command]            # Run all tests
[lint command]            # Run linter
[format command]          # Format code
[migration command]       # Run pending migrations
[seed command]            # Seed local database

---

テスト

テスト方針：［例：「統合テストを中心に実施します。純粋関数にはユニットテストを、DB や外部サービスに接続する処理には統合テストを行います」］

テストの実行

# All tests
[test command]

# Unit tests only
[unit test command]

# Integration tests (requires local deps running)
[integration test command]

# A specific test file or test case
[test command with filter]

テストカバレッジ：［X］%（CI の合格に必要な最低値：［Y］%） カバレッジレポート：［レポートの場所］

テストの作成

• ユニットテスト： [配置場所 — 例：ソースファイルと同じ場所に *_test.go として配置]
• インテグレーションテスト： [配置場所 — 例：tests/integration/]
• テスト用データベース： [仕組み — 例：「各テストではクリーンなトランザクションを使用し、終了時にロールバックします。tests/helpers/db.go を参照してください」]
• モック： [方針 — 例：「リポジトリ層でモックを使用します。データベースを直接モックしないでください」]

---

変更の作成

ブランチ

[ブランチ名の規則 — 例：feature/[ticket-id]-short-description、fix/[ticket-id]-short-description]

PR を作成する前に

• ローカルでテストが成功する
• リンターが成功する（[lint command]）
• 新しい動作にテストカバレッジがある
• 新しい環境変数があれば .env.example に追加し、説明を記載する
• データベースのマイグレーションに後方互換性がある（旧コードが新しいスキーマで動作する）

コードレビュー

• レビュアー： [レビューを依頼する相手 — 例：「[team] のエンジニア全員。認証に関する変更はリードのレビューが必須」]
• 想定レビュー時間： [X 時間／1 営業日]
• PR テンプレート： [リンク、または GitHub が自動生成]

データベースのマイグレーション

# Create a new migration
[migration create command]

# Apply pending migrations
[migration up command]

# Roll back last migration
[migration down command]

マイグレーションのルール：

• すべてのマイグレーションに後方互換性が必要です。旧コードは新しいスキーマで動作しなければなりません
• 1 回のマイグレーションでカラムの名前を変更したり削除したりしないでください。2 段階で行います（新しいカラムを追加し、データを移行してから、古いカラムを削除）
• マージする前にロールバックをテストしてください

---

デプロイ

コードが本番環境に反映される仕組み： [1～2 文で概要を記載 — CI/CD の詳細な手順書があればリンク]

1. main にマージ → ステージング環境へ自動デプロイ
2. ステージング環境でスモークテストを実行
3. 手動承認 → 本番環境へデプロイ
4. デプロイ後、[X 分間] モニタリング

デプロイのドキュメント： [CI/CD の手順書またはパイプラインのドキュメントへのリンク]

デプロイできる人： [すべてのエンジニア／リードエンジニア／オンコールエンジニア — 明記してください]

デプロイ用チャンネル： #[deployments channel]

---

モニタリングと可観測性

ダッシュボード： [Datadog / Grafana / CloudWatch — リンク] ログ： [ログ集約ツールとリンク — 例：「ログは Datadog の service:[name] にあります」] トレース： [トレーシングツールと、該当する場合はリンク] アラート： [アラートの通知先 — 例：PagerDuty / Slack #alerts-[service]]

把握しておくべき主なメトリクス：

• エラー率： <[X]% を目安にします（[Y]% でアラート）
• P99 レイテンシ： <[X]ms を目安にします
• [ビジネスメトリクス：] [例：「キューの深さは <100 件を目安にします」]

---

オンコール

オンコールスケジュール： [PagerDuty / Opsgenie のリンク] 現在のオンコール担当者： [現在のスケジュールまたは #oncall チャンネルへのリンク] エスカレーション： [オンコール担当者 → [チームリード] → [EM] — [X] 分間応答がない場合]

ページャー通知を受けた場合：

1. アラートを確認します
2. [ダッシュボードのリンク] を確認し、最初の手がかりを探します
3. よくあるアラートのランブック：[oncall-runbook または runbook-writer の出力へのリンク]
4. [X 分] 以内に解決できない場合は、[担当者／チャンネル] にエスカレーションします

---

主な連絡先

役割	名前	最適な連絡方法
テックリード	[Name]	Slack: @[handle]
オンコールローテーション	[Team]	PagerDuty / #on-call
プラットフォーム／インフラ	[Team]	Slack チャンネル #platform
データベース／DBA	[Name or team]	Slack チャンネル #database
[Upstream service] の担当者	[Name]	Slack: @[handle]

質問する場所：

• エンジニアリング全般：#engineering
• このサービスに関する質問：#[service-name]
• 緊急／本番環境の問題：#incidents

---

トラブルシューティング

「ローカルでサービスが起動しない」

1. Docker／依存関係が実行中か確認します：[command]
2. .env に値が設定されているか確認します。値が不足していると、エラーが表示されずに失敗することがあります
3. ログを確認します：[log command]
4. #[channel] で質問します

「ローカルではテストが失敗するのに、CI では成功する」

• ローカルの依存関係のバージョンが CI と一致しているか確認します：[version check command]
• クリーンインストールを試します：[clean install command]
• インテグレーションテストにはローカルで依存関係を起動しておく必要があります：[start deps command]

「[internal tool / system] にアクセスできない」

• [手続き — 例：Okta のセルフサービスで申請する／マネージャーに依頼する] を通じてアクセスを申請します

"本番環境で何かおかしいようです"

1. [ダッシュボード]でエラーの急増を確認します
2. #deploymentsで最近のデプロイを確認します
3. インシデントが進行中の場合は、[PagerDuty / Slack command]からオンコール担当者に連絡します

---

さらに詳しく

• アーキテクチャ決定記録（ADR） — コードベースが現在の形になっている理由
• API ドキュメントまたは[外部ドキュメントへのリンク]
• インシデント対応手順書
• CI/CD パイプラインのドキュメント
• チームの作業上の取り決め

---

品質チェック

• ローカル環境のセットアップ手順が新しいマシンで機能する — 最近テスト済み
• 環境変数の表が完全かつ正確である
• 「意外な点」に実際に驚くような点が記載されている（最近参加したメンバーに確認する）
• オンコールのセクションにプレースホルダーではなく実際のリンクがある
• 連絡先が最新である — 実際の Slack ハンドルを持つチームメンバーが記載されている
• トラブルシューティングで、新しく参加したメンバーが実際に尋ねる上位3つの質問を扱っている

アンチパターン

• 理想的なセットアップではなく、実際のセットアップを記載してください。実際の特殊な点や注意点こそ、新しいエンジニアが最も必要とする情報です
• 「マネージャーに聞いてください」のようなプレースホルダーの連絡先を残さないでください。分野ごとに具体的な担当者を記載しないと、新しく参加したメンバーが緊急の質問を抱えたときにドキュメントが役に立たなくなります
• 最近参加したメンバーとレビューせずにオンボーディングドキュメントを書かないでください。作成者は、自分が当然だと思っていることに気づけません
• アーキテクチャの詳細をすべて含めないでください。すべてを網羅するオンボーディングドキュメントでは何も学べません。代わりに、より詳しいドキュメントへのリンクを記載してください
• 「意外な点」のセクションを省略しないでください。文書化されていない、すぐには分からないパターンは、最初の週にエンジニアリングの時間を浪費する最大の原因です

トリガーフレーズの例

• 「このサービスの開発者ガイドを書いてください。」
• 「このサービスの README を書いてください。」
• 「新しいエンジニア向けのオンボーディングドキュメントを書いてください。」
• 「新しい開発者にコードベースの概要を説明してください。」