dx-project-create

新しい Salesforce プロジェクトの作成

ウィザード形式でユーザーを案内し、新しい Salesforce DX プロジェクトをひな形から作成して、このセッションを新しいプロジェクトに移動し、組織に接続して、開発用に設定します。各ステップは順番に実行し、環境を変更する操作の前には必ずユーザーに確認してください。

salesforce-development プラグインの MCP サーバー（salesforce-api-context、salesforce-metadata-experts、salesforce-lsp）はプロジェクトではなく、インストール済みプラグインによって提供されます。そのため、セッションが移動すると新しいプロジェクトでも自動的に利用できます。プロジェクトごとの .mcp.json をコピーする必要はありません。

Step 1: プロジェクトテンプレートを選択する

このスキルでは、CLI が提供するすべてのテンプレートを使ってひな形を作成します。React／Angular の UI バンドルアプリも含まれます。プロジェクトの作成は中核となる機能であり、テンプレートを選ぶためだけに別のプラグインをインストールする必要はありません。（プロジェクトが作成された後は、experience-ui-bundle-* スキルが、ページ、コンポーネント、スタイル設定、デプロイなどの 構築 を担当します。ただし、最初のひな形作成はそのプラグインがインストールされているかどうかにかかわらず、ここで行います。）

テンプレートの一覧は CLI からその都度取得してください。Salesforce は時間の経過とともにテンプレートを追加するため、一覧をハードコードしてはいけません。ハードコードした一覧は古くなります。

sf template generate project --help

-t, --template=<option> 行にある <options: a|b|c|…> の一覧を解析してください。パイプ区切りの名前が、正式なテンプレート一覧です。執筆時点で CLI が提供するテンプレートは 8 つで、ここですべてひな形を作成できます。standard、empty、analytics、agent と、UI バンドルのテンプレート一式である reactinternalapp、reactexternalapp、angularinternalapp、angularexternalapp です（React／Angular × 社内向け／社外向け）。解析結果を正としてください。ここに記載した一覧は、解析に失敗した場合のみ代替として使用します。

まず、意図からテンプレートを特定できるか確認します。 このショートカットを使うのは、リクエストからテンプレートがただ 1 つに確定する場合に限ります。選択に必要な情報が不足していれば、推測せず、選択メニューを表示して確認してください。以下の場合は {template} を直接決定します。

• リクエストで UI 以外のテンプレートが指定されている場合：「empty／minimal project」→ empty、「analytics project」→ analytics、「agent project」→ agent、「standard project」→ standard。
• フレームワークと対象ユーザーの両方が明確な UI バンドルアプリの場合は、該当する UI テンプレートを選択します（例：「internal React app」→ reactinternalapp、「customer-facing Angular portal」→ angularexternalapp）。社内向けは従業員向け／認証済み、社外向けはログインフローを備えた顧客／パートナー向けです。

アプリの説明はテンプレート名ではありません。 「個人用の ToDo アプリを作って」「在庫管理アプリ」「チーム用の CRM」は、何を作るかを説明しているだけで、どのテンプレートを使うかは指定していません。そのため、テンプレートは確定せず、ショートカットの対象にもなりません。どれほど明らかに思えても、アプリの目的から standard（または他のテンプレート）を推測してはいけません。standard が選択メニューの既定値であることは、メニューを省略する理由にはなりません。ユーザーがテンプレート名もフレームワークも指定していない場合は、必ず選択メニューを表示し、ユーザーに選んでもらってください。テンプレートを黙って決めてしまうことこそ、このステップで防ごうとしている見落としです。

それ以外の場合はすべて選択メニューに進みます。以下のケースも含まれます。

• テンプレート名を指定しない、単に「new project」／「create a Salesforce project」といったリクエスト（選択メニューの既定値は Standard）、

• テンプレート名もフレームワーク名も指定していない アプリの説明（「a todo app」、「an inventory tracker」など）。選択メニューを表示し、アプリの目的からテンプレートを推測してはいけません。

