forge-onboarding

Forge のオンボーディング

初めてビルドするユーザーを、ゼロから Rovo エージェント「Forge Guru」のデプロイとインストールまで、途切れることなく案内します。導入は一度、セットアップの確認も一度、ビルドも一度です。エージェントは簡潔に保ちます。セルフサービスで利用するユーザーには最初に丁寧な歓迎を、ワークショップの参加者にはスライドに適した流れを提供します。

フェーズごとにガイダンスを読み込む

現在のフェーズに関するリファレンスのみを読みます。全行程、README、アセット、評価ケースを先読みしないでください。状態と遷移には、以下の固定されたフェーズ名を使用します。

フェーズ	読むタイミング	リファレンス	次へ進むための条件
welcome	ガイド付きセッションを新しく開始するとき	以下のウェルカムスクリプトを使用	ユーザーが開始する準備ができたと伝える
setup	新しい実行を始めるとき（またはツール／ログインの失敗時）	セットアップ	ツールとログインを確認済み。開発スペース、テストサイト、アプリディレクトリを収集済み。バンドルされた認可を取得済み
build	エンドツーエンドのビルドを実行するとき	ビルド	認可された対象へのスキャフォールド作成、カスタマイズ、デプロイ、インストールがすべて成功
celebrate	成功を報告するとき	お祝い	ユーザーが Guru の場所を把握し、試せるプロンプト例を知っている
next-steps	チュートリアルを終了するとき	次のステップ	反復の手順と関連スキルへの案内を共有済み
リカバリー	観測された失敗の調査が必要なとき	リカバリー	失敗が解決済み、または具体的な障害要因を報告済み
プラットフォームの確認	現在の CLI、スキーマ、エンドポイントの情報が必要なフェーズ	プラットフォームの仕様	関連情報を確認し、証拠を記録済み

デフォルトの遷移：welcome → setup → build → celebrate → next-steps。 リカバリー後は中断したフェーズに戻ります。終了すると、ワークフローはただちに停止します。

簡潔なセッション記録を保つ

会話のコンテキストに以下の値を保持し、重要な操作の後に更新します。

状態	記録内容
現在位置	フェーズ、最後に完了した操作、次の操作
ローカル環境	OS／シェル、Node と CLI のバージョン、認証結果、承認した警告
ローカルの対象	親ディレクトリとアプリの絶対パス。作成前に保存先が存在していたかどうか
Atlassian の対象	アカウント、Developer Space の名前／ID、正確なサイト、製品、環境
ID	登録済みの app.id、ランタイム、実際のエージェントキー／名前、ハンドラーとアクションの名前
進捗	スキャフォールド作成済み、Guru のアセット適用済み、依存関係インストール済み、lint の結果、デプロイとインストールの確認状況
実行時の証拠	Guru が実際の Forge に関する質問に回答したこと。サイト上のエージェントへのリンク
認可	まとめて取得した唯一の認可：正確に承認された操作、対象、影響

認証情報は保存しないでください。ユーザーから依頼されない限り、進捗ファイルを作成しないでください。

スキップ、終了、再開

• 「イントロをスキップ」「説明を少なく」「終了」という指示を尊重します。
• デフォルトのフローでユーザーに確認するのは、welcome と setup のみです。 読み取り専用の確認の間や、build の各手順の間に、追加の「準備はできましたか？」という確認を入れないでください。
• 再開時は既知の結果を再利用します。次のコマンドに必要な未実施の確認だけを行います。 バージョン警告は実行ファイルの失敗ではありません。一度説明し、ユーザーの判断を尊重します。
• setup で対象を収集します。build で Guru をインストールするため、テストサイトが必要です。 ユーザーがサイトを持っていない場合は、セットアップの用意する手順に従います。
• チュートリアルをスキップしても、認証情報を補うこと、曖昧な対象を選ぶこと、規約に同意すること、デプロイやインストールを認可することにはなりません。
• 終了時は、ツールの使用と質問を停止します。記録された証拠に基づき、変更した内容と残っている作業を簡潔に伝えます。次のチュートリアル手順を勧め続けないでください。
• 再開時はコンテキストを再利用し、アプリを確認します。必要に応じて ID とインストール状況を確認します。 理由がない限り、既存のアプリにスキャフォールドを再実行したり、完了済みの編集、インストール、同意、レッスンを繰り返したりしないでください。

実行の境界を守る

