onboarding

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

リポジトリをクロールし、リポジトリのルートに ONBOARDING.md を生成します。作成者に説明してもらわなくても、新しいコントリビューターがコードベースを理解できるようにするドキュメントです。

オンボーディングはソフトウェア全般に関わる課題ですが、コードがドキュメントよりも速く書かれる、動きの速いコードベースでは特に深刻です。AI を活用した開発、迅速なプロトタイピング、あるいはドキュメントを書くよりも速くリリースするチームなど、さまざまなケースが当てはまります。このスキルでは、コードそのものからメンタルモデルを再構築します。

このスキルは、ドキュメントを毎回ゼロから生成します。以前のバージョンを読み込んだり、差分を取ったりはしません。すでに ONBOARDING.md が存在する場合は、上書きします。

基本原則

1. まず人間向けに書く — 新しい開発者が読んで理解できる、明確な文章にします。エージェントにとっての使いやすさは、優れた人間向けの文章を書くことによる副次的な効果であり、別の目標ではありません。
2. 説明するだけでなく、見せる — アーキテクチャやフローには ASCII 図を使い、構造化された情報には Markdown の表を使います。また、ファイルパス、コマンド、コードへの参照はすべてバッククォートで囲みます。
3. 6 つのセクションには、それぞれ存在意義を持たせる — 各セクションは、新しいコントリビューターが最初の 1 時間に抱く疑問に答えるものとします。推測に基づくセクションは作りません。利用者がいない純粋なインフラストラクチャの場合、セクション 2 は省略でき、その場合は 5 つのセクションになります。
4. 推測せず、確認できる事実を述べる — 設計上の理由を捏造したり、脆弱性を評価したりしないでください。コードから判断できない理由について、憶測してはいけません。
5. 秘密情報を絶対に含めない — オンボーディングドキュメントはリポジトリにコミットされます。API キー、トークン、パスワード、認証情報を含む接続文字列、その他の秘密の値を絶対に含めないでください。環境変数は値ではなく、名前（STRIPE_SECRET_KEY）を記載します。.env ファイルに実際の秘密情報が含まれている場合は、変数名だけを取り出します。
6. 重複させず、リンクする — 既存のドキュメントで十分に説明されているトピックについては、再説明するのではなく、文中にリンクを記載します。

実行フロー

フェーズ 1：インベントリの収集

バンドルされているインベントリスクリプト（scripts/inventory.mjs）を実行し、すべてのファイルを読むことなく、リポジトリの構造を把握します。

node scripts/inventory.mjs --root .

JSON 出力を解析します。出力には次の情報が含まれます。

• プロジェクト名、言語、フレームワーク、パッケージマネージャー、テストフレームワーク
• ディレクトリ構造（トップレベル、およびソースディレクトリ内の 1 階層）
• 検出されたエコシステムごとのエントリーポイント
• 利用可能なスクリプト／コマンド
• 既存のドキュメントファイル（優先順位を付けるための先頭の見出しタイトルを含む）
• テストインフラストラクチャ
• インフラストラクチャと外部依存関係（環境ファイル、Docker サービス、検出された統合）
• モノレポの構造（該当する場合）

スクリプトが失敗するか、エラーフィールドを返した場合は、問題をユーザーに報告して停止します。不完全なデータに基づいて ONBOARDING.md を作成しようとしてはいけません。

フェーズ 2：主要なファイルを読む

インベントリを参考に、コードベースの理解に不可欠なファイルを読みます。シェルコマンドではなく、標準のファイル読み取りツールを使用してください。

何を、なぜ読むか：

相互に依存しないファイルは、並列のバッチで読みます。たとえば、README.md、エントリーポイント、AGENTS.md／CLAUDE.md は互いの内容に依存しないため、同じターンでまとめて読みます。

具体的で詳細な情報を盛り込んだ6つのセクションを書くために必要なファイルだけを読みます。インベントリには、構造、言語、フレームワーク、スクリプト、エントリーポイントのパスがすでに記載されています。インベントリにある情報を確認するだけのために、ファイルを読み直す必要はありません。必要なファイル数はリポジトリによって異なります。小規模な CLI ツールなら4ファイル、複雑なモノレポなら20ファイルかもしれません。恣意的な数ではなく、各セクションの内容に基づいて読むファイルを決めてください。

優先順位：