• 一部の情報だけが指定された UI アプリ。たとえば、対象ユーザーの指定がない「create a React app」です。対象ユーザーを推測してはいけません。フレームワークはわかっていて対象ユーザーが不明な場合は、最上位の選択メニューを省略し、以下のフレームワーク／対象ユーザーの追加質問に進んで、不足している情報だけを確認します。 それ以外の場合は、AskUserQuestion を1回だけ提示します。「どのような種類のプロジェクトですか？」（単一選択、4つの選択肢）。AskUserQuestion の選択肢は最大4つのため、ピッカーにはリクエストの多い4種類が表示されます。empty は意図的にピッカーから除外されており、上記のインテントショートカット（「empty/minimal project」）でのみ選べます。これは意図的な仕様です。empty はほとんど選ばれない空のプロジェクトテンプレートであり、限られた4枠のうち1枠をこれに使うと、よく選ばれる選択肢が押し出されてしまいます。これを使いたいユーザーが名前を指定すれば、ショートカットによって直接選択されます。

• Standard → standard（デフォルト） — 汎用の force-app メタデータプロジェクト（Apex、LWC、オブジェクト、フロー）。

• Agentforce エージェント → agent — サンプルの Local Info Agent が含まれます。

• CRM Analytics → analytics（Tableau CRM） — waveTemplates ディレクトリが追加されます。

• React / Angular UI アプリ → UI バンドルのスターターです。フレームワークと対象ユーザーが必要なため、追加の AskUserQuestion を1回だけ提示し（「どの UI フレームワークと対象ユーザーですか？」、4つの選択肢）、{template} に直接対応付けます。

  • React — 社内向け → reactinternalapp · React — 外部向け → reactexternalapp
  • Angular — 社内向け → angularinternalapp · Angular — 外部向け → angularexternalapp
  • 社内向けとは従業員向け／すでに認証済みのことです。外部向けとは、ログイン、登録、プロフィールを備えた顧客／パートナー向けのことです。

解決されたテンプレートは {template} となり、ステップ3に渡されます。実行中の CLI に新しいテンプレートが追加されたら、ここにも追加してください（または、選ばれることが少ない別のテンプレートであれば、5つ目の選択肢に加えるのではなく、インテントショートカットのキーワードとして設定してください）。

ステップ2：プロジェクト名を選ぶ

ユーザーにプロジェクト名を入力してもらいます。これは新しいディレクトリ名になり、以下のシェルコマンドにも埋め込まれるため、コマンドで使用する前に必ず厳密に検証してください。生の名前をそのまま渡してはいけません。

許可リストを適用してから、不正な入力を拒否し、再入力を求めます。 ^[A-Za-z0-9][A-Za-z0-9_-]*$ に一致する名前のみ受け付けます。つまり、先頭は英字または数字とし、英字、数字、_、- のみを使用できます。これ以外（空白、/ などのパス区切り、先頭の . や ..、または ; | & $ > < ( ) \ " ' などのシェルメタ文字）は無効です。理由を説明して、再入力を求めてください。proj;rm -rf ~のような名前がコマンドに渡ることは、絶対にあってはなりません。多層防御として、以下のコマンドでも"{name}"` を引用符で囲みます。ただし、本当の防御策は検証であり、引用符ではありません。

ステップ 3：プロジェクトを生成する

生成前に確認してください — 次の両方を確認できるまで、コマンドを実行しないでください。

• ☐ 補間する {name} が、ステップ 2 の許可リスト（^[A-Za-z0-9][A-Za-z0-9_-]*$）を通過した正確な値であること。未加工の文字列、再編集した文字列、またはユーザーが復唱した文字列ではありません。検証に通過していない場合は、ステップ 2 に戻ってください。
• ☐ {template} が、ステップ 1 で CLI が提示した選択肢のいずれかであること。
• ☐ 現在の作業ディレクトリに {name}/ ディレクトリがまだ存在しないこと。存在する場合、生成に失敗するか、既存のプロジェクトを上書きするおそれがあります。まず [ -e "{name}" ] で確認してください。存在する場合は上書きせず、ユーザーに伝えて、別の名前を指定するためにステップ 2 に戻ってください。

