A CLAUDE.md Template for n8n Workflow Projects

A CLAUDE.md file in your n8n project tells Claude Code how your automations are organized: where exported workflow files live, which node types you use, how credentials are referenced, and what counts as a successful run. Without it, Claude Code has to guess at your conventions each session and will likely get them wrong.

Tools like fenbs are a good place to store the automation requirements that shift between projects — approved integrations, lessons from failed runs, decisions about which workflows need human sign-off. Your CLAUDE.md then stays focused on the stable facts that belong in the repo. This page gives you a template to copy and adapt.

What belongs in a CLAUDE.md for n8n

An n8n project typically includes exported workflow JSON files, a short description of each workflow's purpose, and notes on the external services it calls. A useful CLAUDE.md tells Claude Code where those files sit, what naming convention you follow, and which parts of the system it must not change without asking. Keep it short: two or three clear rules beat a long paragraph Claude Code might not reach.

• Workflow file locations and the export format you use (JSON, one file per workflow or a combined export).
• Naming conventions for nodes and workflow files.
• Which credentials each workflow uses and how they are referenced in the JSON — never the credential values themselves.
• How to run or test a workflow, including where to check execution logs.
• Which workflows write to production systems and require a person to review before enabling or changing the trigger schedule.

The template

Copy this into a CLAUDE.md at your project root and fill in the bracketed sections. Remove any section that does not apply to your setup. See CLAUDE.md examples for how other projects structure their files.

# [Project name] — n8n automation project

## Workflow files
Exported workflows live in `workflows/`. Each workflow is a separate JSON file
named after the workflow: `sync-contacts.json`, `send-weekly-report.json`.
To export: Workflow menu → Download → save to `workflows/`.

## Node and naming conventions
- Node names describe their action: "Get Contacts from HubSpot", not "HubSpot1".
- Add a Sticky Note node at the start of each workflow explaining the trigger
  and intended outcome.
- Error workflows are prefixed `_error-`: `_error-email-send.json`.

## Credentials
Credentials are stored in the n8n credential store, not in workflow JSON.
Credential names follow the pattern `[Service] - [Environment]`:
  `HubSpot - Production`, `Slack - Staging`.
Never add credential values to any file in this repo.
Reference only the credential name when describing a node's auth settings.

## Running and testing
- Test locally: import the workflow JSON into your n8n instance, assign
  credentials, run manually from the workflow editor, and check the execution
  log for each node.
- Staging environment: [describe your staging n8n instance or Cloud workspace].
- A run is successful when all nodes show a green check and the downstream
  system reflects the expected change (see each workflow's Sticky Note).

## Production workflows
These workflows write to production data and must be reviewed by [name]
before enabling or changing their trigger schedule:
- [List production workflow file names here]

## What Claude Code must not do without asking
- Enable or disable a workflow trigger.
- Change a credential reference in a workflow JSON file.
- Push or activate workflows in the n8n Cloud workspace.

Credential rules deserve their own section

n8n stores credentials outside the workflow JSON, but the JSON does reference the credential by name. Make sure your CLAUDE.md names the credentials your workflows use without including any actual key, token, or password. A rule like "Never add credential values to any file in this repo" gives Claude Code a clear boundary it can follow consistently.

If you have staging and production credential sets, list both names so Claude Code can distinguish which environment a workflow targets. A mistake here — running a production-credentialed workflow during a test — can be hard to reverse.

Describing completion criteria

Workflow automation has an awkward test boundary: a run can complete without errors but still produce the wrong output. Add a short note to each critical workflow's Sticky Note describing what a successful run looks like — the expected record in the downstream system, the Slack message that should arrive, or the row that should appear in the sheet.

Summarize those criteria in your CLAUDE.md as well. Claude Code can then tell you when a run matched the expected outcome and when it did not, rather than reporting only that execution finished without errors. That distinction saves the time spent checking downstream systems manually after every change.

Node compatibility and version notes

n8n updates its node library regularly. If your project pins a specific n8n version, or if certain nodes behave differently between self-hosted and Cloud, add a short note in CLAUDE.md. Something like "This project runs n8n 1.x self-hosted; do not use nodes that require n8n 2.x or later" prevents Claude Code from suggesting a node that would break your instance.

You can find the full node reference and version notes in the n8n documentation↗ (opens in a new tab). Check there before describing a node's behavior in your instructions — the official description is more precise than a paraphrase.

Lessons from previous runs

When a workflow fails in a non-obvious way — a node returns an empty result, a webhook misses a payload, a schedule runs at the wrong time — the fix often involves context that is too project-specific for a generic CLAUDE.md. A project's Lessons learned in fenbs captures what happened, what the real cause was, and what to check first next time. A connected assistant reads those lessons before similar work.

Keeping the template current

Update your CLAUDE.md when you add a new service integration, rename a workflow, change the export format, or add a production boundary. An outdated instruction misleads Claude Code more than no instruction at all. A short review when you add a new workflow catches most gaps before they become a problem.

For instructions that vary by project — which integrations are approved, which endpoints are in use — keep those in a project context note or decision in fenbs rather than in the CLAUDE.md. That way the file stays small and reusable across similar automation projects. See does Claude Code read AGENTS.md if you need to understand how Claude Code loads instructions from multiple files.

How to do this with fenbs

1. Create a free account. Start a project for your n8n workspace and list its workflows as tasks.
2. Add the approved automation requirements as Decisions and rules: which services are sanctioned for production, which workflows need human review before activation.
3. Connect Claude Code to fenbs from Integrations. Ask it to read the project context at the start of each session so it knows the current rules before editing a workflow file.
4. After a significant debug session, record what failed and how it was fixed as a lesson in fenbs, linked to the relevant task.
5. Review your CLAUDE.md when requirements change and update the corresponding fenbs decision so both records stay in agreement.