1. README.md（存在する場合）— プロジェクトの目的とセットアップ手順を把握するため
2. 主要なエントリーポイント — インベントリの entryPoints に記載されたファイルです。アプリケーションの起動時の動作がわかります。
3. ルート／コントローラーファイル — インベントリの構造にある routes/、app/controllers/、src/routes/、src/api/ などのディレクトリを探します。主要な処理の流れを理解するため、メインのルートファイルを読みます。
4. アーキテクチャや外部依存関係がわかる設定ファイル — docker-compose.yml、.env.example、.env.sample、データベース設定、next.config.*、vite.config.* などです。インベントリに存在する場合に限り読みます。.env 自体は絶対に読まないでください。読み取り可能なのは .env.example または .env.sample のテンプレートのみです。変数名だけを抽出し、値は取得しないでください。
5. AGENTS.md または CLAUDE.md（存在する場合）— すでに文書化されているプロジェクトの規約やパターンを把握するため
6. 見つかったドキュメント — インベントリの docs リストには、各ファイルのタイトル（最初の見出し）が含まれています。まずタイトルを参考に、5つのセクションに関連するドキュメントを判断します。タイトルから直接関連するとわかるドキュメントだけ、全文を読みます。フォーカスのヒントで特に指定されていない限り、日付入りのブレインストーミングや計画ファイルは読み飛ばしてください。

推測でファイルを読まないでください。読むファイルはすべて、インベントリの内容を根拠とし、必要とするセクションとの関連が明確でなければなりません。

フェーズ 3：ONBOARDING.md を作成する

インベントリデータと主要ファイルの内容を、以下のセクションにまとめます。ファイルはリポジトリのルートに作成してください。

タイトル：ドキュメントの見出しには # {Project Name} Onboarding Guide を使用します。インベントリからプロジェクト名を取得してください。ファイル名を見出しにしないでください。

文体 -- 生成されたドキュメントのようではなく、プロジェクトに詳しいチームメイトがコーヒーを飲みながら説明するような文章にしてください。

声とトーン：

• 2人称（「あなた」）で書き、新しいコントリビューターに直接話しかけてください
• 能動態と現在形を使ってください。「ルーターがリクエストをハンドラーに振り分けます」のように書き、「リクエストはルーターによってハンドラーに振り分けられます」とは書かないでください
• 率直に書いてください。前置きではなく、重要なことから文を始めます。「サーバーを起動するには、bun dev を実行してください」ではなく、「bun dev を実行してサーバーを起動してください」と書いてください
• コードベースの形式に合わせてください。簡易的なプロトタイプならくだけた文章にし、エンタープライズシステムならより正確な表現にします。README と既存のドキュメントからトーンの手がかりを得てください

明確さ：

• 各文で読者に何かを教えるか、何をすべきかを伝えてください。どちらにも当てはまらない文は削除してください
• 抽象的な表現より具体的な表現を優先してください。「課金モジュールは決済関連のビジネスロジックを処理します」ではなく、「src/services/billing.ts は顧客のカードに請求します」と書いてください
• 用語を導入するときは、その場で文脈に沿って定義してください。用語集までスクロールさせないでください
• 正確さを保てる範囲で、最も簡単な語を使ってください。「utilize」ではなく「use」、「initialize」ではなく「start」、「transmit」ではなく「send」を使います

避けること：

• 内容のない前置きや言いよどみ：「注目すべきなのは」「前述のとおり」「このセクションでは」
• 曖昧な要約：「このモジュールはさまざまな機能を処理します」ではなく、具体的な処理内容を書いてください
• 事実を述べるときの曖昧な表現：「本質的には」「基本的には」。機能が分かっているなら、はっきり書いてください
• 最上級の表現や宣伝文句：「堅牢な」「強力な」「包括的な」「シームレスな」
• ドキュメント自体についてのメタ的な説明：「このドキュメントでは～を目的としています」ではなく、実際の内容を書いてください

書式要件 -- 全体を通して一貫して適用してください：

• すべてのファイル名（package.json）、パス（src/routes/）、コマンド（bun test）、関数名／クラス名、環境変数、技術用語にはバッククォートを使ってください
• 各セクションには Markdown の見出し（##）を使ってください
• 指定された箇所には ASCII 図と Markdown テーブルを使ってください
• 強調の太字は必要最小限にしてください
• 段落は短くし、2～4文にしてください

セクションの区切り -- 各 ## セクションの間に水平線（---）を入れてください。これらのドキュメントは情報量が多いため、区切りを明確にすると流し読みしやすくなります。