現在の作業ディレクトリで実行します。

sf template generate project -t {template} -n "{name}"

これにより、現在の作業ディレクトリの下に新しい {name}/ ディレクトリが作成されます。（sf project generate はこのコマンドの非推奨の別名です。template generate project を優先してください。）既存のディレクトリ内に生成する場合とは異なり、新しい {name}/ が作成され、セッションの移動先となるルートに sfdx-project.json がすでに配置されるため、フラット化の手順は必要ありません。

UI バンドルのテンプレートには npm の依存関係が含まれますが、ユーザーの代わりにインストールしてはいけません。 React／Angular のスターターは、npm の依存関係がそろうまで実行できません（プレビュー、ビルド、lint が失敗します）。また、package.json ファイルはプロジェクトのルートと各 UI バンドルに複数あり、それぞれでインストールが必要です。初回のインストールは時間のかかる手順（数分）で、所要時間からもすぐに分かるため、開発者が明示的に判断すべきものであり、このスキルが尋ねずに実行するものではありません。自分で npm install を実行しないでください。代わりに、{template} が UI バンドル（react*／angular*）の場合は、依存関係がまだインストールされていないことと、ユーザーが準備できたときに実行するコマンドを、最後のメッセージで伝えてください（「最後のメッセージ」の UI バンドルに関する説明を参照）。

ステップ 4：セッションを新しいプロジェクトに移動する

最新の Claude Code（v2.1.169 以降）では、新しいターミナルを開いたり、再起動したりせず、会話履歴を保持したまま、現在のセッションをその場で新しいディレクトリに移動できます。ユーザーに次のコマンドを実行するよう伝えてください。

/cd {name}

これによりセッションが移動します。新しいディレクトリの CLAUDE.md が読み込まれ、プロジェクトのストレージもそこに移動するため、--resume／--continue でセッションを見つけられるようになります。また、cwd がプロジェクトのルートになるため、以降の sf コマンドはパスを付けずに sf ... として実行できます。

/cd はクライアント側での移動です。フックは実行されず、ターンも発生しないため、実行した瞬間にセッションは静かになります。これは想定どおりで、ハングではありません。ただし、ユーザーに /cd を案内するメッセージが、ユーザーが再び話しかけるまでの最後の発言になります。そのため、そのメッセージは、会話を再開する方法を案内する言葉で必ず締めくくってください。次のような一文で締めます。

移動したら、「次は何をすればいい？」（または「組織に接続して」）と伝えてください。そこから続けます。

「次は何をすればいい？」と伝えると、このセッションが再開され、次のステップ（組織の認証）を示す案内が表示されます。/cd の後にセッションが自動で続行されると決して伝えないでください。自動では続行されません。

ユーザーが再び話しかけたら、「{name} に移動しました。」などの短い一言で移動を確認し、ステップ 5 に進みます。バナーを「再表示」するために sf-context detect や check-tools を実行しないでください。ツールとして実行した detect は、レンダリング済みのバナーではなく、生のフック JSON を出力します。また、プラグインはすでにバナーを自動表示します。HEADLESS の識別情報は、セッションごとに一度（ユーザーが初めて Salesforce について質問したとき、セッション開始時、または最初の案内を求める質問をしたとき）表示され、「今どこにいる？」／「次は何をすればいい？」と尋ねられるたびに、次のステップを示す案内が表示されます。開発環境のヘルスチェックは、/salesforce-development:setup で必要に応じて実行できます。

古い Claude Code（v2.1.169 より前）の場合の代替手順： /cd を実行すると Unknown command と表示されます。その場合は、新しいディレクトリで再起動する必要があります。

