n8n-workflow-lifecycle-official

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

n8n Workflow Lifecycle

n8n工作流生命周期

The six stages

六个阶段

PLAN. Gather requirements, ask clarifying questions, search for existing workflows / sub-workflows that already do this.
BUILD. Write SDK code (with skills: subworkflows, node-config, expressions, code-nodes; readability section below). Use
```
validate_node_config
```
as a side-channel for iteration, debugging, or small single-node edits: clean per-parameter errors without full-graph noise. Not a replacement for
```
validate_workflow
```
in VALIDATE.
VALIDATE.
```
validate_workflow
```
+
```
get_workflow_details
```
for connections, then have the user verify per-node credentials and create anything you couldn't (missing credentials, folders, etc).
TEST.
```
test_workflow
```
with
```
prepare_test_pin_data
```
; iterate until output matches intent.
PUBLISH.
```
publish_workflow
```
only after stages 3 and 4 are clean.
HANDOFF. Production handoff: how to trigger it, what it returns, what to watch, what they should know to use it well.

Skipping a stage produces workflows that look done but break in production, or solve the wrong problem entirely. Three most common skips:

Build before plan. "User asked for X, I'll start coding" without confirming what X means, whether the same logic already exists as a sub-workflow, or which folder/project it belongs in. Cheaper to ask one clarifying question than to rebuild after.
Test before user-side wire-up. Running
```
test_workflow
```
before the user has verified credentials per node hits the wrong service or 401s. Get the user-side setup done as part of VALIDATE.
Publish without test. Validation passing means the SDK is well-formed; it does NOT mean the workflow is correct.

规划。收集需求，提出澄清问题，搜索已有的同类工作流/子工作流。
构建。编写SDK代码（涉及技能：子工作流、node-config、表达式、代码节点；详见下文可读性章节）。使用
```
validate_node_config
```
作为迭代、调试或单节点小修改的辅助渠道：清除单参数错误，避免全图噪音。它不能替代VALIDATE阶段的
```
validate_workflow
```
。
验证。调用
```
validate_workflow
```
+
```
get_workflow_details
```
检查连接，然后让用户验证每个节点的凭据，并创建你无法生成的内容（缺失的凭据、文件夹等）。
测试。结合
```
prepare_test_pin_data
```
调用
```
test_workflow
```
；迭代直到输出符合预期。
发布。仅在完成第3和第4阶段后调用
```
publish_workflow
```
。
交付。生产环境交付：说明触发方式、返回内容、监控要点，以及用户高效使用所需了解的信息。

跳过任一阶段会导致工作流看似完成，但在生产环境中崩溃，或完全解决错误的问题。最常见的三种跳过情况：

未规划先构建。“用户要X，我直接写代码”，未确认X的具体含义、是否已有子工作流实现相同逻辑，或它所属的文件夹/项目。提前问一个澄清问题比事后重写成本更低。
未完成用户端配置先测试。在用户验证节点凭据前运行
```
test_workflow
```
，会导致请求错误服务或返回401。将用户端配置作为VALIDATE阶段的一部分完成。
未测试就发布。验证通过仅表示SDK格式正确；不代表工作流逻辑正确。

Non-negotiables

不可妥协的规则

Validate AND verify before publish. Run
```
validate_workflow
```
on the SDK code, then
```
get_workflow_details
```
after every create/update to check the
```
connections
```
object. Validation alone misses silently dropped wires.
```
validate_node_config
```
is a separate per-node iteration tool, not a replacement for this step.
Surface known limitations to the user. If folders, MCP access, or any other limitation blocks the request, say so explicitly and propose a path. Don't silently dump workflows at the wrong location or report success on a request you couldn't fully fulfill.
Ask before testing when not-auto-pinned downstreams have side effects.
```
test_workflow
```
auto-pins triggers, credentialed nodes, and HTTP Request nodes. Everything else (Code, Edit Fields, If, Wait, Execute Command, file ops, sub-workflow calls, Data Tables) runs for real. Ask the user before running if any of those would fire user-visible side effects. See
```
references/TESTING.md
```
.