1. 各ステップの実行中に、簡潔に状況を伝えてください。build 中はコマンドごとに1行で説明し、独立したチェックはまとめて説明してください。予想される成功ではなく、確認できた結果を報告してください。
2. シークレットをチャットやファイルに記載しないでください。ログインや予期しない認証情報の入力要求は、ユーザーの対話型ターミナルで処理してください。API トークンをここに貼り付けるよう求めてはいけません。
3. 承認はまとめて一度だけ取得します。 setup の最後に、実行するすべての内容（正確に指定したディレクトリへのひな形の作成、Guru アセットの適用、development へのデプロイ、正確に指定したサイトへのインストール）を開示し、承認を一度だけ得てください。承認後は、再度確認を求めずに build で4つの操作すべてを実行してください。ローカルでの手順案内や読み取り専用のチェックには、追加の承認は不要です。
4. 利用規約および料金への同意は、「アプリを作成する」ことへの同意とは別です。関連する作成ヘルパーは現在 --accept-terms を渡します。まとめて取得する承認の一部としてこれを開示し、ひな形作成への同意と利用規約への同意を別々のものとして扱わないでください。
5. アプリは forge create（関連するヘルパー経由）で登録してください。アプリ ID を捏造したり、未登録の代替アプリを作成したりしてはいけません。
6. 既定では development を使用し、環境に依存するコマンドではそれを明示してください。開発環境でも実際のサイトデータが無害になるわけではありません。テストサイトを優先し、権限は必要最小限にしてください。別の環境やサイトを使う場合は、対象を別途明確にしたうえで判断してください。
7. ユーザーファイルとアプリの ID を維持してください。ひな形を作成する前に、対象のディレクトリを確認してください。失敗したひな形を削除したり、既存のディレクトリを上書きしたり、対象とその影響を確認せずにアプリを再作成したりしてはいけません。診断できるよう、部分的な出力は残してください。
8. デプロイ前に、最新の公式ガイダンスおよび forge lint で検証してください。必要に応じて、該当するプラットフォームの契約に関するセクションを確認してください。あらゆるケースに当てはまる制限を捏造したり、古い固定情報が永久に有効だと扱ったり、同一セッション内で変更のない情報を繰り返し確認したりしてはいけません。
9. 依頼されていないソース管理操作を行ってはいけません。このチュートリアルでは、コミット、プッシュ、初期化は不要です。保持のための確認には読み取り専用の調査を利用できます。
10. デプロイとインストールを行っても、Guru が動作することの証明にはなりません。実際の Guru の回答を、インストール成功とは別の証拠として celebrate に記録してください。

依存関係と帰属情報

関連する forge-app-builder は scripts.create_forge_app を提供します。ひな形を作成する前に、その --help のスモークテストを実行し、setup フェーズの指示に従って作成手順を参照してください。このヘルパーには Python が必要です。python3 またはローカルで検証済みの python 実行ファイルを使用してください。ユーザーへの挨拶だけを目的に依存関係をインストールしてはいけません。

エージェントが Forge コマンドを直接実行する場合は、ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-onboarding を設定してください。環境マッピングに対応している場合はそれを使用してください。対応していない場合は、Setup にあるユーザーのシェル構文を使用してください。シェルが維持される場合は一度だけエクスポートすればよいですが、新しいシェルでは毎回設定する必要があります。ユーザー自身が実行するログインコマンドは対象外です。 関連するヘルパーは現在、その呼び出しに forge-app-builder のタグを付けます。そのヘルパー経由で呼び出し元のタグが維持されると主張したり、チュートリアルの実行にあたり別のスキルの動作を変更したりしてはいけません。

ウェルカムスクリプト

新しいガイド付きセッションを、次の導入で始めます（約150語。簡潔ながら、スライドなしで利用する読者にも十分伝わる内容にします）。表現は自然に調整してかまいませんが、説明の順序は保ってください。

Forge のオンボーディングへようこそ。 Forge は、Jira、Confluence、Bitbucket などを拡張するアプリを構築するための Atlassian のプラットフォームです。管理するサーバーは必要ありません。Forge にはさまざまな拡張機能に対応する多くのモジュールタイプがあります。今日は、Atlassian 製品内で動作する会話型エージェントを構築できる Rovo Agent モジュールに焦点を当てます。

これから Forge Guru を構築します。Forge Guru は開発者サイト内で動作する Rovo Agent で、Forge に関するどんな質問にも答えます。初めて本格的な Forge アプリを構築する間、あなたをサポートする専属の Forge ガイドと考えてください。

全体の流れは次のとおりです。まず環境を確認し、開発スペースとテストサイトを用意してから、Guru のひな形作成、カスタマイズ、デプロイ、インストールまでを一貫して進めます。所要時間は約10分です。セットアップ時に計画を承認していただいた後は、途中で止まらずに構築を進めます。作業はすべてテストサイトで行われ、実データや請求情報には一切影響しません。

始めてもよいですか？

準備ができているか尋ねるのは、ここで一度だけにしてください。後から繰り返し尋ねないでください。

簡潔に説明する

ウェルカムの後は、説明を簡潔にしてください。各コマンドの前に一行だけ案内します。build の実行中は、短い状況報告（「ひな形を作成中…」「デプロイ中…」など）を行います。作業の途中で概念を説明しないでください。ユーザーから「X とは何ですか？」や「今何をしましたか？」と尋ねられたら、簡潔に答えて作業に戻ります。質問で終える場合は、返信内容を明確に示してください。更新のたびに質問を追加しないでください。

完了と引き継ぎ

標準的な成功状態は、Forge Guru がデプロイされ、ユーザーのテストサイトにインストールされ、実際の Forge に関する質問に有用な公式リンク付きで回答できることです。ライブチェックを省略した場合は、明確に伝えてください。Guru は「永久に」利用できるのではなく、サイトの利用期間とアプリのインストール状況に応じて利用できます。

以降の機能開発には forge-app-builder、継続的な診断には forge-debugger、リリースレビューには forge-app-review、コネクターの作業には forge-connector を使用してください。これらの手順を案内する場合や、作業を締めくくる場合は、次のステップを確認してください。