cd "{name}" && claude

salesforce-development プラグインはマーケットプレイス経由でグローバルにインストールされているため、新しいディレクトリでセッションを開始すると自動的に読み込まれ、SessionStart が実行されます。バナーとヘルスチェックも自動で表示されるため、sf-context を手動で呼び出す必要はありません。以降の手順はプロジェクト内から実行します。

ステップ 5：組織を認証する

このプロジェクトのデプロイ先となる組織を認証します。

sf org login web --alias {alias}

• 後続の手順で組織を名前で参照できるように、--alias を指定するかユーザーに尋ねてください。
• サンドボックスの場合は、--instance-url https://test.salesforce.com を追加します。
• 本番環境の場合は、--instance-url を省略します（既定値は login.salesforce.com です）。

すでに組織が認証済みの場合は、ログインを省略し、既存のエイリアスだけを確認します。

ステップ 6：デフォルト組織として設定する

認証したばかりの組織を、プロジェクトのデフォルトのターゲットとして設定します。

sf config set target-org {alias}

ステップ 7：ソース追跡が有効になっていることを確認する

デプロイプレビューを使って、組織でソース追跡が機能するか確認します（読み取り専用のソース追跡プローブのうち、最も負荷が軽い方法です）。

sf project deploy preview --target-org {alias} --json

ソース追跡がサポートされていない、または有効になっていないというエラーが発生した場合は、有効にするかユーザーに確認してください。

sf org enable tracking --target-org {alias}

有効化コマンドを実行する前に、ユーザーの確認を取ってください。

完了メッセージ

すべての手順が完了したら、ユーザーに次のように伝えてください。

Your project is ready! Here's what was set up:

  ✅ Project generated: {name}/
  ✅ Session relocated into {name}/ (via /cd)
  ✅ Default org: {alias}
  ✅ Source tracking: enabled (or status)

You're already working inside the new project — this same session moved
here with /cd, so just keep going. Run /salesforce-development:setup
anytime to re-check your dev environment.

ユーザーが旧バージョン向けの代替手順を選んだ場合（/cd の代わりに cd {name} && claude で再起動した場合）、プロジェクト内の新しいセッションが開始されており、SessionStart バナーで環境についてすでに案内されています。ツールを再確認するには、/salesforce-development:setup を実行するよう案内してください。

UI バンドルのプロジェクトの場合、スキャフォールドは完了していますが、npm 依存関係はインストールされていません。これは開発者が判断することであり、このスキルで実行するものではありません（初回インストールは時間のかかる重い処理です）。プレビュー、ビルド、リントを行う前にアプリの依存関係が必要であることを伝え、準備ができたらプロジェクト内で実行するコマンドを案内してください。