コードブロックの幅制限 -- 最大80列。 Markdown のコードブロックは white-space: pre で表示され、折り返されません。長い行があると、GitHub、タブレット、幅の狭い画面で横スクロールが発生します。次のルールを、すべての ``` フェンス内の内容に適用してください。

• ASCII アーキテクチャ図：ボックスは横並びではなく、縦に配置してください。同じ行に置くボックスは2つまでとし、各ボックスのラベルは20文字未満にしてください。これにより、図の幅は約60文字以内になります。
• フロー図：ファイルパスと注釈を合わせて80文字未満にしてください。説明が長すぎる場合は、次の行に移すか短くしてください。
• ディレクトリツリー：インラインの # コメント は30文字未満にしてください。網羅的な一覧（「マーク、ヒートマップ、提案、共同編集カーソルなど」）ではなく、簡潔な役割の説明（「エディタープラグイン」）を優先してください。

セクション 1：これは何ですか？

回答：このプロジェクトは何をするもので、誰を対象とし、どのような問題を解決しますか？

README.md、マニフェストの説明（例：package.json の description フィールド）、エントリーポイントから分かるアプリケーションの目的を参考にしてください。

コードからプロジェクトの目的を明確に判断できない場合は、その旨を明記してください：「このプロジェクトの目的は文書化されていません。コード構造から判断すると、……のようです。」

1～3段落にまとめてください。

セクション 2：どのように使われますか？

回答：このプロジェクトを利用する側から見ると、どのようなものですか？

コントリビューターがアーキテクチャについて考える前に、まずプロジェクトが外部から見て「何をするのか」を理解する必要があります。このセクションでは、「これは何か」（セクション 1）と「どのように構築されているか」（セクション 3）をつなぎます。このセクションの対象読者は、ドキュメントのほかの部分と同様、チームに加わったばかりの開発者です。後のセクションで扱うアーキテクチャやコードの流れを直感的に理解できるよう、利用者の視点から見た製品の姿を示すことが目的です。

プロジェクトを利用する人に応じて、出力するセクションのタイトルを選んでください。

• エンドユーザー向け製品（ウェブアプリ、モバイルアプリ、一般ユーザー向けツール）――タイトル：「ユーザー体験」。ユーザーに表示される内容と主なワークフローを説明してください（例：「登録し、プロジェクトを作成し、共同作業者を招待して、リアルタイムの更新を確認する」）。ルート、エントリーポイント、READMEを参考にしてください。
• 開発者向けツール（SDK、ライブラリ、開発者向け CLI、フレームワーク）――タイトル：「開発者体験」。開発者がこのツールをどのように利用するかを説明してください。インストール方法、主要な API を示す最小限の使用例、最も一般的なコマンドやパターンを 2～3 個含めてください。これはセクション 6（開発者ガイド）とは異なります。セクション 6 では このコードベースへの貢献 を扱い、このセクションではコードベースが生成するものの 利用方法 を扱います。
• 両方（利用者向け製品と開発者向け API／SDK を備えたプラットフォーム）――タイトル：「ユーザーおよび開発者体験」。エンドユーザーの体験から始め、その後に開発者向けの機能を説明してください。

各対象者につき、1～3段落または短いフローにまとめてください。包括的なユーザー向けまたは開発者向けドキュメントがある場合は、そのドキュメントへのリンクを記載し、主なワークフローをそれぞれ 1 文で要約してください。既存のドキュメントと内容を重複させないでください。

利用者が存在しないコードベース（純粋なインフラストラクチャや、直接操作を伴わない内部デプロイツールなど）に限り、このセクションを省略してください。

---

セクション 3：どのように構成されていますか？

回答：アーキテクチャはどのようになっているか、主要なモジュールは何か、それらはどのようにつながっているか、またシステムは外部で何に依存しているかを説明します。

このセクションでは、内部構造とシステム境界の両方、つまりアプリケーションが外部とどのようにやり取りするかを扱います。

システムアーキテクチャ -- 新しいコントリビューターに役立つ図には 2 種類あり、どちらか一方、または両方を使うかはシステムの複雑さによって決まります。

1. アーキテクチャ図 -- コンポーネント、それらのつながり方、使用するプロトコルやトランスポートを示します。開発者は、コードがどこにあり、各要素がどのようにやり取りするかを理解するためにこの図を見ます。エッジには、やり取りの種類（HTTP、WebSocket、ブリッジ、キューなど）をラベルとして付けます。上部にユーザー向けの画面、中間に内部処理、下部にデータストアと外部サービスを配置します。

2. ユーザー操作フロー -- ユーザーが製品を利用する際の論理的な流れを示します。インフラストラクチャではなく、ユーザーの視点から見た一連の操作と、それに対するシステムの動作を示します。

どちらか一方を使うか、両方を使うか：

• 単純なシステム（単一の Web アプリ、CLI ツール、シンプルな API）では、アーキテクチャ図だけでユーザーの体験も伝わるため、図は 1 つで十分です。コンポーネントを通るリクエストの経路が、そのままユーザーフローになります。
• 複数の画面を持つ製品（ネイティブアプリ + Web + API など）や、明確に異なる複数のユーザータイプがあるシステムでは、両方を含めます。アーキテクチャ図は各要素のつながり方を開発者に示し、ユーザー操作フローは各要素を通じた製品の論理的な利用体験を示します。これは、同じシステムを異なる視点から見たものです。

図が 80 列を超えないよう、縦に配置します。

アーキテクチャ図の例：

       User / Browser
            |
            |  HTTP / WebSocket
            v
+------------------+    bridge    +------------------+
| Browser Client   |<----------->| Native macOS App |
| (Vite bundle)    |             | (Swift/WKWebView)|
+--------+---------+             +--------+---------+
         |                                |
         |  WebSocket                     |  bridge
         v                               v
+------------------------------------------+
|            Express Server                |
|  routes -> services -> models            |
+--------------------+---------------------+
                     |
                     |  SQL / Yjs sync
                     v
              +--------------+
              | SQLite + Yjs |
              +--------------+

ユーザー操作フローの例（同じシステムを別の視点から見たもの）：

User opens app
  |
  v
Writes/edits document
  (Milkdown editor)
  |
  v
Changes sync in real-time
  (Yjs CRDT)
  |                \
  v                 v
Document persists   Other connected
  to SQLite         clients see edits
  |
  v
User shares doc
  -> generates link
  |
  v
Recipient opens
  in browser client

単純なプロジェクト（単一目的のライブラリ、CLI ツールなど）では、ディレクトリツリーだけで全体像がわかるため、両方とも省略します。

内部構造 -- 上位レベルのレイアウトを示す ASCII ディレクトリツリーを含めます。

project-name/
  src/
    routes/       # HTTP route handlers
    services/     # Business logic
    models/       # Data layer
  tests/          # Test suite
  config/         # Environment and app configuration

各ディレクトリには、役割を説明する簡潔なコメントを付けます。重要なディレクトリのみを含め、ビルド成果物、設定ファイル、定型的なファイルは省略します。

明確な役割を持つ個別のモジュールやコンポーネントがある場合は、表にまとめます。

| Module | Responsibility |
|--------|---------------|
| `src/routes/` | HTTP request handling and routing |
| `src/services/` | Core business logic |
| `src/models/` | Database models and queries |

モジュール間のつながり、つまり何が何を呼び出し、どこでデータがやり取りされるかを説明します。

外部依存関係とインテグレーション -- システムが自身のコードベースの外部とやり取りするものをすべて明らかにします。プロジェクトの実行を試みる新しいコントリビューターにとって、これが最大の障害になることがよくあります。次の箇所に手がかりがないか確認します。

• docker-compose.yml（データベース、キャッシュ、メッセージキュー）
• 設定ファイルや .env.example 内の環境変数の参照
• クライアントライブラリのインポート文（データベースドライバー、API SDK、クラウドストレージ）
• インベントリで検出されたフレームワーク（例：Prisma はデータベースの利用を示します）

依存関係が複数ある場合は、表にまとめます。

| Dependency | What it's used for | Configured via |
|-----------|-------------------|---------------|
| PostgreSQL | Primary data store | `DATABASE_URL` |
| Redis | Session cache and job queue | `REDIS_URL` |
| Stripe API | Payment processing | `STRIPE_SECRET_KEY` |
| S3 | File uploads | `AWS_*` env vars |

外部依存関係が検出されない場合は、「このプロジェクトは自己完結型であり、外部サービスへの依存関係はないようです」と明記します。

セクション 4：主要な概念と抽象化

回答：このコードベースについて話すために、どのような用語やパターンを理解する必要がありますか？

このセクションでは、次の 2 つを扱います。

ドメイン用語 -- プロジェクト固有の用語です。エンティティ名、API リソース名、データベーステーブル、設定に関する概念、新しい読者がすぐには理解できない専門用語などが含まれます。

アーキテクチャ上の抽象化 -- コードの構成方法や、コントリビューターが変更を加える際の考え方を形作る、コードベースの構造的なパターンです。元の作者がこれらのパターンを意識して選んだとは限らず、AI によって導入されたり、ドキュメントがないままテンプレートから採用されたりしているコードベースでは、特に重要です。

取り上げる価値のあるアーキテクチャ上の抽象化の例：

• 「ビジネスロジックはルートハンドラーではなく、サービスレイヤー（src/services/）にあります」
• 「認証は、保護された各ルートの前に src/middleware/auth.ts のミドルウェアを介して実行されます」
• 「データベースアクセスにはリポジトリパターンを使用しており、各モデルに対応するリポジトリクラスがあります」
• 「バックグラウンドジョブは src/jobs/ で定義され、Redis を利用したキューを通じてディスパッチされます」

ドメイン用語と抽象化は、次の単一の表にまとめてください。

| Concept | What it means in this codebase |
|---------|-------------------------------|
| `Widget` | The primary entity users create and manage |
| `Pipeline` | A sequence of processing steps applied to incoming data |
| Service layer | Business logic in `src/services/`, not handlers |
| Middleware chain | Requests flow through `src/middleware/` first |

項目数は 5〜15 個を目安にしてください。新しい読者が戸惑う概念や、直感的にはわからないアーキテクチャ上の判断のみを含めてください。誰もが理解できる用語は省略してください。

セクション 5：主要なフロー

回答：このアプリが行う主な処理は、実際にどのように進みますか？

異なるサーフェスまたはユーザータイプごとに 1 つのフローをたどってください。「サーフェス」とは、システムへの入り口となる、意味のある違いがある経路のことです。ネイティブアプリ、ウェブ UI、API の利用者、CLI ユーザーなどが該当します。各フローでは、それまでのフローで触れていないアーキテクチャの部分を明らかにしてください。次のフローがすでに示したファイルをほぼなぞるだけになる場合は、そこで終了してください。

シンプルなライブラリや CLI なら、フローは 1 つです。ウェブ UI と API を備えたフルスタックアプリなら、2 つです。ネイティブ、ウェブ、エージェントの各サーフェスを備えた製品なら、3 つです。恣意的な数ではなく、アーキテクチャに基づいて数を決めてください。

最も重要なフローを ASCII フロー図で示してください。

User Request
  |
  v
src/routes/widgets.ts
  validates input, extracts params
  |
  v
src/services/widget.ts
  applies business rules, calls DB
  |
  v
src/models/widget.ts
  persists to PostgreSQL
  |
  v
Response (201 Created)

各ステップでは、具体的なファイルパスを示してください。ファイルパスと注釈は 80 文字未満に収めてください。必要であれば、上記の例のように注釈を次の行に記載してください。

最初の図で構造上のパターンがすでに示されている場合、追加のフローは図ではなく番号付きリストで示してもかまいません。

セクション 6: 開発者ガイド

回答: プロジェクトのセットアップ方法、実行方法、よくある変更の行い方は？

以下の領域をカバーします:

1. セットアップ -- 前提条件、インストール手順、環境設定。README とインベントリのスクリプトから引用します。コマンドはコードブロックで整形します:

   bun install
   cp .env.example .env
   bun dev
   

2. 実行とテスト -- 開発サーバーの起動方法、テストの実行方法、リントの方法。インベントリで検出されたスクリプトを使用します。

3. よくある変更パターン -- 最も一般的な 2〜3 種類の変更について、どこを触ればよいか。例:

   • 「新しい API エンドポイントを追加するには、src/routes/ にルートハンドラーを作成し、src/routes/index.ts に登録します」
   • 「新しいデータベースモデルを追加するには、src/models/ にファイルを作成し、bun migrate を実行します」

4. まず読むべき主要ファイル (複雑なプロジェクト向け) -- コードベースの領域を具体的なエントリポイントファイルに対応付け、「なぜここから読むのか」の簡単なメモを添えた表。これにより、新しいコントリビューターは大きなディレクトリツリーを眺める代わりに、具体的な読書リストを得られます。例:

   | Area | File | Why |
   |------|------|-----|
   | Editor core | `src/editor/index.ts` | All editor wiring |
   | Data model | `src/formats/marks.ts` | The annotation system everything builds on |
   | Server entry | `server/index.ts` | Express app setup and route mounting |
   

   ソースファイルがおよそ 10 個未満のプロジェクトでは、ディレクトリツリー自体が十分な読書リストになるため、これは省略してください。

5. 実践的なヒント (複雑なプロジェクト向け) -- コードベースに特に大きく複雑な領域や、自明ではない落とし穴がある場合は、簡潔なコントリビューター向けヒントとして提示します。これらは、新しいコントリビューターが落とし穴を避けるのに役立つ、実際の状況認識を伝えます。例:

   • 「エディターモジュールは約 450KB あります。ほとんどの動作は src/editor/plugins/ のプラグインを通じて組み込まれています -- エディターを変更する前にプラグインアーキテクチャを理解してください。」
   • 「コラボサブシステムには多くのガードとエポックチェックがあります。どのような不変条件が維持されているかを理解するには、テスト名を読んでください。」

   コードベースが小さいため頭に入るようなシンプルなプロジェクトでは、これは省略してください。

インラインドキュメントリンク

各セクションを書く際に、インベントリの docs リストにあるファイルが、そのセクションで説明する内容に直接関連しているかどうかを確認します。関連している場合は、インラインでリンクします:

認証はトークンベースのミドルウェアを使用しています -- 完全なパターンについては docs/solutions/auth-pattern.md を参照してください。

参照や参考資料の独立したセクションは作成しないでください。そのセクションに関連するドキュメントが存在しない場合は、そのセクションは単独で成立させます -- 存在しないことには言及しないでください。

フェーズ 4：品質チェック

ファイルを書き込む前に、次の点を確認します。

• 各セクションが、冗長な説明や埋め草を加えずに質問に答えている
• ドキュメント内のどこにも、シークレット、API キー、トークン、パスワード、認証情報の値が含まれていない
• 作り上げた設計上の理由（「X を選んだ理由は……」など）が含まれていない
• 脆弱性やリスクの評価が含まれていない
• ドキュメント内で参照されているファイルパスが、インベントリにある実在のファイルと一致している
• すべてのファイル名、パス、コマンド、コード参照、技術用語がバッククォートで囲まれている
• ドキュメントのタイトルが「# {Project Name} Onboarding Guide」形式であり、ファイル名ではない
• 複数のサーフェスを持つプロジェクトには、システムレベルのアーキテクチャ図が含まれている（シンプルなライブラリ／CLI は省略）
• すべてのコードブロックの内容（図、ツリー、フロートレース）が 80 桁以内に収まっている
• アーキテクチャまたは主要なフローのセクションに ASCII 図が含まれている
• サーフェスまたはユーザータイプごとに 1 つのフローがある（任意の数ではなく、アーキテクチャに基づいて決める）
• 外部依存関係と統合がアーキテクチャのセクションに示されている（または、存在しないことが明記されている）
• モジュールの責務、ドメイン用語／抽象概念、外部依存関係に表が使われている
• Markdown のスタイル（見出し、太字、コードブロック、表）が一貫している
• 既存ドキュメントへのリンクは、直接関係する箇所にのみインラインで記載されている
• 文章が直接的かつ具体的で、埋め草、曖昧な表現、ドキュメント自体に関するメタコメントがない
• トーンがコードベースに合っている（小規模で素早く作られたプロジェクトではくだけた調子、エンタープライズでは正確な調子）
• 対象読者に合わせたタイトル（ユーザー体験／開発者体験／両方）の「使われ方」セクションがある。利用者のいない純粋なインフラの場合のみ省略
• アーキテクチャ図のエッジにプロトコル／トランスポートのラベルがあり、複数のサーフェスまたはユーザータイプを持つシステムにはユーザーインタラクションのフロー図も含まれている

ファイルはリポジトリのルートに ONBOARDING.md として書き込みます。

フェーズ 5：結果の提示

書き込み後、ONBOARDING.md が生成されたことをユーザーに伝えます。利用可能な場合は、プラットフォームのブロッキング質問ツール（Claude Code の AskUserQuestion、Codex の request_user_input、Gemini の ask_user）を使って次のステップを提示します。それ以外の場合は、チャットで番号付きの選択肢を提示します。

選択肢：

1. ファイルを開いて確認する
2. Proof に共有する
3. 完了

選択に応じた処理：

• 開いて確認する → 現在のプラットフォームのファイルオープンまたはエディターの機能を使って ONBOARDING.md を開く
• Proof に共有する → ドキュメントをアップロードする：

  CONTENT=$(cat ONBOARDING.md)
  TITLE="Onboarding: <project name from inventory>"
  RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \
    -H "Content-Type: application/json" \
    -d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')")
  PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
  

  成功した場合は View & collaborate in Proof: <PROOF_URL> を表示してから、選択肢に戻る
• 完了 → 追加の処理は行わない