dx-project-create

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Creating a New Salesforce Project

创建新的Salesforce项目

Walk the user through a wizard that scaffolds a new Salesforce DX project, relocates this session into the new project, connects it to an org, and configures it for development. Run each step in order, confirming with the user before any environment-changing action.

The

salesforce-development

plugin's MCP servers (

salesforce-api-context

salesforce-metadata-experts

salesforce-lsp

) are provided by the installed plugin, not by the project — so they stay available in the new project automatically once the session relocates. There is no per-project

.mcp.json

to copy.

引导用户通过向导搭建新的Salesforce DX项目，将会话迁移至新项目，连接到组织并配置开发环境。按顺序执行每个步骤，在执行任何会改变环境的操作前需征得用户确认。

salesforce-development

插件的MCP服务器（

salesforce-api-context

、

salesforce-metadata-experts

、

salesforce-lsp

）由已安装的插件提供，而非项目本身——因此一旦会话迁移，它们会自动在新项目中保持可用。无需复制每个项目的

.mcp.json

文件。

Step 1: Choose a Project Template

步骤1：选择项目模板

Prompt the user to pick a template. Default to

standard

if they don't have a preference.

Template	Use for
`standard` (default)	General-purpose SFDX project with the conventional `force-app` layout
`empty`	Bare project with minimal scaffolding
`analytics`	CRM Analytics (Tableau CRM) development
`reactinternalapp`	React-based internal app
`reactexternalapp`	React-based external/experience app
`agent`	Agentforce agent development

提示用户选择模板。若用户无偏好，默认使用

standard

。

模板	适用场景
`standard` （默认）	通用SFDX项目，采用传统的 `force-app` 布局
`empty`	极简脚手架的空白项目
`analytics`	CRM Analytics（Tableau CRM）开发
`reactinternalapp`	基于React的内部应用
`reactexternalapp`	基于React的外部/体验应用
`agent`	Agentforce agent开发

Step 2: Choose a Project Name

步骤2：选择项目名称

Prompt the user for a project name. This becomes the new directory name, so it must be a valid directory name (no spaces or path separators).

提示用户输入项目名称。该名称将成为新目录的名称，因此必须是有效的目录名称（不含空格或路径分隔符）。

Step 3: Generate the Project

步骤3：生成项目

Run in the current working directory:

bash

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

This creates a new

{name}/

directory under the current working directory.

在当前工作目录中运行：

bash

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

此命令会在当前工作目录下创建一个新的

{name}/

目录。

Step 4: Relocate the Session Into the New Project

步骤4：将会话迁移至新项目

Modern Claude Code (v2.1.169+) can move the current session into the new directory in place — no new terminal, no relaunch, conversation history preserved. Tell the user to run:

text

/cd {name}

This relocates the session: the new directory's

CLAUDE.md

is loaded, project storage moves there (so

--resume

--continue

find it), and the cwd becomes the project root, so all remaining

sf

commands run as plain

sf ...

with no path prefix.

/cd

is a client-side move: it fires no hook and gives you no turn, so the session goes quiet the instant they run it — expected, not a hang. But it also means the message in which you hand them

/cd

is your last word until they speak again, so that message MUST end with an affordance telling them how to resume. Close it with a line like:

Once you're in, just say "what's next" (or "connect an org") and I'll pick up from there.

Saying "what's next" re-engages this session and paints the position rail, which points at the next step (authenticating an org). Never imply the session will continue on its own after

/cd

— it won't.

When they re-engage, confirm the move in one short line (e.g. "You're in {name} now.") and continue to Step 5. Do not run

sf-context detect

check-tools

to "re-surface" the banner:

detect