发布前必须验证并确认。对SDK代码运行
```
validate_workflow
```
，然后在每次创建/更新后调用
```
get_workflow_details
```
检查
```
connections
```
对象。仅靠验证无法发现静默丢失的连接。
```
validate_node_config
```
是独立的单节点迭代工具，不能替代此步骤。
向用户明确告知已知限制。如果文件夹、MCP权限或其他限制阻碍请求，需明确说明并提出解决方案。不要将工作流静默放置在错误位置，或在未完全满足请求时报告成功。
当非自动固定的下游节点有副作用时，测试前需询问用户。
```
test_workflow
```
会自动固定触发器、凭据节点和HTTP请求节点。其他节点（代码、编辑字段、条件、等待、执行命令、文件操作、子工作流调用、数据表）会真实运行。如果这些节点会产生用户可见的副作用，运行前需询问用户。详见
```
references/TESTING.md
```
。

Strong defaults

Validation isn't enough

仅靠验证还不够

validate_workflow

runs schema and shape checks: missing parameters, type errors, references to non-existent nodes. It does not catch:

The
```
.to()
```
-inside-
```
.add()
```
connection trap (silent dropped wires)
Fan-outs collapsed to a single connection
Merge index off-by-one
Error outputs wired without
```
onError: 'continueErrorOutput'
```
Parameters that are syntactically valid but semantically wrong (e.g., wrong sheet ID, wrong column name)

Validation is necessary but not sufficient. The real gate is:

```
validate_workflow
```
passes.
```
get_workflow_details
```
returns a
```
connections
```
object that matches your intent.
```
test_workflow
```
produces the right output on representative pinned data.

Only then call

publish_workflow

For the full pre-publish checklist, see

references/VALIDATION_CHECKLIST.md

validate_workflow

会运行 schema 和格式检查：检查缺失参数、类型错误、引用不存在的节点。但它无法检测：

```
.add()
```
内部使用
```
.to()
```
的连接陷阱（静默丢失的连接）
扇出分支被合并为单个连接
合并索引偏移
错误输出已连接但未设置
```
onError: 'continueErrorOutput'
```
语法有效但语义错误的参数（例如错误的表格ID、错误的列名）

验证是必要但不充分的。真正的发布门槛是：

```
validate_workflow
```
通过。
```
get_workflow_details
```
返回的
```
connections
```
对象符合预期。
```
test_workflow
```
在代表性固定数据上产生正确输出。

只有满足以上条件，才能调用

publish_workflow

。

完整的发布前检查清单详见

references/VALIDATION_CHECKLIST.md

。

Execution model

执行模型

n8n workflows execute sequentially, left-to-right, top-to-bottom. Branches that visually appear parallel on the canvas (fan-out from one source to multiple downstreams) run one after the other, ordered by the target nodes' Y-position on the canvas. There is no automatic concurrency.

Practical consequences:

A fan-out to three slow HTTP calls runs in series; total latency is the sum, not the max.
"Parallel" branches share workflow state in execution order; downstream consumers see whatever the last branch left.

For real concurrency, dispatch sub-workflows with

mode: 'each'

and

waitForSubWorkflow: false

. See

n8n-loops-official

and

n8n-subworkflows-official

This is platform behavior, not an SDK quirk. Don't design fan-outs around assumed parallelism.

n8n工作流按顺序执行，从左到右、从上到下。画布上看似并行的分支（从一个源节点扩散到多个下游节点）会按目标节点在画布上的Y坐标顺序依次运行，不存在自动并发。

实际影响：

三个慢速HTTP请求的扇出分支会串行运行；总延迟是各请求延迟之和，而非最大值。
“并行”分支按执行顺序共享工作流状态；下游消费者会看到最后一个分支留下的状态。

如需真正的并发，使用

mode: 'each'

和

waitForSubWorkflow: false

调度子工作流。详见

n8n-loops-official

和

n8n-subworkflows-official

。

这是平台特性，而非SDK缺陷。不要基于假设的并行性设计扇出分支。

Naming conventions

命名规范

Bad names compound: a workflow that's hard to find six months from now gets duplicated.

