新しいプロジェクトに参加したとき、まずREADMEを読む。
そして数分後、こんな状態になることはないでしょうか。
- このシステムが何をしているかは、なんとなく分かった
- でも、次にどこを読めばいいのか分からない
- いきなりコードを追うのは、正直つらい
結局、詳しい人に聞いたり、過去のPRを眺めたりしながら、
「たぶんここから読めばよさそう」という勘に頼って進めることになります。
最近は、こうした状況でAIにコードを読ませて質問する人も増えてきました。
ただ、何をどう聞けばオンボーディングとして役に立つのかは、意外と難しいものです。
もし、
「このプロジェクトを理解するためのオンボーディング用ドキュメント」が最初から用意されていたらどうでしょうか。
- まず理解すべき業務や用語を整理する
- 次に全体構成や重要なコードの読みどころを把握する
- 最後に、安全に試せる小さな機能追加まで導く
こうした流れを、そのプロジェクト専用のカリキュラムとしてAIに生成させることができれば、
初見のリポジトリでも、キャッチアップの負担は大きく下げられるはずです。
この記事では、
オンボーディングドキュメント生成に特化したプロンプトセット「Jun」と、
それを使うことでどのようなドキュメントが生成できるのか、
そして実際にどう使えばよいのかを紹介します。
1. 従来のオンボーディング、何が大変か
新しいプロジェクトに参加したとき、多くの場合オンボーディングは次のように始まります。
- README を読む
- とりあえずコードを眺める
- 分からないところを人に聞く
これは決して間違ったやり方ではありません。
ただ、実務に入れる状態になるまでに時間がかかりやすいという問題があります。
1.1 「どこから読めばいいのか」が分からない
READMEを読むと、プロジェクトの概要や起動方法は分かります。
しかしその先、
- どの機能が重要なのか
- どのディレクトリから読むべきか
- 自分はまず何を理解すればいいのか
といった 「学習の順番」 は、ほとんど書かれていません。
その結果、
- 初心者には難しすぎるコードから読んでしまう
- 全体像が見えないまま細部に入ってしまう
といった状態に陥りがちです。
1.2 人に依存したオンボーディングになりやすい
分からないことがあれば、詳しい人に聞く。
これはチームとして自然な行動ですが、オンボーディングにおいては問題になることもあります。
- 説明する人によって内容や順番が変わる
- 忙しいと後回しになってしまう
- 「これ前も説明したな…」が何度も発生する
結果として、
- チームリーダーや詳しい人の負荷が高い
- 新しく入った人は、聞くこと自体に気を使う
という構図が生まれます。
1.3 「とりあえず触ってみる」しかなくなる
十分な導線がないままオンボーディングを進めると、
最終的にはこうなりがちです。
「とりあえず動かしてみて、影響が少なそうなところを触ってみる」
このやり方でも学べることはありますが、
- 変更してはいけないところを触ってしまう不安
- プロジェクトのルールを知らないまま実装してしまうリスク
が常につきまといます。
1.4 問題は「情報がない」ことではない
ここまで挙げた問題は、
ドキュメントが足りないから起きているわけではありません。
- README
- 設計資料
- 過去のPR
- ソースコード
情報自体は、すでにプロジェクトの中にあります。
問題なのは、
- 情報が整理されていない
- 学習の順番として提示されていない
- オンボーディング目的でまとめられていない
という点です。
この章で整理したかったのは、
従来のオンボーディングがつらくなりがちな理由は
個人のスキル不足ではなく、構造の問題であるということです。
こうした課題に対して、Junがどんな「新しいオンボーディングの形」を提示するのかを紹介します。
2. 新しいオンボーディングの形：Jun
前章で整理したように、従来のオンボーディングがつらくなりがちな理由は、
「情報がないから」ではなく、情報がオンボーディング向けに整理されていないことにあります。
Junが目指しているのは、この状況を少しだけ変えることです。
2.1 Junがやろうとしていること
Junは、オンボーディングを次のように捉え直します。
- READMEを読んで終わり、ではなく
- コードを闇雲に追うのでもなく
- 「このプロジェクトを理解するための学習ルート」を最初に用意する
具体的には、
- まず何を理解すべきか
- 次にどのコードを読めばよいか
- 最後にどんな変更を試すとよいか
といった流れを、オンボーディング専用のドキュメントとして整理します。
2.2 汎用的な説明ではなく「プロジェクト専用」にする
多くのプロジェクトには、
- 採用している技術スタック
- ディレクトリ構成
- 設計上のルール
- 暗黙の了解
といった、そのプロジェクトならではの前提があります。
Junでは、こうした前提を無視して
「一般的な説明」をするのではなく、
「このプロジェクトでは、どこを理解すれば実務に入れるのか」
という観点でオンボーディングを組み立てます。
そのため、同じ言語・同じフレームワークでも、
プロジェクトが違えば、生成される内容も変わります。
2.3 AIは「考えてもらう相手」として使う
Junは、AIにすべてを任せるツールではありません。
- コードを丸ごと要約する
- 何でも自動で説明させる
といった使い方ではなく、
- オンボーディングとして知りたいことを整理し
- それを適切な問いとしてAIに投げる
そのためのプロンプトセットとして設計されています。
これにより、
- ドメイン理解
- アーキテクチャ把握
- コードリーディング
- 小さな機能追加
といったステップを、一貫した流れとして生成できるようになります。
2.4 Junを使うと何が変わるのか
Junを使うことで、オンボーディングの進め方は次のように変わります。
- 「何から読めばいいか」を考える時間が減る
- 人に聞かなくても進められる範囲が増える
- 安全に手を動かせるポイントが最初から分かる
結果として、
- 新しく入った人は、迷いにくくなる
- チーム側は、毎回同じ説明をしなくてよくなる
といった変化が期待できます。
3. Junで何が生成されるのか（実例）
ここでは、Junで生成される「オンボーディングロードマップ」を紹介します。
前提として、対象プロジェクトはたとえば次のようなものを想定しています。
- チーム向けタスク管理／プロジェクト管理サービスのバックエンドAPI
- タスク、プロジェクト、ユーザー、権限などを扱う
- Go + GraphQL（gqlgen） + クリーンアーキテクチャ + ORM を採用
3.1 生成されるロードマップの全体像（目次イメージ）
Junが生成するロードマップは、
「新しく参加したエンジニアが、短期間で安全に実務に入れる状態になる」ことをゴールに設計されています。
学習内容はフェーズごとに整理され、次のような構成になります。
- Phase 0：環境構築 & プロジェクト全体像の理解
- Phase 1：読めるようになる（主要部分のコードリーディング）
- Phase 2：小さな変更を安全に行えるようになる
- Phase 3：中規模の機能追加やリファクタリングができるようになる
3.2 生成例（抜粋）
以下は、生成されるロードマップを
「目次＋短い説明」レベルに要約したサンプルです
（実際には、各項目にもう少し具体的な指示や参照ファイルが含まれます）。
Phase 0：環境構築 & プロジェクト全体像の理解
ゴール：ローカルでAPIを起動でき、サービスの目的・構造・基本用語を説明できる状態
-
0-1 ローカル開発環境のセットアップ（演習）
Dockerなどを使ってAPIを起動し、GraphQLの動作確認まで行う -
0-2 サービス概要とドメイン知識の把握（読む）
このサービスが解決している課題、主要な概念（タスク／プロジェクト／ユーザー）を理解する -
0-3 ディレクトリ構造とアーキテクチャの把握（読む）
adapter / usecase / domain / infra の役割と依存関係を整理する -
0-4 主要な設定ファイルの理解（読む）
モジュール定義、GraphQL設定、ORM設定、ビルド設定などの役割を押さえる
Phase 1：読めるようになる（主要部分のコードリーディング）
ゴール：APIリクエストからDB操作までの一連の流れを追える状態
-
1-1 GraphQLスキーマの読み方（読む）
Query / Mutation / Type / Input の構造と設計ルールを理解する -
1-2 リゾルバの実装パターン（読む）
リゾルバがユースケースを呼び出す基本構造を把握する -
1-3 ユースケースの実装パターン（読む）
ビジネスロジックの置き場所、エラーハンドリングの型を掴む -
1-4 リポジトリの実装パターン（読む）
ORMを使ったCRUD処理とトランザクション管理を理解する -
1-5 依存性注入（DI）の理解（読む）
各コンポーネントがどのように組み立てられているかを確認する -
1-6 認証・認可とエラーハンドリング（読む）
認可チェックの流れや、APIエラーの返却ルールを理解する -
1-7 テストコードの読み方（読む）
ユニットテストの構造や、モックの使い方を把握する
Phase 2：小さな変更を安全に行えるようになる
ゴール：軽微な修正や改善を、単独で行いテストまで追加できる状態
-
2-1 スキーマにフィールドを追加する（演習）
変更 → コード生成 → 動作確認までを一通り経験する -
2-2 リゾルバの実装（演習）
追加したフィールドをユースケース経由で返す処理を実装する -
2-3 入力バリデーションの追加（演習）
既存ルールに沿ってバリデーションを追加する -
2-4 ユースケースにメソッドを追加する（演習）
設計ルールを守りながら、振る舞いを拡張する -
2-5 ユニットテストの追加（演習）
追加した処理に対してテストを書き、壊していないことを確認する -
2-6 エラーハンドリングの追加（演習）
新しいエラーケースを追加し、APIとして正しく返却する -
2-7 Lint / フォーマットの実行（演習）
コード品質チェックを行い、PRを出せる状態に整える
Phase 3：中規模の機能追加やリファクタリングができるようになる
ゴール：複数レイヤにまたがる変更を、ペアプロで進められる状態
-
3-1 新しい機能のスキーマ設計（演習）
新しいQueryやMutationを設計する -
3-2 新しいユースケースの作成（演習）
責務を意識して、新しいユースケースを追加する -
3-3 リポジトリI/Fと実装の追加（演習）
domainとinfraの境界を守りながら永続化処理を追加する -
3-4 DI設定の更新（演習）
依存関係を更新し、アプリケーションを再構成する -
3-5 複合機能のコードリーディング（読む）
例：タスク更新に伴う通知処理など、複数処理が絡むフローを追う -
3-6 E2Eテストの理解と追加（演習）
API全体を通したテストの考え方を理解する -
3-7 リファクタリング課題（読む／検討）
大きくなったユースケースをどう分割するかを考える
3.3 生成物が「オンボーディング向け」になる工夫
生成されるロードマップには、
そのプロジェクト特有の「つまずきやすいポイント」も併記されます。
たとえば、
- 自動生成されたコードは直接編集しない
- リゾルバから直接DB操作を行わず、必ずユースケースを経由する
- 読み取り処理と更新処理でトランザクションを使い分ける
- 内部IDと外部公開IDを混同しない
- ドメインモデルと永続化モデルは別物として扱う
といった、READMEには書かれにくい実務上のルールが最初から見える形になります。
この章で伝えたかったのは、
Junが生成するロードマップが単なる「学習リスト」ではなく、
- どこから始めればよいか迷わない
- 読むだけで終わらず、手を動かすところまで導かれる
- プロジェクト固有のルールを踏まえて、安全に実務へ入れる
そんなオンボーディング専用の道筋として整理されている、という点です。
4. Junの使い方
Junは、オンボーディングドキュメントを生成するためのプロンプトセットです。
自分が普段使っている生成AIにプロンプトを渡して使うことを前提としています。
ここでは、Claude Code を使う場合を例に説明します。
Cursor や Windsurf など、他のエディタを使っている場合も、
同じプロンプトをカスタムコマンドとして登録すれば、同様の流れで利用できます。
4.1 Claude Code へのセットアップ
Claude Code を使っている場合は、以下のコマンドで Jun のカスタムコマンドを追加できます。
npx @basio0916/jun
これにより、Jun のプロンプトがカスタムコマンドとして登録され、
以降は /jun:xxx という形式で呼び出せるようになります。
4.2 Junを使ったオンボーディング生成の流れ
Junでは、オンボーディングを以下の3ステップで進めます。
1. プロジェクトを解析する（/jun:steering）
/jun:steering
このステップでは、プロジェクト全体を俯瞰し、
- どのようなドメインを扱っているのか
- 全体構成や主要な役割は何か
- オンボーディングで押さえるべきポイントはどこか
といった情報を整理します。
2. 学習ロードマップを作成する（/jun:roadmap）
/jun:roadmap
次に、解析結果をもとに、
「どの順番で理解していくとよいか」という学習ロードマップを作成します。
- 何から学ぶべきか
- どこまで理解すれば次に進めるか
- コードを読む前に知っておくべきことは何か
といった点が整理され、オンボーディングの全体像が見えるようになります。
3. 各カリキュラムを生成する（/jun:curriculum）
/jun:curriculum <TaskID> or <PhaseID>
最後に、ロードマップに沿って、
各ステップごとのオンボーディング用カリキュラムドキュメントを生成します。
このコマンドを実行すると、
jun/curriculum 配下に、ドメイン理解、構成把握、コードリーディング、機能追加など、オンボーディングに必要なドキュメントがまとめて生成されます。
4.3 使用するモデルについて
Claude以外も含めていくつかのモデルで試しましたが、
個人的にはOpus 4.5が最も安定して、実用的なアウトプットを生成できると感じています。
特に、
- ドメイン理解の整理
- コード構成の説明
- 学習順序の妥当性
といった点で、オンボーディング用途との相性が良い印象です。
ただし、トークンを結構消費するのでMaxプラン推奨です。
CursorやWindsurfはリクエスト回数制なので、そちらでOpus 4.5を使うのが個人的にはおすすめです。
5. どんな人・チームに向いているか
Junは「オンボーディングを速くする魔法のツール」というより、
オンボーディングを「再現可能な手順」に落とし込むためのプロンプトセットです。
そのため、特に相性が良いケース／そうでもないケースがあります。
5.1 向いているチーム
-
新しいメンバーが定期的に入ってくるチーム
毎回ゼロから説明する負担を減らせます。オンボーディングの品質もブレにくくなります。 -
オンボーディングが属人化しているチーム
「あの人に聞かないと分からない」を減らし、学習ルートをチーム資産として残しやすくなります。 -
リモート中心で、口頭説明が難しいチーム
「まずこれを読んで進めてください」という導線を作れるので、同期コミュニケーションへの依存を減らせます。 -
ドキュメントはあるが、散らばっているチーム
README・設計資料・コード・PRなどを“オンボーディング目的”で再構成しやすいです。
5.2 向いている個人エンジニア
-
初見のリポジトリで、どこから読めばいいか迷いがちな人
学習順序（地図）があるだけで、読み進め方がかなり楽になります。 -
いきなり大きな変更をするのが怖い人
「安全に試せる小さな変更」まで導線があると、最初の一歩を踏み出しやすくなります。 -
一般的な解説と、実際のプロジェクトとの差に戸惑いやすい人
「教科書的にはこうだが、このプロジェクトではこうする」という前提が整理されていると、理解がスムーズになります。
5.3 向いていない（効果が出にくい）ケース
-
設計が崩壊していて、コードから意図を読み取るのが難しいプロジェクト
責務が混ざっていたり、一貫した構造がない場合、オンボーディングとして整理すること自体が難しくなります。 -
機密情報をAIに入力できないルールの組織
Jun自体はプロンプトですが、実行にはコードや仕様をAIに渡す必要があります。
その場合は、社内ルールに沿った運用（入力範囲の制限、ローカルLLM利用など）が前提になります。 -
すでにオンボーディングが成熟していて、教材が整備されているチーム
既存教材の方が高品質なことも多いので、Junは「補助」や「更新の叩き台」として使うのが向いています。
6. まとめ：まずは「学習ルート」を作ってみる
オンボーディングがつらくなりがちな理由は、情報が足りないからではなく、
情報が「オンボーディング向け」に整理されていないことにありました。
Junは、その整理をAIに手伝ってもらいながら、
- まず何を理解すべきか
- 次にどこを読めばよいか
- 最後にどんな変更を試せばよいか
という学習ルート（ロードマップ）を、プロジェクト専用に組み立てるためのプロンプトセットです。
まず試すなら、この順番がおすすめです
-
/jun:steeringでプロジェクトの全体像を整理する -
/jun:roadmapで学習ロードマップを作る - ロードマップの中から、まずは1つだけ
/jun:curriculumで生成して手を動かす- 例：Phase 0 の環境構築、または Phase 2 の小さな変更タスク
「これなら進められそう」という手応えが出たら、範囲を少しずつ広げていくのがスムーズです。
フィードバック歓迎です
Junはまだ発展途上です。
「この章が分かりづらい」「この観点が足りない」など、改善のヒントがあればぜひ教えてください。
オンボーディングの最初のつまずきを、少しでも減らす助けになればうれしいです。