n8n工作流开发框架

n8n Development Framework

24 n8n workflows from a running system, and the 65-point audit each one passes before it goes live.

Building n8n workflows by hand stops scaling somewhere around 5. You remember the node patterns. At 40, you are guessing at property names, copying from broken examples, and finding failure modes in production.

Governance is the second problem. Workflows that start clean drift. Credentials get hardcoded. Error handling gets skipped. A workflow that ran fine last month can start failing because a full API update stripped its credentials. No error and no alert. You find out through downstream failures.

So I brought Claude into the build from the start, and I wrote the audit before I scaled the workflow count. I have built more than 40 workflows. 26 are active. 36 are published across these repos, and 24 of them are here.

The other 10 live with their domain: 2 in security-governance-framework, 2 in database-security-framework, 1 in rag-knowledge-base, and 5 in back-office-automation. The catalog lists all 33.

What's here

Knowledge

Comms

Intel

Infra

Every export is sanitized. Hostnames, credential IDs, webhook paths, Slack IDs and similar are placeholders such as {{N8N_HOST}} and {{CREDENTIAL}}. Execution data has been removed. Workflows tagged "not in production" are exported as they last ran.

The audit itself is a skill and lives in ai-skills-framework, with the full checklist.

How a workflow gets built

DESIGN   Claude, given the real node specs, drafts the workflow.
BUILD    The n8n API creates it directly. No JSON import.
         Test after each major node.
AUDIT    65 points in 2 phases. Pass mark 48.
DEPLOY   Error handling confirmed, README written, indexed for search.

Claude reads real node definitions through the n8n MCP server. Without them, Claude writes JSON that looks right and has wrong property names or missing required fields. With them, it knows what each node needs. That's the gap between "looks right" and "is right."

The build steps:

1. Name it with a layer, a domain and a capability, and a maturity tag.
2. Start it at L1. It moves up after testing.
3. Look at similar workflows before drawing a new one.
4. Build through the API. Never fall back to JSON import on the first error.
5. Test after each major node.
6. Audit before deploy.

The audit

Every workflow gets scored against 65 points in 2 phases. A few defects are blockers whatever the score, such as a Code node in the wrong execution mode.

Phase 1: JSON analysis, 43 points. Runs on the workflow file. Nothing has to execute.

Phase 2: runtime verification, 22 points. Runs after Phase 1 passes.

Thresholds: 48 or more passes. 36 to 47 is conditional, fix and re-audit. Under 36 fails.

The audit runs in a fresh Claude context, separate from the one that built the workflow. Builders rate their own work too high, and the skill says never to audit a workflow you just built.

Error handling on every workflow

All 36 published workflows have an Error Trigger and write to the health table.

Any workflow error
    -> Error Trigger writes state='error' to the health table
    -> Daily digest surfaces errors each morning
    -> Slack alert only for critical, time-sensitive failures

4 failures that changed how I work

Credential stripping. A full API update silently removed the credentials from every node. No error and no warning. I found it days later through authentication failures downstream. Now there is a mandatory check before any full workflow update, and it is a standing item in the audit.

Two call paths, two payload shapes. The same workflow called from MCP and from a webhook received its input in different places. Failures were intermittent and looked random. Now every utility workflow checks both.

Green run, empty database. An execution showed success and wrote nothing. An upstream node had returned an unexpected shape and passed nothing forward, with no error. Phase 2 category C now catches this by looking for recent records in the target tables, since execution status alone missed it.

Stale search index after a rename. I renamed a workflow folder and the old path stayed in the index. Search returned documents pointing at a location that no longer existed. Renames now trigger an index update.

A related lesson from the tooling side: installing the n8n MCP server through npx broke Claude's connection, because download messages landed in the protocol stream. Installing it globally first fixed it. The write-up is in mcp-server-installation-framework.

Why this matters

Workflow governance is release management and change control under a different name. You apply standards consistently. You don't rely on remembering them. The credential failure and the empty-database failure share a cause: no step asked whether the workflow did what it was supposed to do. Phase 2 is that step.

Built with

n8n, the n8n MCP server, Claude, Supabase (Postgres) for logging and health checks.

Jordan Waxman · LinkedIn · GitHub profile