For full conventions (verb-noun patterns, capitalization, prefixes), read

references/NAMING_CONVENTIONS.md

. Short version:

Workflows: verb-first, scoped.

Send weekly customer report

not

Customer report sender

Nodes: describe what they do in this workflow, not the node type.
```
Fetch active customers
```
not
```
Postgres1
```
.
Sub-workflows: plain descriptive name (
```
Parse RFC2822 date
```
); carry the category in tags (
```
subworkflow
```
, a domain tag,
```
tool
```
), not a name prefix.
```
search_workflows({ tags })
```
filters on them. See
```
n8n-subworkflows-official
```
```
references/NAMING_AND_DISCOVERY.md
```
.
Tags: the AI-side discovery mechanism (n8n 2.27.0+). The MCP lists (
```
list_tags
```
), filters (
```
search_workflows({ tags })
```
), and attaches them (
```
update_workflow
```
```
addTags
```
/
```
removeTags
```
, auto-creating unknown names). Lowercase, 2-4 per workflow. See
```
references/NAMING_CONVENTIONS.md
```
.

糟糕的命名会导致问题累积：六个月后难以找到的工作流会被重复创建。

完整规范（动名词模式、大小写、前缀）详见

references/NAMING_CONVENTIONS.md

。精简版：

工作流：动词开头，明确范围。例如
```
Send weekly customer report
```
而非
```
Customer report sender
```
。
节点：描述其在当前工作流中的功能，而非节点类型。例如
```
Fetch active customers
```
而非
```
Postgres1
```
。
子工作流：使用直白的描述性名称（如
```
Parse RFC2822 date
```
）；通过标签携带类别（
```
subworkflow
```
、领域标签、
```
tool
```
），而非名称前缀。
```
search_workflows({ tags })
```
可按标签过滤。详见
```
n8n-subworkflows-official
```
的
```
references/NAMING_AND_DISCOVERY.md
```
。
标签：AI端的发现机制（n8n 2.27.0+）。MCP支持列出标签（
```
list_tags
```
）、按标签过滤（
```
search_workflows({ tags })
```
）以及添加/移除标签（
```
update_workflow
```
的
```
addTags
```
/
```
removeTags
```
，自动创建未知标签）。小写，每个工作流2-4个标签。详见
```
references/NAMING_CONVENTIONS.md
```
。

Readability: descriptions, node groups, sticky notes, conventions

可读性：说明、节点组、便签、规范

For any workflow over ~5 nodes, four levers carry the readability load:

