codebase-onboarding

コードベースのオンボーディング

あらゆるコードベースを分析し、対象者に合わせた本番品質のオンボーディングドキュメントを生成します。システム図を含むアーキテクチャ概要、主要ファイルに注釈を付けたマップ、ローカル環境の段階的なセットアップガイド、一般的な開発タスクの手順書、実際のエラー解決策を含むデバッグガイド、コントリビューションガイドラインを作成します。Markdown、Notion、Confluence の出力形式に対応しています。

主な機能

• アーキテクチャ分析 — マニフェストやロックファイルから技術スタックを特定し、システム境界のマッピング、Mermaid によるデータフロー図、依存関係グラフ、モジュールの担当範囲を作成します。
• 主要ファイルへの注釈 — 最も重要な20個のファイルとその重要性を示し、エントリーポイント、設定の中核、共有ユーティリティ、調整なしに変更すると危険なファイルを明記します。
• セットアップガイドの生成 — 正確なバージョンを記載した前提条件、git clone からテストまでの手順、環境変数の説明、インフラのセットアップ（Docker／DB／キャッシュ）、確認チェックリストを含みます。
• タスク手順書 — API エンドポイントの追加、テストの実行・作成、マイグレーションの作成・適用、ステージング環境／本番環境へのデプロイ、依存関係の安全な追加を扱います。
• デバッグガイド — よくあるエラーの正確なメッセージと解決策、環境ごとのログの場所、診断用の SQL／CLI クエリ、本番環境の問題をローカルで再現する方法を含みます。
• 対象者に合わせた出力 — ジュニア開発者、シニアエンジニア、コントラクター向けに内容を調整します。Markdown／Notion／Confluence 形式に対応しています。

キーワード： コードベースのオンボーディング、開発者エクスペリエンス、ドキュメント、アーキテクチャ概要、セットアップガイド、デバッグガイド、コントリビューションガイドライン、コードの解説、新入社員のオンボーディング

使用する場面

• 新しいチームメンバー（ジュニア、シニア、コントラクター）のオンボーディング
• 大規模なリファクタリング後に既存のドキュメントが古くなったとき
• プロジェクトをオープンソース化する前
• 担当サービスのチーム Wiki ページを作成するとき
• 長期休暇やチームの引き継ぎに備えて、ドキュメントを整備するとき
• ドキュメントが必要なコンプライアンス監査に備えるとき

まず確認すること

ドキュメントを生成する前に、次の入力内容を確認してください。不明または曖昧な項目があれば、推測せずに質問してください。

• 対象コードベースのパス — 分析するプロジェクト（3つのスクリプトすべてがスキャンする対象）
• 対象者 — ジュニア開発者、シニアエンジニア、コントラクターのいずれか（表示するセクションと詳しさを調整します）
• 出力形式 — Markdown、Notion、Confluence のいずれか（生成するドキュメントの形式を指定します）

停止ルール：出力を最も大きく左右する2～3項目だけを質問してください。ユーザーが「とりあえず草案を作って」と言った場合は、そのまま進め、成果物の冒頭に前提条件を記載してください。

ツール

ツール	用途	コマンド
architecture_mapper.py	プロジェクト構造を分析し、概要レベルのアーキテクチャマップを生成します	python scripts/architecture_mapper.py /path/to/project --json
onboarding_generator.py	プロジェクトディレクトリをスキャンし、オンボーディングガイドを生成します	python scripts/onboarding_generator.py /path/to/project --json
setup_validator.py	プロジェクトの開発環境セットアップがどの程度整っているかを検証します	python scripts/setup_validator.py /path/to/project --json

すべてのツールは、省略可能な directory 引数（デフォルトは現在のディレクトリ）と、機械可読な出力を指定する --json を受け付けます。

参考資料

タスクに合った参考資料を読み込み、ファイルは簡潔に保ち、必要に応じて詳細を参照してください。

• references/fact-gathering-and-patterns.md — Phase 1 の事実収集用シェルコマンドと、Phase 2 のアーキテクチャパターン分類表が記載されています。ドキュメント作成前にコードベースを分析するときに参照してください。
• references/documentation-templates.md — アーキテクチャ概要、主要ファイルマップ、ローカル環境のセットアップ、デバッグガイドのテンプレートに加え、対象者別（ジュニア／シニア／コントラクター）の追加項目が記載されています。オンボーディングドキュメントを実際に作成するときに参照してください。
• references/quality-and-best-practices.md — 品質確認チェックリスト、よくある落とし穴、ベストプラクティス、トラブルシューティングマトリックス、成功基準が記載されています。オンボーディングドキュメントを公開する前に参照してください。

対象範囲と制限事項

このスキルの対象範囲：

• コードベースの分析に基づく、アーキテクチャ概要、主要ファイルマップ、セットアップガイド、タスク別手順書、デバッグガイドの作成
• ジュニア開発者、シニアエンジニア、コントラクター向けに調整した、対象者に応じたドキュメント
• Markdown、Notion、Confluence 形式での出力
• 品質確認チェックリストと鮮度監査プロセス

このスキルの対象外：

• コードアノテーションからの API リファレンスの自動生成 — リリース関連ドキュメントについては engineering/changelog-generator を、API 品質については engineering/api-design-reviewer を参照してください
• 継続的なドキュメントパイプラインや CI によって実行されるドキュメントビルド — パイプラインの自動化については engineering/ci-cd-pipeline-builder を参照してください
• 脅威モデルやアクセス制御マトリックスなど、セキュリティに特化したドキュメント — セキュリティ監査については engineering/skill-security-auditor を参照してください
• インシデント対応や本番運用向けの手順書の作成 — 運用手順書については engineering/runbook-generator を参照してください

統合ポイント

スキル	統合	データフロー
engineering/runbook-generator	オンボーディング用のタスク別手順書は、本番インシデント対応向けの運用手順書の土台になります	オンボーディング手順書のテンプレート → 運用レベルへの拡充のために Runbook Generator へ
engineering/api-design-reviewer	Phase 1 での API ルート分析は、API 設計品質レビューに活用できます	発見された API エンドポイント → 一貫性確認のために API Design Reviewer へ
engineering/database-schema-designer	主要ファイルのマッピング時に特定されたデータベーススキーマファイルは、スキーマ設計レビューに役立ちます	スキーマファイルのパスと ORM の型 → マイグレーション計画のために Schema Designer へ
engineering/tech-debt-tracker	アーキテクチャ分析で見つかった技術的負債は、追跡できるよう記録してください	アーキテクチャ分析の結果 → Tech Debt Tracker のバックログ項目へ
engineering/ci-cd-pipeline-builder	Phase 1 で見つかった CI/CD 設定は、パイプラインビルダーで検証・改善できます	CI 設定のパスとワークフローの一覧 → 最適化のために Pipeline Builder へ
engineering/dependency-auditor	Phase 1 で収集した依存関係の数とロックファイルは、セキュリティ監査とライセンス監査に直接活用できます	パッケージマニフェストとロックファイル → 脆弱性スキャンのために Dependency Auditor へ