Artur Pososhko

Downloads · starter kit

n8n house rules for building with Claude Code

The rules Claude Code follows in every client repo, readable here. The zip adds the per-client template they belong to.

Download the starter kit (zip)All downloads

These are the rules I give Claude Code before it touches an n8n instance, in every client repo. The short version: Claude builds on a dev instance only and a human promotes to production; send nodes never carry recipients; workflows stay under 15 nodes; no secret is ever hardcoded; every session leaves a checkpoint the next one can resume from. Copy them, change them, make them yours.

They are the house layer of a two-part prompt. Part A, not included here, is the upstream guidance from the n8n-MCP project: the "Claude Project Setup" section of its README at github.com/czlonkowski/n8n-mcp. Credit for Part A goes to that project. Paste it above these rules in one file; where the two conflict, these rules win.

Paths such as n8n-conventions/30-mistakes.md and n8n-conventions/40-doc-standard/ refer to a shared conventions folder that sits next to every client repo (the starter kit README shows the layout). Start your own: an append-only list of mistakes, and the handover doc template from the same downloads page.

House rules (apply in every client repo)

Scope Guardrail

  • You may only touch the n8n instance whose URL is in this repo's .mcp.json. That is always a DEV instance.
  • Production is deployed exclusively by a human running ./deploy.sh. Never call any tool against a prod URL. Never set active: true on deploy.

Session Start

  • First action in any session that touches n8n: READ before you write. List workflows, fetch one, describe it. This verifies the connection, the instance, and your understanding.
  • Read n8n-conventions/30-mistakes.md and this file before building.

Checkpointing (adapted from enterprise practice)

Maintain PROGRESS.md in the repo root. After every meaningful step and before any risky/long operation, update it using this format:

CHECKPOINT
Task: …
Status: …
Last completed step: …
Key facts:
- …
Artifacts created (workflow IDs, files):
- …
Open issues:
- …
Next step:
- …

If a session dies or errors, the next session resumes from the latest checkpoint instead of restarting. Store concise resumable state, never verbose reasoning.

House Workflow Standards

  • Node naming with numeric prefixes: 01_Trigger, 02_Normalize_Input, 03_…, last two are always NN_Notify_Success and NN_Handle_Error where used.
  • Arrange left-to-right, readable coordinates. Keep workflows under 15 nodes; split into sub-workflows beyond that.
  • Node preference order: official app node → core node → HTTP Request → Code node last resort.
  • Reliability: failure branches for critical steps; retries max 3 with backoff where supported; every production workflow connects to the client's global error workflow (alerts to a channel you own unless the client specifies another one).
  • Idempotency: stable business key preserved through execution; dedupe/upsert where retriggers are possible.
  • Security: no hardcoded secrets, ever. {{$env.NAME}} expressions or n8n credentials only. Minimize sensitive data in logs/notifications.
  • Credentials: never create credentials from scratch when a credentials-template workflow exists on the instance: copy node + credential references from it. Identical credential names exist on dev and prod; never rename them.

Dev Side-Effect Safety

Instance separation protects workflow definitions, NOT side effects. A dev execution with real credentials sends real emails to real people. Therefore:

  • Send/notify/write nodes NEVER hardcode recipients, channels, or target IDs. They read them from instance env vars: {{$env.ALERT_CHANNEL}}, {{$env.REPORT_EMAIL_TO}}, {{$env.TARGET_BOARD_ID}}, etc. Dev's env points at test targets (a test channel you own); prod's env points at real ones. The workflow JSON promotes unchanged.
  • While building in dev: keep send-type nodes DISABLED until upstream logic is verified with pinned data and step-by-step manual executions. Enable them only for the final test against dev's test targets.
  • For high-risk services (client email, CRM writes), dev's credential with the shared name (e.g. gmail_main) must be a test account, not the production account. If you cannot confirm which account a dev credential points to, ask before executing a workflow that sends or writes externally.
  • Reads of real data in dev are fine and expected. Writes and sends to real recipients from dev are never acceptable.

Safe Defaults (unless the user explicitly overrides)

{
  "active": false,
  "settings": {
    "executionOrder": "v1",
    "saveDataErrorExecution": "all",
    "saveDataSuccessExecution": "all",
    "saveManualExecutions": true,
    "callerPolicy": "workflowsFromSameOwner"
  }
}

Tags on every generated workflow: mcp-generated, {{CLIENT_TAG}}.

Build Cadence

  • One PRD = one build. If there is no PRD (source, logic, error destination, success criteria), ask for one or draft it for approval first.
  • Templates first, then node-by-node build-and-validate. Iterate via n8n_update_partial_workflow, never full rewrites of a deployed workflow.
  • A green validator is necessary, never sufficient: finish every build by telling the human to eyeball the workflow in the n8n UI and run a pinned-data test.
  • After every build, ask: "What should I have been told upfront?" Append the answer to n8n-conventions/30-mistakes.md.

Documentation

  • Every workflow that reaches prod gets a doc generated from the repo per n8n-conventions/40-doc-standard/, saved in the client repo docs/ and exported for the client folder.