Workflow
description
: capture the why, including AI-derived context. Two sentences: what it does and why it exists. Most importantly, capture context you had during conversation that won't otherwise survive into the file (the constraint that drove the design, why this approach over the alternative, the user's reason for asking). Otherwise it dies with the chat.
Node groups: the only way to group nodes. Partition the canvas into named groups, one per logical step (
```
Validate input
```
,
```
Enrich order
```
,
```
Notify
```
), via
```
update_workflow
```
```
setNodeGroups
```
(n8n 2.28.0+). Group every logical step past ~10 nodes. Each group must be a connected, trigger-free run with a single entry and exit (n8n rejects anything else); collapsed, the workflow reads as its steps, not its nodes. Split a section too branchy to form one group into smaller groups that each qualify, or leave it ungrouped. Organization only, members run inline (reuse/isolation is a sub-workflow's job).
Each group also accepts an optional description
string (shown when the group is collapsed). Use it to add a one-sentence summary of what the group does, especially useful for groups whose name alone doesn't convey the why. Blank or whitespace-only descriptions are ignored. Keep descriptions concise; they appear in a small collapsed label.
Sticky notes: annotate, don't group. Grouping is the node group's job (above). Sticky notes are a follow-up layer for context a group can't carry: a callout on a tricky section, a TODO, a warning, a note on the trigger. Use the
```
n8n-nodes-base.stickyNote
```
node with markdown
```
content
```
(
```
### Title
```
on the first line, 1-3 sentences of body) and an integer
```
color
```
1-7. Pick a small palette and stick to it (e.g. gray/yellow for notes, red for warnings, pink for TODOs); random colors communicate nothing.
Node
notes
for non-obvious config. Explain why a workaround exists or a Code node does what it does. Don't annotate obvious nodes.

Plus two notes:

Match existing project conventions before introducing your own. Skim a couple of nearby workflows via
```
search_workflows
```
+
```
get_workflow_details
```
and mirror the sticky palette, naming, and description style.
Layout is auto-applied on create / update. SDK
```
position
```
values for non-sticky nodes are ignored. Stickies, node groups, and naming are your readability levers.

对于超过约5个节点的工作流，四个要素决定可读性：

工作流
description
：记录设计初衷，包括AI推导的上下文。两句话：说明功能和存在原因。最重要的是，记录对话中产生的、不会保存到文件中的上下文（驱动设计的约束、选择此方案的原因、用户的需求背景）。否则这些信息会随聊天结束而丢失。
节点组：唯一的节点分组方式。通过
```
update_workflow
```
的
```
setNodeGroups
```
（n8n 2.28.0+）将画布划分为命名组，每个组对应一个逻辑步骤（如
```
Validate input
```
、
```
Enrich order
```
、
```
Notify
```
）。节点超过约10个时，每个逻辑步骤都要分组。每个组必须是一个连通、无触发器的运行单元，有单个入口和出口（n8n会拒绝不符合要求的分组）；折叠后，工作流会按步骤展示，而非单个节点。如果某个部分分支过多无法形成一个组，可拆分为多个符合要求的小组，或不分组。分组仅用于组织，成员会内联运行（复用/隔离是子工作流的职责）。
每个组还可添加可选的**
```
description
```
**字符串（折叠组时显示）。用一句话总结组的功能，尤其适用于名称无法传达设计初衷的组。空白或仅含空格的描述会被忽略。描述需简洁，因为会显示在较小的折叠标签中。
便签：用于注释，而非分组。分组是节点组的职责（见上文）。便签是补充层，用于记录节点组无法承载的上下文：复杂部分的提示、待办事项、警告、触发器说明。使用
```
n8n-nodes-base.stickyNote
```
节点，内容为markdown格式（第一行是
```
### 标题
```
，正文1-3句话），颜色为1-7的整数。选择少量配色并保持一致（例如灰色/黄色用于注释，红色用于警告，粉色用于待办）；随机配色无法传递有效信息。
节点
notes
：用于非明显配置的说明。解释为何需要变通方案，或代码节点的功能。无需为明显的节点添加注释。

另外两点注意：

遵循现有项目规范，再引入自己的规范。通过
```
search_workflows
```
+
```
get_workflow_details
```
查看几个同类工作流，模仿其便签配色、命名和说明风格。
创建/更新时会自动应用布局。SDK中非便签节点的
```
position
```
值会被忽略。便签、节点组和命名是提升可读性的关键。

Folder limitations

文件夹限制

The MCP can place a workflow into a folder that already exists. It cannot:

Create new folders
Move existing folders
Move existing workflows between folders

If the user asks for a folder that doesn't exist, say so before building. Don't silently create at the project root and report success. Surface options:

User creates the folder manually, then you place workflows into it.
Use a different existing folder.
Confirm root-level placement is acceptable.

For the full protocol including detecting existing folders via

search_folders

, read

references/FOLDER_LIMITATIONS.md

MCP可将工作流放入已存在的文件夹，但无法：

创建新文件夹
移动现有文件夹
在文件夹间移动现有工作流

如果用户要求的文件夹不存在，构建前需告知用户。不要将工作流静默创建在项目根目录并报告成功。提供以下选项：

用户手动创建文件夹，然后你将工作流放入其中。
使用其他已存在的文件夹。
确认是否可放置在根目录。

完整流程包括通过

search_folders

检测现有文件夹，详见

references/FOLDER_LIMITATIONS.md

。

Per-workflow MCP access

按工作流划分的MCP权限

Each workflow has an

availableInMCP

flag. The default depends on who created it:

Workflows created via the MCP (
```
create_workflow_from_code
```
) default to MCP-accessible. No toggle step needed: you can find them via
```
search_workflows
```
and operate on them right away.
Workflows created in the n8n UI can default to off. Until the user flips the toggle, the workflow is invisible to you.

The #1 case where this bites: the user built a workflow manually in the UI and now wants you to inspect or edit it, but you can't see it. Before assuming it doesn't exist or you're searching the wrong project, ask the user to confirm MCP access is enabled.

Sub-workflows called via MCP: the caller can use them as code-level sub-workflows without the toggle. To invoke as MCP-exposed tools, the toggle is required (and is on by default for MCP-created sub-workflows).

For the full case-by-case guide and user-facing message, read

references/MCP_ACCESS_PER_WORKFLOW.md

每个工作流都有

availableInMCP

标志。默认值取决于创建者：

通过MCP创建的工作流（
```
create_workflow_from_code
```
）默认可被MCP访问。无需切换：你可通过
```
search_workflows
```
找到并直接操作它们。
在n8n UI中创建的工作流默认可能不可被MCP访问。在用户切换开关前，你无法看到这些工作流。

最常见的问题场景：用户在UI中手动构建了工作流，现在想让你检查或编辑，但你无法看到它。在假设工作流不存在或搜索项目错误前，先让用户确认已启用MCP权限。

通过MCP调用的子工作流：调用者可将其作为代码级子工作流使用，无需切换开关。如需作为MCP暴露的工具调用，则需要切换开关（通过MCP创建的子工作流默认已开启）。

完整的场景指南和面向用户的提示详见

references/MCP_ACCESS_PER_WORKFLOW.md

。

User-side wire-up (part of stage 3)

用户端配置（第3阶段的一部分）

There are things the user has to do that you can't, and they need to be done before testing, otherwise the test fires against the wrong credential, hits a missing folder, or 401s. Surface these as a short list during VALIDATE, before TEST:

Verify credentials per node.
```
newCredential('Label')
```
is cosmetic. n8n auto-assigns the most recently edited credential of the right type, which silently picks the wrong one when the user has multiples (prod vs staging Gmail, two API keys). Tell them: "open every node that uses a credential and confirm the right one is selected." See
```
n8n-credentials-and-security-official
```
non-negotiable #2.
Create missing credentials. If the user pasted a secret in chat or the workflow needs an account that doesn't exist yet, name the credential type and have them create it in the UI.
Create missing folders. The MCP can't create folders. If the user wanted a folder that doesn't exist, they create it before you can place the workflow there. See
```
references/FOLDER_LIMITATIONS.md
```
.
MCP access toggle for user created workflows. Workflows you create via the MCP are MCP-accessible by default. The toggle only matters when the test depends on a UI-created workflow being callable from the MCP. See
```
references/MCP_ACCESS_PER_WORKFLOW.md
```
.

Don't proceed to TEST until these are confirmed done.

有些事情必须由用户完成，且需在测试前完成，否则测试会使用错误的凭据、访问不存在的文件夹或返回401。在VALIDATE阶段、TEST前向用户列出这些事项：

验证每个节点的凭据。
```
newCredential('Label')
```
仅用于标识。n8n会自动分配最近编辑的对应类型凭据，当用户有多个凭据（生产/测试环境Gmail、两个API密钥）时，可能会静默选择错误的凭据。告知用户：“打开每个使用凭据的节点，确认选择了正确的凭据。”详见
```
n8n-credentials-and-security-official
```
的不可妥协规则第2条。
创建缺失的凭据。如果用户在聊天中粘贴了密钥，或工作流需要尚未创建的账户，告知凭据类型并让用户在UI中创建。
创建缺失的文件夹。MCP无法创建文件夹。如果用户需要的文件夹不存在，需先让用户创建，再将工作流放入其中。详见
```
references/FOLDER_LIMITATIONS.md
```
。
用户创建工作流的MCP权限开关。你通过MCP创建的工作流默认可被MCP访问。只有当测试依赖于UI创建的工作流可被MCP调用时，才需要提及开关。详见
```
references/MCP_ACCESS_PER_WORKFLOW.md
```
。

在用户确认完成这些事项前，不要进入TEST阶段。

Handoff: production handoff (stage 6)

交付：生产环境交付（第6阶段）

After

publish_workflow

and a clean test, the workflow is technically live, but the user still needs enough context to actually use it in production. Treat this like the freelancer-to-customer handoff: short, structured, and oriented toward how they'll operate it from here.

What to include:

How it triggers. Webhook URL (live now that it's published), schedule cadence + timezone, manual trigger button, sub-workflow caller, whichever applies. For webhooks, hand them the URL.
What it returns / where the data goes. One sentence. "Writes new rows to the
```
customers
```
table," "responds JSON to the caller," "fires the on-call Slack channel."
How to invoke it for real, with an example. "Hit the webhook with
```
curl -X POST <url> -d '{...}'
```
," "trigger manually from the UI," "wait until 09:00 UTC for the first scheduled run."
What to watch. Failure modes that surface as alerts/errors, rate-limit ceilings on upstream services, and where to look first when something breaks (executions tab, error workflow, audit log, etc.).
MCP access status. If you created the workflow via the MCP, it's already MCP-accessible. Let the user know they can revoke access in Settings if they want to lock it down. If they hand-built it in the UI, they need to flip MCP access on for any other agent to call it.
Anything still pending on their side. Secret rotation if a token was pasted in chat, follow-up wiring you couldn't reach, known TODOs left in stickies.

Keep it tight: half a dozen bullets, not a wall of text. The user shouldn't have to ask "ok, what now?"

调用

publish_workflow

并完成测试后，工作流在技术上已上线，但用户仍需要足够的上下文才能在生产环境中实际使用。将此视为自由职业者向客户交付：简短、结构化，聚焦于用户后续的操作方式。

需包含的内容：

触发方式。Webhook URL（发布后已生效）、调度周期+时区、手动触发按钮、子工作流调用者，根据实际情况选择。对于Webhook，提供URL。
返回内容/数据去向。一句话说明。例如“将新行写入
```
customers
```
表”“向调用者返回JSON”“发送消息到值班Slack频道”。
实际调用示例。例如“使用
```
curl -X POST <url> -d '{...}'
```
调用Webhook”“从UI手动触发”“等待UTC时间09:00的首次调度运行”。
监控要点。会触发警报/错误的故障模式、上游服务的速率限制上限，以及出现问题时的首要排查位置（执行选项卡、错误工作流、审计日志等）。
MCP权限状态。如果你通过MCP创建工作流，它默认已可被MCP访问。告知用户如需锁定，可在设置中撤销权限。如果是用户在UI中手动构建的工作流，其他Agent调用时需要开启MCP权限。
用户仍需完成的事项。例如聊天中粘贴的密钥需要轮换、你无法完成的后续配置、便签中记录的已知待办事项。

保持简洁：约6个要点，不要大段文字。用户不应需要问“接下来该怎么做？”

Reference files

参考文件

File	Read when
`references/NAMING_CONVENTIONS.md`	Naming a new workflow, sub-workflow, or node
`references/FOLDER_LIMITATIONS.md`	User mentions a folder, project structure, or wants workflows organized
`references/MCP_ACCESS_PER_WORKFLOW.md`	Building a workflow that you or another agent will call via MCP
`references/VALIDATION_CHECKLIST.md`	Just finished a workflow and about to call `publish_workflow`
`references/REVIEW_CHECKLIST.md`	Reviewing or auditing an existing workflow (any age, any author). Severity-tiered findings, distinct from the pre-publish validation checklist
`references/TESTING.md`	About to run `test_workflow` or `execute_workflow` , mocking trigger input, side-effect protocol

文件	阅读时机
`references/NAMING_CONVENTIONS.md`	为新工作流、子工作流或节点命名时
`references/FOLDER_LIMITATIONS.md`	用户提及文件夹、项目结构，或需要整理工作流时
`references/MCP_ACCESS_PER_WORKFLOW.md`	构建你或其他Agent将通过MCP调用的工作流时
`references/VALIDATION_CHECKLIST.md`	完成工作流并准备调用 `publish_workflow` 时
`references/REVIEW_CHECKLIST.md`	审核现有工作流（任何时间、任何作者）时。按严重程度分级的检查项，与发布前验证清单不同
`references/TESTING.md`	准备运行 `test_workflow` 或 `execute_workflow` 、模拟触发器输入、处理副作用时

Anti-patterns

反模式

Anti-pattern	What goes wrong	Fix
Calling `publish_workflow` without validating	Broken workflows reach production	Validate, verify connections, then test
Creating workflows at root because the requested folder doesn't exist	Workflows get lost, and the user has to drag them manually	Surface the limitation before building
Generic node names ( `HTTP Request1` , `Set2` )	Workflows are unreadable a month later	Rename to describe the action
Missing `description` on `create_workflow_from_code`	Workflow invisible in search, no context for maintainers	Always include 1-2 sentences
Asking the user to flip the MCP access toggle on a workflow you created via the MCP	Wastes their time, agent-created workflows default to MCP-accessible	Only mention the toggle for UI-created workflows, or when the user wants to revoke MCP access on an agent-created one
Running `test_workflow` on a workflow with side-effecty non-pinned downstreams without asking	Real Data Table write, real sub-workflow side effects, real Execute Command output, etc. Triggers + credentialed nodes + HTTP get pinned, nothing else does	Ask first. See `references/TESTING.md` .
No node groups on a 15-node workflow	Reader has to read every node to find what they want	Group each logical step via `setNodeGroups` . See "Readability" above
Sticky note used to fake a group, or sticky-of-every-color	Grouping is the node group's job / color becomes pure noise	Group with `setNodeGroups` ; reserve stickies for callouts, one color per category
`description: "Sends Slack."`	Adds nothing visible from the trigger and Slack node	Include why + AI-derived context: "Sends weekly summary to founders. Replaces manual report that kept getting skipped."
Designing fan-out branches as if they execute concurrently	n8n runs fan-out branches sequentially, top-to-bottom by Y-position. Total runtime is the sum of branches, not the max	For real concurrency, dispatch via `Execute Workflow` with `mode: 'each'` + `waitForSubWorkflow: false` . See `n8n-subworkflows-official` "Fire-and-forget parallelization"

反模式	问题	修复方案
未验证就调用 `publish_workflow`	损坏的工作流进入生产环境	先验证、确认连接，再测试
因请求的文件夹不存在而在根目录创建工作流	工作流丢失，用户需手动拖动	构建前告知限制
通用节点名称（ `HTTP Request1` 、 `Set2` ）	一个月后工作流难以阅读	重命名为描述具体操作的名称
`create_workflow_from_code` 时缺失 `description`	工作流在搜索中不可见，维护者无上下文	始终添加1-2句话的说明
要求用户切换你通过MCP创建的工作流的MCP权限开关	浪费用户时间，Agent创建的工作流默认可被MCP访问	仅在用户创建的工作流，或用户想撤销Agent创建工作流的MCP权限时提及开关
未询问用户就对有副作用的非固定下游节点运行 `test_workflow`	真实的数据表写入、子工作流副作用、执行命令输出等。触发器+凭据节点+HTTP GET会被固定，其他节点不会	先询问用户。详见 `references/TESTING.md`
15节点工作流未设置节点组	读者需逐个节点查找所需内容	通过 `setNodeGroups` 为每个逻辑步骤分组。详见上文“可读性”章节
用便签模拟分组，或使用多种随机颜色的便签	分组是节点组的职责/颜色成为无效信息	使用 `setNodeGroups` 分组；便签仅用于提示，每种颜色对应一类内容
`description: "Sends Slack."`	从触发器和Slack节点即可看出，无额外信息	包含设计初衷+AI推导的上下文：“向创始人发送每周摘要。替代经常被遗漏的手动报告。”
假设扇出分支并行执行而设计	n8n按Y坐标从上到下串行运行扇出分支。总运行时间是各分支时间之和，而非最大值	如需真正的并发，使用 `Execute Workflow` 并设置 `mode: 'each'` + `waitForSubWorkflow: false` 。详见 `n8n-subworkflows-official` 的“Fire-and-forget parallelization”