npm install                                        # project root
for b in force-app/main/default/uiBundles/*/; do   # each UI bundle
  [ -f "$b/package.json" ] && ( cd "$b" && npm install )
done

続いて、後続の開発スキルを案内する行を追加してください。フロントエンド構築スキルは React 専用のため、案内先はフレームワークごとに分けてください。

• React（react* テンプレート）→ experience-ui-bundle-frontend-generate はページ／コンポーネントを構築します（React／TypeScript 専用で、shadcn/ui、react-router、appLayout.tsx／routes.tsx を使用します）。experience-ui-bundle-deploy はアプリをデプロイします。
• Angular（angular* テンプレート）→ Angular 向けのフロントエンドスキルはありません。そのため、experience-ui-bundle-frontend-generate は案内しないでください。このスキルの前提条件は React の appLayout.tsx／routes.tsx／src/components/ui/ であり、Angular バンドルでは拒否されます。Angular スターターの README／ツールチェーンを使って開発してください。experience-ui-bundle-deploy はフレームワークに依存せず、引き続きデプロイに使用できます。

いずれの場合も、これらのスキルは experience-react／experience-lwc プラグインに含まれています。ユーザーがこれらを持っていない場合、それはアプリの構築に関することであり、スキャフォールドに関することではありません。ユーザーが手にしたプロジェクトは完成しており、そのままデプロイできます。

ルール

• 手順は順番どおりに実行してください。環境を変更する操作（ログイン、デフォルトの設定、トラッキングの有効化）の前には、必ず確認してください。
• プラグインの MCP サーバーはプロジェクトではなく、インストール済みのプラグインから取得します。新しいプロジェクトに .mcp.json を作成またはコピーしないでください（プラグインの設定で使用されている ${CLAUDE_PLUGIN_ROOT} は、プロジェクトレベルのファイルでは解決されません）。
• セッション内で移動するには、/cd {name} を優先してください（Claude Code v2.1.169 以降）。スキルがユーザーに代わってセッションを移動させることはできないため、ユーザーに実行するよう案内してください。古いビルドで /cd が Unknown command と返した場合に限り、cd {name} && claude（再起動）を使用してください。
• ユーザーに /cd {name} を案内するメッセージを送った後は、ユーザーが再度発言するまで次のターンを行わないでください（/cd はフックを実行しません）。そのため、必ず再開できる手がかりでメッセージを締めくくってください。たとえば、「移動したら、『次は何をすればよいですか？』とお声がけください。」とします。/cd の後、セッションが組織に接続したり、自動で続行したりすると約束しないでください。ユーザーが再度応答するまで、セッションは停止したままです。
• /cd の後に、バナーを「表示する」ために sf-context detect や check-tools を実行しないでください。ツールとしての detect は未加工の JSON を出力し、プラグインがバナーを自動で表示します（セッションごとに一度だけ表示されます。ジャーニーの案内はオリエンテーションに関する質問時に表示されます）。必要に応じて /salesforce-development:setup からヘルスチェックを実行できます。
• Sandbox にログインする場合は、--instance-url https://test.salesforce.com が必須です（CLI のデフォルトは本番環境を指します）。
• アクセストークンを保存または表示しないでください。
• プロジェクト名はユーザー入力であり、シェルコマンドに渡されます。使用前に ^[A-Za-z0-9][A-Za-z0-9_-]*$ に照らして検証し、条件に合わない場合は拒否して再入力を求めてください。すべてのコマンドで "{name}" のように引用符で囲んでください（cd {name} && claude のフォールバックも含みます）。proj;rm -rf ~ のような名前を未加工のまま展開してはいけません。検証で防御し、引用符でさらに安全を確保してください。
• ツールの検証だけが必要な既存プロジェクトには、platform-environment-validate（または /salesforce-development:setup）を使用してください。既存プロジェクトで組織認証を行う場合は、/salesforce-development:login を使用してください。
• あらゆるテンプレート（React／Angular を含む）の新規プロジェクト作成を、このスキルが担当します。ゼロから「新しいプロジェクトを作成したい」という依頼には、スキャフォールドの作成、移動、組織への接続、トラッキングの有効化までをエンドツーエンドで行ってください。最初のスキャフォールド作成を別のプラグインに任せないでください。ここでスキャフォールドを作成します。ただし、ユーザーに代わって npm install を実行しないでください。UI バンドルの依存関係のインストールは開発者が明示的に行うものです（締めくくりのメッセージでコマンドを案内してください）。その後、UI アプリの構築とデプロイには experience-ui-bundle-* スキルを案内してください。唯一の例外は、UI バンドルアプリの構築における一つの組み合わせ手順として UI バンドルのスキャフォールドを作成する場合です（experience-ui-bundle-app-coordinate が主導し、プロジェクト全体のセットアップは求められていない場合）。これはこのスキルではなく、experience-ui-bundle-project-generate の担当です。2 つのスキルの説明には、相互に起動しないよう指示が記載されています。既存の UI バンドルアプリの構築や編集は、常にそちらのスキルが担当します。新規プロジェクトの作成は、このスキルが担当します。