invoked as a tool prints the raw hook JSON (not a rendered banner), and the plugin already surfaces the banner on its own — it shows the HEADLESS identity once per session (at the user's first Salesforce ask, at session start, or on their first orientation question), and paints the position rail whenever they ask "where am I" / "what's next". A dev-environment health check is available on demand via

/salesforce-development:setup

Fallback for older Claude Code (before v2.1.169):

/cd

reports

Unknown command

. In that case the user must relaunch in the new directory instead:

bash

cd {name} && claude

The

salesforce-development

plugin is installed globally (via the marketplace), so a fresh session in the new directory loads it automatically and fires SessionStart — the banner and health check appear on their own, no manual

sf-context

calls needed. The remaining steps below then run from inside the project.

新版Claude Code（v2.1.169及以上版本）可直接将当前会话迁移至新目录——无需打开新终端、无需重启，对话历史将被保留。告知用户运行：

text

/cd {name}

此操作会迁移会话：加载新目录的

CLAUDE.md

，项目存储转移至该目录（因此

--resume

--continue

命令可找到它），当前工作目录变为项目根目录，后续所有

sf

命令可直接以

sf ...

形式运行，无需路径前缀。

/cd

是客户端侧操作：不会触发钩子，也不会返回响应，因此用户运行后会话会立即静默——这是正常现象，并非卡顿。但这也意味着告知用户运行

/cd

的消息是你在用户再次发言前的最后内容，因此该消息必须以提示用户如何恢复会话的内容结尾。例如：

进入新目录后，只需说**"下一步是什么"**（或"连接组织"），我就会继续后续步骤。

用户说"下一步是什么"会重新激活会话并显示进度栏，指向下一步（验证组织身份）。切勿暗示会话会在

/cd

后自动继续——实际上不会。

当用户重新激活会话时，用简短的一句话确认迁移完成（例如"你现在已进入{name}目录。"），然后继续步骤5。请勿运行

sf-context detect

或

check-tools

来重新显示横幅：作为工具调用的

detect

会打印原始钩子JSON（而非渲染后的横幅），且插件会自动显示横幅——在用户首次请求Salesforce相关操作、会话启动或首次询问定位问题时，会显示一次HEADLESS标识；当用户询问"我在哪里"/"下一步是什么"时，会显示进度栏。可通过

/salesforce-development:setup

按需进行开发环境健康检查。

旧版Claude Code（v2.1.169之前）的替代方案：

/cd

会提示

Unknown command

。此时用户必须在新目录中重新启动：

bash

cd {name} && claude

salesforce-development

插件是全局安装的（通过市场），因此在新目录中启动的新会话会自动加载该插件并触发SessionStart——横幅和健康检查会自动显示，无需手动调用

sf-context

。后续步骤将在项目内部运行。

Step 5: Authenticate to an Org

步骤5：验证组织身份

Authenticate the org this project will deploy to:

bash

sf org login web --alias {alias}

Prompt the user for an
```
--alias
```
so later steps can reference the org by name.

For a sandbox, add

--instance-url https://test.salesforce.com

For production, omit
```
--instance-url
```
(defaults to login.salesforce.com).

If the user already has the org authenticated, skip the login and just collect the existing alias.

验证项目将部署到的组织：

bash

sf org login web --alias {alias}

提示用户输入
```
--alias
```
，以便后续步骤通过名称引用该组织。

若为沙箱环境，添加

--instance-url https://test.salesforce.com

。

若为生产环境，省略
```
--instance-url
```
（默认指向login.salesforce.com）。

若用户已验证过该组织身份，跳过登录步骤，仅收集现有别名即可。

Step 6: Set as Default Org

步骤6：设置为默认组织

Set the freshly authenticated org as the project's default target:

bash

sf config set target-org {alias}

将刚验证的组织设置为项目的默认目标：

bash

sf config set target-org {alias}

Step 7: Ensure Source Tracking Is Enabled

步骤7：确保源跟踪已启用

Check whether source tracking works against the org using a deploy preview (the lightest read-only source-tracking probe):

bash

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

If this fails with an error mentioning source tracking not supported or not enabled, offer to enable it:

bash

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

Confirm with the user before running the enable command.

通过部署预览（最轻量的只读源跟踪探测）检查组织的源跟踪是否可用：

bash

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

若命令失败并提示源跟踪不支持或未启用，可提供启用命令：

bash

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

运行启用命令前需征得用户确认。

Closing Message

结束消息

Once all steps are complete, tell the user:

text

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.

If the user took the older-version fallback (relaunched with

cd {name} && claude

instead of

/cd

), they're in a fresh session in the project and the SessionStart banner already walked them through the environment — point them to

/salesforce-development:setup

to re-check tools.

所有步骤完成后，告知用户：

text

你的项目已准备就绪！以下是已完成的设置：

  ✅ 项目已生成：{name}/
  ✅ 会话已迁移至{name}/（通过/cd命令）
  ✅ 默认组织：{alias}
  ✅ 源跟踪：已启用（或当前状态）

你已在新项目中工作——当前会话通过/cd命令迁移至此，可继续后续操作。随时运行/salesforce-development:setup
重新检查你的开发环境。

若用户使用了旧版替代方案（通过

cd {name} && claude

重启而非

/cd

），他们处于项目中的新会话，SessionStart横幅已引导他们完成环境配置——可告知他们通过

/salesforce-development:setup

重新检查工具。

Rules

规则

Run the steps in order; confirm before any environment-changing action (login, set-default, enable tracking).
The plugin's MCP servers come from the installed plugin, not the project — do NOT create or copy a
```
.mcp.json
```
into the new project (the plugin's config uses
```
${CLAUDE_PLUGIN_ROOT}
```
, which does not resolve in a project-level file).
Prefer
```
/cd {name}
```
to relocate the session in place (Claude Code v2.1.169+) — a skill can't relocate the session on the user's behalf, so instruct the user to run it. Only fall back to
```
cd {name} && claude
```
(relaunch) when
```
/cd
```
reports
```
Unknown command
```
on an older build.
The message that hands the user
```
/cd {name}
```
is your last turn until they speak again (
```
/cd
```
fires no hook), so it MUST end with a resume affordance — e.g. 'once you're in, just say "what's next".' Never promise the session will connect an org or continue on its own after
```
/cd
```
; it stays silent until the user re-engages.
After
```
/cd
```
, do NOT run
```
sf-context detect
```
or
```
check-tools
```
to "show" the banner —
```
detect
```
as a tool prints raw JSON, and the plugin surfaces the banner itself (once per session; the position rail on orientation questions). Just confirm the move in one line and continue. Health is available on demand via
```
/salesforce-development:setup
```
.
For sandbox login,
```
--instance-url https://test.salesforce.com
```
is REQUIRED (the CLI default points at production).
NEVER store or display access tokens.
For an EXISTING project that just needs tooling validated, use
```
platform-environment-validate
```
(or
```
/salesforce-development:setup
```
); for org auth on an existing project, use
```
/salesforce-development:login
```
.

按顺序执行步骤；在执行任何会改变环境的操作（登录、设置默认组织、启用跟踪）前需征得用户确认。
插件的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
```
按需进行健康检查。
沙箱登录时，必须添加
```
--instance-url https://test.salesforce.com
```
（CLI默认指向生产环境）。
绝不要存储或显示访问令牌。
若仅需验证现有项目的工具，使用
```
platform-environment-validate
```
（或
```
/salesforce-development:setup
```
）；若为已有项目进行组织身份验证，使用
```
/salesforce-development:login
```
。